Miu2D：用原始 WebGL 組织一套浏覽器 2D ARPG 引擎

原始 WebGL，零游戏框架依赖 · luckyyyyy-miu2d-deep-analysis

Miu2D 是一個用 TypeScript 和 Rust 编寫的 2D ARPG 引擎，其渲染層直接调用 WebGLRenderingContext。README 稱引擎约有 17.6 万行代码，并刻意避免使用 Unity、Godot、Phaser、PixiJS 或任何其他游戏框架。精灵批处理、A* 寻路、二進制格式解码器、脚本虚拟机、天气粒子和屏幕特效等子系统都是從第一性原理實現的。項目還標明從第一天起就采用 AI 辅助编程，標籤為'Vibe Coding'。

三款金山武侠游戏作為概念驗證 · luckyyyyy-miu2d-deep-analysis

作為演示，Miu2D 在浏覽器中复刻了三款西山居（金山）的经典动作 RPG，并稱可完整游玩。《月影传說》（2001）被描述為当時西山居规模最大的制作，拥有七個或更多結局、超過 100 個故事事件、30 人团队和 14 個月開發周期。《剑侠情缘贰》（1998）引入了類似暗黑的實時战斗，包含超過 200 個 NPC，運行在 640×480 16 位色下，主題曲由谢雨欣演唱。《新剑侠情缘》（2001）是 1997 年原作的复刻版，地图數量超過 110 张，并使用《剑侠情缘贰》的實時战斗引擎。README 没有提供這些游戏的下载大小或帧率數據。

pnpm monorepo 中的 11 個包 · luckyyyyy-miu2d-deep-analysis

该倉庫組织為 pnpm 工作区，包含 11 個包。引擎包 @miu2d/engine 是纯 TypeScript，包含 215 個文件、19 個模块，不依赖 React。游戏運行時 @miu2d/game 使用 React 19，提供经典、現代和移动三种 UI 主題。WASM 包 @miu2d/engine-wasm 是编譯為 WebAssembly 的 Rust，承载 A* 寻路、解码器、空間哈希和 zstd 压缩。後端包 @miu2d/server 基于 Hono、tRPC 和 Prisma ORM，有 21 张 PostgreSQL 表和 19 個路由。dashboard 包提供類似 VS Code 的编辑器，包含 13 個编辑模块。其余包涵盖類型、Web 應用外壳、转換器、查看器、UI 組件和共享的 i18n/上下文代码。

渲染器：批处理、回退與光照 · luckyyyyy-miu2d-deep-analysis

渲染器直接使用 WebGLRenderingContext。SpriteBatcher 累积顶點數據并在纹理變化時刷新，將典型地图帧的大约 4800 個瓦片减少為 1 到 5 次绘制调用。RectBatcher 將天气粒子和 UI 矩形合并為一次绘制。纹理管理通過 ImageData 转換為 WebGLTexture，使用 WeakMap 缓存并由 FinalizationRegistry 自动清理。GLSL 片段着色器為中毒、冻結和石化状态應用颜色滤镜，渲染循環合成淡入淡出、闪光和水波纹等屏幕效果。Canvas 2D 回退實現了相同的 Renderer 接口，為没有 WebGL 的設備提供完整功能。局部光照使用發光實體的加性辉光遮罩，并匹配 JxqyHD 項目中的 C++ 参考實現，對不同魔法移动類型的子投射物有特定的發光模式。

脚本：自定义 DSL 加 Lua 5.4 · luckyyyyy-miu2d-deep-analysis

Miu2D 包含两种共享同一 GameAPI 的脚本模式。DSL 模式使用自定义解析器解析 .txt 和 .npc 文件，并通過异步执行器運行。README 列出了 218 条命令，覆盖對话、玩家、NPC、游戏状态、音频、特效、對象、物品和其他九類。Lua 模式通過 wasmoon 嵌入完整的 Lua 5.4 運行時，wasmoon 將 Lua 编譯為 WASM。全部 170 個 GameAPI 函數以 PascalCase 全局變量暴露，wasmoon 的代理系统將 JavaScript 异步函數桥接到 Lua 协程，因此 PlayerWalkTo() 或 Talk() 等阻塞操作無需顯式 await 即可工作。同一個 ScriptExecutor 根據文件扩展名路由：.lua 交给 Lua 执行器，.txt 和 .npc 交给 DSL 执行器。README 中的示例 Lua 脚本加载地图、設置玩家位置、播放對话，并询问是否加入任務以添加魔法和经驗。

寻路、二進制解码器與天气 · luckyyyyy-miu2d-deep-analysis

A* 寻路器用 Rust 编寫并编譯為 WebAssembly。它通過 Uint8Array 视图將障碍位图直接寫入 WASM 線性內存，就地执行 A*，并通過 Int32Array 指针视图讀取結果，避免序列化和复制。README 报告了五种寻路策略，從贪心到完整 A*，可配置最大迭代次數，典型查询约 0.2 毫秒，比等效 TypeScript 實現快约 10 倍。引擎解码原作的八种二進制格式：ASF、MPC、MAP、SHD、XNB、MSF、MMF 和 INI/OBJ，其中 MSF 和 MMF 使用自定义 zstd 压缩。天气系统模拟风驱雨、溅射和闪电，屏幕水滴的折射透镜效果，以及具有摇摆、旋转、漂移和逐渐融化的雪花。README 没有說明性能數據對應的具體硬件或浏覽器版本。

编辑器、操作與部署 · luckyyyyy-miu2d-deep-analysis

倉庫附帶一個 VS Code 风格的游戏數據编辑器，其 13 個模块涵盖魔法、NPC、场景、物品、商店、對话、玩家、等级、游戏配置、文件管理器、資源和统计。桌面操作包括左键移动或交互，右键交替交互，Ctrl+左键原地攻击，Q 和 E 交互最近物體或 NPC，A/S/D/F/G 施放魔法槽位，Z/X/C 使用物品快捷栏，V 切換打坐/修炼。移动端使用虚拟摇杆移动，點击交互。部署方面，README 描述前端通過 Vercel 部署為静态 SPA，完整栈使用 Docker Compose 搭配 PostgreSQL、MinIO、Hono 和 Nginx。還列出了 pnpm dev、make dev、make tsc、pnpm lint、make test 和 make convert 等命令，要求 Node.js 18+ 和 pnpm 9+。

把浏覽器复現拆成可观察步骤

Miu2D 的驗證不應只停留在首頁能否打開。先确認 pnpm 工作区安装完成，再观察引擎是否创建 WebGL context；随後载入地图，检查 SpriteBatcher 的绘制调用、角色移动和碰撞結果。浏覽器不支持目標 WebGL 路径時，再确認 Canvas 2D 回退是否仍能顯示地图、角色和 UI。

脚本测試可以选一条 .txt、.npc 和 .lua 事件，比較 DSL 與 Lua 共享 GameAPI 時的對话、移动和音效行為。WASM 寻路则记錄障碍位图、路径长度和查询耗時，同時注明浏覽器與硬件。這样能把 README 的架構描述對應到具體輸出，也能發現原始資源缺失、格式解码和移动端輸入之間的真實边界。\n\n编辑器驗證還應覆盖資源热重载、移动端虚拟摇杆、音频播放和地图室內外切換。每項测試都注明資源文件、浏覽器版本和控制台輸出；若只完成桌面端，文章結论就只覆盖桌面端。引擎的 MIT 代码許可與复刻游戏素材授權必须在發布前分別确認。\n\n在性能观察之外，還要检查資源生命周期和错误回退。關闭 WebGL context 後重新加载地图，确認 Canvas 2D 路径不会留下旧纹理；切換 Lua 與 DSL 脚本，确認异步操作結束後角色状态和對话状态一致。移动端测試则應记錄虚拟摇杆坐標、触控交互和屏幕比例。README 给出的數字没有硬件条件，不能当作跨設備承诺。

編輯結論

适合研究浏覽器 2D RPG 引擎、需要直接控制 WebGL 渲染或想閱讀 TypeScript 與 Rust WASM 协作代码的人；不适合直接把复刻資源用于商業發行的团队。先運行倉庫提供的前端開發命令，观察 WebGL 與 Canvas 2D 回退是否都能启动，再單独核對游戏資源的版權范围。

官方來源

1. Official documentation
2. Official README
3. Project repository