水墨横版刀剑动作游戏。直接控制角色，以连斩开路，以弹反破势。Three.js / WebGL 2 渲染，独立的 60 Hz 战斗逻辑。
这是独立项目，与 last-beacon 同级，不依赖灯塔的代码、资源或启动服务。
git clone [email protected]:stackloomdev/ink-blade.git
cd ink-blade
npm run dev打开 **http://localhost:4174/**。项目没有需要安装的 npm 依赖；Three.js 随源码保存在本地。
npm test # 战斗回归
npm run build # 生成独立静态站点 dist/dist/ 可由普通静态 HTTP 服务托管。不使用服务器端接口；不能直接双击 HTML 以 file:// 运行 ES modules。
- 三段竹林遭遇战：斗笠刀客、长枪兵。
- 白袍剑客三阶段：持剑对招、收鞘拔刀、破门。卷首可直接挑战；抵达 Boss 后重试从 Boss 开始。
- 三连斩、挑空、主动跳起追击、下劈、带短暂无敌的冲刺。
- 有方向要求的格挡与精准弹反、自身与敌方架势、破势处决。
- 攻击与精准弹反积累墨势，主动释放墨影连斩。
- 主角、白袍剑客直接使用用户原图：原始脸、服饰、纹理和配色，不再投射到简化三维人物上。
- 正侧背面分别读取对应的原始 PNG；横版实战用侧面原画的 2.5D 分层网格、手臂逆向运动学、独立腿部、衣摆和发束变形。
- 步态按移动距离推进，髋、膝、踝分别求解；支撑脚锁在地面，回收腿屈膝，摆臂配合前后脚，脚步声与水花跟随落脚。
- 刀、刀鞘、剑和挂饰取自原武器图，刀柄跟随手掌，实际刀尖驱动轨迹；残影使用当前姿势的原图轮廓。
- 冷灰雨夜竹林、月色与远山、地面水波、局部断竹、击杀墨迹、第三阶段寺门破坏。
- 命中姿势与战斗判定对齐，真实刀路、重击火花、弹反冲击与雨水排开；朱红绝技、克制的镜头和墨色后期。
- Web Audio 分层合成雨声、挥刀、命中、钢铁碰撞与低鼓音，关键命中压低雨声。
- 暂停、失焦暂停、招式说明、失败重试、通关统计、基础触屏操作。
当前是可玩的 2.5D 原型。人物保留原图 RGB，场景继续使用三维渲染；普通敌人暂为程序模型。静态三视图没有提供动作逐帧，所以战斗姿势、衣摆运动和被遮挡区域的拼接由代码制作，不能称为原画动作逐帧复刻。触屏需要继续真机调试，尚无手柄、存档或装备成长。
原画素材与还原说明 记录六张源图、分层骨架、透明轮廓与验证边界。主角、Boss 和武器造型已经齐全，不需要重复生成。
当前角色的可编辑源是 src/art-rig-data.js 与 src/art-warrior.js，不需要付费的骨骼编辑器。assets/models/ 中原有 GLB / Blender 是此前的三维底稿，保留作历史材料，已经不用于主角或 Boss 的实战渲染，也不代表本轮原画还原结果。生产构建包含原始 PNG 和渲染轮廓，不包含旧模型和开发工具。
| 操作 | 按键 |
|---|---|
| 行走 / 转向 | A / D，或左右方向键 |
| 三连斩 | 连续按 J |
| 挑空 | W + J |
| 跳跃 / 空中追斩 | Space / 空中 J |
| 下劈 | 空中 S + J |
| 冲刺 | Shift |
| 格挡 / 精准弹反 | K；命中前短窗口按下精准弹反，按住仅持续格挡 |
| 处决 / Boss 破势反击 | 敌人出现「破」时靠近按 L |
| 墨影连斩 | 墨势满后按 Q |
| 暂停 / 声音 | Esc 或 P / M |
运行不调用 AI、付费服务或第三方素材 CDN，不需要账号和 API Key。人物直接使用用户提供的图片；没有使用付费模型、Spine 或外购音效。离线制作轮廓时使用本机 Apple Vision，源 PNG 不重绘、不上传。轮廓经过无损行程编码，七份数据合计约 1.5 MB。浏览器必须支持 WebGL 2。
vendor/three.module.js、vendor/three.core.js 来自 npm 官方包 [email protected]，按 MIT 许可证分发，许可证保存在 vendor/THREE-LICENSE.txt。游戏源码采用 MIT 许可证。
开发工具的 tools/vendor/GLTFExporter.js 同样来自 [email protected]，仅修改本地导入路径；不进入生产构建。用户提供的参考图保留原有权利，不由项目源码许可证重新授权。
src/combat.js：固定步长战斗、招式、架势、敌人 AI、Boss 阶段、关卡与结算。src/art-warrior.js：原画人物、分层网格、持刀逆向运动学、衣摆变形与轮廓残影。src/art-rig-data.js：原图的视图、剪裁区域、部位轮廓和骨架坐标。src/locomotion.js：距离驱动的步态、落脚锁定、腿部逆向运动学与重心高度。src/art-coverage.js：无损透明轮廓解码；原始 RGB 和轮廓独立存储。src/warrior.js：普通敌人的三维造型和动作，旧三维底稿也保留在这里。src/reference-art.js、src/reference-weapons.js：旧三维底稿的纹理与武器；原画角色不使用这条路径。src/scene.js：Three.js 光照、粒子、刀光、人物与镜头协调。src/ink-world.js：雨夜山林、寺门、湿地面、雾与可破坏竹子。src/ink-post.js：水墨后期、弹反冲击与绝技色彩。src/main.js：键盘 / 触屏输入、HUD、菜单与暂停。src/audio.js：浏览器合成音效。tests/combat.test.mjs：战斗回归，包括正常数值的完整战役验证。tests/locomotion.test.mjs：落脚滑动、屈膝方向、腿长、步态连续性、暂停和不同帧率回归。tools/character-study.html：原图对照、行走 / 奔跑、地面标尺、慢放与动作定格；不进入生产构建。tools/locomotion-check.js：正常按键检查实战起跑、停步、反向、暂停、接斩及支撑脚滑动。tools/verify-original-art.js：使用实际角色类做原生分辨率像素比较和动作网格检查。tools/reference-coverage.swift、tools/pack-coverage.mjs：本机生成轮廓、无损打包；正常运行无需执行。tools/export-hero.js、tools/prepare-model.py：仅用于旧三维底稿，不能导出当前原画分层动画。
运行开发服务后，可通过 http://localhost:4174/tools/character-study.html 放大检查人物。
浏览器开发检查可只读访问 window.inkBlade，没有修改生命、位置或墨势的接口。
- 独立项目
npm test：19 项全部通过（13 项战斗、6 项步态）；npm run build通过。 - 六个静态视图用实际
ArtWarrior在原生分辨率渲染，采样不透明内部像素，RGB 通道误差全部为 0；透明发丝和衣摆边缘的分割不计入“像素相同”声明。 - 两个角色共 36 个状态 / 招式组合，逐帧检查网格与刀尖坐标为有限值，覆盖左右朝向。
- 生产构建与正常按键实战的最新结果记录在
docs/VALIDATION.md。 - Safari、手机真机与手柄未验证。