尧图网页设计 
拆解threejs-game-skills脚手架ViteTypeScriptThree.js游戏架构代码实现原理【免费下载链接】threejs-game-skillsAgent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.项目地址: https://gitcode.com/gh_mirrors/th/threejs-game-skillsthreejs-game-skills 是一套面向 AI Agent 的 Three.js 游戏开发技能包其中内置了一个开箱即用的Vite TypeScript Three.js 游戏脚手架位于 gameplay 技能目录内。本文带你完整拆解这套 Three.js 游戏架构的代码实现原理从主循环、渲染器配置到输入统一、帧率无关的物理移动、确定性测试钩子看懂它如何保证游戏可玩、可测、可发布。上图正是脚手架自带演示游戏收集 Relays 竞技场的运行画面黄色胶囊玩家 8 个拾取球 极简 HUD与下面要讲的代码一一对应。脚手架在哪里一个技能包里的游戏模板这个脚手架不是独立项目而是打包在 gameplay 技能内部当 Agent 从空目录创建新游戏时它就是起点skills/threejs-gameplay-systems/assets/threejs-vite-game/ ├── src/ │ ├── core/ # 主循环、输入、渲染器 │ ├── entities/ # 玩家、拾取物等实体 │ ├── game/ # Game 总装配类 │ ├── systems/ # 相机、碰撞、HUD、音频、调试工具 │ ├── utils/ # 种子随机数、资源释放 │ └── main.ts # 入口 └── tests/ # Playwright 视觉/冒烟测试依赖极轻核心运行时只有 package.json 中的three和一个 lil-gui 调试面板开发侧则是 Vite 8、TypeScript 和 Playwright。架构总览Game 类是总装配线一切由 main.ts 启动找到页面上的#game-canvasnew Game(canvas)然后game.start()。Game.ts 是架构的核心它把各子系统在构造函数里一次性装配好渲染层createRenderer(canvas)创建 WebGL 渲染器场景、透视相机各自独立输入层InputController同时接管键盘和触屏摇杆实体层Player玩家、Pickup[]拾取球系统层CollisionSystem碰撞、CameraRig相机跟随、Hud、AudioSystem、DebugTools驱动层Loop持有update和render两个回调每帧依次执行这种core 驱动 entities 表现 systems 服务的分层让 AI Agent或人类扩展游戏时只需新增实体和系统而不用动主循环。主循环实现requestAnimationFrame 帧时间钳制Loop.ts 只有 30 行却藏着两个关键细节const deltaSeconds Math.min((time - this.lastTime) / 1000, 0.05);delta 钳制在 0.05 秒切后台再回来时不会收到一个巨大的时间差物理不会穿墙每帧严格遵循update(delta, elapsed) → render()顺序逻辑先跑、渲染后跑相机位置永远基于最新逻辑帧start()/stop()用requestAnimationFrame / cancelAnimationFrame成对管理running标志防止重复启动——这是最标准也最稳的浏览器游戏主循环写法。渲染器配置一次调好色彩、阴影与 DPRRenderer.ts 把渲染器配置收敛成两个函数值得逐行看创建时一次性设置createRendererantialias: truepowerPreference: high-performance开启抗锯齿并声明性能优先outputColorSpace SRGBColorSpaceACESFilmicToneMapping线性工作流 电影级色调映射这是Three.js 游戏画面不显灰的关键shadowMap用PCFShadowMap柔和阴影每帧检查尺寸resizeRendererconst dpr Math.min(window.devicePixelRatio || 1, maxDpr); // maxDpr 2DPR 封顶 24K 屏不会白白渲染 4 倍像素用canvas.clientWidth/Height比对缓冲区尺寸只在真正变化时才setSize 更新相机宽高比避免每帧白算注意setSize(width, height, false)第三参为 false——尺寸由 CSS 管避免样式抖动输入统一键盘与触屏摇杆汇成一个向量InputController.ts 的设计思路是两套输入一个出口键盘侧用Setstring记录按住的event.codeWASD 方向键空格/Shift 触发冲刺触屏侧摇杆用 Pointer Events setPointerCapture锁定指针按下位置记为中心偏移除以半径归一化出口是readMovement(target)键盘向量 指针向量相加长度超过 1 就归一化防止斜向加速游戏逻辑只关心一个方向向量 是否冲刺完全不关心输入来源。测试脚本可以直接伪造键盘或鼠标事件来驱动游戏这是它能被自动测试的前提。帧率无关的移动指数平滑是灵魂Player.ts 的移动代码是整套脚手架里最值得抄作业的片段const smoothing 1 - Math.exp(-tuning.acceleration * delta); this.velocity.lerp(this.targetVelocity, smoothing); this.group.position.addScaledVector(this.velocity, delta);目标速度 输入方向 × 速度 × 冲刺倍率当前速度向目标速度做 lerp平滑系数1 - e^(-acceleration·delta)保证手感与帧率无关60fps 和 144fps 下加速曲线完全一致位置用addScaledVector(velocity, delta)积分同样是帧率无关边界用MathUtils.clamp锁在竞技场范围内朝向用atan2面向速度方向细节加分项position.y叠加一个与速度挂钩的正弦微浮动角色活起来CameraRig.ts 用同一个公式做相机惯性跟随lag 0.16s这是浏览器 3D 游戏高级感最便宜也最有效的来源。轻量碰撞不引入物理引擎的取舍CollisionSystem.ts 只有 20 行——它刻意没有引入 Cannon.js 之类的物理引擎而是做 2D 圆-圆相交比较前把delta.y 0只在水平面上判定用lengthSq() r²比较平方距离避免开方开销复用同一个Vector3实例零每帧分配对竞技场收集类游戏来说这足够且快仓库的 gameplay 技能文档physics-engine-selection.md也说明了何时该升级物理方案。确定性设计种子随机数 测试钩子这是整个脚手架最有工程味的部分也是 AI Agent 能自我验证游戏的基础1. 全局种子 RNGrandom.ts 实现了一个 mulberry32 种子随机数并在 Game.ts 中有一条硬约束所有游戏内随机数必须走this.rng禁止Math.random否则截图基线和机器自测就无法复现。2.__THREE_GAME_TEST_HOOKS__钩子Game 类把一组控制函数挂到window上钩子作用seed(n)重置随机种子保证基线可复现setState(active-play \| complete)强制进入指定游戏状态截图setPausedForScreenshot(true)冻结逻辑只保留渲染setReducedMotion(true)冻结环境动画时间让截图逐像素稳定3.__THREE_GAME_DIAGNOSTICS__诊断每帧把分数、玩家位置、renderer.infodraw call / 三角形数、canvas 实际分辨率写回 window测试脚本和调试面板DebugTools.ts直接读取——游戏对外暴露了它自己的仪表盘。QA 闭环用 Playwright 验证画上了、能玩了脚手架的 tests/visual.spec.ts 展示了它如何把上述钩子用起来等__THREE_GAME_DIAGNOSTICS__.frame 10确认主循环真的在转像素采样防空白截 canvas 图用 pngjs 算亮度方差和颜色桶数排除黑屏也通过测试真实操控验证桌面项目按W键、移动项目拖虚拟摇杆然后断言玩家 z 坐标确实前进了收集 console error 与 pageerror断言必须为空全页截图作为证据附件配套的 inspect-threejs-canvas.mjs 脚本还能在非浏览器环境测量颜色熵、边缘密度等指标。模板文件bot-playtest.template.ts、visual-regression.template.ts则预留了机器自玩和视觉回归基线的扩展位。一键跑起来脚手架的 package.json 脚本已经把常用动作都配好了npm run dev # Vite 开发服务器127.0.0.1:5188 npm run build # tsc 类型检查 生产构建 npm test # Playwright 全套 QA npm run verify:visual # 仅跑视觉冒烟测试Vite 配置vite.config.ts锁定 127.0.0.1 与固定端口strictPort: true就是为了测试脚本能稳定连接——开发工具链本身也是为可测试性服务的。总结这套架构教给我们什么设计点做法收益分层装配core 驱动 / entities 表现 / systems 服务扩展不动主循环主循环delta 钳制 update→render 固定顺序防时间炸弹渲染ACES 色调映射 DPR 封顶 2 按需 resize好看且不浪费输入键盘/触屏归一为一个向量桌面移动一套逻辑手感1-e^(-k·delta)指数平滑帧率无关的物理可测试种子 RNG window 钩子 诊断对象Agent 能自我验证QAPlaywright 像素采样 真实操控断言能玩有证据对于新手来说这个脚手架最大的价值不是那几行 Three.js 代码而是它示范了浏览器 3D 游戏的完整工程闭环写代码只是开始可复现、可测量、可回归才是能交付的标准。把 skills/threejs-gameplay-systems/SKILL.md 和上面的源码对照着读你会对一个可玩的 Three.js 游戏到底由什么构成建立起清晰的直觉。【免费下载链接】threejs-game-skillsAgent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.项目地址: https://gitcode.com/gh_mirrors/th/threejs-game-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 拆解threejs-game-skills脚手架：Vite+TypeScript+Three.js游戏架构代码实现原理
拆解threejs-game-skills脚手架ViteTypeScriptThree.js游戏架构代码实现原理【免费下载链接】threejs-game-skillsAgent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.项目地址: https://gitcode.com/gh_mirrors/th/threejs-game-skillsthreejs-game-skills 是一套面向 AI Agent 的 Three.js 游戏开发技能包其中内置了一个开箱即用的Vite TypeScript Three.js 游戏脚手架位于 gameplay 技能目录内。本文带你完整拆解这套 Three.js 游戏架构的代码实现原理从主循环、渲染器配置到输入统一、帧率无关的物理移动、确定性测试钩子看懂它如何保证游戏可玩、可测、可发布。上图正是脚手架自带演示游戏收集 Relays 竞技场的运行画面黄色胶囊玩家 8 个拾取球 极简 HUD与下面要讲的代码一一对应。脚手架在哪里一个技能包里的游戏模板这个脚手架不是独立项目而是打包在 gameplay 技能内部当 Agent 从空目录创建新游戏时它就是起点skills/threejs-gameplay-systems/assets/threejs-vite-game/ ├── src/ │ ├── core/ # 主循环、输入、渲染器 │ ├── entities/ # 玩家、拾取物等实体 │ ├── game/ # Game 总装配类 │ ├── systems/ # 相机、碰撞、HUD、音频、调试工具 │ ├── utils/ # 种子随机数、资源释放 │ └── main.ts # 入口 └── tests/ # Playwright 视觉/冒烟测试依赖极轻核心运行时只有 package.json 中的three和一个 lil-gui 调试面板开发侧则是 Vite 8、TypeScript 和 Playwright。架构总览Game 类是总装配线一切由 main.ts 启动找到页面上的#game-canvasnew Game(canvas)然后game.start()。Game.ts 是架构的核心它把各子系统在构造函数里一次性装配好渲染层createRenderer(canvas)创建 WebGL 渲染器场景、透视相机各自独立输入层InputController同时接管键盘和触屏摇杆实体层Player玩家、Pickup[]拾取球系统层CollisionSystem碰撞、CameraRig相机跟随、Hud、AudioSystem、DebugTools驱动层Loop持有update和render两个回调每帧依次执行这种core 驱动 entities 表现 systems 服务的分层让 AI Agent或人类扩展游戏时只需新增实体和系统而不用动主循环。主循环实现requestAnimationFrame 帧时间钳制Loop.ts 只有 30 行却藏着两个关键细节const deltaSeconds Math.min((time - this.lastTime) / 1000, 0.05);delta 钳制在 0.05 秒切后台再回来时不会收到一个巨大的时间差物理不会穿墙每帧严格遵循update(delta, elapsed) → render()顺序逻辑先跑、渲染后跑相机位置永远基于最新逻辑帧start()/stop()用requestAnimationFrame / cancelAnimationFrame成对管理running标志防止重复启动——这是最标准也最稳的浏览器游戏主循环写法。渲染器配置一次调好色彩、阴影与 DPRRenderer.ts 把渲染器配置收敛成两个函数值得逐行看创建时一次性设置createRendererantialias: truepowerPreference: high-performance开启抗锯齿并声明性能优先outputColorSpace SRGBColorSpaceACESFilmicToneMapping线性工作流 电影级色调映射这是Three.js 游戏画面不显灰的关键shadowMap用PCFShadowMap柔和阴影每帧检查尺寸resizeRendererconst dpr Math.min(window.devicePixelRatio || 1, maxDpr); // maxDpr 2DPR 封顶 24K 屏不会白白渲染 4 倍像素用canvas.clientWidth/Height比对缓冲区尺寸只在真正变化时才setSize 更新相机宽高比避免每帧白算注意setSize(width, height, false)第三参为 false——尺寸由 CSS 管避免样式抖动输入统一键盘与触屏摇杆汇成一个向量InputController.ts 的设计思路是两套输入一个出口键盘侧用Setstring记录按住的event.codeWASD 方向键空格/Shift 触发冲刺触屏侧摇杆用 Pointer Events setPointerCapture锁定指针按下位置记为中心偏移除以半径归一化出口是readMovement(target)键盘向量 指针向量相加长度超过 1 就归一化防止斜向加速游戏逻辑只关心一个方向向量 是否冲刺完全不关心输入来源。测试脚本可以直接伪造键盘或鼠标事件来驱动游戏这是它能被自动测试的前提。帧率无关的移动指数平滑是灵魂Player.ts 的移动代码是整套脚手架里最值得抄作业的片段const smoothing 1 - Math.exp(-tuning.acceleration * delta); this.velocity.lerp(this.targetVelocity, smoothing); this.group.position.addScaledVector(this.velocity, delta);目标速度 输入方向 × 速度 × 冲刺倍率当前速度向目标速度做 lerp平滑系数1 - e^(-acceleration·delta)保证手感与帧率无关60fps 和 144fps 下加速曲线完全一致位置用addScaledVector(velocity, delta)积分同样是帧率无关边界用MathUtils.clamp锁在竞技场范围内朝向用atan2面向速度方向细节加分项position.y叠加一个与速度挂钩的正弦微浮动角色活起来CameraRig.ts 用同一个公式做相机惯性跟随lag 0.16s这是浏览器 3D 游戏高级感最便宜也最有效的来源。轻量碰撞不引入物理引擎的取舍CollisionSystem.ts 只有 20 行——它刻意没有引入 Cannon.js 之类的物理引擎而是做 2D 圆-圆相交比较前把delta.y 0只在水平面上判定用lengthSq() r²比较平方距离避免开方开销复用同一个Vector3实例零每帧分配对竞技场收集类游戏来说这足够且快仓库的 gameplay 技能文档physics-engine-selection.md也说明了何时该升级物理方案。确定性设计种子随机数 测试钩子这是整个脚手架最有工程味的部分也是 AI Agent 能自我验证游戏的基础1. 全局种子 RNGrandom.ts 实现了一个 mulberry32 种子随机数并在 Game.ts 中有一条硬约束所有游戏内随机数必须走this.rng禁止Math.random否则截图基线和机器自测就无法复现。2.__THREE_GAME_TEST_HOOKS__钩子Game 类把一组控制函数挂到window上钩子作用seed(n)重置随机种子保证基线可复现setState(active-play \| complete)强制进入指定游戏状态截图setPausedForScreenshot(true)冻结逻辑只保留渲染setReducedMotion(true)冻结环境动画时间让截图逐像素稳定3.__THREE_GAME_DIAGNOSTICS__诊断每帧把分数、玩家位置、renderer.infodraw call / 三角形数、canvas 实际分辨率写回 window测试脚本和调试面板DebugTools.ts直接读取——游戏对外暴露了它自己的仪表盘。QA 闭环用 Playwright 验证画上了、能玩了脚手架的 tests/visual.spec.ts 展示了它如何把上述钩子用起来等__THREE_GAME_DIAGNOSTICS__.frame 10确认主循环真的在转像素采样防空白截 canvas 图用 pngjs 算亮度方差和颜色桶数排除黑屏也通过测试真实操控验证桌面项目按W键、移动项目拖虚拟摇杆然后断言玩家 z 坐标确实前进了收集 console error 与 pageerror断言必须为空全页截图作为证据附件配套的 inspect-threejs-canvas.mjs 脚本还能在非浏览器环境测量颜色熵、边缘密度等指标。模板文件bot-playtest.template.ts、visual-regression.template.ts则预留了机器自玩和视觉回归基线的扩展位。一键跑起来脚手架的 package.json 脚本已经把常用动作都配好了npm run dev # Vite 开发服务器127.0.0.1:5188 npm run build # tsc 类型检查 生产构建 npm test # Playwright 全套 QA npm run verify:visual # 仅跑视觉冒烟测试Vite 配置vite.config.ts锁定 127.0.0.1 与固定端口strictPort: true就是为了测试脚本能稳定连接——开发工具链本身也是为可测试性服务的。总结这套架构教给我们什么设计点做法收益分层装配core 驱动 / entities 表现 / systems 服务扩展不动主循环主循环delta 钳制 update→render 固定顺序防时间炸弹渲染ACES 色调映射 DPR 封顶 2 按需 resize好看且不浪费输入键盘/触屏归一为一个向量桌面移动一套逻辑手感1-e^(-k·delta)指数平滑帧率无关的物理可测试种子 RNG window 钩子 诊断对象Agent 能自我验证QAPlaywright 像素采样 真实操控断言能玩有证据对于新手来说这个脚手架最大的价值不是那几行 Three.js 代码而是它示范了浏览器 3D 游戏的完整工程闭环写代码只是开始可复现、可测量、可回归才是能交付的标准。把 skills/threejs-gameplay-systems/SKILL.md 和上面的源码对照着读你会对一个可玩的 Three.js 游戏到底由什么构成建立起清晰的直觉。【免费下载链接】threejs-game-skillsAgent skills for building playable, polished Three.js browser games with gameplay, AAA-style graphics, UI, QA, and optional AI-generated 3D, image, and audio assets.项目地址: https://gitcode.com/gh_mirrors/th/threejs-game-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考