Repo ↗ · 原始 README ↗ · 文件包（Markdown／授權）

封面參考（原作）： Grand Theft Auto: San Andreas · 原作宣傳圖，由 IGDB 提供。圖片版權屬原權利人，供辨識原作使用，不代表此重寫／模組專案的實際畫面。

來源維護者： goonJungus · 版本： 0501ca100e33 · 整理日期： 2026-10-12

文件授權： MIT · LICENSE · 本文形式： README 翻譯

下文為來源 README 的繁中翻譯，由 Kirikirin 使用 AI 輔助整理；功能、完成度與測試結果均為原作者描述，本站未逐項實機驗證。圖片改為來源連結，指令與技術識別保留原文。

gta-sa-cpp

[README 圖片：Discord](https://discord.com/users/261653544854093825)

《俠盜獵車手：聖安地列斯》的 C++ 移植，進行中。類別是從一份完整的反編譯原始碼移植而來，按照原版遊戲組織它們的方式來組織，並在落地時對照反編譯原始碼進行驗證。

目標： 一個可編譯的 C++ 程式碼庫，反映原版遊戲的結構——每個類別都移植完成，每個方法都經過驗證。

🙏 請踴躍貢獻

這是個大工程——將近一千個類別——人手越多進展越快。你不需要是逆向工程師：挑一個類別，移植它，驗證它，那就是一份實實在在的貢獻。port_plan/ 會明確告訴你該做什麼、按什麼順序做，而 CONTRIBUTING.md 會帶你走過整個流程。每個落地的類別都是進展。來幫忙吧。

進度

~21% — 996 個類別中有 206 個已移植標頭檔，且完整的 gta_sa 靜態程式庫能以零錯誤建置（13.3 MB 的 lib）。

████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 21%

統計於 2026-10-11：include/ 中已移植的標頭檔對比 port_plan/classes.txt 中的類別。標頭檔代表該類別存在；BUILD_NOTES.md 追蹤哪些方法主體已驗證、哪些仍是 TODO 佔位。

只有程式碼——請自備你的遊戲副本

這個儲存庫只包含程式碼。這裡不散布任何遊戲資產、遊戲資料、音訊、材質、模型，也沒有任何從零售版遊戲擷取的檔案，而要建置這個程式碼庫也不需要這些東西。

若要執行任何由此程式碼建置而成的東西，你必須自備你自己合法取得的《俠盜獵車手：聖安地列斯》副本（PC，1.0 US）。從你的副本載入資產的功能尚未實作；等實作之後，建置產物會指向你的安裝，除此之外別無其他。

狀態

已移植： 核心數學／容器、碰撞（CColModel / CCollision）、世界實體（CPlaceable → CEntity → CPhysical → CObject、CBuilding、CWorld）、攝影機、渲染器、後製效果、陰影、天氣、字型、精靈、模型資訊、動畫、載具、武器、火焰／爆炸、音訊引擎、fx、檔案管理員、計時器、手把輸入、行人、玩家、HUD、串流，以及 SCM 腳本虛擬機（目前 84 個 opcode）。

仍待辦： 真正的 RenderWare 層（RenderTypes.h 只是替代品）、CGame、完整的音訊實體／列舉、剩餘的 26 個 SCM opcode 分派區塊，以及許多標記為 TODO 的方法主體。佔位是誠實的——BUILD_NOTES.md 說明了哪些已驗證、哪些是佔位，而它是這個專案的持續紀錄。

port_plan/ 是地圖：類別清單、相依性（deps.tsv）、子系統拆解（subsystems.tsv），以及建置順序（layering.json）。

儲存庫結構

include/        # Class headers, organized like the original game
src/            # Method implementations
port_plan/      # Contributor map: classes, deps, subsystems, build order
CMakeLists.txt  # Static lib (gta_sa) + standalone D3D9 exe (gtasa_cpp)
BUILD_NOTES.md  # Running port log — read this first

使用的工具

  • Ghidra — 用來驗證移植正確性的反編譯原始碼（獨立工作流程，不在這個儲存庫中）
  • CMake 3.20+ — 建置設定
  • MSVC / Visual Studio 2022 — 唯一測試過的編譯器，Win32（x86）目標以符合原始二進位檔
  • Git — 版本控制

沒有套件管理員，沒有外部相依性。靜態程式庫只需要一個編譯器；gtasa_cpp 執行檔連結系統的 D3D9。

建置

Windows，PowerShell：

cmake -B build -G "Visual Studio 17 2022" -A Win32
cmake --build build --config Debug

注意事項：

  • C++20，/W3 /permissive-。僅限 MSVC——GCC/Clang 未經測試。
  • CPed.cpp 需要 /Zm8000（編譯器堆積）；CMake 檔案會透過 CL 環境變數自動設定它。如果你手動編譯檔案，請先設定 $env:CL="/Zm8000"。
  • build/ 已被 git 忽略。僅限原始碼外建置。

貢獻

請見 CONTRIBUTING.md。簡短版：從 port_plan/ 挑一個類別，移植它，對照反編譯原始碼驗證，並記錄在 BUILD_NOTES.md 中。

致謝與參考資料

這個專案站在 GTA 模組與逆向工程社群的肩膀上：

  • gta-reversed — include/ 中的許多標頭檔改編自這裡（已剝除 plugin-sdk 的特定內容）。SA 類別佈局的權威來源。
  • re3 / reVC — GTA III/VC 的淨室重實作。碰撞佈局與載入時行為的參考。
  • librw（aap）— 開源 RenderWare 實作。DFF/TXD 格式參考。
  • openrw — RenderWare 格式的洞見。
  • SanAndreasUnity — 引擎行為參考。
  • opensa — 格式與串流參考。
  • jte/GTASA — 淨室重實作的 C++ SA。結構佈局、區塊公式。
  • GTA-San-AnSkateas（ryglizzy）— 三角形湯碰撞方法。
  • ariane（Dryxio）— 二進位 IPL 研究、地圖編輯器工具、逆向工程工作流程。

這個儲存庫中的所有移植程式碼都是為本專案所撰寫。未包含任何 Rockstar Games 資產。

AI 代理

這個專案是在 AI 協助下建置的：

  • Pi + Opus 5.5 — Pi 是執行框架，Opus 5.5 負責反編譯到重寫的流程（從反編譯到 C++ 移植）。
  • Claude Code — 在建置機器上處理複雜的編碼任務。
  • Muse Spark — 專案基礎設施、儲存庫自動化與鷹架。

法律

這個專案不包含、不下載、也不重新散布任何 Rockstar Games 資產或遊戲資料。你必須自備你自己合法取得的《俠盜獵車手：聖安地列斯》副本。移植自為互通性研究而進行的反編譯。依 MIT 授權條款 授權。

授權與來源聲明

原始 README 與翻譯沿用 MIT 授權；本次修改為繁中翻譯、連結與排版調整。可修改的 Markdown、原始 README、LICENSE 與 NOTICE 收錄於頂部文件包。原作遊戲內容與商標不因此獲得授權。

LICENSE

MIT License

Copyright (c) 2026 goonJungus

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.