仓库物理地图
本页说明 GTAV Source 快照的物理组织：有哪些顶层树、每棵树里是什么、规模多大、各目录由 Wiki 的哪一页负责。逻辑架构（层次、依赖方向、运行时拓扑）见 overview.md，构建系统见 build-and-config.md。
1. 快照性质#
- 快照不是 Git 仓库，也没有提交号；目录时间戳是 2024-04-16。可识别的版本标识来自源码本身：
- 项目名是
gta5，代码分支目录是dev_ng，MSBuild 通过目录名推导分支和各根路径（RS_CODEBRANCH、RS_SCRIPTBRANCH、RS_TOOLSROOT、RAGE_DIR等）src/dev_ng/Directory.Build.props:10-49。 - forceinclude 配置头写死了
GTA_VERSION 501（例如src/dev_ng/rage/base/src/forceinclude/orbis_master.h:488）和 RAGE 版本RAGE_RELEASE 378、1.15src/dev_ng/rage/base/src/forceinclude/win64_final.h:17-20。
- 项目名是
- 这是 NG（PS4/Xbox One/PC）代码线，并且带有部分 Gen9（PS5/Xbox Series）移植痕迹：
Gen9Settings.h定义RSG_GEN9（缺省 0）、IS_GEN9_PLATFORM、GEN9_STANDALONE_ENABLED等开关src/dev_ng/rage/framework/src/fwutil/Gen9Settings.h:7-34；入口文件也包含它src/dev_ng/game/Core/main.cpp:7。- 构建属性在分支名包含
gen9时改用tools_ng/etc/projgen9，并引用RageBuilderGen9src/dev_ng/Directory.Build.props:53-54、src/dev_ng/Directory.Build.props:78；VS 用户设置里有 PS5 (ProsperoSKU) 选项src/dev_ng/projgen/RSG.xml:24-34。 - 但 forceinclude 目录中只有
win32*、win64*、durango*、orbis*、psn*、spu_psn*、xenon*配置头，所有现存配置都把RSG_PROSPERO/RSG_SCARLETT定义为 0（例如src/dev_ng/rage/base/src/forceinclude/win64_final.h:138-139、src/dev_ng/rage/base/src/forceinclude/durango_bankrelease.h:117-118）。游戏代码只在少数位置（如network/Voice/NetworkVoice.cpp、script/commands_network.cpp）出现RSG_PROSPERO/RSG_SCARLETT分支。这表明 Gen9 平台的专有后端与配置不在本快照中；Wiki 中所有“平台差异”结论都以现存的 PC/Durango/Orbis/PS3/Xenon 代码为准。
- 旧平台代码仍然大量存在：PS3（
__PPU/__SPU、SPU 作业.job/.frag、VS_Project_frags等）和 Xbox 360（__XENON）分支散布在各处，例如入口文件中针对 PS3 的 SDK 版本检查与 title IDsrc/dev_ng/game/Core/main.cpp:256-289。
2. 顶层布局与规模#
规模由本次分析用脚本对快照逐文件统计得到（物理行数，含注释与空行），只用于说明量级，不是覆盖率指标。
| 顶层树 | 文件数 | 体积 | 内容 | 主要语言 |
|---|---|---|---|---|
src/dev_ng/ | 约 7.6 万 | 约 8.4 GB | 游戏 C++、RAGE 引擎、第三方库、代码工具、安装/启动器 | C++、C#、HLSL |
script/dev_ng/ | 约 4.5 千 | 约 450 MB | 游戏逻辑脚本（单机任务、GTA Online）及脚本工具 | SanScript（.sc/.sch） |
tools_ng/ | 约 5.8 万 | 约 7.1 GB | 资产流水线、DCC 插件、构建与自动化脚本、预编译工具 | Python、Ruby、C#、MaxScript |
按代码量看（同一统计）：
| 范围 | 文件 | 物理行数 |
|---|---|---|
src/dev_ng/game（.cpp/.h/.inl/.c，不含 shader_source） | 4,701 | 约 367 万 |
src/dev_ng/game/shader_source（.fx/.fxh） | 452 | 约 11.5 万 |
src/dev_ng/rage/base/src（C/C++） | 4,224 | 约 178 万 |
src/dev_ng/rage/framework/src（C/C++） | 852 | 约 33 万 |
src/dev_ng/rage/suite/src（C/C++） | 2,752 | 约 82 万 |
src/dev_ng/rage/script/src（脚本 VM） | 43 | 约 1.8 万 |
src/dev_ng/rage/naturalmotion（C/C++） | 707 | 约 34 万 |
src/dev_ng/rage/scaleform（C/C++） | 477 | 约 28 万 |
src/dev_ng/rage/3rdparty（C/C++） | 7,731 | 约 378 万 |
src/dev_ng/rage/{base,framework,script,suite}/tools（主要为 C#） | 约 1.8 万 | 约 288 万 |
script/dev_ng（.sc/.sch） | 4,053 | 约 1009 万 |
tools_ng（.py/.rb/.cs/.ms/.cpp/.h，含大量第三方 Python 包） | 约 1.8 万 | 约 599 万 |
3. src/dev_ng/ —— 代码分支根#
根目录只有少量批处理和 MSBuild 配置：setenv.bat 通过 tools_ng/bin/PropertySheetViewer.exe dumpenvironment 导出环境变量并打印各根路径 src/dev_ng/setenv.bat:1-77；BuildEmAll.bat 调用 %RS_TOOLSROOT%\script\util\projGen9\generate.bat 为整个游戏生成工程 src/dev_ng/BuildEmAll.bat:13-15；projgen.config 指向 %PROJGEN_DIR%\game.build。详见 build-and-config.md。
| 目录 | 内容 | Wiki 页面 |
|---|---|---|
game/ | GTA V 游戏层 C++（约 60 个子目录，见 §4） | 01、05–23 各节 |
rage/ | RAGE 引擎（base/framework/suite/script）及第三方（见 §5） | 02–04、09–18 各节 |
tools/ | 游戏专用离线工具（NavMeshGenerator、AudMeshGenerator、HeightMapGenerator、MemoryHasher、DllInject 等） | standalone-tools-and-extra.md |
extra/ | PC 启动器 launcher、安装器、补丁器、DLC/补丁打包（NSIS 脚本）、语言切换器、Windows 错误报告分析器、protection | standalone-tools-and-extra.md |
projgen/ | 工程生成用的 MSBuild props/targets（cpp.props、psc.targets、unity.targets、RSG.xml） | build-and-config.md |
objects/ | 只有一个 projgen.prune | — |
4. src/dev_ng/game/ —— 游戏层#
游戏层源码按功能分目录；根目录的 game_config.h 集中定义跨系统容量常量（物理请求列表、活动实体上限、场景点/路口/交通灯上限、目标帧率等），并按 XENON_OR_PS3 区分旧世代与 NG 的数值 src/dev_ng/game/game_config.h:27-59；例如 NG 上 MAX_ACTIVE_ENTITIES 为 61440，DESIRED_FRAME_RATE 在 PC 为 60、主机为 30 src/dev_ng/game/game_config.h:34-42。optimisations.h 提供按目录开关优化的宏（见 build-and-config.md）。
| 目录 | 物理行数（C++） | 职责 | Wiki 页面 |
|---|---|---|---|
Core/ | 约 1.1 万 | 入口、CApp 状态机、CGame 系统装配、会话状态机、权利/加密狗 | 01-runtime |
system/ | 约 4.3 万 | 输入/控制映射、设置、平台服务、文件管理、任务调度、GPU 自动采集、反篡改动作 | 22-input-platform、23-debug-security |
scene/ | 约 11.5 万 | 世界与实体类层次、地图数据、LOD、室内/门户、场景流式、玩家切换 | 05-world |
modelinfo/ | 约 3.4 万 | 模型信息（archetype）类层次 | model-info.md |
streaming/ | 约 3.5 万 | 游戏侧流式封装 | game-streaming-and-scene-streamer.md |
Objects/ | 约 2 万 | 物件、门等 | world-and-entities.md |
Peds/、PedGroup/ | 约 21 万 | 行人、玩家、人口、变体 | 06-peds |
task/ | 约 70 万 | 任务（AI 行为）系统，最大的单一目录 | 07-ai-tasks |
event/、ai/、pathserver/ | 约 8.5 万 | 事件、AI 辅助、导航网格寻路服务 | 07-ai-tasks |
Vehicles/、vehicleAi/ | 约 29 万 | 载具、操控、损坏、车辆 AI、路网 | 08-vehicles |
physics/、cloth/ | 约 3.9 万 | 游戏物理胶水、布料 | 09-physics |
animation/、ik/、Cutscene/ | 约 12.5 万 | 动画、IK、过场动画 | 10-animation |
renderer/、shaders/、shader_source/、timecycle/ | 约 22 万 C++ + 11.5 万 HLSL | 渲染管线、着色器、时间周期 | 11-rendering |
vfx/ | 约 12.6 万 | 粒子、贴花、天空/云、各类视效系统 | 12-vfx |
audio/ | 约 23 万 | 游戏音频 | 13-audio |
script/、script_headers/ | 约 20 万 C++ + 7.8 万 .sch | 脚本运行时、原生命令（natives）、脚本头 | 14-script-runtime |
network/ | 约 34 万 | 联机：会话、对象同步、事件、云服务、商城、语音 | 16-network-online、17-network-sync |
frontend/、text/ | 约 23 万 | 暂停菜单、HUD、落地页、商店、视频编辑器、文本 | 18-frontend-ui |
SaveLoad/、SaveMigration/、Stats/ | 约 8.5 万 | 存档、存档迁移、统计 | 19-persistence-replay |
control/、replaycoordinator/ | 约 15 万 | 回放系统、视频录制、游戏逻辑杂项（车库、重生、特技跳、交通灯、录像） | replay-and-video.md、20-gameplay |
game/ | 约 4.5 万 | 时钟、天气、风、区域、通缉、犯罪、目击、调度、作弊 | 20-gameplay |
pickups/、apps/ | 约 1.5 万 | 拾取物、手机应用数据 | pickups-cheats-misc.md |
weapons/、camera/ | 约 17 万 | 武器、相机 | 21-weapons-camera |
debug/、performance/、tools/、security/ | 约 12 万 | 调试工具、性能、游戏内工具、安全（仅高层） | 23-debug-security |
VS_Project*/、vs_project*_lib/、vs_project_lib_psc/ | — | 生成的 VS 工程、unity 构建单元、PS3 SPU 作业/片段工程 | build-and-config.md |
templates/、utils/、test_ignore/ | < 0.2 万 | 通用模板与零散工具代码 | — |
多数游戏子目录带有 makefile.txt（RAGE 的工程生成输入）和 .psc（parser 反射模式，生成可序列化结构的元数据），见 parser-and-metadata.md。
5. src/dev_ng/rage/ —— RAGE 引擎#
RAGE 分为四个源码层和若干支持目录。包含方向基本是 base ← framework ← game（framework/src 中没有找到包含游戏目录的 #include），但 base 有少量反向依赖 framework 头的例外，例如 audiohardware/waveslot.cpp 包含 fwsys/timer.h src/dev_ng/rage/base/src/audiohardware/waveslot.cpp:11、paging/streamer.cpp 包含 fwmaths/random.h src/dev_ng/rage/base/src/paging/streamer.cpp:22、file/cachepartition.cpp 包含 fwutil/Gen9Settings.h src/dev_ng/rage/base/src/file/cachepartition.cpp:10，rline/durango/rlxbl_interface.h 包含 fwnet/nettypes.h src/dev_ng/rage/base/src/rline/durango/rlxbl_interface.h:14。因此 base 与 framework 实际上是一起编译链接的，而不是可独立发布的两层。
| 目录 | 内容 | Wiki 页面 |
|---|---|---|
base/src/ | 约 70 个模块：系统/诊断/参数（system、diag、bank、profile）、数据与反射（parser、parsercore、data、paging、file）、数学与容器（vectormath、math、atl）、图形（grcore、grmodel、rmcore、grpostfx、grshadowmap…）、物理（phcore、phbound、physics、pharticulated…）、动画（cranimation、crskeleton、creature…）、音频（audioengine、audiohardware、audiosynth…）、网络（net、rline）、输入、Scaleform 绑定、安全等 | 02、03、09、10、13、16、22、23 各节 |
framework/src/ | fw* 中间层：实体/archetype、场景图与可见性、流式引擎、计时器/FSM/配置、池、AI 任务基类、事件、网络对象（fwnet）、脚本基类（fwscript）、渲染与 drawlist（fwrenderer、fwdrawlist）、动画导演（fwanimation）、timecycle、vfx 等 | 04-rage-framework（并含归属索引） |
suite/src/ | 较高层的可复用组件：MoVE 动画网络（move、crmotiontree）、fragment 碎裂体、cloth、玻璃、绳索、粒子（rmptfx、gpuptfx）、草/树/光照、过场（cutscene、cutfile）、会话（snet）、Social Club（rgsc）、语音聊天（avchat）、遥测、bink 视频等 | 各相关节 |
script/ | 脚本虚拟机（src/script：program、thread、opcodes）、脚本 GUI/Scaleform 绑定，以及 SanScript 编译器与语言工具（tools/） | 14-script-runtime |
naturalmotion/ | NaturalMotion Euphoria 行为物理（库源码、行为文档、资产） | game-physics-and-ragdoll.md |
scaleform/ | Scaleform GFx 源码（Include、Src）及 RAGE forceinclude | scaleform-integration.md |
3rdparty/ | AMD、Arxan、breakpad/crashpad、curl、cyassl/wolfssl/OpenSSL、freetype、libjson、miniupnpc、NVidia、Oculus SDK、RenderDoc、Steam、Telemetry 等 | 本页；不单独分析 |
stlport/ | STLport 标准库实现 | 不单独分析 |
lib/ | 预编译库（bink2、breakpad） | 不单独分析 |
base/tools、framework/tools、suite/tools | 引擎工具链（RAG 远程调试界面、资源/动画/音频工具等，大部分为 C#） | rage-tools-and-rag.md |
rockon/ | C# Web 服务与工具 | standalone-tools-and-extra.md |
lint/、qa/、top/、contrib/ | PC-Lint 配置、QA 构建脚本与测试、引擎文档与样例入口、社区贡献代码 | 本页；QA 见 debug-tools.md |
各引擎层根目录下的 samples/、test/、doc//docs/ 是引擎自带样例与文档，不参与游戏构建；Wiki 只在需要佐证设计意图时引用。
6. script/dev_ng/ —— 游戏脚本#
| 目录 | 内容 | Wiki 页面 |
|---|---|---|
singleplayer/ | 单机脚本工程 GTA5_SP.scproj、scripts/（约 196 万行 .sc）与 include/（约 94 万行 .sch） | singleplayer-flow.md |
multiplayer/ | GTA Online 脚本：scripts/（约 151 万行 .sc + 179 万行 .sch）、include/（约 269 万行 .sch）、globals/ | multiplayer-freemode.md |
core/、shared/ | 公共脚本库、HUD/暂停菜单脚本 | shared-script-libraries.md |
Code/ | 程序员测试脚本（相机、战斗、载具、过场、物理性能等测试关卡） | shared-script-libraries.md |
BGNG/ | 后台脚本（BGScript/BGScript.scproj、公共头 Common_Bg_Headers/）以及把它们打包成 RPF 的 tools/CreateRPF.bat | script-tree-overview.md |
Tools/ | 脚本组的 C# 数据编辑工具（EmailStar、MarketStar、CarcolsEditor、mishstatstar 等）和编译批处理 | script-tree-overview.md |
| 根目录 | 编译器与辅助程序（sc.exe、scriptrc_x64.exe、scannative.exe、randomizenatives.exe）和枚举生成批处理 | script-compiler-and-toolchain.md |
7. tools_ng/ —— 工具链根#
| 目录 | 内容 | Wiki 页面 |
|---|---|---|
bin/ | 预编译工具与运行时：RAG、RageBuilderGen9、RPFViewer、StreamingVisualize、RockyProfiler、MoVE、ParticleEditor、内置 Python/Ruby/IronRuby 等 | tools-ng-overview.md |
etc/ | 配置：projgen/projgen9 工程生成规则、内容树、处理器、自动化、RAG 配置、骨架 .skel 等 | tools-ng-overview.md、build-and-config.md |
lib/ | Ruby 流水线库（pipeline、util、data） | asset-pipeline.md |
ironlib/ | IronRuby/.NET 流水线程序集（含 RSG.Pipeline.Convert.exe，见 src/dev_ng/Directory.Build.props:75） | asset-pipeline.md |
script/ | 构建/编码/音频/网络/统计等批处理与脚本，含 util/projGen9 | tools-ng-overview.md |
dcc/、wildwest/、techart/ | 3ds Max/MotionBuilder 插件与脚本、技术美术工具 | dcc-and-techart.md |
web/ | 内部 Web 服务与站点（dev/staging/prod/release） | dcc-and-techart.md |
packages/、p4/、data/、tmp/ | 安装包、Perforce 配置、少量数据与临时文件 | 本页 |
8. 未纳入快照的内容#
构建属性引用的 assets*、build/dev*、titleupdate/ 等根（RS_ASSETS、RS_BUILDBRANCH、RS_TITLE_UPDATE）src/dev_ng/Directory.Build.props:45-61，以及 RAGE_3RDPARTY 指向的 X:\3rdparty\dev src/dev_ng/Directory.Build.props:72，都不在快照中。因此运行时数据文件（.meta、.ymt、RPF 包等）的具体内容只能从解析代码与 .psc 模式推断。