brynnb/new-yokosuka

# New Yokosuka - 莎木 1 (Dreamcast) 资产查看器

Video: New Yokosuka Demonstration

**立即体验！ [www.newyokosuka.com](https://www.newyokosuka.com/)** 该项目代号为 New Yokosuka，这是一个针对 Dreamcast 原版 [Shenmue](https://en.wikipedia.org/wiki/Shenmue) 的基于网页的概念验证模型查看器。我对这个项目的愿景是提取《莎木 1》的港口区域及其叉车模型，以重现原版游戏中的日常叉车工作。模型提取已完成，但将资产重新导入到新游戏引擎将是后续的工作阶段。 目前，它利用自定义解析器处理来自游戏多张光盘的场景和地图数据，直接在您的浏览器中渲染二进制 .MT5 模型。该查看器将模型数据导入 Babylon.js 引擎，这允许轻松导出为 GLTF 格式，以便在其他引擎、建模软件或 3D 打印中使用。 虽然该查看器成功渲染了绝大多数环境模型，但目前仍缺少一些核心引擎功能。最显著的缺失元素是正确的角色渲染以及在地图内自动放置动态对象（装饰品、车辆、门等）。此外，与原始 Dreamcast 源相比，某些纹理可能会显示出轻微的质量差异或瑕疵。 最复杂的进行中工作包括完善无缝的时间转换和实现道具分布。道具放置是一项特别困难的任务，因为 Shenmue 经常使用游戏脚本而不是静态数据表来定位对象。要实现完整的场景填充，需要逆向工程这些脚本以提取坐标，这比简单的数据解析要复杂得多。 更深入的信息可以在 [SHENMUE_DOCUMENTATION.md](SHENMUE_DOCUMENTATION.md) 文件中找到。 ## 功能与实现 - **原生 .MT5 支持**：用于二进制 MT5 模型文件的自定义 JavaScript 解析器。 - **PVR 解码**：实时解码 PVR/PVRT 纹理数据（包括 DXT 压缩格式）。 - **时间系统**：在白天、日落、傍晚和夜间预设之间循环，并伴随相应的纹理包交换。 - **FPS 导航**：真正的第一人称控制，支持 WASD 移动和环顾。 - **资产流式传输**：优化从 Cloudflare R2 流式传输资产以实现快速加载。 - **天空盒**：与所选时间同步的动态天空穹顶 —— 某种程度上是。分离一天中特定时间独有的资产有些挑战。 - **可搜索目录**：按游戏场景和区域组织的数千个模型。 ## 研究工具与提取 除了基于网页的查看器外，该项目还包括用于原始逆向工程和提取过程的一套基于 Python 的实用工具。这些工具允许： - 反汇编 SCN3 字节码以进行基于脚本的事件分析。 - 解压缩档案（.PKF, .PKS）并解码 PVR/PVRT 纹理。 - 为网页渲染器生成优化的二进制包和 JSON 目录。 关于这些实用工具的完整文档可以在 [**Research Tools README**](tools/README.md) 中找到。 ## 控制方式 当渲染器处于活动状态时： - **点击**：捕获鼠标以进入第一人称视角。 - **WASD**：向前、向后移动和扫射。 - **鼠标**：环顾四周。 - **Space / C**：向上飞 / 向下飞。 - **Q / E**：减少 / 增加移动速度。 - **ESC**：释放鼠标。 ## 已知问题与限制 - **动画**：目前仅支持静态几何体；骨骼/蒙皮动画尚未实现。 - **碰撞**：未利用物理和碰撞数据（仅限穿墙探索）。 - **光照**：仅基础光照模拟；尚不支持原始游戏的光场数据。 ## 设置：提取游戏资产 网页查看器默认从 Cloudflare R2 流式传输资产，因此**仅查看网站无需提取**。下面的提取管道仅在您想处理自己的游戏数据副本时（例如，添加新区域或更新资产）才需要。 ### 前置条件 - 带有 Pillow 的 **Python 3**：`pip install Pillow` - **Node.js**（用于网页查看器和 R2 上传） - **Shenmue (Dreamcast) GDI 光盘镜像** —— 见下文 ### 关于光盘 Shenmue (USA) 在 **3 张 GD-ROM 光盘** 外加一张奖励 Passport 光盘上发行： - **Disc 1**：包含场景 1 区域（Dobuita、Hazuki Residence、Sakuragaoka 等） - **Disc 2**：包含额外的场景 1 区域和所有场景 2 区域（Harbor、仓库等） - **Disc 3**：最终游戏光盘（额外的场景 1/2 内容） - **Passport Disc**：奖励内容，本项目未使用 本项目目前使用 **Disc 1 和 Disc 2**。您需要 GDI 格式的 GD-ROM 转储文件（每张光盘一个 `.gdi` 文件加上几个 `.bin`/`.raw` 轨道文件）。 ### 目录结构 将您的光盘镜像放在 `gamedata/` 文件夹中： ``` new-yokosuka/ ├── gamedata/ # Your disc images go here (gitignored) │ ├── disc1/ # Disc 1 GDI dump │ │ ├── Shenmue (USA) (Disc 1).gdi │ │ ├── Shenmue (USA) (Disc 1) (Track 1).bin │ │ ├── Shenmue (USA) (Disc 1) (Track 2).bin │ │ └── ... │ └── disc2/ # Disc 2 GDI dump │ ├── Shenmue (USA) (Disc 2).gdi │ ├── Shenmue (USA) (Disc 2) (Track 1).bin │ └── ... ├── extracted_files/ # Auto-created: Disc 1 extracted filesystem (gitignored) ├── extracted_disc2_v2/ # Auto-created: Disc 2 extracted filesystem (gitignored) ├── public/ │ ├── models/ # Auto-created: processed model + texture files (gitignored) │ ├── models.json # Auto-created: model catalog │ └── textures/sky/ # Sky dome PNGs (committed) └── tools/ # All extraction scripts ``` ### 运行完整管道 单个脚本即可处理整个提取过程： ``` # 完整 pipeline：提取 GDI → 处理模型 → 转换天空纹理 python3 tools/extract_all.py ``` 这将： 1. **提取** GDI 光盘镜像到 `extracted_files/` 和 `extracted_disc2_v2/` 2. **处理** 所有区域为 `public/models/` 中的 `.MT5` 模型文件和 `.bin` 纹理包 3. **生成** `public/models.json`（网页查看器读取的目录） 4. **转换** 天空 PVR 纹理为 PNG，位于 `public/textures/sky/` 选项： ``` python3 tools/extract_all.py --skip-extract # Skip GDI extraction (if already done) python3 tools/extract_all.py --extract-only # Only extract GDI, don't process ``` ### 运行查看器 ``` npm install # First time only npm run dev # Start dev server at http://localhost:5173 ``` 默认情况下，查看器从 R2 流式传输资产。要使用本地提取的文件，请在 `.env` 中设置： ``` VITE_OFFLINE_ASSETS=true ``` ### 上传到 R2 (生产环境) 提取后，将资产推送到 Cloudflare R2 以进行 CDN 分发： ``` node tools/upload_to_r2.js ``` ### 运行单个脚本 如果您需要手动运行特定步骤，请参阅 [tools/README.md](tools/README.md) 获取完整列表。关键脚本： | Script | Purpose | |--------|---------| | `tools/extract_all.py` | Full pipeline (recommended) | | `tools/gditools3.py -i --extract-all` | Extract a single GDI disc image | | `tools/sync_models.py` | Process extracted files into viewer format | | `tools/convert_sky_textures.py` | Convert sky PVR textures to PNG | | `tools/upload_to_r2.js` | Push assets to Cloudflare R2 | ## 研究与文档 本项目中的自定义解析器和技术实现参考了记录 Shenmue 二进制格式的现有逆向工程工作。对于那些对基础研究感兴趣的人，请参阅 [SHENMUE_DOCUMENTATION.md](SHENMUE_DOCUMENTATION.md) 和 [**/tools**](tools/README.md) 目录以获取字节码分析实用工具。 ## 参考仓库 这些外部项目在开发过程中被用作参考，但**并非必需**： - **[Shenmue-Export-Tools](https://github.com/seiche/Shenmue-Export-Tools)**：原始 PythonPVR 解码器库（由 seiche/Benjamin Collins 开发）。 - **[mt5_extraction_tools](https://github.com/yazgoo/mt5_extraction_tools)**：C++ PVR 解码器（`ypvr`），可用作参考实现。 - **[ShenmueHDTools](https://github.com/derplayer/ShenmueHDTools)**：HD Remaster 模组工具，用于交叉引用格式。 ## 致谢与资源 特别感谢以下资源： - **Shenmue Export Tools**：来自 [Shenmue-Export-Tools](https://github.com/seiche/Shenmue-Export-Tools) 项目的技术文档和提取提示。 - **Wulinshu Wiki**：[Shenmue Format Documentation](https://wulinshu.com/wiki/index.php) 作为某些数据结构的有用参考。 - **Wudecon**：来自 [LemonHaze420/wudecon](https://github.com/LemonHaze420/wudecon) 项目的研究笔记和格式逻辑。 - **gditools3**：一个用于从 SEGA Gigabyte Disc (GD-ROM) 转储中提取文件、sorttxt.txt 和引导扇区 (ip.bin) 的 [python 库](https://github.com/AltoRetrato/gditools3)。 当然也要感谢原版开发者！ ### 法律免责声明 Shenmue 是 SEGA 的注册商标。本项目是一个非商业的、粉丝制作的工具，仅用于教育和研究目的。它不隶属于 SEGA，也未受其认可或赞助。所有原始游戏资产、模型和相关内容均为其各自商标和版权所有者的财产。 ## 许可证 本项目根据 [GNU General Public License v3.0](LICENSE) 授权。

标签：3D场景复刻, 3D打印, 3D模型查看器, Babylon.js, Dreamcast, GLTF, MITM代理, TypeScript, Web3D, WebGL, 世嘉, 二进制解析, 前端可视化, 安全插件, 怀旧游戏, 数字遗产, 数据可视化, 浏览器游戏, 游戏 preservation, 游戏地图, 游戏逆向工程, 莎木, 资产提取, 逆向工具