迁移前的项目是一个“汉字游戏启动器”，里面有两个可玩的网页3D原型游戏： 我们现在先专注在字海上

1. 字海残卷

• 实时动作生存 / roguelite
• 核心是“偏旁收集 -> 自动合字 -> 汉字技能 -> 更高阶词技”

2. 仓颉之路

• 类 Slay the Spire 的卡牌爬塔 / deckbuilder
• 核心是“偏旁、汉字、语义组合”直接进入战斗和构筑

当前整体结构

• 技术上目前是 HTML/CSS/JS
• 启动页有一个 Three.js 抽象漂浮背景：汉字 sprite + 半透明几何体在空间中漂浮碰撞
• 字海残卷 和 仓颉之路 目前战斗层都还是网页原型，其中 仓颉之路 明确走 Babylon.js 主线
• README.md 和 CHANGELOG.md 一直在持续更新

启动器 / 首页现状

• 首页标题已经改成 汉字游戏启动器
• 视觉上是类似主机首页 / PS5 选游戏的感觉
• 只有两个游戏入口卡片，信息非常精简，每个游戏只留一句 tagline 和一个抽象图标
• 较长说明被收进二级 关于游戏 面板
• 有微信 / iOS 的视觉引导：
  • 微信里提示尽量用系统浏览器打开
  • iOS 提示 分享 -> 添加到主屏幕
• 最新改动：点击 字海残卷 后，不是直接进 Babylon 战斗页，而是先进入一个真正的二级菜单层
• 这个 字海 二级菜单保留和首页一样的漂浮 Three.js 背景
• 只有在选完角色并确认开始后，才真正进入 字海 的 Babylon 战场

字海残卷（目前已经是较完整可玩原型）

核心玩法

• 实时移动、生存、自动攻击
• 收集偏旁后自动尝试合字
• 合出完整汉字后解锁技能
• 重复偏旁不会浪费，而是会给已有合字技能升级
• 词技系统存在：部分高阶内容不只是单字，而是更高一层的“词”
• 现在词技不再是纯自动解锁，而是要在 砚 那里把满级合字进一步磨成词

角色

• 至少两个角色：
  • 书生
  • 侠
• 侠 已经不是远程，而是近战剑士
• 侠 手里有实体剑模
• 攻击时会真实挥剑
• 剑会随着 刂 刀字旁收集和成长而变大，而且已经被做得更夸张、更宽

敌人系统

当前已经不只是普通怪，谱系明显丰富了：

• basic 普通敌人
• swift 快速敌人
• tank 坦克敌人
• archer 弓箭手
• assassin / 忍
• cavalry / 墨骑
• ritualist / 阵师
• elite

这些新增敌人都不是简单换皮，而是有明确行为差异：

• 忍
  • 中距离游走
  • 会短暂预警后沿直线突刺
  • 地上有偏紫色突进轨迹
• 墨骑
  • 会从一侧冲锋到另一侧
  • 冲锋前地面会出现红色长方形路线预警
  • 命中会造成 1 秒晕眩
• 阵师
  • 会在地图上放字阵 AOE 区域伤害
  • 有预警圈，之后转成持续危险区域
• elite
  • 不再只是高数值怪
  • 已经有技能池：
    • 爆圈
    • 一长串线性弹幕
    • 梅花形旋转弹幕
    • 类重骑的大型冲锋
  • 冲锋类技能也会在地上显示即将冲锋的路线

刷怪节奏

• 敌人出现波次整体被提前了
• 混编更早发生
• 每种兵种数量也更多了
• 战斗现在更早进入多兵种混合压力

地图 / 场景生态

地图里已经不只是空地：

• 宝箱
  • 打开后给道具
• 树
  • 大型实体
  • 人物走进去会半透明 / see-through
• 草丛
  • 进入后短暂隐身
  • 敌人丢失目标
  • 后来又做了反滥用机制：
    • 草丛本身有恢复期
    • 玩家也有一个短的重入锁
    • 不能靠反复蹭草丛无限隐身
• 笔
  • 临时属性增益
• 墨
  • 群体 AOE
• 纸
  • 现在不是圆形，而是长方形卷轴状的增益区域
• 砚
  • 工具台，用来把满级合字进一步磨成词技

地形

• 目前已经做了一版“轻量自然感地形”
• 不是完整 heightmap，也不是复杂高低差玩法
• 只是低成本的地面起伏 / mound / painted ridge，让场地不再死平
• 这是有意保守的第一步，为了避免性能和寻路复杂度爆炸

战斗反馈 / 视听

• 新合出汉字时会有明显的大特效：
  • 角色周围更重的笔画爆字
  • 屏幕上方会漂浮出更大的“合字成型”动画
• 攻击残影、打击反馈、音色区分等都做过多轮强化
• 新增两首程序化 16-bit 背景音乐：
  • 一首静谧夜林感
  • 一首稍轻快
• 会随机轮换播放
• 角落会 pop 出当前曲名通知

进度 / 局外系统

• 角色选择界面已经改成“两张角色卡直接二选一”
• 地图迷雾 / fog-of-war 存在
• 地图 modal 已经有缩放、拖拽、图例
• 成语 / 句子类地图事件已经接入，且由精英守卫
• 暂停系统存在
• 死亡结算页可以直接：
  • 重开
  • 回启动器
  • 看排行榜
• 有 人物志、合字图谱、怪物图鉴
• 这些现在都属于 字海 的二级菜单层，而不是最外层首页的一部分

排行榜

• 最初做的是本地排行榜
• 后来已经接成 Firebase Realtime Database 在线排行榜
• 使用匿名登录
• 同时保留本地 cache fallback
• 每局结束自动记录：
  • 波次
  • 击杀
  • 存活时间
  • 用的角色
  • 偏旁 / 合字 / 词技 / 神器
  • 各类敌人击倒数
• 玩家可以输入名字
• 如果跳过，则随机生成武侠风名字

移动端 / 平台适配

字海 这边已经做了很多移动端适配：

• 手机 portrait 会被阻止，要求横屏
• 移动端有虚拟摇杆和暂停按钮
• 摇杆已经改成自由位置出现，左右手都能操作
• iPad 识别和摇杆显示问题修过
• 微信内打开的 viewport / UI 混合问题修过
• 提示 toast、失败页滚动、选择页尺寸等都针对手机横屏修过
• 偏旁/神器/磨词选择页在手机上改成居中约 70% 大小的弹窗

UI / 可读性

• 最近还做过一轮纯 UI 优化，不改玩法，只强化信息分层
• 偏旁、合字、词技、神器不再都是一坨同色同字重
• 战斗桌面 HUD 还整体缩小过约 15%
• 当前更强调“重点字、重点类别、重要信息”的视觉层级

仓颉之路（目前也已经超过 bare prototype）

核心玩法

• 三路塔图
• 战斗 / 精英 / 事件 / 宝箱 / Boss 流程
• 金币经济、商店、删牌、事件抉择
• Ink 作为第二资源
• 不是纯 StS 换皮，已经把汉字组合逻辑深度接进卡牌系统

汉字系统

• 类似 日 + 月 = 明、人 + 木 = 休 这类组合逻辑已经在战斗中体现
• 双语方向明确：不仅给中文母语者玩，也考虑给非中文母语者学习

战斗呈现

• 中央 Babylon 3D duel stage
• 浮动伤害 / 护盾 / 治疗 / 能量数字
• 玩家和敌人的状态信息已经做成场内漂浮 3D 面板，而不是传统侧边 HTML 卡
• 手牌移到底部，不塞进 3D 中心舞台
• 手牌现在是简略版，hover / 拖拽时显示更完整的大卡
• 摄像机可以鼠标旋转，但不能缩放
• 舞台灯光已经被调成更明确的两束斜打聚光
• 信息栏增大过，模型缩小过，整体更像舞台 duel 演出

最近工程修复

• 首次进入战斗模糊问题修过
• 移动端进不去的报错修过
• 旧浏览器 / 手机兼容做过 fallback
• 默认 avatar glow 降低，并加过 3D Effects 控件
• 英文 / 中文双语 UI 骨架已经开始接入

工程结构

字海残卷

• 主要页面：hanzi-hero.html
• 主逻辑：src/game.js
• 已部分模块化到：
  • src/hanzi-hero/data.js
  • src/hanzi-hero/dom.js
  • src/hanzi-hero/utils.js
  • src/hanzi-hero/audio.js
  • src/hanzi-hero/rendering.js

仓颉之路

• 主要页面：cangjie-road.html
• 主逻辑：src/cangjie-road.js

启动器

• index.html
• launcher.css
• src/launcher.js
• src/launcher-background.js

当前整体判断

• 字海残卷 已经是一个“核心循环、敌人谱系、世界物件、进度系统、移动端适配、在线排行榜都存在”的完整动作原型
• 仓颉之路 也已经不是 barebones，而是有自己汉字 identity 的 deckbuilder 原型
• 整个项目现在最重要的价值，不只是“会显示汉字”，而是“汉字结构和语义已经变成玩法系统”

如果迁移到 Godot，最值得保留的核心

优先保留这几条设计主轴：

1. 首页启动器 -> 游戏二级菜单 -> 真正进入战斗 的层级体验
2. 字海 的偏旁 -> 合字 -> 词技 成长链
3. 字海 的多类型敌人和明确地面预警
4. 字海 的地图生态物件（草丛、树、纸、砚、宝箱等）
5. 字海 的角色差异化，尤其 侠 的近战身份
6. 仓颉 的“字形组合直接进入卡牌构筑”的核心
7. 双语 / 学习向定位

Godot 迁移追踪

• 当前目标不是做一个全新题材，而是把 hanziHero 网页原型里已经验证过的核心体验稳步迁移到 Godot 版本的 字海残卷。
• 长期迁移清单见 MIGRATION_CHECKLIST.md。
• 每次迁移优先落一个小到中等、低风险条目，并同步更新清单、README 和验证脚本。

Vercel 预览部署

• 仓库现在带了 vercel.json，把 GitHub 仓库接到 Vercel 之后，每次 push 都会自动触发一次 web 导出和部署。
• 构建命令是 ./scripts/export_web.sh，会先导入资源，再导出到 build/index.html，所以不需要把 build/ 产物提交进仓库。
• 在 Linux / Vercel 环境里，脚本会自动下载 Godot 4.6.1 编辑器和 export templates；本地如果已经装了 Godot，则直接复用本机安装。
• 本地手动验证可以先跑 ./scripts/check_scenes.sh 做场景冒烟，再跑 ./scripts/export_web.sh 做完整 web 导出。