← 返回记录总览

问题修复方案 · 2026-10-25

来源:_归档-20261026/游戏-output__playthrough/问题修复方案-2026-10-25.md · 14.3 KB


《鲸鱼魔盗团》问题修复方案

配套文档:游玩问题总表-2026-10-25.md(12 条待修 + 1 条已修)
本方案按「先止崩、再修手感、最后补文案」三批推进,每条都给出文件:行 → 改法 → 风险 → 验证

零、总体判断

批次内容条数建议时长是否阻断发布
A 阻断QA-01 冻结、QA-02 信标台取件区、QA-08 长按互动偶发失效31.5h是(评审第一眼就是"卡住")
B 手感QA-03 检查点丢资料、QA-04 冲刺刹车、QA-05 跳跃判定、QA-06 陷阱预警42h否,但直接影响重玩意愿
C 打磨QA-07 动线、QA-09 破障提示、QA-10 暴露释义、QA-11 总结入口、QA-12 阈值51.5h否
修改点在 src/,改完必须跑 node src/core/verify-core.mjs + node scripts/verify-world.mjs + node scripts/build-game.mjs,否则 dist/ 与实际不一致(发布包用的是 dist/)。

A 批:阻断级

QA-01 偶发「角色不响应移动」→ 三处一起改

已排除:焦点在按钮(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=[]。


QA-02 第5章信标台三块数据全在守卫巡逻区间内

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(不再掉血)。


QA-08 长按互动偶发不生效

根因是 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,日志里不应再出现 [重试] 换房未生效 / 广播未能关闭。


B 批:手感

QA-03 死亡回档丢"已收集未交付"资料

改法(src/main.mjs worldEvent,拾取后立即落检查点)

+ if(type==='pickup')makeCheckpoint((world.currentRoom?.name||'房间')+' · 拾取后');
makeCheckpoint 内部已有 if(!active()||evacuationStarted)return 保护;每章最多 6 次写盘,可接受。

验证:第5章取 1 块后故意踩陷阱死亡 → 检查点重试 → 背包里那块应还在。


QA-04 冲刺惯性 117px 无刹车

改法(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)。


QA-05 教程跳跃判定窗过窄

改法(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 有真实腾空高度)。


QA-06 地面陷阱无预警

改法(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 不变),如不想动数值就只加预警。


C 批:打磨

编号改法文件
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-notesrc/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-12campaignGrade: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章 + 战役总结

必须复现确认的三条(改完应消失):

  1. walkTo 卡死(…) screen=none barriers=[](QA-01)
  2. [重试] 换房未生效 / 广播未能关闭(QA-08)
  3. 第5章数据未拿齐 + health 掉到 35 以下(QA-02)

需要你拍板的三处

  1. QA-02:是"必须挨打"的紧张设计,还是失误?——决定挪数据还是缩巡逻。
  2. QA-12:A 线是否下调到 360(正常通关给 A,做可选内容给 S)?
  3. QA-07:副房间动线要不要动(会改地图美术的"门"位置,需要同步素材)?

落地方式建议

仓库现在有 262 行未提交改动(main.mjs / world.mjs / ui-v3.mjs / rooms.mjs 都在别人手上动着)。建议:

  1. 先 git stash 或提交当前进度,锁定基线;
  2. 我按 A→B→C 顺序分三个 commit 落代码,每个 commit 附对应验证命令的输出;
  3. 每批改完跑一次上面的回归清单,再进下一批。

要我现在就动手吗? 告诉我「按 A 批开始」即可,我改完直接把 git diff 和验证日志贴给你。


落地记录(2026-10-25 21:0x)

按拍板结果执行:QA-02 保留紧张设计不改、QA-12 A 线降到 360、QA-07 动线不动。

已改动

编号文件:行改动
QA-01main.mjs frame()新增看门狗:screen=none && phase=playing 且世界时钟停滞 >1.2s → 打警告并 setPaused(false)+input.clear();隐藏页面持续 0.8s 补一次「暂停」面板(保留"隐藏不重绘"的既有契约,未删 !document.hidden)
QA-01input.mjs keydown方向/爬梯/冲刺/互动键不再被"焦点在 button"吞掉(Space 仍交给按钮,避免破坏菜单键盘激活)
QA-08input.mjs keyup + main.mjs新增 interact-released 动作:一松 E 立刻清 mustReleaseInteract
QA-03main.mjs worldEventtype==='pickup' 立即 makeCheckpoint(房间+' · 拾取后'),死亡回档不再丢已捡资料
QA-04world.mjs 玩家/冲刺新增 slideUntil:冲刺后 0.18s 减速度 3000→9000,滑行 117px → ~35px
QA-05lesson-bridge.mjs跳跃通过条件去掉 startX 限制,只判"从 A 台跳到 B 台"
QA-06world.mjs 陷阱通电前 0.45s trap.warning:scan-grid 波纹 + guard-warning 提示音(伤害与判定未改)
QA-09world.mjs actionGeometry路线不可达文案改为「X 还在障碍的另一侧,正在绕行(约 N 秒)」
QA-10ui-v3.mjs 结算「暴露」加 tooltip + 一行释义
QA-11ui-v3.mjs + main.mjs通关后标题新增「查看航程总结」→ 新动作 campaign-summary
QA-12chapters.mjs:121campaignGrade A 线 375 → 360

未改:QA-02(信标台取件压力是设计)、QA-07(副房间动线不动)。

验证证据

检查结果
src/core/verify-core.mjsPASS(事务/重试/资源/500 分制/存档恢复)
scripts/verify-input.mjs5 项 PASS(含"菜单 Space 保持原生按钮行为"、"1000 次焦点/可见性中断")
scripts/verify-world.mjsPASS,五章物理输入模拟通关
scripts/verify-main-flow.mjs8/8 PASS(含"隐藏页面不重绘"契约)
scripts/verify-runtime-save.mjs / verify-experience.mjs / verify-story-flow.mjs / verify-lesson-bridge.mjs13 / 18 / 18 / 12 全 PASS
scripts/verify-maps.mjs / verify-mission-completeness.mjs / verify-rendering.mjsPASS
scripts/build-game.mjs + verify-build.mjsbuilt 148 files, missing 0
真机(QA_MODE=demo5)页面异常 0 次(改前 351 次),第5章跑到撤离 60s 倒数并成功登艇

过程中自己踩的坑(已修,写进约定)

仍未闭环

  1. QA-01 根因:看门狗是"兜底自愈",不是根治。需要真机复现一次抓 core.view().phase;若确认为"无遮罩暂停态",应在 setPaused(true) 处统一收口。
  2. 第5章整链跑:脚本玩家仍会在信标台被守卫打死→检查点回档打断流程(游戏本身可通关,demo5 已证 75/A)。这是脚本走位问题,不是新缺陷。
  3. 仓库仍有并发未提交改动,本次改动未提交(不替你 commit)。建议 git diff 过一遍再封板。