Miu2D

在 Phaser、PixiJS 或 Unity WebGL 成为主流选择的今天，Miu2D 选择了一条极其硬核的道路：从零构建一个纯原生的 2D ARPG 引擎。

这个项目不仅是一个技术验证，更是一次对经典的致敬。它完整复刻了西山居三款经典武侠 RPG——《剑侠情缘贰》、《月影传说》和《新剑侠情缘》，并使其能在现代浏览器中流畅运行。整个项目包含约 176,000 行代码”，采用 TypeScript 和 Rust 编写，完全摒弃了第三方游戏框架，直接通过 WebGLRenderingContext 进行渲染。

核心架构：为何要“重复造轮子”？

Miu2D 的目标是构建一个每一层都可见、可调试、专为 2D ARPG 定制的系统。其核心优势在于：

1. 原生 WebGL 渲染管线

• 零抽象税：没有场景图开销，没有不必要的 3D 数学计算。
• 极致批处理：
  • SpriteBatcher：将约 4,800 张地图瓦片合并为 1–5 次 WebGL 绘制调用。
  • RectBatcher：将约 300 个天气粒子归并为 1 次调用。
• 高级特效：原生实现 GLSL 颜色滤镜（中毒/冰冻/石化）、屏幕特效（水波纹/闪光）以及基于 SHD 的真实光影系统（加法光晕、逐实体发光）。

2. Rust + WASM 性能加速

• 零拷贝寻路：A* 寻路算法由 Rust 编写并编译为 WebAssembly。通过共享线性内存，JS 直接写入障碍物数据，WASM 就地计算，JS 直接读取结果。单次寻路仅需约 0.2ms，比同等 TS 实现快 10 倍。
• 空间哈希碰撞：同样由 Rust/WASM 实现，提供 O(1) 复杂度的宽相实体查询。

3. 双模脚本引擎

• 自研 DSL：解析并执行原版游戏的 218 条指令（对话、战斗、特效等）。
• Lua 5.4 支持：通过 wasmoon 嵌入完整 Lua 运行时，所有 GameAPI 自动桥接为 Lua 全局函数，支持异步协程，完美兼容原版逻辑。

引擎子系统全览

Miu2D 实现了 17 个完整的 ARPG 子系统，涵盖了从底层渲染到上层逻辑的所有环节：

全栈工具链与编辑器

Miu2D 不仅仅是一个运行时引擎，它还配备了一套完整的开发工具链：

• Dashboard 编辑器：VS Code 风格的 Web 编辑器，包含武功、NPC、场景、物品、商店、对话等 13 个编辑模块，支持实时预览和资源管理。
• 后端服务：基于 Hono + tRPC + Prisma ORM 构建，使用 PostgreSQL 存储用户数据，MinIO/S3 存储资源。
• 资源转换器：Rust 编写的 CLI 工具，批量将原版 ASF/MPC 格式转换为引擎专用的 MSF/MMF 格式。

技术栈详情

• 语言：TypeScript 5.9 (Strict), Rust, GLSL
• 前端：React 19, Vite 8, Tailwind CSS 4
• 渲染：原生 WebGL API
• 性能：Rust → WebAssembly (wasm-bindgen, 零拷贝)
• 后端：Hono, tRPC 11, Prisma ORM, PostgreSQL 16
• 代码质量：Biome (Lint+Format), Zod 4 (Schema 校验)

快速开始

1. 环境要求

• Node.js 18+
• pnpm 9+
• 支持 WebGL 的现代浏览器

2. 安装与运行

git clone https://github.com/nicologies/miu2d.git
cd miu2d
pnpm install

# 启动前端开发服务器
pnpm dev            # → http://localhost:5173

# 全栈启动 (需 Docker)
make init           # 初始化 PostgreSQL + MinIO
make dev            # 启动 Web + Server + DB

3. 操作指南

• 桌面端：左键移动/交互，右键备用交互，Ctrl+左键攻击，ASDFG 释放技能。
• 移动端：虚拟摇杆移动，轻触交互。

对于开发者而言，Miu2D 是一座宝库：你可以学习如何处理原生 WebGL 批处理，如何实现零拷贝 WASM 通信，如何逆向解析二进制游戏格式，以及如何构建一个复杂的脚本虚拟机。对于玩家而言，它则是一把钥匙，重新打开了那段充满江湖气息的剑侠记忆。