10 KiB
冒险运行时开发经验沉淀
日期：2026-03-24
1. 这轮工作主要覆盖了什么
这轮迭代不是单点 UI 修改，而是同时改了 4 条链路：
- 战斗演绎链路：近战突进、远程施法、投射物/特效、受击结算时机。
- 探索链路：向前探索、呼喊、NPC 离队、切换场景时的新 encounter 生成与入场动画。
- NPC function 链路：聊天、招募、观察征兆、交易、离队、上下文注入边界。
- 面板链路：队伍页、角色详情、背包页、移动端空间分配、入口 icon 语义。
这类项目最重要的判断是： 很多需求表面看是“改个界面”或“改句文案”，实际同时影响状态机、动画时序、AI 提示词、实体生成规则和移动端布局。
2. 这轮最值得沉淀的结论
2.1 function 的职责边界必须先定死
后面事实证明，只有少数 function 应该负责生成新 encounter：
idle_explore_forwardidle_call_outnpc_leave- 进入新场景
其他 function 如果也偷偷新增 NPC、怪物、宝箱，后面一定会出现这些问题：
- 剧情上下文越来越乱
- 场景上实体数量失控
- 玩家以为“聊天/招募/观察”也会强行推进世界
- AI 生成内容和本地规则互相打架
经验： 先定义“谁能创造世界实体”，再写文案和动画。
2.2 动画完成点必须和数值结算点绑定
这轮一个关键修正是： 攻击特效播放完后，受击目标才扣血。
如果不这样做，玩家看到的就是：
- 特效还没打到，血条先掉了
- 投射物还在飞，目标已经结算
- dash 还没到位，攻击已经命中
经验： 战斗系统里不能只写“播放动画”，必须写清楚：
- 起手阶段是什么
- 位移阶段是什么
- 命中阶段是什么
- 哪个阶段结束后才改数值
2.3 视觉素材选择要按“语义 + 小尺寸可读性”来做
这轮做过两类视觉判断：
- 战斗特效素材该怎么挂到角色/技能上
- 冒险页入口 icon 应该换成什么
经验不是“素材越花越好”，而是：
- 先看素材本身表达的动作语义
- 再看缩小到按钮尺寸后是否还能一眼看懂
- 最后才考虑风格统一
例如：
- 队伍入口用“盔甲”不如用“盾牌”更像角色/编队
- 背包入口用真正的包袋图，比木板式 HUD 图更直观
- 远程施法不移动时，特效就必须承担“动作已经发生”的视觉职责
2.4 角色型 NPC 和普通 encounter 不能混着处理
这轮踩过的坑说明：
- 可扮演但未入队的 NPC
- 已入队同伴
- 普通场景 NPC
这三者虽然都可能显示为 NPC，但数据完整度、立绘来源、详情页能力并不一样。
经验：
- 角色型 NPC 要按角色数据链路渲染
- 普通 NPC 要按 encounter/NPC state 渲染
- 详情弹窗必须对缺失字段做空值保护
否则就会出现点击小人直接报 map 相关错误这类问题。
2.5 角色和同伴的朝向/位移必须彼此独立
idle_observe_signs 的修正说明了一件事：
如果主角和同伴在 transform、朝向、随机停顿上仍然存在隐含父子级关系，最后视觉表现一定不自然。
经验：
- 主角随机转向和同伴随机转向要分别计算
- 位置、朝向、停留时长都要独立采样
- 不要让父容器顺手把子角色的朝向也带过去
这条经验同样适用于：
- 招募入队时的新同伴 dash
- 多角色待机观察
- 场景内多实体同步演绎
2.6 大模型负责“推理与叙述”，本地规则负责“世界变更”
这轮对 npc_chat、npc_recruit、idle_observe_signs 的调整，本质上都指向同一个原则：
- 大模型可以生成观察结果、聊天内容、氛围描述
- 大模型不应该偷偷新增实体、替玩家做决定、绕开本地规则结算
经验：
- 聊天生成要明确禁止提及其他 function 行为。
- 招募对话可以引导到成功入队，但最终入队仍应由本地流程触发。
idle_observe_signs可以走大模型推理，但写入剧情上下文的内容要可控。npc_recruit这种流程不要顺手给下次推理塞一个“新 NPC”。
一句话总结： AI 可以解释世界，但不能私自改世界。
2.7 移动端面板要优先保信息密度，不要保装饰
这轮背包和队伍页的调整很能说明问题：
- 队伍页只保留成员列表
- 成员详情放到弹窗
- 背包页去掉多余标题、提示文案、厚重背景框
- 装备信息移到角色详情，不和背包抢空间
经验：
- 主面板只放“高频扫读信息”
- 低频详情放二级弹窗
- 任何重复信息都要尽量去重
在小屏上，空间不是拿来“显得完整”的，而是拿来“保证可操作”的。
3. 这轮最典型的踩坑记录
3.1 encounter 生成距离只改一处是不够的
一开始只是把某个函数里的怪物生成位置往后挪，但后来发现：
- 其他会生成 encounter 的 function 仍然太近
- 新场景进入时也可能直接出现在屏幕里
经验： “从屏幕外进场、要走 4 秒距离”必须是统一约束，不是某个函数里的特判。
3.2 详情文案改源头不一定等于改到了最终显示层
这轮“选项小字太长”的问题最后证明：
真正该改的是渲染层显示的 detailText，而不是只改某个上游数据源。
经验： 用户说“没有生效”时，要优先检查最终渲染层，而不是只检查中间数据。
3.3 新同伴入队时，尺寸问题本质是缩放基准不统一
招募流程里位置正确但大小不对，说明问题不在路径，而在：
- 新同伴使用的缩放基准
- 主角扮演角色使用的缩放基准
不一致。
经验： 只要角色加入到主队镜头体系里，尺寸基准必须复用主角/同伴那套规则，不能临时另开一套。
3.4 背包和角色详情职责不清，会持续挤压移动端布局
这轮背包页一度同时承担：
- 物品网格
- 装备总览
- 装备卸下
- 详情查看
最后结果就是移动端空间不够、信息层级混乱。
经验：
- 背包负责“物品”
- 角色详情负责“装备”
职责一旦分清，后面很多 UI 冲突会自然消失。
4. 可复用的开发方法
4.1 新增一个 function 前，先问 6 个问题
- 它会不会生成新 encounter？
- 它会不会写入后续推理上下文？
- 它的动画分几段？
- 哪一刻才算真正生效？
- 哪些内容由 AI 生成，哪些必须本地决定？
- 它是否需要从屏幕外入场？
这 6 个问题先答清，后面返工会少很多。
4.2 配战斗动画时，至少明确 4 个时点
- 起手
- 位移/施法
- 特效命中
- 扣血/击退/结算
特别是：
- 近战攻击前的 dash
- 远程不移动但要挂特效
- 受击延后到命中特效之后
都属于这套时点设计。
4.3 做素材替换时，不要只看资源名
正确顺序更接近：
- 打开素材看实际形状
- 判断它在当前语义里是不是“最像这个功能”
- 缩到真实 UI 尺寸再看一遍
- 再决定 active/inactive 怎么处理
4.4 做聊天流式界面时，反馈一定要插到正在发生的流里
这轮加“好感度 +x”提示后，更明确了一件事：
- 系统反馈不应该只藏在最终结果
- 要插进聊天进行中的体验里
- 文本流超出剧情框时要自动滚动
否则用户会错过真正重要的状态变化。
5. 以后继续做这类需求时，建议坚持的原则
- 先收拢 function 边界，再改剧情文案。
- 先确定动画结算时序，再接特效素材。
- 先做本地规则兜底，再让大模型生成文本。
- 先保证移动端可扫读，再考虑装饰性面板。
- 先复用已有角色/场景坐标体系，再做个别修正。
- 先看最终显示层，再判断“改动是否生效”。
6. 这轮最重要的一句话总结
这类 AI 冒险 RPG 的开发，最难的不是“把功能做出来”，而是：
让 function 边界、世界状态、视觉演绎、移动端面板和大模型文本在同一套规则下稳定协作。
7. 聊天输入区布局补充经验
7.1 聊天框变大时，要优先增加“消息展示区”而不是只放大输入框
- 玩家感知里的“聊天框高度”主要来自消息气泡和剧情滚动区，不是输入栏本身。
- 如果只把输入框做高，实际会压缩选项区和底部按钮区，移动端反而更挤。
- 更稳妥的做法是： 先让剧情/聊天滚动区在剩余空间里拿到更高的伸缩优先级，再微调输入条高度和底部留白。
- 移动端不要随意给聊天区写死过大的最小高度，否则很容易把选项按钮和自定义输入一起挤出首屏。
7.2 底部输入区要向安全区贴近，但不能直接贴死
- 自定义输入要更贴近屏幕底部，应该缩小底部控制区的额外 padding，而不是去掉安全区。
env(safe-area-inset-bottom)仍然要保留，否则刘海屏、手势条机型会出现输入框被顶起或遮挡的问题。- 正确方向是： 保留安全区补偿，只减少设计层自己额外加上的底部留白。
7.3 底部操作区下沉时，要同步增加和聊天区之间的呼吸感
- 当“队伍 / 背包 / 换一换 / 退出聊天 / 自定义输入”整体下移后，上下区块更容易挤在一起。
- 这时要略微增加聊天区和操作区之间的垂直间距，保证视觉层级仍然清楚。
- 目标不是做出更厚的面板，而是让用户一眼分清： 上面是正在发生的对话，下面是马上可点的操作。
8. 战斗态底部面板布局经验
8.1 战斗态不应继续保留剧情框占位
- 战斗画面里玩家关注的是敌我状态与可执行动作，剧情文本框如果继续占据底部高度，会直接挤压操作按钮。
- 战斗态应隐藏剧情框组件，只保留操作区；战斗结果叙事可放到结算或下一次非战斗剧情里展示。
8.2 战斗选项数量要由剩余高度决定
- 不要固定渲染全部战斗选项，否则移动端低高度屏幕会把按钮挤出可点击区域。
- 更稳妥的做法是测量底部操作区可用高度，用单个按钮的最小高度和间距计算本帧可显示数量。
- 至少保留 1 个操作，避免极端高度下玩家看不到任何战斗入口。