Sheilem/maplewright

## 这是什么 Maplewright 是对 v83 时代 MapleStory 客户端的全新重制。它不是现有客户端的分支， 也不是私服包——而是一个读取原始数据格式、重现 原始物理和网络协议、并自行绘制整个世界的新引擎。 它的诞生是因为经典客户端是一个 2005 年的 32 位 DirectX 8 可执行文件，只能在 Windows 上运行。一个使用相同数据格式的现代引擎可以运行在**任何有浏览器的设备上**， 分辨率更高，且没有原版平台的历史包袱——并且它是开放的，可以被研究、扩展和 改进。 我们的目标是**精准还原，而非近似模拟**。凡是能从真实基准中测量得出的值——无论是物理常数、 UI 坐标还是数据包结构——我们都绝不去猜测。这种严谨的态度 正是本项目极具挑战性的原因，也是它值得去做的价值所在。 ## 状态 处于早期，但已经可用。核心的承重系统——数据读取、物理系统、网络协议、 前端——已经能在真实的 v83 服务器上端到端地运行。广度和 GPU 渲染器仍在开发中。以下是真实的进展快照： | 领域 | 状态 | 备注 | |---|---|---| | WZ 档案读取器 | **正常工作** | AES/校验和，目录树，所有画布格式 -> RGBA | | 地图渲染 | **正常工作** | 地块、对象、分层视差背景 | | 物理系统 | **部分完成** | 行走/跳跃/坠落/坡道/下跳已通过抓包验证；暂不支持梯子、游泳或上爬墙壁 | | 网络协议 (v83) | **正常工作** | 登录 -> 世界 -> 频道 -> 游戏内；怪物、战斗、掉落物、EXP、物品栏、技能、其他玩家 | | 前端 (登录/世界/角色) | **正常工作** | UI 位置从真实客户端中恢复提取（见下文） | | GPU 渲染器 (wgpu) | **早期阶段** | 实例化 sprite 批处理器；原生 + WebGL2/WebGPU；正在将游戏接入其中 | | 浏览器客户端 (WASM) | **正常工作** | 与原生客户端使用相同的代码路径运行 | | Asset pipeline | **临时方案** | 目前按地图进行 PNG 烘焙；图集/打包 pipeline 已设计但尚未构建 | | 声音 | **尚未开始** | | | 内容广度 (NPC、任务、商店, ...) | **尚未开始** | 仅包含核心循环 | 客观估计：目前已经可以在单张地图上实现端到端的可玩体验—— 尽管这只是完整客户端的一小部分。那些困难且充满不确定性的部分 已基本解决；剩下的多数只是工作量的问题。 ## 架构 **技术栈：** Rust - wgpu (WebGPU / WebGL2) - WebAssembly。一套代码库，两个目标：原生窗口 和浏览器，驱动同一个与平台无关的游戏核心。 **预先确定的设计决策：** - **面向数据的 2D sprite 渲染器。** 绘制的所有内容都是带纹理的轴对齐四边形，因此 渲染器只专注于做好一件事：基于纹理图集的实例化四边形批处理器，从后向前渲染， 无深度测试。它的设计形态来源于原版客户端在 draw-call 层面的真实行为， 而不是凭空猜测。 - **使用烘焙的 assets，而非运行时解析 WZ。** Runtime 不应携带 WZ 读取器。WZ 是在离线状态下被读取 并转换为 GPU 就绪的打包文件的。（目前该 pipeline 还很基础；具体设计见 [ARCHITECTURE.md](ARCHITECTURE.md)。） - **事实依据优于主观猜测。** 物理常数来源于 WZ 并通过与真实移动 数据包对比进行校验。UI 坐标来源于客户端自身的绘制列表。数据包结构来源于 参考服务器自身的序列化器。当测量值与猜测值发生冲突时，以测量值为准。 **Workspace crates：** ``` crates/ wz WZ archive reader + offline tools (map render, sprite extract, layout recovery) physics Movement + foothold collision, derived from ground truth net v83 packet protocol: AES-OFB + Shanda crypto, structured packet types client Platform-free game core (world, entities, UI) + a native window binary web WebAssembly browser shell around the same core render GPU sprite renderer (wgpu) assetd Dev asset server: renders character/mob art on demand from WZ wsproxy WebSocket <-> TCP bridge so the browser can reach a TCP game server d3dhook Research tool: logs the original client's DirectX 8 draw list to recover UI layout ``` ``` your v83 WZ files | [ offline tools: wz ] | baked maps / sprites / layouts | native window <---- client core (physics, net, UI) ----> browser (web + WASM) | | | render (wgpu) net <--> wsproxy <--> v83 game server (TCP) ``` 关于更深入的技术细节——渲染器模型、网络流程、UI 坐标是如何恢复的、 物理推导过程——请阅读 **[ARCHITECTURE.md](ARCHITECTURE.md)**。 ## 部分功能的实现原理 一些让它不仅仅是简单移植的技术： - **基于捕获数据包的物理系统。** 四个移动常数存在于 WZ (`Physics.img`) 中，但 时间步长和缩放比例在任何地方都没有明文记载。我们通过捕获真实的 移动数据包来校准它们，并验证跳跃高度是否精确等于测量值、坠落速度是否 封顶在测得的终端速度上等等。最终结果是一个确定性的、经过逐帧测试的物理模拟。 - **基于客户端自身绘制列表的 UI 布局。** v83 将美术资源保留在 WZ 中，但将 UI *坐标* 硬编码进了可执行文件中——数据文件中根本不包含位置信息。我们没有 手动测量截图，而是使用 `d3dhook` 工具记录客户端的 DirectX 8 绘制调用（哪种 纹理、哪个屏幕矩形区域、哪种混合模式），然后通过将像素与 WZ 进行对比，为每个 sprite 命名。最终输出的是客户端自身的布局， 极其精准，同时涵盖所有屏幕—— 包括截图永远无法获取的信息，如输入框矩形和动画时序。 - **基于参考服务器序列化器的协议。** 线上传输格式是通过参考一个开源 v83 服务器写入数据包的方式来重现的，随后进行了实时验证：发送格式正确的操作指令， 就能收到正确的游戏响应；发送格式错误的指令，则毫无响应。从真实服务器 获得伤害、死亡、掉落物和 EXP 的反馈，就是证明数据包结构正确的最佳依据。 ## 编译和运行 你需要 **Rust (稳定版)** 和一个终端。在 Windows 上，本项目是针对 GNU 工具链 （`x86_64-pc-windows-gnu`）开发的；如果你还没有安装 Rust，请从 [rustup.rs](https://rustup.rs/) 下载安装。 ``` git clone https://github.com/Sheilem/maplewright cd maplewright ``` ### 1. 验证它 - 无需游戏文件 物理引擎和网络协议是独立的，并自带测试。你可以在全新克隆的代码库上 编译并运行它们，无需安装任何其他东西——它们证明了核心逻辑是可用的： ``` # Physics: 复现真实的 v83 移动（跳跃高度、terminal velocity、行走速度、斜坡、down-jump） cargo run -p physics --bin validate # Network: v83 packet crypto + protocol，已通过 known-answer vectors 和捕获的流进行验证 cargo run -p net --bin netvalidate ``` 预期结果：每一行都会打印出 `[ok]`。这是引擎经过基准测试的核心模块，并且 它无需任何 WZ 文件和 GPU 即可运行。 ### 2. 编译所有内容 ``` cargo build --workspace --exclude web --release ``` 这将编译所有的离线工具和原生客户端。（排除了 `web` 是因为它需要嵌入你自行生成的 assets ——见下文；`d3dhook` 是一个独立的 32 位工具，请参阅其 [README](crates/d3dhook/README.md)。） ### 3. 运行客户端 - 请自备 WZ 图形客户端需要游戏数据，而 Maplewright **不包含**这些数据。请提供你自己的 v83 WZ 文件，并用它们生成烘焙的 assets。完整且精确的命令——地图烘焙、UI 提取、 在原生或浏览器中针对 v83 服务器运行——都在 **[docs/ASSETS.md](docs/ASSETS.md)** 中， 并且每个工具都可以使用 `--help` 打印用法说明。 简而言之： ``` # 从你的 Map.wz 烘焙 map（完整命令和选项请参见 docs/ASSETS.md） cargo run -p wz --release --bin wzmap -- "PATH_TO_WZ/Map.wz" out/fg.png Map/Map1/100000000.img # Native window：使用方向键行走，使用 Alt/Space 跳跃，Esc 退出 cargo run -p client --release -- out/ # Browser：构建为 wasm32，运行 wasm-bindgen，serve crates/web/dist，通过 wsproxy 连接 ``` ### 各目标平台的前置条件 - **核心模块 / 工具 / 原生客户端：** Rust 稳定版。仅此而已。 - **浏览器构建：** 需要 `wasm32-unknown-unknown` 目标和匹配的 `wasm-bindgen-cli`。 - **`d3dhook` 研究工具（可选）：** 32 位 MinGW-w64 (winlibs i686, DWARF)。编译或 运行引擎不需要此工具。 ## 路线图 请参阅 **[ROADMAP.md](ROADMAP.md)**。简而言之：完成 wgpu 渲染器并将浏览器端迁移至其上， 构建真正的烘焙 asset pipeline，完善物理系统（梯子、墙壁、水流），然后是内容广度（NPC、 任务、商店）以及 HD 美术。 ## 法律与道德 Maplewright 是一个独立的、粉丝制作的游戏引擎。它**与 Nexon 没有任何形式的关联、认可或 联系**。*MapleStory* 是其各自所有者的商标。 - **不包含也不分发任何游戏内容。** 本代码库仅包含原创的源代码。 所有美术、音频、地图和数据均从**你**提供的 WZ 文件中读取，并且 预期你是合法拥有的。这与其他开源重制项目的基础立场一致。 - `d3dhook` 工具是一个 DirectX 8 API 记录器，用于对你拥有的客户端进行互操作性研究—— 这与图形调试器属于同一类工具。编译或运行引擎并不需要它。 - 本项目重现文件格式、物理系统和网络协议是为了实现互操作性。它 不绕过 DRM，且不包含任何专有代码。 如果你是版权持有人并有任何疑虑，请提交 issue。 ## 鸣谢 ## 许可证 **GNU Affero General Public License v3.0** - 详见 [LICENSE](LICENSE)。 Maplewright 是 copyleft（著佐权）的：你可以使用、研究、修改和分享它，并且任何分发或 网络托管的衍生作品都必须在同一许可证下保持开源。这确保了该引擎及其每一个 分支都能对所有人保持开放。

标签：AI工具, 信息收集, 可视化界面, 通知系统