skate-3-rust-engine 是一个基于 Skate 3 逆向研究、用 Rust + Bevy 重写的滑板游戏引擎。本文是一份面向新手的 Skate 3 资产转换指南：教你如何用一键式的 setup 向导，把 Xbox 360 版 Skate 3 的 ISO 光盘镜像（或已解压的游戏目录）自动转换成 skate3rust 可直接加载的地图、角色、音频等数据，无需安装 Blender、Python 或 Rust 环境。

准备工作：开始转换前需要这4样东西

⚠️ 重要：data文件夹必须与default.xex（或 ISO）保持相邻。游戏资产不随仓库分发，一切以你自己合法拥有的光盘数据为准。

如果选择 ISO 方式，注意为data目录预留足够的磁盘空间——首次转换需要完整解包整个光盘。

一键转换步骤：从ISO到可玩数据只需3步

整个转换由内置的 setup 向导自动完成，核心入口逻辑见 tools/setup.py。

第 1 步：解压并启动解压 Windows 发行版 ZIP，直接运行skate3rust.exe。首次启动会弹出“Skate 3 Rust Engine setup”设置窗口。

第 2 步：选择游戏来源点击“Select ISO or default.xex”，浏览到你的 Skate 3.iso文件，或已解压目录中的default.xex。如果之前转换过，更新时会优先复用上次记录的来源，免去重复选择。

第 3 步：等待“Setup complete”窗口会实时显示进度（如“Extracting your ISO”“Converting 10 maps”）。完成后显示Ready；若有部分可选组件不可用，会提示“N warnings”，详情写入setup-report.json。

setup 转换流程背后做了什么

很多人好奇“一键”背后跑了什么。安装主流程在 tools/asset_pipeline/install.py，大致分为几个阶段：

1. ISO 提取：自动下载并校验extract-xiso工具，按-x -d <目录> <iso>的顺序解包出default.xex和data目录。参数顺序曾是个大坑——工具在遇到第一个镜像路径后就停止解析选项，顺序写错会把-d当成第二个 ISO，最终报open error: -d No such file or directory。相关修复记录见 docs/hails-additions/01-iso-extraction.md。
2. 来源校验：确认default.xex、data/big/miscload.big、data/big/db.big等关键文件齐全，并计算default.xex的指纹，防止混用不同游戏版本。
3. 资产分组转换：按core（滑手/输入/动画）、hud、character（角色定制器）、environment、audio、maps六组流水线处理，各自独立指纹、独立校验。
4. 地图并行转换：光盘里 10 个worldDIST_*.big城区档案会分配给多个 worker 并行处理（默认最多 3 个），每转完一张就立即用skate3rust --validate-maps校验，产出的就是引擎可读的.skate地图文件（仓库自带一张原创演示地图 maps/format-demo.skate 可参考格式）。性能优化细节见 docs/hails-additions/08-setup-performance.md。
5. 角色定制器：会尝试与地图转换并行跑，多核机器上全量 setup 可快约三成。

转换后的数据放在哪里

所有转换结果都留在可执行文件旁边的data文件夹里：

• data/installations/<32位ID>/—— 本次安装目录，由 installation.json 记录当前版本；
• maps.json—— 地图清单；settings/default-map.json—— 默认地图（通常是 University）；
• setup-report.json、setup.log—— 转换报告与日志，排查问题先看这里。

每次更新会生成新的安装 ID，旧目录在新安装成功后才清理；未变化的地图和角色套装直接复用（硬链接），不重复转换。

常见转换错误与快速排查

另外，若从快捷方式/启动器直接拉起且控制台管道已失效，setup 会静默丢弃进度打印而继续转换（历史 issue #20 的修复，见 tools/setup.py#L15-L36），不会因此中断。

转换完成后：开始滑板

• 发行版直接运行skate3rust.exe，默认进入 University，按Esc可切换地图、难度和图形设置，游戏内换图无需重启；
• 源码构建则运行 PLAY.bat 启动测试世界，拖一个.skate文件到PLAY.bat上即可加载该地图；想自己编译可看 BUILD.bat 与 README.md 的 Build 章节；
• 进阶玩法：用 Lua mod 扩展（参考 sdk/AGENTS.md 与 sdk/examples/ 下的示例）。

相关文档与源码速查

• 设置向导：tools/setup.py
• 安装与分组转换主流程：tools/asset_pipeline/install.py
• 角色定制器指纹与准备：tools/asset_pipeline/customiser_setup.py
• .skate地图写入器：tools/asset_pipeline/map_writer.py
• ISO 参数顺序修复记录：docs/hails-additions/01-iso-extraction.md
• 长路径问题记录：docs/hails-additions/02-long-paths.md
• 开发实现笔记总目录：docs/hails-additions/README.md

按以上步骤操作，从 Xbox 360 ISO 到可玩的 skate3rust 数据只需一次点击，剩下的交给 setup 向导自动完成。