开发日志3#

5 小时前9 浏览综合

一、项目基线

编组为 6 节，单节车长 19.5 米，车宽 2.80 米，总长 117 米。轨顶高度统一为 ballastHeight 减 0.15 再加 railHeight，也就是 0.30 减 0.15 加 0.176，等于 0.326 米。线路共 4 条，分别是地铁 1 号线 11.0 公里、地铁 2 号线环线 15.0 公里、地铁 3 号线跨江 19.2 公里、机场快线 21.8 公里。可驾驶车型三款，B 型地铁（银青涂装）、蓝翼机场快线、赤羽都市快线。坐标系使用 Y-up 左手系，+X 向右、+Y 向上、+Z 向前，长度单位是米。所有可调参数集中在 core/Config.lua，玩法代码只读不写。

二、上一轮已交付（背景）

一是列车外观真实化，包含曲面车头、弧形车顶、空心客室与驾驶室、独立车门、转向架与车轮、受电弓、双屏操纵台。二是连续滑动视角，驾驶视角支持鼠标拖动与手机滑动连续转头，松手保留观察角，R 键与 Home 键明确复位。三是外部环绕视角，外部视角真正绕车改变相机位置，使用 urhox-libs/Camera/ThirdPersonCamera 库。四是车库 3D 预览，可拖动缩放的真实 3D 预览，另外有独立的外观设定图展示，设定图不是 3D 模型。五是三款可驾驶车型，各有车头曲面样式与涂装。

三、本轮需求（用户反馈原文要点）

用户原话是：列车有的地方不灵敏，语音播报会有一些卡顿的效果，列车头没有轨道，地铁地底下的那个视角隧道可以往上提高一些，这个地铁也可以在地面上跑，也可以在隧道里面跑，游戏大厅几个页面字体给他规划好，不要有溢出。

拆解为六项：操作与滑动观察不灵敏；语音播报卡顿、断句、重复插播；车头前方与全编组下方没有轨道；地下隧道观察空间局促；地面、隧道、高架需要连续运行；大厅各页面文字溢出。

四、逐项实现

4.1 连续 3D 轨道，新增 world/Track.lua

问题根因是轨道原本挂在隧道环境根节点下，露天段整棵环境被禁用时，钢轨跟着消失。方案是让轨道独立成段池，按材质合批成 5 个 geometry，分别是轨头、轨腰轨底、轨枕、扣件、道床。每段 10 米，按 2 米线路采样摆放短钢轨与道床。轨枕间距 0.625 米，按全局里程格点生成，段边界不重复。轨距 1.435 米是两轨头内侧净距，轨头宽 0.075 米，所以轨头中心 X 坐标是正负 (1.435+0.075)/2，等于正负 0.755 米。环池按 modulo 回收，只重建被回收的段，不每跨段重建全池。

4.2 地面、隧道、高架连续切换

core/Route.lua 里 IsTapTapr 的判据，从旧的 y 减 groundY 大于 6，改为 y 大于等于 groundY 减 0.05，贴地即判为露天。world/Tunnel.lua 与 world/Surface.lua 改为按段自身里程判断地上地下，不再按车头禁用整棵环境根，洞口同屏可以同时有露天前部与地下尾部。world/Surface.lua 废弃整块大地面板，改按露天段生成左右地形，路基降到轨道下方不盖住轨顶。

4.3 隧道观察空间

隧道净半宽设为 7.60 米，净高设为 9.60 米，这是面向观车空间的宽松设计，不是真实工程断面。接触线固定 5.16 米，独立于顶板，抬高隧道不会让受电弓失去接触。自由环绕默认距离 20 米，FOV 62，不再贴近车头。

4.4 操作灵敏度

改动文件是 world/CameraRig.lua 与 ui/TouchControls.lua。灵敏度从 0.11 提高到 0.16 度每系统逻辑像素。PointerUp 会消费最终坐标，修复低帧率下最后一次 Move 缺失导致的丢段。惯性年龄阈值从 80 毫秒放宽到 160 毫秒，Cancel 不补位移。牵引拉杆的 LeverPointerUp 会先按 Up 的最终 Y 更新档位。

4.5 语音播报

改动文件是 core/Announcer.lua、core/AudioScene.lua、core/Sfx.lua。

卡顿根因已经确证：超速提醒每 6 秒重播一次，而现有双语语音长度已经超过 6 秒。中文 2.533375 秒加英文 3.932 秒，等于 6.465375 秒，超过 6 秒。所以下一次提醒会截断上一句英文。

修复方式是改成完整状态机，状态为 idle、zh、segment-gap、en、subtitle，同类 pending 去重，冷却从完整结束时刻开始算。暂停改用 PauseSoundType(SOUND_VOICE) 与 ResumeSoundType，真正冻结播放位置，不再用 SetGain(0) 假静音。运行期只取缓存，不再每帧解码或加载。29 个 WAV 文件，24kHz、16bit、单声道，总共约 4.153 MiB，配置了预下载组 audio_ready。

4.6 列车渲染合批，新增 world/TrainBatch.lua

同材质三角形真正拼接为单个 geometry，保留 UV、法线、切线。一期按车厢内区域分桶，二期把门叶四块门板合一。组件数从 1863 降到 457，同时保留 6 节车、48 个旋转轮、92 个门叶、双驾驶室屏幕以及各自动态材质。

4.7 大厅文字布局

ui/Theme.lua 统一了字号角色，包含 brand、page、title、body、small、button 等，以及 lineHeight。ui/Common.lua 的 Text 明确 width、自然换行、minHeight 撑高，按钮按真实 MeasureTextWidth 定宽。各页面标题与徽章分槽，KV 键值独立分列，低高度主菜单与加载页可滚动。ui/Widgets/RouteMap.lua 的自绘站名改用实际字形 bounds，分左右标签栏加引线，先画点线后画字。

五、关键问题与根因

第一，露天钢轨消失，根因是轨道挂在隧道根节点下随环境被禁用，修复方式是轨道独立成段池。

第二，贴地被判成地下，根因是 y 减 groundY 大于 6 的判据过严，改为达到地表即露天。

第三，洞口整片闪换，根因是按车头状态切换整棵环境，改为按段自身里程分类。

第四，露天被巨大灰面遮挡，根因是 Node:SetEnabled(false) 不会隐藏子节点上的渲染组件，环境段改用 SetDeepEnabled。

第五，超速播报自截断，根因是语音 6.46 秒大于 6 秒重播间隔，改为去重加完整结束冷却。

第六，外挂视角穿隧道墙，根因是按车头判断地下但眼位在后方，改为按实际眼位所在段夹断面。

第七，低帧率丢末段输入，根因是 Up 携带的最终坐标未被消费，改为 PointerUp 先消费最终位置。

其中第四条是引擎已知陷阱，已经记录在 engine-docs/gotchas/index.md：Component:IsEnabledEffective() 只检查直接父节点，不递归检查祖先节点。

六、验证记录（本地离屏 Runtime）

_metro_validate 覆盖轨道、环境、相机、合批、门动画，共 268 项断言，PASS，错误 0。

_audio_validate 覆盖序列、冷却、暂停、设置、无输出边界，共 60 项断言，PASS，错误 0。