Genarrative/docs/experience/MOBILE_UI_DEV_EXPERIENCE.md

奇幻酒馆 UI 开发经验沉淀

1. 总体原则

1.1 先保证移动端成立，再兼容网页端

• 入口页、世界选择、角色选择、冒险页、弹窗面板，都要先按手机竖屏去定义信息密度。
• 网页端只做“放宽容器、增加留白、补充 hover”，不要反过来让桌面布局压垮手机体验。
• 任何区域如果在移动端需要滚动，必须明确谁滚动，不能让整页和局部同时争夺滚动。

1.2 游戏 UI 要优先“状态清晰”，而不是“文案很多”

• 开始页应该像主菜单，不像产品介绍页。
• 角色选择页应该像角色选择器，不像角色说明书。
• 冒险页应该像战斗/剧情操作台，不像文档阅读器。

1.3 一屏内的层级顺序要稳定

• 上半部分：画面演出。
• 中间部分：剧情或核心信息。
• 底部：操作按钮。
• 玩家必须能快速判断“我在看什么、下一步点哪里”。

2. 入口页经验

2.1 开始页

• 极简化是对的。
• 当前实践证明：开始页只保留“开始游戏”和“开发团队”两个主按钮，体验明显更像游戏。
• 游戏名和英文副标题可以保留，但不要再加长段描述。

2.2 世界选择

• 纵向焦点轮播比普通列表更适合移动端。
• 当前居中的卡片应该最大、最清晰、最亮；上下卡片缩放和透明度随滚动连续变化。
• 世界确认动作应该绑定当前聚焦卡，而不是每张卡都塞太多按钮。

2.3 角色选择

• 横向轮播是正确方向。
• 中间卡片应承担“主视觉 + 主要信息”。
• 左右卡片只做预览，不需要承载完整信息。
• 左右卡片倾斜方向一定要符合透视直觉： 左侧卡片向左外倾，右侧卡片向右外倾。
• 中间卡片不要出现任何模糊，否则会破坏“当前选中”的确认感。

3. 角色选择页经验

3.1 聚焦卡的表现

• 中间聚焦卡用角色 run 动画是有效的，能明显提升“角色活着”的感觉。
• 但动画资源和静态立绘的锚点通常不一致，必须单独做位置与缩放修正。
• 结论： 动画版角色不要直接复用静态图样式，要单独给 transform、height、transform-origin。

3.2 信息区要紧凑

• 角色数值和角色背景应该放在轮播下方，但必须压缩高度。
• 如果下方面板过高，会直接破坏上半部分轮播体验，尤其在手机上。
• 删除背景面板里的额外动画模块是正确的，因为它与主轮播重复抢视觉焦点。

3.3 文案层级

• 页面标题只保留一句： “选择你扮演的角色”
• 不要再强调 CHARACTER SELECT 之类的开发向分类标签。
• 聚焦卡下方直接显示角色名，比把名字只放在卡片底部更直观。

3.4 按钮位置

• “确认选择”必须放在角色轮播和信息区之后，作为页面最后的主动作。
• 按钮不宜过宽过高，否则会抢轮播的视觉重心。

4. 冒险页经验

4.1 剧情区必须自适应

• 剧情文本区不应该写死高度。
• 正确做法是： 让它自动填满“上方画面下缘”和“底部按钮区上缘”之间的剩余空间。
• 这样才能同时保证：
  1. 上方画面一屏可见
  2. 下方三个选项一屏可见
  3. 中间剧情尽量大

4.2 底部操作区必须锚定到底

• 队伍、背包、换一换、选项列表，都应该属于底部控制区。
• 用户会天然在屏幕底部寻找交互入口，尤其是手机。
• 因此： 不要把这些按钮漂在中间，不要让剧情区把它们挤走。

4.3 队伍与背包不应打断主流程

• 在冒险页内，队伍和背包更适合“弹出面板”而不是“切换整页”。
• 原因：
  1. 不会打断当前剧情阅读
  2. 用户返回成本更低
  3. 操作像手游副面板，更符合预期

4.3.1 弹出确认面板不能透明

• 删除作品、发布后分享、确认离开等关键弹窗必须有实体面板底色，不能只靠透明背景、毛玻璃或遮罩承载内容。
• 通过 portal 挂到 body 的平台弹窗必须在遮罩层补齐平台主题类，否则主题变量会脱离页面容器，轻则颜色漂移，重则面板背景看起来透明。
• 移动端关键确认弹窗优先居中显示，并保留 max-height + 内部滚动，避免被底部导航、安全区或底部抽屉布局遮住。

4.4 图标优于文字按钮

• 在底部工具区，队伍/背包改成 icon 后更紧凑。
• 但必须保留 aria-label，保证语义清晰、后续也方便测试。

4.5 冒险主场景不要挂右上角账号悬浮条

• 冒险页右上角属于画面演出和战斗/剧情信息的高频观察区。
• 全局账号信息条挂在这里，会直接压住场景、敌人血条或顶部提示，手机端尤其明显。
• 结论： 账号入口应收回平台首页、个人页或设置面板，不要在实际冒险主场景常驻悬浮显示。
• 当前仓库已进一步收口为： 不再提供右上角全局账号悬浮条，统一只保留页面内入口与独立账号面板。

4.6 冒险主场景双方角色必须按画面中线镜像

• 非滚动画面的交谈、预览、单体对峙态，主角和对面角色不能分别用左右边距、世界坐标和角色宽度重复推算。
• 正确做法是先定义“角色容器中心距离画面中线”的统一间距，再让主角中心落在中线左侧、对面角色中心落在中线右侧。
• 角色容器宽度、角色图片缩放和左右朝向必须各自独立处理，不能用额外 left inset 去修正角色图片，否则会破坏左右对称。
• 自定义图片 NPC、模板角色和组合式 NPC 都要进入同一 112px 场景容器，再按各自素材锚点做场景缩放，保证视觉大小不漂移。

5. 队伍面板经验

5.1 移动端成员列表不能太“卡片化”

• 如果每个成员都再套一层大边框卡片，手机上会显得很挤。
• 更好的方式是直接在主面板里陈列成员，弱化分隔、强化内容。

5.2 队伍列表展示什么

• 头像
• 姓名
• 称号
• 身份标记（领队/同行）
• HP / MP

5.3 队伍详情弹窗

• 弹窗必须可滚动。
• 弹窗宽度不宜太大，手机优先单列或偏单列。
• 技能、装备、属性三个区块保持稳定结构，便于扫读。

6. 背包页经验

6.1 格子数要优先适配手机

• 手机端格子间距要小一号。
• 图标尺寸和分类角标要跟着缩小。
• 目标不是“每个格子信息很多”，而是“单屏能看更多格子”。

6.2 背包详情弹窗

• 手机端改成单列/窄宽度布局更合理。
• 详情窗里的信息顺序建议固定：
  1. 名称与类别
  2. 品质与数量
  3. 大图标
  4. 说明
  5. 标签

7. 样式与动画经验

7.1 轮播动画要连续，不要离散

• 滚动时应根据“当前位置与当前卡片中心的距离”实时计算：
  • scale
  • opacity
  • rotate
  • translate
• 不要做成“翻页后才跳变”的效果。

7.2 焦点卡与非焦点卡的职责要不同

• 焦点卡负责可读性与确认感。
• 非焦点卡负责预告与空间深度。
• 所以焦点卡不该模糊，非焦点卡可以轻微降透明度、缩放、偏移。

7.3 资源锚点要单独校准

• 静态立绘和动画帧经常不是同一锚点。
• 只要切换成动画，就需要重新调：
  • 高度
  • Y 偏移
  • 缩放
  • transform-origin

8. 工程经验

8.1 组件要继续拆

• 本轮重构证明，把入口页、冒险页、队伍页、背包页拆成独立组件是正确的。
• 后续新增 UI 需求时，应优先落在：
  • GameShell.tsx
  • AdventurePanel.tsx
  • CharacterPanel.tsx
  • InventoryPanel.tsx

8.2 不要相信“服务已经在跑”

• 这轮出现过“端口上有进程，但浏览器仍然拿到旧模块”的问题。
• 实际经验：
  1. 要检查 src 文件内容
  2. 要检查 dev server 实际返回的模块内容
  3. 要确认启动脚本是否是当前项目真正使用的脚本

8.3 本项目当前开发服务入口

• 本地正确启动脚本是： node scripts/vite-cli.mjs --port=3000 --host=0.0.0.0
• 历史脚本或旧进程会导致“代码已改但 UI 看起来没变”的假象。

9. 后续建议

9.1 可以继续统一中英混杂文案

• 当前部分新旧文本仍有历史遗留字符问题。
• 如果后面继续做 UI 精修，建议单独做一轮文案清洗。

9.2 可以把轮播抽成通用组件

• 世界纵向焦点轮播
• 角色横向倾斜轮播
• 这两套逻辑已经足够稳定，适合后续抽成通用 hook 或通用组件。

9.3 可以补移动端安全区适配

• 当前已经偏移动端优先，但还可以继续加：
  • safe-area-inset-bottom
  • safe-area-inset-top
  • 更细的竖屏断点处理

10. 一句话结论

这一轮最关键的经验是： 游戏 UI 的移动端优化，本质不是把元素缩小，而是重组视觉重心、固定操作锚点、让焦点内容在一屏内自然成立。

10.1 可扮演角色形象预览保持 1:1

• 可扮演角色的形象预览容器统一使用 1:1 方形，入口选择轮播、角色资产工坊和结果页角色卡片都不能用纵向长卡片去拉伸预览图。
• 预览图片本身使用 object-contain，保证 AI 生成主形象、模板像素角色和运行时动画都在方形容器内完整显示，不裁切角色主体。
• 卡片可以在方形预览下方放角色名、称号、状态等信息，但这些文本区不能反向影响预览区比例。
• 编辑角色弹窗也遵循同一规则：移动端不能用固定高度压扁预览区，预览容器应随宽度保持 aspect-square。

10.2 运行画面怪物锚点按视觉底边校准

• 对战预览里主角和对手要沿画面中线成对出现，但纵向不能只共用一个 bottom 常量。
• 怪物精灵帧的空白、体型和脚底位置差异很大，运行画面应按帧高分档下沉，让怪物视觉底边落在主角同一条地面线上。
• 后续新增怪物资源时，先检查红圈标注的实际落点，再调整锚点分档或单怪物偏移，避免出现“悬在地面上方”的状态。
• 自定义世界里敌对角色已经先作为场景 NPC 存在，即使它同时携带 characterId 和 monsterPresetId，画布也不能直接沿用模板角色的 groundOffsetY；只要 encounter 自身有 imageSrc 或 visual，就按场景 NPC 自定义形象锚点处理。
• 幕预览运行时还会构造“无 characterId、但有 visual 的场景 NPC”，这类和平相遇分支同样必须套用场景 NPC 自定义形象锚点，否则会停在画面中上部。

10.3 移动端固定整页画布缩放

• 主站移动端以固定游戏画布体验为准，入口 viewport 需要锁定 minimum-scale=1.0、maximum-scale=1.0 和 user-scalable=no，同时保留 viewport-fit=cover 适配安全区。
• 浏览器仍可能通过 iOS gesture* 或多指 touchmove 触发整页缩放，因此主站启动入口应统一调用 lockMobileViewportZoom() 拦截页面级捏合与快速双击缩放。
• 不要在每个画布组件里重复注册缩放拦截；单指滚动、点击、拖拽应继续留给具体页面和玩法处理。