albertovillaosorno/shar

# SHAR SHAR 是一个确定性的迁移 pipeline 和 Unreal Engine 5 重现工作区，旨在将合法的本地游戏原始副本重构为 干净、原生且可玩的项目。 该仓库包含第一方源代码、schema、manifest、转换 工具、验证规则、架构记录以及一个 Unreal 项目 shell。它 **不**包含或分发原始游戏、提取的游戏资产、 专有引擎源码、第三方音频、艺术作品、CG 动画、可执行文件 或替代内容。 用户需在 `game/` 目录下提供合法的本地安装。该 pipeline 旨在 解码该安装内容，规范化其内容，构建原生的 Unreal 资产，编译独立编写的 runtime，并生成本地 独立版本。 ## 目标 本项目有一个明确的边界目标：生成一个忠实、技术干净且 完全可玩的 Unreal 重构版本，该版本可从用户提供的 游戏安装中重建，并可通过本地 package 进行修改。 主要交付物包括： 1. 对每个所需源格式进行无损、fail-closed 解码； 2. 确定性的 manifest 和 package 身份标识； 3. 规范化的 FBX、媒体、本地化、UI、任务和游戏数据； 4. 无需手动编辑器组装即可生成的原生 Unreal 资产； 5. 独立编写的 C++ runtime 行为； 6. 轻量级 **Retro** 图形配置； 7. 忠实的高保真 **Ultra** 图形配置； 8. 通过文档化的 schema 和 AI-agent 技能支持的本地即插即用 mod； 9. 通过一个命令重建并打包 Windows 可执行文件；以及 10. 端到端验证、优化，并完成主要路线图。 本项目不包含单独的现代游戏模式、联网的 沙盒、多人游戏、服务器浏览器、托管的 mod 服务、社交层、 通用启动器或类似 Roblox 的编辑器。这些产品超出了 本仓库的范围。 ## 法律与项目边界 这是一个独立的互操作性和重构项目。它不 附属于、不受认可、不受赞助，也未经 原始游戏的发行商、开发商、授权方、平台持有者、Epic Games、NVIDIA 或 文档或兼容性目标中提到的任何其他第三方批准。 仓库拥有的材料根据 [`LICENSE`](LICENSE) 中的 MIT License 授权。MIT License 仅适用于仓库 所有者有权授权的材料。它不授予对原始 游戏、第三方资产、商标、专有软件、引擎 分发版、外部插件或用户提供的 mod 的权利。 用户需负责： - 获取并使用其自己的合法游戏副本； - 遵守管辖 Unreal Engine 和可选插件的条款； - 确定本地转换、修改、打包或 重新分发在其司法管辖区是否合法； - 保留所需的版权和许可证声明；以及 - 验证第三方 mod 的来源和可信度。 本仓库不下载原始游戏、验证所有权、 分发提取的有效载荷，或授予重新分发生成的版本的权限。 有关特定项目边界，请参阅 [互操作性 ADR](docs/adr/legal/reverse-engineering/educational-interoperability-and-user-responsibility.md)。 本文档不构成法律建议。 ## 工程模型 该 pipeline 是 fail-closed（失败即停止）、确定性且证据驱动的。 - 解码器要么生成一个有类型、经过计数检查的表示，要么报告 失败。不接受无声的字节丢失。 - 生成的身份标识、顺序、package 选择、输出名称和计划 在输入相同时必须保持稳定。 - 提取、分类、打包、转换、Unreal 导入和 runtime 行为保持独立的架构边界。 - Rust 负责编排、解析、manifest、确定性转换和 验证。 - C++ 负责 Unreal runtime。 - 仅在 Blender 或 Unreal 暴露出实质上更好的 原生集成边界时，才允许使用 Python。 - Blueprints 仍兼容用于内容检查和编写，但 C++ 和经过验证的数据仍是事实的最终来源。 - JSON 是一种中间审查和交换表示。当 Unreal 提供合适的原生资产类型时，它不是 最终的 runtime 格式。 - 直接拖放不是生产导入策略。资产 创建必须能从 manifest 和转换计划中重现。 代码库使用明确的领域、应用、port 和 adapter 边界。 共享的 CLI 和文件系统 crate 仅拥有稳定的机制；领域策略保留 在拥有该行为的 crate 内。 ## 当前状态 | 阶段 | 范围 | 状态 | | :--- | :--- | :--- | | 1 | 解码源格式并创建游戏 manifest | 完成 | | 2 | 生成次要单元 manifest | 完成 | | 3 | 将次要单元分类为确定性 package | 完成 | | 4 | 将模型 package 转换为二进制 FBX 7.7 | 进行中 | | 5 | 将规范化数据转换为原生 Unreal 资产 | 已计划 | | 6 | 实现完整的 Unreal runtime | 已计划 | | 7 | 验证 Retro 和 Ultra 图形配置 | 已计划 | | 8 | 添加即插即用 mod 和 AI-agent 技能 | 已计划 | | 9 | 打包完整的从路径到可执行文件的 pipeline | 已计划 | | 10 | 优化、验证、记录并关闭路线图 | 已计划 | 该表格描述的是当前的公开路线图，而非交付保证。 生成的计数可能会在测试其他合法源版本或 更严格的验证使之前接受的证据失效时发生变化。 ## 十阶段路线图 ### 阶段 1 — 解码所有必需的源格式 **状态：** 完成。 **执行结果：** 本地安装已从不透明的旧版 容器转换为有类型、可审计、确定性的源证据。下游 系统不再需要理解未记录的二进制布局。 已完成的工作： - [x] 创建简单的 `game/manifest.jsonl` 完整性契约，且不 发布原始文件名。 - [x] 将 RTF 文档解码为标准化的 Markdown。 - [x] 提取 LMLM/LSPA 档案并进行负载大小验证。 - [x] 提取 RCF 档案，并验证 header、名称、偏移量、对齐 和确定性的输出路径。 - [x] 将 RSD 音频转换为原生 PCM WAV，同时保留声道、采样 率和位深。 - [x] 将 RMV CG 动画转换为 HAP 视频 package，包含编号的 WAV 音轨、 探测元数据、解码报告、manifest 和时序账本。 - [x] 解码 P3D 几何体、基本体组、索引、位置、法线、 切线、副法线、UV 通道、颜色、矩阵调色板、权重、边界 和渲染元数据。 - [x] 解码 P3D 纹理并保留类型化纹理元数据和图像输出。 - [x] 解码场景图、复合绘图对象、实例图、渲染 引用、变换、可见性、附件、摄像机和排序顺序。 - [x] 解码碰撞、物理、地形、世界区块成员资格、基本体、 质量属性、惯性、所有权和关节元数据。 - [x] 解码骨架、关节、父子关系、静息变换、蒙皮、 控制器、动画组、通道、关键帧和顶点动画。 - [x] 将支持的 UI、字体、粒子和摘要族解码为类型化 表示，而不是通用的字节摘要。 - [x] 将 MFK 任务和游戏脚本解析为结构化 JSON。 - [x] 将 CON 车辆和游戏配置解析为结构化 JSON。 - [x] 将 Scrooby 的 PAG、SCR 和 PRJ 文件解析为结构化 UI 记录。 - [x] 将 CHO 编排和 rig-bank 文本解析为结构化记录。 - [x] 将 TextBible 和语言通道文件解析为标准化的本地化 记录。 - [x] 将 TYP 声音资源元数据解析为结构化 JSON。 - [x] 将 RADMusic RMS 元数据和 SPT 文本结构解码为确定性 中间记录。 - [x] 将日志、不支持的元数据和非运行时工件标记为明确的 禁止导入输入，而不是假装它们是游戏资产。 完成标准： - 接受的数组与其声明的计数相匹配； - 几何体、绑定、碰撞和动画没有静默的仅 header 成功路径； - 格式错误的数据会失败并停止； - 游戏完整性 manifest 保持确定性和公共安全；以及 - 提取的资产保留在本地并被 Git 忽略。 相关决定： - [无损提取契约](docs/adr/pipeline/extraction/lossless-extraction-contract.md) - [网格和蒙皮解码](docs/adr/pipeline/extraction/mesh-and-skin-geometry-decode.md) - [场景组装解码](docs/adr/pipeline/extraction/scene-assembly-decode.md) - [碰撞和世界解码](docs/adr/pipeline/extraction/collision-physics-and-world-chunk-decode.md) - [骨骼和运动解码](docs/adr/pipeline/extraction/rig-motion-decode.md) - [提取来源](docs/adr/pipeline/extraction/extraction-provenance-and-manifest-linkage.md) ### 阶段 2 — 生成次要单元 manifest **状态：** 完成。 **执行结果：** 每个规范化输出都成为一个类型化、可独立 审计的次要单元。该 manifest 是分类和打包的 结构性事实来源。 已完成的工作： - [x] 将解码后的 package 组件和规范化的松散文件暂存到 一个连贯的结构视图中。 - [x] 分配确定性、不透明、无名称的标识符。 - [x] 记录混淆的路由，这些路由在不暴露 源名称的情况下保留了有用的结构。 - [x] 记录源块种类、源块序号、扩展名、来源 和恢复状态。 - [x] 使用 `snake_case` JSON 字段和 `kebab-case` 领域值定义受控的分类法值。 - [x] 按类型、子类型、种类、功能、来源、 schema 和预期的规范化目标对支持的单元进行分类。 - [x] 拒绝原始的、仅包含元数据的、不支持的或错误恢复的行作为 成功的运行时单元。 - [x] 审计生成的 manifest，直到没有任何接受的单元被 错误哨兵分类。 - [x] 将内容哈希和真实游戏名称排除在公共分类 账本之外。 完成标准： - 每个接受的次要单元都已完全解码； - 每条记录都符合版本化的分类法； - manifest 顺序是稳定的； - 源名称仍然保密；以及 - 没有后续转换器需要重新发现提取的内部细节。 ### 阶段 3 — 将次要单元组织到 package 中 **状态：** 对于当前的证据集已完成。 **执行结果：** 孤立的记录被组合成确定性的实体 package，下游工具无需路径猜测或手动 管理即可使用。 已完成的工作： - [x] 从次要单元记录构建生成的 package 索引。 - [x] 为每个接受的 package 分配一个受控的类别和子类别。 - [x] 保留成员、成员角色、源类型、块类型和稳定的 package 标识符。 - [x] 通过精确的标识符、类别或子类别前缀解析 package。 - [x] 为 FBX 模型、Unreal 原生数据、媒体、UI、音频、 世界和禁止导入的元数据定义类型化计划。 - [x] 消除成功的占位符标签和错误 package 标识符。 - [x] 验证当前生成的证据集，包含 2,964 个 package 且没有错误 package 行。 完成标准： - 每个接受的次要单元都属于正确的 package 或明确的 禁止导入 package； - package 身份和成员顺序是确定性的；以及 - package 读取器不依赖于原始路径；以及 - 计划者使用类型化的 package 记录，而不是临时的 JSON。 相关决定： - [Unreal manifest 和 package 分类法](docs/adr/pipeline/unreal/unreal-manifest-and-package-taxonomy.md) - [原生资产转换](docs/adr/pipeline/unreal/native-asset-translation-and-no-copy-paste.md) ### 阶段 4 — 将模型 package 转换为二进制 FBX 7.7 **状态：** 进行中。 **执行结果：** 每个类似模型的 package 都会收到一个干净的、 通用的交换工件，该工件可以在项目外部检查 并导入到 Unreal 中，而不会将旧格式债务带入 runtime。 已完成的边界工作： - [x] 使二进制 FBX 7.7 成为规范的 FBX 生产表示。 - [x] 从生成的 package 索引中选择源 package。 - [x] 生成确定性的输出身份和能力报告。 - [x] 在 FBX 工件中嵌入引用的 PNG 纹理。 - [x] 实现类型化的场景、几何体、材质、纹理、骨架、蒙皮、 动画、时序、摄像机和变换领域。 - [x] 为角色、车辆、道具和地形定义 package 配置。 - [x] 保留作者编写的网格分区，而不是强行合并 不相关的几何岛。 - [x] 提供可选的 Blender 审查和 Maya 导入助手，但不让 任何一个应用程序成为事实的来源。 - [x] 完成角色 FBX package 通道，涵盖几何体、材质、纹理 引用、骨架、蒙皮簇和原生动画曲线。 - [x] 在 Blender 5.1 和 Maya 2027 中验证相同的规范角色 FBX 7.7 工件，无需备用场景序列化或手动骨骼。  角色写入通道已完成。代表性的验收测试 确认了几何体、材质、嵌入式纹理、作者编写的网格分区、 骨架层级、蒙皮、原生动画曲线、源速率时序和 在两个应用程序中的动画姿态。Blender 和 Maya 仍然是审查 adapter； 规范工件仍然是二进制 FBX 7.7。 下一个角色里程碑是在 `fbx-assets/characters/` 下生成确定性目录：每个角色 package 对应一个独立的 FBX 文件， 直接存储在该目录中，外加一个描述每个结果的 manifest。 该目录是本地生成的证据，并被 Git 忽略。 剩余工作： - [ ] 在 `fbx-assets/characters/` 下生成完整的角色目录及其确定性 manifest 。 - [ ] 完成道具 FBX 覆盖。 - [ ] 完成车辆 FBX 覆盖。 - [ ] 完成地形和世界地块 FBX 覆盖。 - [ ] 完成剩余的动态对象、摄像机和特效 FBX 覆盖。 - [ ] 证明在 package 索引中材质槽、纹理、坐标系、缩放、轴心点、骨架、 蒙皮权重和动画时间的一致性。 - [ ] 拒绝那些声称支持模型但缺少所需 能力的 package。 - [ ] 为每个生成的 FBX 文件生成确定性一致性报告。 - [ ] 在无需未记录的场景修复的情况下验证干净的 Unreal 导入。 完成标准： - 每个类似模型的 package 都有一个有效的二进制 FBX 7.7 工件或明确的、 合理的非 FBX 路线； - 没有 package 依赖于硬编码的本地路径； - 没有 ASCII FBX、DAE、MA 或 MB 输出成为规范的；以及 - 在格式边界内，重复转换保持确定性。 相关决定： - [FBX 输出契约](docs/adr/fbx/export/fbx-output-contract-boundary.md) - [网格基本体边界](docs/adr/fbx/geometry/mesh-primitive-boundary.md) - [材质分配边界](docs/adr/fbx/materials/material-assignment-boundary.md) - [蒙皮附加边界](docs/adr/fbx/skeletons/skin-attachment-boundary.md) - [FBX 输出检查](docs/adr/fbx/validation/output-checks.md) ### 阶段 5 — 将规范化数据转换为原生 Unreal 资产 **状态：** 已计划。 **执行结果：** JSON、FBX、WAV、HAP 视频、图像和 package 元数据 通过确定性导入代码成为原生 Unreal 资产，而不是 手动编辑器工作。 计划工作： - [ ] 从不透明的 package 标识符生成提交的、公共安全的 Unreal 导入 manifest。 - [ ] 将 FBX 文件导入为 Static Mesh、Skeletal Mesh、Skeleton、Physics Asset、Animation Sequence、材质、纹理和摄像机。 - [ ] 将 WAV 文件导入为 Sound Wave 并构建原生声音元数据和 路由表。 - [ ] 将 HAP 视频和编号的音轨导入为同步媒体资产。 - [ ] 将本地化记录转换为 String Table 和语言资产。 - [ ] 将任务、车辆、游戏、UI、收藏品和调整记录 转换为 Data Table、Data Asset、State Tree 或专门构建的原生资产。 - [ ] 将从 Scrooby 派生的 UI 记录转换为 UMG 资产或经过验证的原生 UI 描述。 - [ ] 将世界 package 转换为 World Partition 单元、Data Layer、流送 资产、碰撞数据和作者编写的组装记录。 - [ ] 保留导入来源和确定性的 Unreal 对象身份。 - [ ] 使整个导入过程可以从干净的项目状态重复进行。 完成标准： - 每个接受的 package 都解析为原生 Unreal 目标或明确的 禁止导入结果； - 删除生成的资产并重新运行导入器可重现相同的 逻辑项目状态； - 失败会识别出 package、成员、不变量和纠正措施；以及 - 没有生产资产需要未记录的仅限编辑器修复。 ### 阶段 6 — 实现完整的 Unreal runtime **状态：** 已计划。存在以 C++ 为主 Unreal 项目 shell 和构建目标； 但完整的游戏行为尚不存在。 **执行结果：** 独立编写的 runtime 可以使用阶段 5 生成的资产从头到尾 完整地游玩整个游戏。 计划工作： - [ ] 实现启动、存档数据、配置、设置、加载、暂停和 进度。 - [ ] 实现玩家移动、摄像机行为、交互、车辆、 交通、行人、碰撞、伤害和恢复。 - [ ] 实现任务、目标、触发器、对话、奖励、收藏品、 搞笑动作、比赛和进度门。 - [ ] 实现 HUD、雷达、导航、菜单、字幕、本地化、音频、 CG 动画和辅助功能设置。 - [ ] 通过原生 Unreal 系统实现世界流送、actor 放置、物理、动画、特效 和平台输入。 - [ ] 通过稳定的 port 绑定生成的资产，而不是直接的路径 假设。 - [ ] 为可观察的游戏行为和状态转换添加一致性测试。 - [ ] 将所有第三方专有 runtime 实现保留在受追踪的 仓库内容之外。 完成标准： - 完整的游戏可以从头到尾游玩； - 没有已知的阻碍进度缺陷； - runtime 行为由经过验证的数据和第一方 C++ 驱动； - 存档/读取和重启行为是确定性的；以及 - Unreal 项目在没有未追踪的专有依赖项的情况下构建。 相关决定： - [Runtime 一致性边界](docs/adr/unreal/runtime/remake-parity-boundary.md) - [Runtime 一致性测试](docs/adr/unreal/runtime/runtime-parity-test-boundary.md) - [六边形 Runtime](docs/adr/unreal/architecture/hexagonal-runtime-and-no-technical-debt.md) ### 阶段 7 — 验证 Retro 和 Ultra 图形配置 **状态：** 已计划。 **执行结果：** 一个游戏实现支持两种渲染 配置，而无需创建第二种模式或更改任务、物理、时序 或进度语义。 #### Retro 配置 Retro 配置是项目的低成本配置。它应该保留 原始的视觉语言，同时使用干净的 Unreal 实现。 - [ ] 定位适合较低端受支持 PC 的轻量级渲染。 - [ ] 使用克制的材质、阴影、后处理、特效和绘制 距离，与后主机时代的表现相一致。 - [ ] 保留可读的轮廓、颜色、UI 和关卡标识。 - [ ] 避免使用那些不能实质性地改善忠实 呈现的昂贵功能。 - [ ] 验证降低的设置不会移除与游戏相关的几何体、 特效、导航提示或碰撞。 #### Ultra 配置 Ultra 配置在不重新设计游戏的情况下提高渲染保真度。 - [ ] 使用高质量材质、纹理过滤、阴影、反射、 特效、抗锯齿和可视距离。 - [ ] 在 Unreal 和目标硬件提供稳定实现的情况下，支持可选的硬件光线追踪 。 - [ ] 当生产就绪的 Unreal 插件和许可证兼容的分发路径 可用时，以官方 NVIDIA DLSS 5 集成的兼容性为目标。 - [ ] 保持 DLSS、帧生成、光线追踪和神经渲染为可选。 - [ ] 保留原始的艺术方向，并提供原生分辨率或 Unreal TSR 后备方案。 - [ ] 当某项增强改变了角色身份、任务 可读性、游戏时序、碰撞感知或作者编写的构图时，拒绝该增强。 完成标准： - Retro 和 Ultra 使用相同的游戏数据和 runtime 代码； - 图形设置不影响确定性模拟行为； - 不支持的供应商功能优雅地失败； - 视觉对比捕获是可重现的；以及 - 为代表性场景记录性能预算。 相关决定： - [Retro 和 Ultra 图形配置](docs/adr/unreal/runtime/retro-and-ultra-graphics-profiles.md) ### 阶段 8 — 添加即插即用 mod 和 AI-agent 技能 **状态：** 已计划。 **执行结果：** 用户可以将一个经过验证的 package 放在 `mods/` 目录下，以 替换或扩展支持的游戏数据，并且 AI 编程 agent 可以通过遵循仓库拥有的技能和 schema 来创建该 package。 本项目提供的是契约，而不是托管平台。不需要 服务器、帐户、市场、专用图形编辑器或专有 AI 服务。 计划工作： - [ ] 定义确定性的 mod package 身份、优先级、依赖关系、 兼容性、取代和冲突规则。 - [ ] 支持对模型、纹理、材质、 动画、任务、本地化、UI、音频、CG 动画、调整和其他 明确建模的资产系列进行替换和添加。 - [ ] 从本地 `mods/` 目录加载支持的数据和资产 package。 - [ ] 将原生代码 mod 保留在明确的信任边界之后，因为仅靠文件验证无法安全地沙盒化原生 代码。 - [ ] 在激活之前验证 schema、引用、package 拓扑、资产兼容性、 版本约束和确定性的加载顺序。 - [ ] 提供预览和试运行命令，准确显示 mod 更改的内容。 - [ ] 为具备终端能力的 AI agent 编写实用的 `skills/` 指令。 - [ ] 让 agent 将自然语言请求转换为所需的资产、 任务逻辑、package 更改、验证证据和可审查的预览。 - [ ] 要求 agent 请求缺失的许可资产，或仅生成 用户有权创建的内容。 - [ ] 在替换现有的本地内容或 启用受信任的原生代码之前，要求明确的用户批准。 典型的 agent 工作流程是： 1. 用户用普通语言描述任务或资产更改； 2. agent 识别所需的模型、动画、声音、规则和权限； 3. agent 请求缺失的输入或提供合法的原始占位符； 4. agent 生成任务和 package 数据； 5. agent 验证引用、加载顺序、游戏流程和性能； 6. agent 呈现预览并询问结果是否可接受；以及 7. 批准后，package 被安装在 `mods/` 下。 完成标准： - 非程序员能够使用 agent 和仓库技能生成有效的 mod； - 相同的工作流程仍可通过文档化的文件和 CLI 手动使用； - 无效的 package 在 runtime 激活前失败； - 加载顺序和取代是确定性的；以及 - 本项目不声明任意的第三方原生代码是安全的。 相关决定： - [即插即用 mod package 和 AI 技能](docs/adr/modding/drop-in-mod-packages-and-ai-skills.md) ### 阶段 9 — 打包完整的从路径到可执行文件的 pipeline **状态：** 已计划。 **执行结果：** 用户选择合法游戏安装的路径，然后 pipeline 执行提取、规范化、打包、转换、Unreal 导入、编译和本地打包，无需未记录的手动步骤。 目标命令： ``` pipeline full --game ``` 计划工作： - [ ] 检测并验证源安装。 - [ ] 按依赖顺序运行阶段 1 到 5。 - [ ] 确定性地创建或更新 Unreal 项目。 - [ ] 编译阶段 6 的 runtime。 - [ ] 应用选定的阶段 7 图形默认设置。 - [ ] 安装阶段 8 的本地 mod 目录和 schema。 - [ ] 中断后安全恢复，不接收陈旧的部分输出。 - [ ] 报告进度、警告、失败、来源和最终工件路径。 - [ ] 打包本地的 Windows 可执行文件和所需的 runtime 文件。 - [ ] 验证打包的版本在编辑器之外启动。 #### 所需的外部安装 打包目标是有意保持小巧的，但 C++ Unreal 项目不能 凭空构建。用户必须提供： - 受追踪的项目描述符所选择的 Unreal Engine 版本； - 该 Unreal 安装支持的 C++ 编译器和 Windows SDK；以及 - 打包版本所需的任何 Epic 提供的先决条件。 #### 可选的外部安装 - 当官方 NVIDIA Unreal 或 Streamline 插件可用且被选中作为 DLSS 兼容性目标时，可能是必需的。 - Blender 是可选的审查 adapter，而不是规范的 FBX 生成器。 - 不捆绑任何第三方游戏资产或替代内容包。 在许可和平台政策允许的情况下，pipeline 应管理由仓库固定版本的 Rust、Python、FFmpeg 和其他 便携式依赖项。它绝不能 静默下载专有游戏内容或代表 用户接受外部许可证。 完成标准： - 干净且受支持的工作站可以从一个源 路径和文档化的先决条件中生成打包的版本； - 所有中间阶段都是可恢复和内容寻址的； - 最终报告标识每个外部依赖项和生成的工件； - 失败绝不会留下误导性的成功标记；以及 - 没有私有的本地路径或源名称进入受追踪的公共输出。 ### 阶段 10 — 优化、验证、记录并关闭路线图 **状态：** 已计划。 **执行结果：** 游戏和 pipeline 被视为已完成的工件， 而不是永久的开发路线图。 最终清单： - [ ] 完成从头到尾的完整游戏流程，没有已知的 阻碍进度缺陷。 - [ ] 验证每个任务、关卡转换、车辆、收藏品、CG 动画、 存档点、本地化路径和结局。 - [ ] 分析 CPU、GPU、内存、存储、shader 编译、加载、流送 和 package 生成成本。 - [ ] 移除可避免的技术债务、不确定性、重复、死代码、 未记录的变通方法以及不支持的兼容桥接。 - [ ] 在代表性的受支持硬件上验证 Retro 性能和 Ultra 视觉正确性 。 - [ ] 从干净的源安装中重建，并比较确定性 manifest、package、报告和逻辑 Unreal 输出。 - [ ] 创建具有代表性的 mod，替换模型、纹理、任务、 本地化条目、UI 元素、音频资产和游戏规则。 - [ ] 验证 AI 编程 agent 能够根据发布的 技能创建和验证 mod，而无需私有的仓库知识。 - [ ] 诚实地记录已知的限制。 - [ ] 在最终验证后记录并发布完整的游戏视频链接。 - [ ] 在不使用缓存的情况下运行规范的全局验证。 - [ ] 标记已完成的主要路线图。 在阶段 10 之后，仓库可以保持公开和活跃，但不承诺任何维护 计划、响应时间、问题分类、兼容性窗口或未来功能 工作。可重现的缺陷可由所有者自行决定是否修复。 问题可能仍然无人回答，仓库可能随时被归档。 MIT License 允许其他人根据其条款检查、下载、复刻、修改和维护 仓库拥有的代码。 相关决定： - [十阶段交付路线图](docs/adr/pipeline/ten-phase-remake-delivery-roadmap.md) ## 仓库布局 ``` game/ User-supplied lawful source installation. Ignored by Git, except for the tracked obfuscated completeness manifest. assets/ Local legacy and staged assets. Ignored by Git. cache/ Local generated state. Ignored by Git. dependencies/ Repository-managed toolchains and portable dependencies. docs/adr/ Architecture decision records. docs/bibliography/ Public references and third-party notices. extracted/ Local decoded and classified output. Ignored where required. skills/ Planned practical instructions for mod authors and AI agents. src/ Rust crates, Unreal adapters, and the C++ Unreal project. temp/ Validation caches, reports, and review output. Ignored by Git. validate.sh Canonical repository validation entry point. ``` 根 Rust workspace 目前包含专注于共享 CLI 和 文件系统机制的 crate，以及 pipeline、game-manifest 处理、FBX 导出、LMLM、 P3D、RCF、RSD、RMV、RTF 和 Unreal 集成。 ## 游戏输入 在 `game/` 下放置合法的本地副本。该目录被 Git 忽略，除了 `game/manifest.jsonl`，它记录了每个文件夹的混淆后的最小计数。 不会发布真实的源文件名。 混淆后的 manifest 行示例： ``` {"dir":"ss/ms","ext":"mfk","min":2} ``` 该行意味着一个被混淆的文件夹路径至少需要两个 `.mfk` 文件。 它不会发布原始目录或文件名。 完整性命令为： ``` cargo run -p game-manifest --bin generate-manifest cargo run -p game-manifest --bin validate-game ``` ### 可选的拉美西班牙语输入 用户可以在本地提供受支持的拉美西班牙语 mod，如下所示： ``` game/jebano_latino_mod.lmlm ``` 该文件是可选的。本仓库不分发它。缺少该文件绝不能 阻止基础安装的验证或构建。 ## 验证 从仓库根目录运行规范验证器。不要用直接的 格式化程序、编译器、linter 或测试命令代替最终证据。 ``` # 验证完整的 repository。 bash validate.sh # 验证一个 path 及其下的每个 child。 bash validate.sh src/fbx/ # 强制确定性 diagnostic 排序。 bash validate.sh --deterministic # 在不重用 cache 的情况下证明当前 state。 bash validate.sh --no-cache # 为一个 scope 替换成功的 cache 记录。 bash validate.sh --refresh-cache src/pipeline/ ``` 成功的门控记录是内容寻址的，并存储在被忽略的本地 表面下。失败、中断、部分或陈旧的运行绝不能被缓存为 成功。缓存命中保持可见，并且必须在相关的字节、 配置、工具、策略、环境或工具链版本发生更改时失效。 ## 资产和保密政策 请勿提交： - 原始游戏或任何提取的有效载荷； - 本地启动器或游戏安装； - 专有引擎材料； - 第三方替换模型、纹理、声音、音频或 CG 动画； - 生成的 Unreal 二进制文件、导入的资产、缓存或派生数据； - 私有证据路径、特定于计算机的路径、凭据或 token；或 - 本地审查导出和临时报告。 受追踪的测试必须使用独立编写的、合成的或以其他方式合法 可分发的 fixture。 ## 许可证 仓库拥有的原创材料受 [`LICENSE`](LICENSE) 中的 MIT License 约束。第三方名称、软件、游戏数据、艺术作品、音频、 引擎材料、插件和文档仍受其各自 所有者条款的管辖，本仓库不会对其重新授权。 ## 附录 — 公共代码、自动化分析与工程责任 ### 公开可用性与法律许可是不同的概念 公共仓库在技术上可供人类和自动化系统 检索、索引、分析和转换。这一可观察到的事实并不能抹除 版权、合同、隐私、商标、出口管制或平台规则。 同样，抽象的合法权利也不能使公共字节序列在 物理上变得不可发现。专业的工程要求同时承认 这两个现实。 对于仓库拥有的材料，所有者明确允许根据 MIT License 使用，并且不反对合法的自动检索、索引、 分析、代码搜索、模型训练或代码生成。该声明不 授予所有者不具备的权利，不重新授权第三方 材料，不放弃署名或许可条件，也不为 规避访问控制或滥用个人数据提供借口。 因此，适用规则很简单：机器可以读取公共代码，其 程度与人类合法阅读的程度相同，并且输出仍受 相同的来源、许可、安全和正确性义务的约束。 ### 字节序列的作者不是正确性的论据 代码是由人键入的、由生成器发出的、由模型合成的，还是 通过这些方法的混合产生的，都不能证明 结果是正确的。作者身份不能证明内存安全性、确定性、 可维护性、合法来源或适用性。 生成的代码不会免于审查。人类代码也不会被认为 具有优越性。两者都必须满足相同的契约： - 明确的所有权和依赖方向； - 所需的确定性行为； - 有界的资源使用； - 完整的错误处理； - 可测试的不变量； - 合法的来源； - 规范的验证；以及 - 可理解的维护边界。 编译器不评估真诚。runtime 不奖励努力。 经过一周仔细手动键入的缺陷仍然是缺陷，而正确的 实现不会因为工具产生了 初稿而变得有缺陷。 ### 代码可能具有美学价值，但美学不能凌驾于工程之上 软件可以包含优雅、创造力和文化价值。这些 品质都不能暂停其操作义务。在本仓库中，将 代码描述为艺术绝不能作为 不确定性、隐藏状态、不安全的内存行为、无法验证的抽象或可避免的复杂性的辩护理由。 不禁止面向对象。禁止的是不合理的间接。澄清 所有权和不变量的类层次结构可能是有用的；隐藏 数据移动、生命周期、分配或控制流的层次结构是技术 债务。同样的规则适用于函数式、面向数据、元编程和 AI 生成的代码。范式标签不能成为糟糕边界的借口。 软件烂泥的真正形式不是机器创作。它是行为、 所有权、失败模式和成本无法解释或验证的代码。 ### 论技术卢德分子 仅仅因为自动化减少了手动键入而拒绝自动化的技术卢德分子 是在捍卫一种劳动仪式，而不是工程原则。当 怀疑论识别出具体的失败模式时，它是有价值的：虚构的行为、 许可证污染、安全缺陷、依赖风险、不确定性 输出或人类控制的丧失。当怀疑论不提供可测试的 主张并将工具的存在视为缺陷时，它就变成了阻碍。 现代工程师不仅仅是打字员。工程师定义契约， 选择数据模型，建立信任边界，约束工具， 审查结果，衡量系统，并对发布的内容负责。 委派机械工作并不委派责任。 ### 持久性、死亡和有用的视野 人是暂时的。公共技术工作可以比其作者活得更久，被 陌生人复刻，被机器理解，并获得编写时 未曾预料到的用途。这不是假装所有权消失的理由；这 是编写清晰许可证、稳定的 schema、确定性工具和 诚实边界的理由。 人类可能会到达火星。本仓库有一个更近、更可衡量的 视野：将合法的本地安装转换为正确的可执行文件，保留 游戏的身份，使结果可修改，记录过程，并在 工程契约完成后停止。 ### 无担保且无永久服务义务 公共可用性不是服务级别协议。该仓库 受 MIT License 中的免责声明约束提供。自动化系统、 mod 作者、下游维护者和最终用户必须独立验证 其使用情况。所有者不承诺持续维护、与 未来工具链的兼容性、审查每个问题、接受外部补丁或 以未归档状态保留仓库。 持久的工件是获得许可的源代码及其记录的契约，而不是 其原始作者将永远可用的承诺。

标签：C++, Homebrew安装, Mod支持, 二进制格式工具, 可视化界面, 数据擦除, 游戏开发, 游戏重制, 虚幻引擎5, 资产管线, 运行时重实现, 逆向工具, 通知系统