Repo ↗ · 原始 README ↗ · 文件包（Markdown／授權）
封面參考（原作）： Half-Life 2 · 原作宣傳圖，由 IGDB 提供。圖片版權屬原權利人，供辨識原作使用，不代表此重寫／模組專案的實際畫面。
來源維護者： kvalls · 版本： dedeb1944fb0 · 整理日期： 2026-10-12
文件授權： MIT · LICENSE · 本文形式： README 翻譯
下文為來源 README 的繁中翻譯，由 Kirikirin 使用 AI 輔助整理；功能、完成度與測試結果均為原作者描述，本站未逐項實機驗證。圖片改為來源連結，指令與技術識別保留原文。
HL2-RS
一個獨立、部分實作的 Half-Life 2 Rust 重建版本，會從已安裝的遊戲複本讀取地圖、模型、貼圖、動畫與音效。它不會載入 Valve 的遊戲或引擎 DLL。完整戰役目前尚無法遊玩。
平台
| 作業系統 | 狀態 | 證據 |
|---|---|---|
| Windows 11 64 位元 (x86_64) | 主要測試平台 | 擁有者建置、單元與自有檔案測試、封裝重播/擷取與原生遊戲比較；CI 在 windows-latest 上執行。 |
| Apple Silicon 上的 macOS 15+ (aarch64, Metal) | 由貢獻者測試 | 在 Apple M1 Pro 上：建置、測試，以及封裝建置 (./scripts/build-bevy.sh、./launch-bevy.sh) 執行 d1_trainstation_02，包括腳本化的販賣機、Metrocop 序列與佇列，結束代碼為 0 (PR #1)。重播、擷取與原生比較未測試。 |
| Linux | 未測試 | 安裝探索會查看 ~/.steam/steam 與 ~/.local/share/Steam，但建置與 POSIX 腳本皆未在 Linux 上執行過。歡迎回報。 |
| Intel 上的 macOS、其他系統 | 未測試 |
分支與貢獻
HL2-RS 是 Bevy 0.19 / wgpu 的 Rust 重寫版本。自有資源讀取器、共享模擬與渲染依循 iw4L 分離。2026-10-07 時，Bevy 相關工作已合併至 main，原本的 Macroquad/OpenGL 主機已從中移除。
| 分支 | 用途 | Pull request |
|---|---|---|
main |
Bevy/wgpu 重寫：共享移動、實體/武器模擬、編排、動畫呈現、模型光照、自有 HUD/音訊、天空與監視器。 | 以此分支為目標。 |
| macroquad-prototype | 原始 Macroquad 原型的保存快照。 | 僅供歷史參考。 |
| bevy-migration | 遷移分支，凍結於合併至 main 的時間點。 |
僅供歷史參考。 |
source-assets 讀取 Source 格式，modkit-core 擁有共享契約、玩家與姿勢數學，hl2-simulation 擁有遊戲玩法、物理與編排，hl2-ui 擁有 HUD、選單與主控台，hl2-bevy 則是主機。Bevy 的預設 PBR 材質不會重現 Source 著色器或物理；那些有其自身的實作與比較。不應僅因引擎本身而假設速度或保真度有所提升。開啟 PR 前請參閱 CONTRIBUTING。
使用 scripts/build-bevy.ps1 建置並執行 launch-bevy.cmd。使用 launch-bevy-1080p.cmd 可獲得 1920x1080 視窗，或使用 launch-bevy-borderless.cmd 取得主要桌面解析度。執行檔預設以共享的 15 ms Player 控制器與 Physics 碰撞查詢行走；--fly 或 F2 可啟用飛行。Escape 會開啟暫停選單並釋放游標；選擇 Resume 以繼續。波浪號鍵會開啟開發者主控台。門與物理道具會隨其碰撞器移動，實體片段與武器視角模型會播放動畫，場景/武器/投射物邏輯則以固定步長執行。F3 會給予開發者裝備；E 使用門，欄位/滑鼠滾輪選擇武器，滑鼠按鍵則開火/確認。自有環境、場景、武器與 HUD 提示音會透過 Bevy 音訊播放。自有天空背景（若有 HDR 面時使用）、微型景物、模型驅動的虹膜投影、臉部伸縮、脣形同步與即時 _rt_Camera 監視器畫面皆會渲染。作者製作的 changelevel 觸發器會攜帶地標相對位置與物品欄；主控台 map 則重新開始。存檔/全域實體狀態與完整的玩家轉移仍未完成。以 tick 為基礎的 --movement-script 測試夾具會記錄玩家/遊戲玩法狀態並擷取最終畫面。針對無人值守執行，--volume 0.01 設定主音量，--no-focus 則開啟視窗而不取得焦點。請參閱 Bevy 指示與里程碑。
GPU 蒙皮與保守的 BSP PVS 剔除（連同 Bevy 視錐剔除）讓受測的 station02 出生點在 1080p 無上限下維持約 157-175 FPS。其他視角、原生效能同等性與持續 144 FPS 仍未驗證；請參閱 效能測量。launch-bevy.cmd --uncapped 在測試時不使用 VSync 進行呈現；--profile 記錄有界的 CPU 階段測量。
README 圖片：HL2-RS Rust 執行階段渲染 trainstation，附手槍、HUD 與開發診斷
擷取自 d1_trainstation_02 上的封裝 Rust 建置，附 F1 診斷與開發者武器裝備。這是渲染預覽，並非完成戰役遊戲玩法的證據。螢幕擷取畫面描繪的是自有 HL2 內容；可散布的遊戲資源並未包含在內。
模型作者製作的活動查詢現在會修復不支援的隱含 NPC 待機標籤，包括 Kleiner，同時保留明確預設值與現有已載入姿勢。場景 GESTURE 事件現在會以分層動畫播放（Source delta/post 層、骨骼遮罩、自動層、Faceposer 標籤時序），適用於 Barney 與 Kleiner 等角色。與原版遊戲的並排比較正在進行中：Barney 現在會從他的 point_template 生成，並在前往桌子的途中開門，但 NPC 觸碰觸發器仍然缺少。原生 AI 排程、頭部/臉部動畫、脣形同步與第一關卡編排仍未完成。
建置全新簽出
你需要一份自有、已安裝的 Steam PC 版 Half-Life 2、Windows 64 位元、具備 MSVC 工具鏈的 Rust stable，以及含 Windows SDK 的 Visual Studio C++ 建置工具。渲染器使用 Bevy/wgpu（在 Windows 上以預設後端測試）；GPU 與 RAM 最低需求尚未測量。在 macOS 上請使用 ./scripts/build-bevy.sh 與 ./launch-bevy.sh；各系統已測試的內容請參閱 平台。
受測的安裝為 Steam 應用程式 220，組建 19307283，修補 9912070。其他遊戲組建未經驗證。記錄的 Windows 檢查使用 Rust 1.99.0。Cargo 會解析 Cargo.lock 中的函式庫版本；不需要外部模組、載入器或 Source 引擎執行階段。
私有研究現在包含 42 個選定的原生模組、122,721 筆已儲存的分析項目，以及 10,752 筆獨立的暫時探索項目。經稽核的合併資料庫持有 133,473 個不同的已觀察位址，附帶部分虛擬碼，並保留精確位元組、原始失敗與匯出變體。已審查的名稱/型別、Rust 實作與原生驗證仍各自分離；此研究不設定任何完成旗標。完整執行階段範圍、探索、ABI 與行為同等性仍未驗證。所有原生二進位檔、程式碼、工具與資料庫皆保留在此儲存庫之外。請參閱 研究證據。
git clone https://github.com/kvalls/hl2-rs.git
cd hl2-rs
.\scripts\build-bevy.ps1
.\launch-bevy.cmd
此儲存庫包含原始碼，而非預先建置的執行檔。建置會產生 bin/hl2-bevy.exe 及其著色器資料夾 bin/bevy-assets。若 PowerShell 封鎖本機建置腳本，請為該處理程序叫用 powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-bevy.ps1。若要解除安裝，請移除簽出；遊戲安裝為唯讀。
macOS
在已安裝 Rust 工具鏈的 macOS（Apple Silicon / POSIX）上，請使用提供的 shell 腳本來建置並啟動遊戲。位於 ~/Library/Application Support/Steam 的 Steam 安裝會自動探索。
git clone https://github.com/kvalls/hl2-rs.git
cd hl2-rs
./scripts/build-bevy.sh
./launch-bevy.sh
建置會產生 bin/hl2-bevy 與 bin/bevy-assets 著色器資料夾。執行檔與著色器資料夾必須保持在一起。
遊玩目前建置
在此資料夾中雙擊 launch-bevy.cmd。它會啟動 bin/hl2-bevy.exe，即封裝的發行建置。只有在重新建置時才需要 Rust。預設地圖為 d1_trainstation_02。
.\launch-bevy.cmd --map d1_trainstation_01
.\launch-bevy.cmd --game 'C:\Program Files (x86)\Steam\steamapps\common\Half-Life 2'
.\launch-bevy.cmd --borderless
.\launch-bevy.cmd --width 1920 --height 1080
Steam 函式庫會自動探索；HL2_ROOT 可覆寫探索。原始資源會就地讀取。執行階段中沒有隨附的遊戲資源、反編譯工具或原生遊戲 DLL。不需要 FAL 帳號或 credits。
| 控制 | 動作 |
|---|---|
| WASD / 滑鼠 | 移動 / 環顧；點擊視窗以捕捉滑鼠 |
| Escape / 波浪號 | 先取消武器選擇；否則暫停 / 開啟開發者主控台 |
| Space / Ctrl | 跳躍 / 蹲下 |
| Shift / Alt | 衝刺 / 慢走 |
| E | 使用伸手可及的門或按鈕 |
| 左/右鍵、R | 主要 / 已實作的次要攻擊、重新裝填 |
| 1-6 / 滑鼠滾輪 | 開啟/循環自有武器；任一攻擊按鈕皆可確認 |
| Q | 切換至上一把武器 |
| F3 | 開發者裝備：鐵撬、手槍、.357、SMG1、AR2、霰彈槍、儲備彈藥與防護衣 |
| F1 | 切換開發疊層；預設隱藏 |
| G | 對附近道具施加測試衝量 |
| F2 | 切換飛行（Space/Ctrl 上升/下降） |
| F10 | 離開 |
起始地圖通常沒有玩家武器。F3 是測試輔助。它並不展示戰役武器取得。部分戰役腳本仍會阻擋進度。
暫停選單具有可用的 Resume Game、Developer Console 與 Quit 控制項。主控台支援歷史記錄、編輯與使用 Tab 的指令名稱補全。help 列出已實作的指令。輸入 sv_cheats 1; impulse 101 以取得六把已實作武器、彈藥與防護衣。其他支援的指令包括 noclip、getpos、setpos、setang、map、ent_fire、find、echo、clear、toggleconsole 與 quit。ent_fire <target> [input] [parameter] [delay] 會將一般實體 I/O 傳送至具名目標；其主控台延遲使用整秒。Classname 回退與完整 Source 指令登錄仍未完成。不支援的指令會回報錯誤。存檔/載入、選項與按鍵綁定仍未完成。選單或主控台開啟時，玩家、武器、實體與道具模擬會暫停；環境音訊尚未暫停。UI 使用已安裝的 GameUI 標籤/顏色與系統字型，但其版面配置並非精確的 VGUI 重建。
目前已實作
簡言之：自有 VPK/BSP/VMT/VTF/MDL/PHY/音訊讀取器；世界、位移、道具與模型渲染，附烘焙光照圖、Source 模型光照、HDR 自動曝光、泛光、天空與即時監視器；固定步長玩家移動與碰撞；實體 I/O、門、觸發器與編排場景，附分層手勢、臉部伸縮與脣形同步；六把武器（鐵撬、手槍、.357、SMG1、AR2、霰彈槍）及其 HUD；以及地圖轉換。逐項完整清單位於 docs/features.md。
尚待完成的保真度工作
這不是 Source 的完成重寫。主要缺口包括一般 NPC 導航/排程/戰鬥、其餘軍火、後座力/槍口閃光/曳光彈/彈殼退出、精確預測散布與霰彈槍彈丸外殼軌跡、溺水與其餘玩家傷害管線（擊退、打擊角度、基於時間的傷害）、載具、存檔/載入、戰役狀態轉移、完整編排移動/迴圈/子場景/對話/脣形同步、非音效動畫事件/混合/分層手勢/IK/伸縮、布娃娃物理、動態/動畫 PHY 碰撞、移動平台行為與受阻門處理。腳本化移動與父子關係/附件仍未完成。歷史/輔助電力面板、縮放/convar 閘門與額外 VGUI 動畫指令仍未完成。投射物碰撞/材質反應、關係與傷害篩選、水體拒絕、導引瞄準、溶解視覺效果與爆炸粒子並未重現完整原生行為。
水/梯子、表面移動修正、精確蹲下轉換與預測仍需進一步處理。渲染器缺少 Source 的完整光照/材質系統：LDR 模式、凹凸漫射光照、自發光遮罩、模型/筆刷實體上的環境貼圖（世界 LightmappedGeneric $envmap 反射已實作，含遮罩與凹凸法線）、光照探針、陰影、天空多邊形遮罩、天空霧、霧、水/折射、動態光照風格以及許多材質代理。符號語音現在使用擁有的演員模型性別註冊表與已註冊的 wave 替代項目。音訊具有 Source 距離增益，用於 ambient_generic 迴圈與 env_soundscape 背景（SDK 選擇與 3 秒交叉淡入淡出，已在 d1_trainstation_02 測試）、玩家腳步聲（SDK 步伐時序與表面音效）以及子彈與鐵撬的表面相依撞擊音效，但仍缺少串流、立體聲平移、DSP 空間效果與其他壓縮格式。玩家傷害遵循 SDK 順序（技能 2 縮放、整數護甲/生命值、玩家與 NPC 的 trigger_hurt、墜落傷害），且在地圖的 gordon_invulnerable env_global 開啟時被拒絕（d1_trainstation_01-03）；env_global 狀態會跨關卡變更保留。傷害會顯示擁有的 HudDamageIndicator 序列、DamageEffect/env_fade 畫面淡出，且僅在穿著防護衣時顯示 HEV 語音句子（來自 sentences.txt 的 VOX 詞彙，死亡時為 HEV_DEAD）；未穿防護衣時僅播放 Player.Death / Player.FallGib。玩家透過重新啟動地圖重生；溺水與存檔尚未完成。MP3 會解碼一次至有界的記憶體內 PCM 快取；其首次請求可能在解碼時停滯。內容掛載並非通用的 gameinfo.txt 實作。支援的地圖載入並不證明地圖的遊戲玩法可運作。
重建與檢查
在安裝 Rust stable、rustfmt、Clippy 與 Visual Studio C++ 工具的情況下，使用以下指令重建：
.\scripts\build-bevy.ps1
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo fmt --all --check
.\launch-bevy.cmd --movement-script test-inputs/bevy-movement.json --capture artifacts/check-movement.png --report artifacts/check-movement.json
build-bevy.ps1 會替換啟動器所使用的執行檔；變更原始碼或提交它並不會重建該執行檔。僅在刻意封裝除錯組建時使用 -DebugBuild。bin/build-bevy-info.json 會記錄封裝的執行檔與著色器指紋。執行階段擷取/報告會寫入被忽略的 artifacts/。
研究邊界
此檢出項目的獨立原生研究資料夾為 ../../work/hl2-decompiled。其私有二進位副本、Ghidra 資料庫、C 虛擬碼、索引與研究腳本均在本專案之外。它是實作行為的參考；其原生程式碼不會被載入或編譯至 Rust 執行階段。原生匯出為近似虛擬碼，並非復原的原始原始碼。
開發使用了 universal-modder Codex 外掛與十項技能，版本 0.2.0。它們並非執行階段或建置相依項目。其 FAL 功能未使用。所要求的三個參考儲存庫已被閱讀並記錄於 research。具體檢查請見 validation，實作備註請見 MODLOG。
這是一個 AI 輔助專案，使用 OpenAI Codex（GPT-6）開發，並自 2026-10-06 起使用 Anthropic Claude Code（Claude Opus 5.5），包含原版遊戲測試與選定原生行為的手動審查。它仍是一項實驗性重建。歡迎貢獻；請閱讀 CONTRIBUTING 以了解程式碼邊界、檢查項目與 PR 中應包含的有用證據。
原專案程式碼採用 MIT 授權。已安裝的資產與私有分析保留其自身權利，並排除於 Git 之外。相依項目保留其自身授權。
授權與來源聲明
原始 README 與翻譯沿用 MIT 授權；本次修改為繁中翻譯、連結與排版調整。可修改的 Markdown、原始 README、LICENSE 與 NOTICE 收錄於頂部文件包。原作遊戲內容與商標不因此獲得授權。
LICENSE
MIT License
Copyright (c) 2026 HL2-RS contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
評論
…