games-development-ai/game-runtime/games/shanhai-xingji

山海行纪(北极星顶级线② · 肉鸽割草)

持符巡山使夜巡镇兽:拖动 = 浮动摇杆走位,符器自动索敌出手,击杀掉灵晶、磁吸升级三选一,兽潮按波表爬坡,10:00 战狰王、20:00 斩九婴即胜。规格 SoT = 开发设计书;当前进度 = M4 局外 meta(角色 8 巡使 / 天赋树 48 节点 / 图鉴收集投影 / 成就 60 / 每日挑战固定种子 / 存档 SaveEnvelope 版本信封;M3 = 首图完整:图 1「裂谷原」全 20 分钟局 / 潮汐脉冲 / 词缀精英 6 / 双 Boss / 事件 4 种 / 全程录证,M2 = build 体系:武器 12×8 级五族 / 被动 14×5 级 / 进化 12 / 暂停总览,M1 = 手感+性能件,M0 = 核心循环)。

目录

• src/balance.js — 数值表(零魔法数唯一来源,扫描器直接吃表;M3 增:20 分钟 WAVES(hp/speed/gem 三乘区列)/TIDE 潮汐/ELITE+AFFIXES 词缀/BOSSES 战技组/EVENTS 事件池/XP 二次曲线)
• src/build-model.js — build 派生模型(武器×等级×进化×被动的派生数值与理论 DPS 唯一解释器,sim/单测/扫描器同源防双写;M4 增可选 meta 纯数值折叠)
• src/sim.js — 纯逻辑核心(零 DOM/引擎,node 直跑;M3 增 Boss 战技状态机/精英词缀/事件调度/胜利线;M4 增可选 meta 增益消费、阵亡续命、图鉴收集追踪,全 additive)
• src/meta-tables.js — M4 局外 meta 数据表(零魔法数唯一来源:角色 8 / 天赋树 48 / 成就 60 / 图鉴收集投影 / 每日挑战固定种子 / 存档 schema 版本)
• src/meta.js — M4 局外 meta 逻辑核(金币经济 / 天赋购买+静态可达 / 角色解锁 / 图鉴投影 / 成就评估 / 每日挑战 / SaveEnvelope 信封读写 / deriveMetaBonus 注入 sim;node 直跑)
• src/game-logic.js / src/render.js — 壳层(摇杆核接线/反馈泵/三选一弹层/出击页/暂停总览/取证;M4 接 meta:出击页角色 roster 真投影、局末回写、每日挑战入口)与渲染层
• src/art.js / src/atlas-frames.js — M4 美术接线层:图集加载(宿主预载 boot.assets,boss 页懒加载)+ sprite 绘制(裁剪补偿/翻转/旋转)+ 缺图降级兜底(缺帧回退色块+日志,不崩)+ 九宫格/tile/bg;atlas-frames.js = free-tex-packer 帧坐标紧凑表(gen-atlas-frames.mjs 生成)
• src/sfx.js — M4 内容音效引擎:分层 WebAudio foley(噪声瞬态+滤波+多分音,替 audio-music 的 ZzFX 芯片音作 hit-feedback 的 sfx 后端;CC0 采样懒加载优先路径预留);AudioContext 经 host-config buildFactoryOpts 惰性绑定
• src/host-config.js / src/main.js / src/game.js — L1 宿主装配(17 插件 + 内容音效引擎,沿 _template 骨架)
• scripts/ — headless 冒烟 / 参数扫描(sim-scan.mjs)/ 全程录证(record-run.mjs)/ 合成压测 / 包体实测 / M4 三门(save-compat.mjs / content-audit.mjs / l3-structure-check.mjs)/ 美术接线证据(render-evidence.mjs:各场景真图 drawImage 计数)/ 帧表生成(gen-atlas-frames.mjs);scripts/lib/p2-driver.mjs = P2 档走位单一实现
• test/ — 纯逻辑单测 + build 数据表门 + boot 冒烟 + 渲染崩溃回归 + 手感断言 + 触发器② UI 断言 + M4 meta 表门 / meta 逻辑门 / 美术接线断言(art-wiring)/ 内容音效结构断言(sfx-content)

测量面(手感断言的机验入口)

• 取证:_forensicsView().measures.events[] 逐条 {eventName, frame, timeMs, sourceId, visualEventFrame, sfxStartFrame}(hit-feedback 探针;音画同帧断言=比对两帧号)+ measures.joystick(摇杆探针)+ measures.menu(M2:出击页滚动/难度选择探针)。
• 轨迹 driver:plugins.vjoy.runTrajectory({from,to,ms}, advance)(与壳层共核,注入即驱真游戏;e2e CDP drag 的 headless 孪生)。
• 量值面:balance.FEEDBACK(手 4 顿帧档位/手 5 震幅上限/手 7 飘字上限,全部草案〔真机校准后锁〕;crit 档事件源 M2 已落,bossKill/bossSpawn/eventStart 档 M3 已落=双 Boss 与事件)。

跑起来

# 全部测试(本机零依赖;44 测 = M0–M3 二十七测零倒退 + M4 meta 表门六 + meta 逻辑门十一)
node --test test/*.test.mjs

# 三场景 headless 单局(P0 静止必死 ≤90s / 关火纯走位 ≥60s / P2 贪心跑到终态)
node scripts/headless-smoke.mjs

# 仿真参数扫描(build 四判据;M3 20 分钟口径门档 = A 12武器×20局 + B 24随机build×12局 = 528 局)
node scripts/sim-scan.mjs            # 门档(≈11 分钟@6 worker;非绿退出码 1;M4 夜批回满 n)
node scripts/sim-scan.mjs --mid      # 调参可信档 304 局;--quick 粗读档 110 局(只出数)
#   分批前台跑:--arm A --save dist/scan-a.json → --arm B --save dist/scan-b.json
#   → --merge dist/scan-a.json dist/scan-b.json(合并判读,单批墙钟 ≤6 分钟)

# 首图真玩全程录证(M3 门 headless 面:D0/D1 各一局,轨迹 5s 采样+关键帧+§3.1 断言)
node scripts/record-run.mjs

# 合成压测(逻辑层:敌600+弹500+晶300;渲染侧与基准机=真机窗口另测)
node scripts/stress-test.mjs

# 打包 + 包体两本账证据(dist/shanhai-bundle.js + dist/build-report.json)
node scripts/build-report.mjs

# ── M4 meta 门(局外系统)──
node scripts/save-compat.mjs         # 存档兼容门:SaveEnvelope 往返 + 坏版本 fail-closed + 0 版迁移
node scripts/content-audit.mjs       # 10h 内容图谱核数(§5.4 机械和;真表溯源 + 设计锚)
node scripts/l3-structure-check.mjs  # L3 留存结构面机验(下一个解锁/回归钩/首 3 分钟;rubric 分数走 LLM)

# 浏览器试玩:构建后 serve 本目录
#   ?engine=stub(缺省)/ ?engine=real(LittleJS 掌帧)/ ?seed=N / ?mode=evidence(CDP 取证)
npx serve .   # 或任意静态服务器,打开 index.html

桌面调试:WASD/方向键移动,1/2/3 选卡,P/Esc 暂停(build 总览),空格开局/重开;出击页拖动列表滚动、点「潮汛」行切难度(D0/D1)。

M0 验收留证(2026-07-06)

单测 5/5 · boot 冒烟 2/2 · 三场景冒烟全过(P0 39.1s 死 / 纯走位满血 60s / P2 撑满 300s 胜,724 杀 11 升级)· 逻辑压测 p95 1.167ms(预算 6ms)· 包体首屏 251,078B(预算「引擎+代码 0.6MB」内;dist/build-report.json)。渲染侧 60fps@2500 与基准真机数据、九门 harness 完整跑(需 survivor driver,书内 M1)为 M0 未覆盖面,详见开发汇报。

M1 验收留证(2026-07-06)

游戏测试 13/13(M0 七测零倒退+渲染崩溃回归+手感接通五测)· 插件库整库 260/260 · manifest 19/19 · 六件新插件 gz 预算全 ✔(SIZES.md 增量法)· 三场景冒烟数值与 M0 逐值一致(724 杀/39.1s)· 压测 p95 1.174ms(vs M0 1.167ms,沉淀换装零回退)· 包体 258,905B gz 89,268B(+11KB=六件内核内联,0.6MB 门内)。浏览器崩溃修复:play 首帧 drawGround 哈希有符号右移产负半径 -0.5 → IndexSizeError → RAF 链断(mini-desktop CDP 验出);修 >>> 位提取+校验型桩回归(test/render-negative-radius.test.mjs,修前红修后绿)。真机校准锁值(60fps/震感/音频端到端)与九门 survivor driver 完整跑仍待 mini-desktop/真机窗口,详见开发汇报断言表。

M2 验收留证(2026-07-06)

build 四判据全绿(sim-scan.mjs 门档 1080 局,D1×P2,确定性种子复跑逐值一致):①每件武器定向 build 胜率 43–63% 全 ≥40% ②最强 build 85% ≤85% ③随机 build 中位胜率 55% ∈35–55% ④武器出现↔获胜 |r|max 0.250 ≤0.6(初始武器雷符链恒在、无变异,④对其不适用,可行性由定向臂覆盖)。仿真墙钟 spike 实测:单局 mean 1.88s / p95 3.29s(300s 局=18000 帧,≈135µs/帧),6 worker 吞吐 180 局/分,门档 6.0 分钟,已回填书 §8.3(唯一书内改动)。游戏测试 27/27(M0/M1 十三测零倒退 + build 表门九测 + 手 4 暴击全链一测 + 触发器② UI 四测)· 三场景冒烟全过(S1 38.6s 死/S2 满血 60s/S3 win 981 杀 30 次升级)· 逻辑压测 p95 1.433ms(多武器+区域实体增量,6ms 门内)· 整库插件 269/269(基线 260 全含;canvas-ui-kit v1.1 additive 滚动列表 +3 测)· manifest 19/19 · 包体首屏 287,663B(gz 99,767B,0.6MB 门内;dist/build-report.json)。M2 调参实录(数据表内收敛,12 轮):波表增 hpMul/speedMul 爬坡列(§8.1 g^w 表化+反风筝速度压力)、三选一改持有件偏权池(ownedWeight 2,治「新件洪水稀释构筑」)、P2 档修成真「贪心磁吸+避险」混合矢量(纯二值版后期永不捡晶,build 进度饿死)。触发器② CDP 走查+截图留证与真机校准仍待 mini-desktop 窗口(headless 结构断言已先行钉死,见 test/ui-trigger2.test.mjs)。

M3 验收留证(2026-07-07)

首图真玩全程录证(M3 门 headless 面,record-run.mjs,dist/run-recording.json):图 1「裂谷原」D0/D1 各一局全 20 分钟走完并击杀终 Boss 胜利——D0 win@1258.9s(lv48/4823 杀/精英 265/双 Boss 2/事件 5 次 4 类{宝箱/裂谷×2/流星/祭坛}/收割 7/进化 1),D1 win@1219.7s(lv61/7742 杀/精英 602/双 Boss 2/事件 5 次/收割 10);WAVES 出怪率全程单调不减(含 18:00 收割期跳升)、双 Boss 10:00 战狰王/20:00 斩九婴按时出场、首杀 D0 3.15s/D1 2.32s(手 11)、潮汐脉冲按 60–90s 节律 17/16 次、事件 ≥3 次 ≥2 类——逐条断言全过。

build 四判据锁值(M2 数值门在 M3 20 分钟口径下重验,sim-scan.mjs 门档 528 局 = A 12 武器 ×20 + B 24 随机 build ×12,D1×P2;20 分钟口径下按墙钟预算把 M2 的 1080 裁半、M4 夜批回满;确定性种子复跑逐局全等,分片 s3 66/66):①定向 build 胜率 45%–85% 全 ≥40% PASS ②最强 build 92% > 85% FAIL ③随机 build 中位胜率 38% ∈35–55% PASS ④武器出现↔获胜 |r|max 0.344 ≤0.6 PASS。唯一未绿 = ②:最强 build 是一条随机组合 rand-4(缚灵桩+风刃符+缚灵+寒渊 / 多重·回复·移速·急速)以 92%(11/12)离群,次高是缚灵桩定向 build 恰 85%、领先第二梯队(75%)达 7 点——是真协同离群,非小样本噪声;四判据阈值为书 §8.2 首版工作阈值〔草案·首轮仿真回填后锁,修订走质量轨校准〕,本次即首轮回填。收敛留 M4:directedBuildFor 把缚灵桩作携伴塞进几乎所有 build(缚灵桩定向已在 85% 天花板),下调它会同时拖垮全体含它 build 的地板——耦合系统的定点微调属书 §8.3/§12「M4 夜批千局×网格调参」,非单点可解,M4 夜批回满 n 后按质量轨校准锁阈值。

仿真墙钟 spike(§8.3 已回填 M3 实测):干净单线程 20 分钟正式局(72000 帧,2500 实体峰值)≈8s/局 ≈111µs/帧(record-run D0 8.0s/D1 7.7s),优于 M2 折算预测 9.7s/局,「量级不构成障碍」坐实;门档报告内 wallClock(单局 mean 24.8s/p95 64.2s)因分片跨批叠加开发机 overlapping 进程争用被抬高、非干净吞吐,批吞吐锁值留 M4 夜批清机复测。

回归零倒退:游戏测试 27/27(M0/M1/M2 全含,node --test test/*.test.mjs)· 整库插件 269/269(基线全含,改动不触任何插件)· 三场景冒烟全过(S1 静止 lose 60.6s / S2 纯走位满血 60s / S3 贪心 lose@610.8s 1930 杀 30 升级,单默认局 P2 死于中 Boss 段属胜率分布内)· 逻辑压测 p95 1.555ms(vs M2 1.433,M3 波表/潮汐/精英词缀/双 Boss 状态机/事件调度增量在 6ms 门内)· 包体首屏 300,917B(gz 104,303B,「引擎+代码 0.6MB」门内;dist/build-report.json)。

M3 门剩余面(非本机 headless 可覆盖,如实列):首局门 CDP+真机、品类 rubric 首评(割草品类件 M3 前另切小单)、创始人眼验风格版 30 帧样张(题材拍定+资产席产出)——headless 结构与数值断言已先行,CDP/真机/眼验待 mini-desktop 窗口与创始人。

M4 验收留证(2026-07-07)

局外六系统全落地(src/meta-tables.js 数据 + src/meta.js 逻辑核,零魔法数同源、node 直跑):角色 8 巡使(五行属性由初始符箓意象定,clean-room 巡使谱系半文半白;基准巡使 trait 数值中性=默认路径 metaBonus 全 no-op 零回归,其余 7 名各带 trait 偏置)/ 天赋树 48 节点(金木水火土五脉 + 中枢命脉,六根,金币消费端)/ 图鉴收集投影(从真实内容表派生 51 条=兽 3+Boss 2+符 12+被动 14+进化 12+角色 8,敌 32 扩表归 M5 后自动增至 80,非手写化石)/ 成就 60(收集长尾十四轴)/ 每日挑战(固定种子仅依赖日期=天下同题,每日首登去重)/ 存档 SaveEnvelope 版本信封。meta 增益经 deriveMetaBonus 真注入 sim——角色初始符箓、生命乘区、符力折叠、阵亡续命全部可观测,非孤儿设计;局末 recordRun 一体推进金币/图鉴/成就/角色解锁/每日。build-model 的 derivePlayer/deriveWeapon 加可选 meta 纯数值折叠(无 meta 逐值同 M3),sim 的 meta 消费与续命、图鉴追踪全部 additive。

存档兼容门全绿(save-compat.mjs,SaveEnvelope 走 save-progress setVersioned/getVersioned 真实通道,12/12):①往返=写→读逐值一致 + 落盘值为 {schemaVersion:1, data} 信封 + data 承载真态;②坏版本负例=未来版(999)fail-closed 回退默认、versionFallbacks 计数、原档不毁,非信封垃圾(数组)同回退不崩;③0 版迁移=无版本旧档经 migrators[0] 升 v1、字段并入默认骨架、versionMigrations 计数、迁移后回写 v1 信封。介质=影子存档(内存/localStorage,§13 降级口径),M5 前切正式 save:{gameId}:{versionId} 槽(65536 码元)并跑跨介质迁移验证。

10 小时内容图谱核数首验(content-audit.mjs,§5.4 机械和):去重保守和 = 首通线 3.17h + 角色线 2.42h + 难度线 3.88h + 收集天赋线 1.75h ≈ 11.21h ≥ 10h(余量 1.21h,与书 §5.4 的 11.2h 自洽)。M4 的贡献 = 把角色线的「边际 5 角色」与收集天赋线的长尾(天赋 48 / 图鉴 51 / 成就 60)从纯估值坐实为真表支撑的乘法轴;地图 5、D2–D5、敌 32 为 §5.2 设计锚(逐处标 M4 已交 / M5 待扩,不冒称)。

L3 留存结构面机验(l3-structure-check.mjs,质量 SoT §7 观测线「L3 组 ≥2/3」,3/3 成立):L3-a 下一个解锁=nextUnlock() 全新→半程恒非空(目标梯度不断);L3-b 放置回归=每日挑战固定种子天下同题 + 每日首登去重(回归钩);L3-c 首 3 分钟脚本=真玩首杀 2.8s(≤10s)+ 首升级 14.6s([10,60]s)+ 后续锁露出。红线守位:rubric 分数是纯 LLM 软判(质量 SoT §4 规范四),本脚本只走 L1 真玩/结构硬断言轨机验「三条 rubric 各自评的结构在不在」,不打 rubric 分、不进九门/项目代码;rubric 的体验层评分(层次够不够 / 勾不勾人)如实标待 LLM/创始人窗口。

天赋树静态可达门(test/meta-tables.test.mjs,§12 M4):6 道检查逐条机验——①节点数=48 ②id 唯一 ③无悬空依赖(每个 requires 引用都在节点集内)④无环(DFS 三色回边检测,DAG)⑤有根(6 根=六脉)⑥从根经 AND 前置闭包全可达 48(缺口=死枝/隐环)。全绿=树无死环、依赖可达。

回归零倒退:游戏测试 44/44(M0–M3 二十七测零倒退 + M4 meta 表门 6 + meta 逻辑门 11,node --test test/*.test.mjs)· 整库插件 269/269(插件全未触,纯 additive)· 三场景冒烟全过(7/0)· 逻辑压测 p95 1.617ms(6ms 门内)· 包体首屏 328,848B(gz 112,089B,「引擎+代码 0.6MB」门内;+28KB=M4 meta 系统)· 首图录证 D0 win@1258.9s / D1 win@1219.7s(与 M3 逐值一致=meta additive 对无 meta 路径零偏移)。

c2 平衡离群(顺带收敛尝试,书 §8.2):离群源 = 随机 build rand-4[缚灵桩+风刃符+缚灵+寒渊 / 多重·回复·移速·急速]92%(11/12)> 85%。本波做外科手术式尝试:只削缚灵桩进化「锁山镇桩」的减速场(耦合放大器假设:slow 0.3→0.2 / s 0.6→0.4 / zoneRMul 1.3→1.18),基座伤害与进化 DPS 带不动。门档 A 12×20 + B 24×12 = 528 局重验(D1×P2)结果:c1 十二件全 ≥40%(逐值同 M3=证进化 slow 杠杆对 c1 携伴地板零伤害)/ c3 中位 42% ∈[35,55] / c4 |r|max 0.320 ≤0.6 全过,但 c2 rand-4 仍 92% 纹丝未动——削进化减速场没翻掉任一 seed。根因精化:rand-4 的 92% 不是缚灵桩进化减速场驱动,而是三投射符器(雷符链+风刃符+寒渊符,各带链跳/镜像穿透/基座减速)叠 multi/haste/speed 的协同,缚灵桩只是携伴。故按「别硬凑」回退到 M3 干净基座,c2 收敛留 M5 夜批千局×网格调参(书 §8.3/§12;耦合系统的定点微调非单点可解,需在 proj 协同 + slow 叠加的多参数面上网格扫)。

M4 打磨验收留证:美术接线 / UI 国风化 / 内容音效(2026-07-07)

创始人验玩后批三条:①割草美术图集入库了但没接进渲染(render.js 全程序色块);②UI 方方正正;③音效是 ZzFX 8-bit 芯片音。三条本波逐条兑现,纯逻辑内核(sim/meta/readState)语义零改,只动渲染层与音效后端。

① 美术接线(头号 bug):新增 src/art.js 图集接线层——据 atlas-frames.js 帧表查坐标、据宿主预载的 boot.assets(manifest 补 assets[] 让 loadHostAssets 预载首屏页)用 drawImage 画真 sprite,主角 13 帧(idle/run/hurt 按走位与受击态切+朝向翻转)、三常规兽(狰/梼杌/穷奇 move/hurt 帧+朝玩家翻转)、双 Boss(sim 的 zhengwang/jiuying → 图集 paoxiao/luwu 贴图+蓄势预警)、12 符器弹道(fx-{wid} 旋向速度)、轨道/驻场符阵、灵晶/灵珠/铜钱拾取、地表 tile(8 变奏按世界哈希+3px 重叠去缝)、装饰物、局内事件物件全部替换程序色块;boss 页 1.03MB 懒加载(首个 Boss 现身前拉)不进首屏。缺图降级兜底保留:缺帧/未载完回退色块+日志、不崩不留白。证据(headless 注入桩图计数,render-evidence.mjs):战场帧真图 drawImage=63(tiles 45/主角 8/异兽/UI/事件)、暂停总览 184、菜单 22、fellBack=0 零缺帧;无图对照 drawImage=0+程序回退 82(降级成立)。真机 CDP 截图(Chrome headless,mode=evidence 驱动)四态坐实真 sprite 在画。

② UI 国风化(去方框):出击页接远景 vista 底 + ui-panel-sortie 面板九宫格 + ui-btn 按钮 + 选中行描金高亮;HUD 血球(ui-orb-hp 裁剪填充血量)、Boss 血条(ui-bar-boss 框套液条,液条几何锁死=触发器②断言事实源不动)、摇杆(ui-joystick base+knob);暂停总览符器/被动槽(暗底+描金边+fx-icon 符器图标,弃方形圆徽拉伸保可读);升阶三选一接 ui-card-frame 龙纹国风卡框(经 canvas-ui-kit picker 的 drawPanel 后端注入,奇偶交替 01/02);全场文字加墨描边压图保可读;弹层缩放淡入(picker 既有手 9 动画)。UI 美术全部图集既有帧,未额外生图。

③ 内容音效(去芯片音):新增 src/sfx.js 分层 WebAudio foley 引擎替 ZzFX——按事件语义合成多层(噪声瞬态 + biquad 滤波 + 多分音包络):灵晶进账=清脆水晶叮(高正弦+泛音+上滑)、击破/击毁=碎裂闷响(带通噪声下扫+低音体)、受击=低闷撞击+下坠、升级=上行叠泛音编钟(C5-E5-G5-C6 琶音)、聚灵珠=上扫流光、Boss 登场=威压上涌、Boss 伏诛=轰然崩解、异象=玄秘微光;FEEDBACK.tiers 的 sfx 名细分到八配方,高频同名节流防噪墙,CC0 采样懒加载优先路径预留(缺采样落合成)。经 host-config 换 hit-feedback 的 sfx 后端、AudioContext 经 buildFactoryOpts 惰性绑定(用户手势解锁后真声)。证据:结构断言(sfx-content 5/5)钉死每音效 ≥2 声源层(证非单振荡器芯片音)+ 噪声+滤波在场 + 八事件全覆盖 + 无上下文静默降级 + 节流;真机 CDP 探针(patch AudioContext 节点工厂计数)坐实解锁+击杀后音频图真构建(振荡器/噪声源/滤波/增益节点 >0、零渲染错误)。真声色人耳评待真机窗口。

回归零倒退:游戏测试 53/53(M0–M4 四十四测零倒退 + 美术接线断言 4 + 内容音效结构断言 5)· 整库插件 269/269(canvas-ui-kit 未改,卡框走 picker 既有 drawPanel 后端注入=零插件改动)· 三场景冒烟全过(7/0)· 逻辑压测 p95 1.503ms(6ms 门内,渲染改动不进逻辑热路径)· 包体首屏 349,549B(gz 119,380B,「引擎+代码 0.6MB」门内;+21KB=图集帧表 + art/sfx 接线层)· 首图录证 D0 win@1258.9s / D1 win@1219.7s(与 M3/M4 逐值一致=渲染/音效改动对 sim/meta 零偏移)· 存档兼容门 13/13。边界:只动 games/shanhai-xingji/(render/art/sfx/game-logic/host-config/balance FEEDBACK 名/manifest assets)+ 帧表生成器;src/host、tier2、其他游戏、插件库一律未触;dist 不入库。