AI 参与 3D 游戏开发的最佳实践

摘要结论先行

本次实践最有效的做法，不是让 AI 一次性「写完游戏」，而是把 AI 放进一个「可断言、可回滚、可看图」的闭环。人负责目标、审美、范围与对外动作；AI 负责调研、实现、自检与诊断；每一轮改动都由两层自动化断言加人工视觉验收收口。

01AI 与人工的协作边界

边界不按「技术难度」划分，而按「可逆性与后果」划分。可回滚、可断言、不改契约的实现工作交给 AI；涉及审美判定、范围变更、资产处置、依赖升级与对外发布的动作由人确认。

三条边界原则

• 可回滚、可断言、不改契约 → AI 自主推进。纯逻辑规则、演出效果、几何外形等改动，只要两层断言全绿且不触碰硬约束，可连续迭代多轮。
• 触及资产、账户、许可、范围、审美 → 先确认再动。只读代码审查列出的三处边界（新建仓库、联网安装依赖、素材处置）在实施前单独征求意见；依赖审计发现的 9 个 high 因修复涉及破坏性升级，未擅自处理。
• 否决即彻底回退，并升级为断言。2D 脸部贴图链路被否决后，删除数据注入与相关断言、保留历史素材但不入库，并把 texturedMeshes === 0 与「产物不含贴图链路」写进验收，避免路线反复。

02需求拆解与范围控制

把大目标切成能独立验收的垂直切片，并把「不做什么」写成显式约束。本次的可交付定义是「能打完一局」，而非完整格斗游戏。

• 决策前置：先完成方案交流并锁定四项基础决策，再进入实现；方案未定时不动代码。这使后续所有技术选择都有可追溯的出处。
• 范围双清单：M0 + M1 为在范围内；M2、M3 明确标注未解禁，POW 槽只作展示。README 同步写明「已知差距」，把未完成项公开化而不是隐藏。
• 按层分轮：后续迭代依次是「规则与手感 → 打击演出与镜头 → 纯 3D 几何精修 → 工程化硬化与零风险修复」。每轮开头都声明「本轮不动哪些层」，例如几何精修只改外形网格、判定与姿态一行未动。
• 先审查后动手：一次全量只读代码审查把改进项分为 P0 工程化、P1 零风险修复、P2 规则细节、P3 已排期四层，且每条带 文件:行 证据；由人选定「P0 + P1」后，AI 给出精确清单并等待确认再实施。
• 改进建议：把「本轮允许改动的文件 / 层」与「禁止触碰的契约」写进每轮任务描述，比事后 review 更容易控制扩散；路线图只保留下一轮，避免 AI 提前实现未解禁内容。

03内容生成与校验

瓶颈不在「能否生成」，而在「生成物能否被验收、被否决、被替换」。AI 生成的资产与代码必须带许可证据、可替换接口和视觉验收位。

资产：先做许可与可得性实证

• 对候选 VRM 资产逐个做 glb header 与许可元数据审计：某候选的自定义条款明文禁止暴力表现，直接排除；功能测试模型视觉不符，排除；CC0 候选许可最干净但为低模卡通风，仅用于插槽验证。结论是「免费 + 可商用 + 可再分发 + 允许暴力表现 + 好看的动漫美少女」这一交集里公开可下载资产基本为空。
• 工具链可行性同样需要核实：VRoid Studio 为纯 GUI、本机辅助功能未授权，无法无人值守导出；Blender 已安装但缺 VRM 导出插件；网络单次响应约 10 MiB 截断，是靠 glb header 声明长度比对才发现的，而非「看着像下完了」。
• 能力核实先于投入：AI 可绘制 2D 立绘；文生 3D 可产出 GLB 但无骨骼，接进格斗游戏只能整体平移，需额外绑骨，因此未列为主线。把能力边界与代价讲清楚，比先做再返工更省。

生成物：可替换、可否决

• 可替换契约：抽出 CharacterView 接口与与骨架无关的 Pose 类型，程序化骨架与 VRM 共用同一套动作系统；替换资产只需覆盖输入文件后重跑构建，逻辑层与帧表完全未动。
• 可否决：2D 脸部贴图被判「不自然」后删除整条链路（脸板、数据注入、相关断言），几何五官升为唯一实现；默认产物从 957 KB 回到 752 KB。历史素材保留但构建不再引用、不入库。
• 外形与骨架解耦：纯 3D 几何精修只换外形网格，禁止改动关节层级、骨骼长度与末端局部坐标；指纹逐字节未变，网格从 86 → 111、方块件 31 → 4、三角面 8528 → 18858。

校验：人工看图不可省略

• 固定的视觉验收资产包括九格动作拼图、单人近景 2 倍图、打击演出图、静止对峙图与竖屏图。验收顺序固定为纯逻辑单测 → 构建 → 浏览器自检连跑两次全绿 → 人工看图。
• 断言全绿时仍靠看图发现过：站防/蹲防剪影几乎一样、跳攻摆拍裁掉头顶、柔光像「脏玻璃」、速度线像背景横线、残影与本体重合发虚、挑染刘海变成「皇冠」与三角耳、上衣下摆黑半圆。
• 诊断手法同样可复用：把描边壳临时染色再设透明，区分「描边问题」还是「几何本身问题」，最终定位为四肢旋转体两端留平口、BackSide 壳从斜下方露出黑色内壁，用首尾半径 0 收口解决。

04逻辑实现

把「能被离线断言覆盖的部分」与「必须靠浏览器观察的部分」切干净。确定性是格斗玩法可复现、可测试、可调试的共同基础。

• 确定性步进：逻辑固定 60Hz 步进 + 渲染插值，rAF 不直接驱动逻辑；招式帧表分 startup / active / recovery，判定为自研状态机 + AABB（hitbox / hurtbox / pushbox），不引入物理引擎。帧数据与步进方式一旦改动会破坏可复现性。
• 纯逻辑层离线可测：用 esbuild 把纯逻辑层打包为 tests/.build/logic.mjs，node --test 覆盖帧表、判定、防御、输入、AI、Match 共 38 条单测，不需要浏览器。
• 契约显式化：Match.step() 返回「本帧是否被 hitstop 冻结」，消除「step 前读 hitstop、step 内递减」的隐式耦合；受击打断的旧招式在全部配对结算完之后统一清理，避免改变互击的先手结算顺序。
• 逻辑时间与视觉时间分离：hitstop 冻结逻辑帧时同时冻结视觉时间，但 FX 仍按渲染 dt 推进，于是定格画面上火花继续炸开；玩法与帧表一行未改。
• 改动收口：纯逻辑规则改动同步更新 tests/*.test.mjs，渲染与演出改动同步更新浏览器自检脚本，两层断言必须同时全绿。

05调试迭代

把 AI 的调试能力沉淀为「可复跑的探针 + 可收敛的断言」，而不是一次性的手工排查。可观测性做得越细，越能把「看起来不对」变成可验证的数值。

• 运行时状态可观测：window.__kof 暴露 snapshot / setPose / clearPose / limbs / setJoint / setDebug / showImpact / sampleAttackTags；snapshot 含镜头、FX 计数、视觉时间、骨架指纹与双口径帧率。冻结逻辑摆拍使关键帧截图可复现。
• 用坐标而非描述判断动作：通过 limbs() 读拳套与脚的世界坐标扫描标定，发现「绕 X 轴旋转只让肢体朝 ±Z、屏幕投影几乎不变」，据此把主伸展改到 Z 分量并统一 R 侧主动肢体；又把判定已生效但姿态仍停在 windup 的 active 首帧改为 strike 混合。
• 断言要抗时序波动：headless 帧率在 15~60fps 区间波动，按固定等待时间读落地缓冲会偶发假失败。改法是轮询到姿态收敛（标签为 idle 且位移阈值达标）再采样、以「下一个 rAF 立刻读 + 稍后再读」验证触发与递减、以及确定性两段采样。
• 效果生命周期可断言：FX 同时维护存活计数与累计计数，效果淡出后仍能断言触发过；调试线框直接读取与结算同源的世界 AABB；KO 特写改挂回合结束事件而非整场结束事件，因为自检只打完第一回合就会发现特写未触发。
• 改进建议：断言失败时先区分「产品回归」与「时序假失败」，后者应修断言而非放宽阈值；探针应随功能一起交付，避免下次重新造轮子。

06性能与质量把控

性能结论必须来自正确的口径，质量结论必须来自可移植、可复跑的验收链。本次把「换台机器也能跑通」当作交付能力的一部分。

• 双口径计数：fps 统计逻辑步/秒，renderFps 才统计真实渲染帧/秒。实测 headless 下逻辑 60 / 渲染 29，高负载时 34 / 15；旧口径会完全掩盖掉帧。
• 零风险优化优先：HUD 加入脏检查（此前每渲染帧无条件写 14 处 DOM 属性并重建 2 次 innerHTML）；残影先判断容量再克隆整套 111 meshes 骨架；复用临时对象与模块级几何缓存。均为不改玩法、不改视觉的改动。
• 交付契约可断言：默认产物 kof-3d.html 为 790,806 字节（约 772 KB），file:// 下零外部请求、零贴图材质网格、产物不含内联图片数据；单文件内联脚本要求构建产物恰好 1 个 JS chunk、至多 1 个 CSS chunk，多 chunk 直接报错而非静默覆盖出坏文件。
• 自检链可移植：浏览器自检改为本地 require('puppeteer-core') 加 CHROME_PATH / 常见路径探测，九格拼图用浏览器 Canvas 合成、近景图用 deviceScaleFactor:2 裁切，移除对 ImageMagick 与绝对路径的依赖；相关工具显式声明在 devDependencies，换机器安装依赖即可跑全套。
• 风险不擅自处置：npm audit 报 9 个 high，全部来自本地开发依赖的传递链、不进入单文件产物；修复需破坏性升级，因此评估后交人决策。只读审查发现工程未纳入版本管理、缺 README、素材体积大等问题时，采用「新建仓库、补文档、只加忽略规则绝不删除」的处置方式。
• 发布治理：开源时由人拍板仓库名、MIT、干净单提交与「只提交源码」；补 LICENSE 与 CREDITS.md 标注 CC0 资产来源；发布后按「clone 后能否复现」实测安装、单测、构建、浏览器自检，并核对远端文件与本地一致、产物与历史素材未公开。

07可复用原则速查

以下原则均可直接迁移到下一个 3D / 交互项目；每条标注适用环节与本次实践中的出处，便于复核。

08常见风险与改进建议

下列风险均在本次实践中真实出现过，改进建议来自已采取的处置或事后审查结论。