用途:为 three.js Web 3D 游戏处理玩法循环、输入状态、物理世界、资源生命周期与游戏状态;three.js 本身只提供渲染与场景图。
主要能力:固定时间步与输入辅助模块(物理和规则用固定 dt,渲染用 accumulator/step 插值);后台暂停、失焦与 Pointer Lock 解除时清空按键,恢复时重置时间戳与积累量,禁止补算整段后台时间;最多追赶有限步数并记录丢弃时间;输入边沿每模拟步只消费一次。分离渲染 Scene 与玩法 scene controller,控制器负责 enter、fixedUpdate、renderUpdate、exit、dispose,入口只装配服务;规则与数值模块不依赖 WebGL、DOM 或材质。GPU 资源由资产服务引用计数持有,移除 Object3D 不会自动释放 geometry、material、texture 或 render target;异步加载返回后先核对场景代次,过期资源交还资产服务。退出时清理事件、定时器、mixer、physics/nav handle 与独占资源,共享资源仅在最后持有者释放时 dispose。
使用方式:新项目运行 node <技能目录>/scripts/create-game.mjs <空目录>,脚本复制工程模板并注入同一运行模块;模板目录本身不是完整可构建产物。生成后执行 npm ci、npm run build,落实实际玩法再验收。
适用场景:搭建游戏基础,或排查帧率相关玩法、场景泄漏与后台恢复问题。
限制:世界使用米、秒、弧度、Y 向上,明确前向和玩家尺寸;模型 pivot、碰撞体中心、HUD 锚点是不同契约。高速物体按实测使用 CCD,Raycaster 负责选取但不替代刚体碰撞。resize 从 Canvas CSS rect 推导 renderer 大小与相机投影。禁止把二维效果图拆解直接当作三维世界变换。最坏玩法密度记录帧时间 p50/p95、draw calls、triangles、材质与纹理数量、阴影与后处理开销、加载字节和切场景后的资源基线;先减少冗余绘制、材质、阴影和全屏 pass,再按已声明档位调整画质;不得在无数据时承诺 FPS。它只演示渲染、响应式输入、固定步和暂停恢复,不是完整游戏。