构建、平台资源、发布与兼容性
1. 主链路及产物职责#
源码编译、平台资源化和打包是不同阶段。.sco 导出 ZIP 与平台资源 RPF 是批处理中的两条相关输出路径，不宜误写成“先 ZIP 再从 ZIP 编译脚本”。本文没有执行任何构建阶段。[S1][S2]
2. 工程配置本身是语言环境#
SP 工程声明 SanScript，指向 sc.exe 和 scriptrc_x64.exe，包含 Win64、PS4、XboxOne、PS5、XBSX 平台与 DEBUG、PROFILE、RELEASE 等配置。原始路径使用 X:\gta5\...，当前工作副本在 D 盘，不能把工具存在理解成已具备运行条件。[S1]
关键选项：
| 选项 | 作用 | 分类 |
|---|---|---|
-include、-ipath | 自动前置包含及查找路径 | 影响源码可见内容 |
-PlatformName | 平台条件编译 | 影响语义与产物 |
-shortcircuit | 改变 AND/OR 求值 | 语言语义选项 |
-strictreferencetypechecking | 严格引用参数检查 | 类型规则选项 |
-final | Final 条件及调试调用裁剪 | 产物和可观察行为 |
-forcename | Final 下仍保留过程名 | 可观测性；PROFILE 配置可见 |
-nodebug | 不生成调试文件 | 元数据选项；不同于 final |
-depfile | 输出依赖 | 增量构建 |
-dis、-dis_file | 反汇编输出 | 分析能力，本次未运行 |
-nodeHeapSize、-stringHeapSize | 编译器工作存储上限 | 离线内存，不是游戏预算 |
本报告中所有“当前项目语义”都应与这些配置一起理解。建议新语言把会改变语义的项目设置纳入模块版本或可复现构建标识，而非当成不显眼的优化开关。
3. 编辑器如何组织编译#
SanScriptCompilingSettings 拼接源码编译命令、include、依赖、Native 输出及自定义参数，也枚举 .sco/.scd 和平台输出文件。SanScriptProjectResolver 根据源文件、依赖和工具的修改时间等信息判断是否需要重新编译/资源化；通用 Compiler.cs 执行任务并解析错误格式。[S3]
这是有工程意识的专用工具链，并非只能手工调用单文件 compiler。但从时间戳增量判断不能推出内容寻址缓存、远程可复现构建或跨版本缓存绝对安全；配置变化、包含图变化和生成代码都需要被正确纳入依赖。
共享工具目录还保留 IncrediBuild、CruiseControl 和脚本头生成/扫描工具。它们说明编译和 API 维护有自动化基础，不代表本机可运行完整内部流水线。
4. .sco 对象格式#
program.cpp 的 Header 记录魔数/格式版本、全局哈希、压缩大小、加密相关标志、代码大小、静态/全局槽数、启动参数槽数、Native 数量、字符串大小与全局块号。当前魔数使用 SCR 和版本 12。[S4]
代码、字符串、Native 标识、静态初值与全局初值组成压缩数据；使用 zlib，按条件处理加密。Native 标识为 64 位，静态/全局初始元素以 32 位写入；64 位资源转换/装载再扩展到 scrValue 槽。格式里同时存在不同端序处理，不能按当前 CPU 内存布局直接读写。[S4]
Native 表保存时可随机重排并修补 NATIVE 索引。因此直接对两个构建产物做字节级比较可能包含布局变化，语义比较应反汇编/规范化表引用。这是对可复现构建的限制，不是性能结论。
压缩、加密、标识扰动服务于资源与保护需求；它们不等价于完整字节码验证、可信来源证明或安全沙箱。
5. scriptrc 与平台化#
scriptrc.cpp 根据输出扩展名设置目标平台及字节交换，加载 .sco，通过 pgRscBuilder 多 pass 建立资源，再以 scrProgram::RORC_VERSION 保存。[S5]
发布批处理中的前缀映射：
| 平台 | 前缀 / 脚本扩展名 | 输出平台目录 |
|---|---|---|
| Win64 | y / .ysc | x64 |
| PS4 | o / .osc | ps4 |
| XboxOne | d / .dsc | xboxone |
| PS5 | p / .psc | ps5 |
| XBSX | z / .zsc | xbsx |
这里 PS5 的 .psc 是平台脚本资源扩展名，与原生工程中作为元数据代码生成输入的 .psc 同名但职责不同。批处理还保留旧主机分支，不能据此判断所有分支均在当前产线上使用。[S2]
6. 兼容性并非一个版本号#
至少有六个需要一致的契约：源码语言/编译选项、opcode 编码、Native 标识与参数 ABI、GLOBALS 槽位布局、调试映射、网络/存档数据 schema。
全局哈希由初始槽值计算，具有一致性检查用途；它不是包含字段名、完整类型和语义版本的强 schema 标识。仅交换两个初始值相同的字段可能不能被这种哈希表达，故不能视为完整结构兼容证明。[S6]
调试器会拒绝旧版或不匹配的 .scd。资源可重新装载也不等于运行中替换代码后自动迁移 PC、栈和资源引用；本次未确认完整保状态热重载协议。
7. 对新工具链的建议#
把 Native API schema 作为声明、包装器、文档和兼容测试的单一来源；以代码/依赖/语义选项内容哈希作为构建标识。资源中记录 ABI 与模块版本，调试信息绑定确切代码哈希。
从早期就区分“重新启动脚本”“替换下一次实例”“迁移当前运行状态”三种更新能力，分别定义验收条件。优先实现可重复产物、可定位错误、可靠增量编译，再按实际需求加入远程构建和跨平台资源转换。
源码证据#
- S1 — GTA5_SP.scproj。
- S2 — CompileReleaseScriptImg.bat。
- S3 — SanScriptEditorSettings.cs：命令构造；SanScriptProjectResolver.cs：依赖时间。
- S4 — Header 与 Load；Save。
- S5 — scriptrc.cpp::Main。
- S6 — CalculateGlobalHash。