配套文档:游玩问题总表-2026-10-25.md(12 条待修 + 1 条已修)
本方案按「先止崩、再修手感、最后补文案」三批推进,每条都给出文件:行 → 改法 → 风险 → 验证
| 批次 | 内容 | 条数 | 建议时长 | 是否阻断发布 |
|---|---|---|---|---|
| A 阻断 | QA-01 冻结、QA-02 信标台取件区、QA-08 长按互动偶发失效 | 3 | 1.5h | 是(评审第一眼就是"卡住") |
| B 手感 | QA-03 检查点丢资料、QA-04 冲刺刹车、QA-05 跳跃判定、QA-06 陷阱预警 | 4 | 2h | 否,但直接影响重玩意愿 |
| C 打磨 | QA-07 动线、QA-09 破障提示、QA-10 暴露释义、QA-11 总结入口、QA-12 阈值 | 5 | 1.5h | 否 |
修改点在src/,改完必须跑node src/core/verify-core.mjs+node scripts/verify-world.mjs+node scripts/build-game.mjs,否则dist/与实际不一致(发布包用的是dist/)。
已排除:焦点在按钮(activeElement=CANVAS)、碰撞体(barriers=[])、平台边缘(grounded=true、y=490)。 新发现:当前 frame() 的世界更新被加了一道 !document.hidden 硬闸;一旦浏览器把页面判为隐藏(后台标签/最小化/部分无头环境),世界会静默停更——画面保持最后一帧、screen 仍是 none、没有任何暂停提示。这与"卡住但看起来一切正常"的现象完全吻合。
改法 1(src/main.mjs,删掉静默闸)
- if(world&&renderer&&['none','command'].includes(ui.screen)&&!document.hidden){
+ if(world&&renderer&&['none','command'].includes(ui.screen)){
安全性:input.mjs的visibilitychange → lost-focus已经会在隐藏时暂停并弹出「暂停」面板,所以这道闸是重复的,且它的失败模式是"静默"。
改法 2(src/main.mjs frame 加看门狗,兜住未知根因)
// 放在 frame() 顶部,模块级声明 let wdTime=0, wdAt=0;
if(world&&ui.screen==='none'&&core.view().phase==='playing'&&!mustStayPaused()&&now-wdAt>600){
const t=world.time||0;
if(t<=wdTime+0.05){ // 0.6s 内世界时间没走
console.warn('[watchdog] world stalled',{t,screen:ui.screen,phase:core.view().phase,dash:world.player.dashCooldown});
core.setPaused(false);input.clear(); // 强制回到可操作态
}
wdTime=t;wdAt=now;
}
改法 3(src/game/input.mjs:18,移动键不受按钮焦点影响)
- const action=this.actionFor(event.code);
- if(action&&!event.target?.closest?.('button')){
+ const action=this.actionFor(event.code);
+ const movement=['left','right','up','down','jump','dash','interact'].includes(action);
+ if(action&&(movement||!event.target?.closest?.('button'))){
风险:移动键在菜单里也能触发 → 但菜单打开时 getScreen()!=='none',sample() 的下游(frame 的世界块)本来就不吃输入,安全;且这样还顺带修掉「点完剧情按钮后用键盘走不动」。 验证:QA_MODE=import5 node output/playthrough/play.cjs,看日志里不再出现 walkTo 卡死 ... phase=playing screen=none barriers=[]。
src/game/rooms.mjs 第5章副房间:
- items:at(c.items,[['final-data-1',1040,270],['final-data-2',1120,270],['final-data-3',1180,270]])
+ items:at(c.items,[['final-data-1',1000,270],['final-data-2',1060,270],['final-data-3',1120,270]])
- guards:[{id:'evacuation-upper-guard',x:1160,y:270,minX:1030,maxX:1200,speed:48}]
+ guards:[{id:'evacuation-upper-guard',x:1175,y:270,minX:1140,maxX:1210,speed:48}]
效果:三块数据全部落到巡逻带之外(1140 起点),东侧警报(x=1205)仍然惩罚贪走位;玩家有"贴着信标取件"的稳妥解法。 风险:章节难度下降(原本是压力设计);如果这是刻意设计的"必挨打",可改为只挪 final-data-3 → 1130。 验证:QA_MODE=demo5,日志里应出现 背包:[3 块] health=100(不再掉血)。
根因是 mustReleaseInteract 只能靠"下次读到的 input.interact===false"来清,而 input.clear()/暂停恢复的时序会把它一直卡住。
改法(src/game/input.mjs keyup + src/main.mjs 接线)
// input.mjs:keyup 里补一条
window.addEventListener('keyup',event=>{
this.keys.delete(event.code);
if(this.actionFor(event.code)==='interact')this.onAction('interact-released',{});
});
// main.mjs 的 act() 里加一个分支(放在 switch 里任意位置)
case 'interact-released':if(world)world.mustReleaseInteract=false;break;
风险:极低(只是让"松手"这个事实立刻生效)。 验证:QA_MODE=import5,日志里不应再出现 [重试] 换房未生效 / 广播未能关闭。
改法(src/main.mjs worldEvent,拾取后立即落检查点)
+ if(type==='pickup')makeCheckpoint((world.currentRoom?.name||'房间')+' · 拾取后');
makeCheckpoint内部已有if(!active()||evacuationStarted)return保护;每章最多 6 次写盘,可接受。
验证:第5章取 1 块后故意踩陷阱死亡 → 检查点重试 → 背包里那块应还在。
改法(src/game/world.mjs,给冲刺后 0.18s 强摩擦)
this.player={...dashCooldown:0,dashTime:0,hurtUntil:0,climbing:false};
+ // 新增字段
+ this.player.slideUntil=0;
- if(input.dashPressed&&p.dashCooldown===0){p.dashTime=.22;p.dashCooldown=2.8;...}
+ if(input.dashPressed&&p.dashCooldown===0){p.dashTime=.22;p.dashCooldown=2.8;p.slideUntil=this.time+.18;...}
- const wanted=axis*speed,maxChange=(axis?2500:3000)*dt;
+ const wanted=axis*speed,maxChange=((this.time<(p.slideUntil||0))?9000:(axis?2500:3000))*dt;
效果:滑行从 117px 降到约 35px,review-data-4 那种"冲下平台"不再发生。 风险:冲刺手感变"顿";若想保留惯性感,把 9000 调成 6000(滑行约 60px)。 验证:第3章机房连续两次冲刺后应停在 (≈500,490) 而不是 (654,600)。
改法(src/game/lesson-bridge.mjs:223)
- const crossedRight = rightGap >= 20 && this.jump.startX <= from.x + from.w + 3 && current.x >= to.x + 2;
+ const crossedRight = rightGap >= 20 && current.x >= to.x + 2;
- const crossedLeft = leftGap >= 20 && this.jump.startX >= from.x - 3 && current.x <= to.x + to.w - 2;
+ const crossedLeft = leftGap >= 20 && current.x <= to.x + to.w - 2;
判定改成"从 A 平台起跳、落到 B 平台"即可,不再限制起跳像素。 风险:无(仍然要求 to.id!==from.id 且 minY 有真实腾空高度)。
改法(src/game/world.mjs 陷阱循环)
- trap.active=!this.expanded||(this.time+(trap.x%5))%4<2.5;
- if(trap.active&&Math.abs(this.player.y-trap.y)<12&&this.player.x>trap.x&&this.player.x<trap.x+trap.w){this.hurt(20);this.triggerAlarm(trap.id);}
+ const cycle=(this.time+(trap.x%5))%4;
+ trap.active=!this.expanded||cycle<2.5;
+ // 下次通电前 0.45s 预警:裂纹 + 提示音
+ trap.warning=this.expanded&&cycle>=3.55&&cycle<4;
+ if(trap.warning&&!trap.warned){trap.warned=true;this.cue('alert',trap.x+trap.w/2,trap.y-6);this.emit('sound',{name:'guard-warning'});}
+ if(cycle<3.55)trap.warned=false;
+ if(trap.active&&Math.abs(this.player.y-trap.y)<12&&this.player.x>trap.x&&this.player.x<trap.x+trap.w){this.hurt(14);this.triggerAlarm(trap.id);}
渲染层(scene-renderer.mjs)若有绘制 trap 的分支,按 trap.warning 加一层描边/闪烁即可;没有也不影响逻辑。 风险:伤害 20→14 会改变评分压力(alarms 不变),如不想动数值就只加预警。
| 编号 | 改法 | 文件 |
|---|---|---|
| QA-07 | 副房间到达点从 {x:85,y:600} 改到资料侧(第2/3章建议 {x:1040,y:600},出口同步挪到 x=1170),或两个机房各加一条中部梯路 | src/game/rooms.mjs pair() |
| QA-09 | 路线为 null 时区分文案:if(!route)return {ok:false,reason:${actor.name} 还在障碍另一侧,正在绕行(约 ${Math.ceil(distance(actor,target)/195)}s)} | src/game/world.mjs actionGeometry |
| QA-10 | 结算面板「暴露」加说明:<span title="公开指令/公开交付/警报 各计 2 点,上限 20">暴露</span> + 底部一行 tiny-note | src/ui/ui-v3.mjs renderChapterResult |
| QA-11 | 通关后标题加「查看航程总结」:renderTitle 里 completed 时追加 btn('campaign-summary','查看航程总结','text-button');main.mjs 的 act() 加 case 'campaign-summary':updateUI();ui.show('campaign-result',{core:core.view()});break; | ui-v3.mjs + main.mjs |
| QA-12 | campaignGrade:score>=360?'A'(当前 375,实测正常通关 369–371 卡在 B) | src/core/chapters.mjs:121 |
# 1) 逻辑层
node src/core/verify-core.mjs
node scripts/verify-world.mjs && node scripts/verify-maps.mjs && node scripts/verify-art.mjs
# 2) 构建 + 部署包一致性
node scripts/build-game.mjs && node scripts/verify-build.mjs
# 3) 真机回归(本套驱动)
node output/playthrough/play.cjs # 整局 5 章
QA_MODE=demo5 node output/playthrough/play.cjs # 第5章(验 QA-02/QA-08)
QA_MODE=import5 node output/playthrough/play.cjs # 第5章 + 战役总结
必须复现确认的三条(改完应消失):
walkTo 卡死(…) screen=none barriers=[](QA-01)[重试] 换房未生效 / 广播未能关闭(QA-08)第5章数据未拿齐 + health 掉到 35 以下(QA-02)仓库现在有 262 行未提交改动(main.mjs / world.mjs / ui-v3.mjs / rooms.mjs 都在别人手上动着)。建议:
git stash 或提交当前进度,锁定基线;要我现在就动手吗? 告诉我「按 A 批开始」即可,我改完直接把 git diff 和验证日志贴给你。
按拍板结果执行:QA-02 保留紧张设计不改、QA-12 A 线降到 360、QA-07 动线不动。
| 编号 | 文件:行 | 改动 |
|---|---|---|
| QA-01 | main.mjs frame() | 新增看门狗:screen=none && phase=playing 且世界时钟停滞 >1.2s → 打警告并 setPaused(false)+input.clear();隐藏页面持续 0.8s 补一次「暂停」面板(保留"隐藏不重绘"的既有契约,未删 !document.hidden) |
| QA-01 | input.mjs keydown | 方向/爬梯/冲刺/互动键不再被"焦点在 button"吞掉(Space 仍交给按钮,避免破坏菜单键盘激活) |
| QA-08 | input.mjs keyup + main.mjs | 新增 interact-released 动作:一松 E 立刻清 mustReleaseInteract |
| QA-03 | main.mjs worldEvent | type==='pickup' 立即 makeCheckpoint(房间+' · 拾取后'),死亡回档不再丢已捡资料 |
| QA-04 | world.mjs 玩家/冲刺 | 新增 slideUntil:冲刺后 0.18s 减速度 3000→9000,滑行 117px → ~35px |
| QA-05 | lesson-bridge.mjs | 跳跃通过条件去掉 startX 限制,只判"从 A 台跳到 B 台" |
| QA-06 | world.mjs 陷阱 | 通电前 0.45s trap.warning:scan-grid 波纹 + guard-warning 提示音(伤害与判定未改) |
| QA-09 | world.mjs actionGeometry | 路线不可达文案改为「X 还在障碍的另一侧,正在绕行(约 N 秒)」 |
| QA-10 | ui-v3.mjs 结算 | 「暴露」加 tooltip + 一行释义 |
| QA-11 | ui-v3.mjs + main.mjs | 通关后标题新增「查看航程总结」→ 新动作 campaign-summary |
| QA-12 | chapters.mjs:121 | campaignGrade A 线 375 → 360 |
未改:QA-02(信标台取件压力是设计)、QA-07(副房间动线不动)。
| 检查 | 结果 |
|---|---|
src/core/verify-core.mjs | PASS(事务/重试/资源/500 分制/存档恢复) |
scripts/verify-input.mjs | 5 项 PASS(含"菜单 Space 保持原生按钮行为"、"1000 次焦点/可见性中断") |
scripts/verify-world.mjs | PASS,五章物理输入模拟通关 |
scripts/verify-main-flow.mjs | 8/8 PASS(含"隐藏页面不重绘"契约) |
scripts/verify-runtime-save.mjs / verify-experience.mjs / verify-story-flow.mjs / verify-lesson-bridge.mjs | 13 / 18 / 18 / 12 全 PASS |
scripts/verify-maps.mjs / verify-mission-completeness.mjs / verify-rendering.mjs | PASS |
scripts/build-game.mjs + verify-build.mjs | built 148 files, missing 0 |
真机(QA_MODE=demo5) | 页面异常 0 次(改前 351 次),第5章跑到撤离 60s 倒数并成功登艇 |
this.cue('alert', …),但 assets/runtime-catalog.json 的 animations 只有 water-dash / axe-impact / paper-decoy / scan-grid 四组 —— 渲染层直接抛 Unknown effect: alert,每帧一条 P0 异常(真机跑了 351 条)。已改为 scan-grid。cue(<group>),group 必须已存在于 catalog 的 animations 里;这类错误 verify-*.mjs 抓不到,只有真机跑才会暴露。core.view().phase;若确认为"无遮罩暂停态",应在 setPaused(true) 处统一收口。demo5 已证 75/A)。这是脚本走位问题,不是新缺陷。git diff 过一遍再封板。