黑屏、卡顿、移动端错位threejs-debug-profiler的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-skillsThree.js 游戏开发中最头疼的三类问题——黑屏、卡顿、移动端错位在开源项目 threejs-game-skills 中都有对应的专家技能threejs-debug-profiler。它把先复现、再测量、后优化的调试方法论固化成一套可执行清单帮你定位根因而不是瞎猜适合新手和独立开发者快速上手 Three.js 游戏调试与性能剖析。一、threejs-debug-profiler 是什么它是 threejs-game-skills 仓库中专门负责调试与性能剖析的 Agent 技能核心目标只有一句话找到根因优化测量到的瓶颈且不破坏可玩性。它内置了完整的双工作流调试工作流按 9 个固定步骤排查渲染、运行时、加载、动画、resize、移动端输入、黑画布、物理碰撞等问题性能工作流先记录基线指标FPS、Draw Call、三角形数、显存再逐项优化并复测拒绝凭感觉优化技能入口文件SKILL.md二、黑屏排查一张 11 项空白画布检查清单画面一片黑是最常见的新手噩梦。在 scene-debugging.md 中技能要求按固定顺序逐项检查而不是随机翻代码Canvas 是否存在于 DOM 中Canvas 的 CSS 尺寸是否非零且可见绘制缓冲区drawing buffer尺寸是否匹配 DPR 行为WebGL 上下文是否创建成功渲染循环是否只启动了一次且在持续运行相机 aspect、投影矩阵、near/far 是否正确场景中是否有位于相机前方的可见物体灯光、材质 side、opacity、深度与色彩管理是否正常资源 URL、CORS、异步加载顺序是否有失败请求动画 delta 是秒还是毫秒物理/更新顺序是否正确碰撞层的半径与缩放是否匹配视觉预期 关键原则先本地复现、先读控制台第一条报错再改代码。很多黑屏其实是 CSS 覆盖层挡住了 Canvas、或背景色/雾色与物体颜色撞了。三、移动端错位触控输入检查清单手机端出现按钮点不动、页面乱滚、控制区挤成一团根源通常在这几处。mobile-input.md 给出了针对性清单症状对应检查点手势被页面滚动抢走viewport meta、touch-action: none只在需要的地方设置按钮点不到触控目标尺寸、是否位于安全区域内旋转后画面拉伸orientation/resize 处理、相机 aspect 更新高分屏上模糊或掉帧高 DPR 下的画布缩放必要时限制 DPR虚拟摇杆松开失效pointer release/cancel 路径测试清单还强调用 Playwright 移动端模拟 真机烟测双重验证桌面输入在加入移动控件后必须仍然可用。四、性能剖析FPS、Draw Call、三角形数怎么测卡顿不能靠感觉。performance-profile.md 规定了一套标准测量流程性能剖析基线步骤记录环境目标设备、浏览器、视口、DPR、构建模式务必在生产 preview 下测别测开发服务器采集基线FPS/帧时间预热后、renderer.info中的 Draw Call、三角形数、几何体与纹理数量归类瓶颈CPU 模拟 / GPU 绘制 / GPU 片元overdraw、后处理/ GPU 顶点 / 显存 / 包体积一次只改一项复测同一场景并检查画面与可玩性是否回归高优先级优化手段清单按性价比排序给出了推荐优化项新手可以直接照着做InstancedMesh重复出现的树木、栏杆、子弹用实例化共享资源复用几何体、材质、纹理杜绝每个物体一份对象池特效、子弹、碎片用池子避免每帧 new✂️裁剪与 LOD视锥/距离裁剪远景道具降精度️限制 DPR 或自适应画质高刷屏上的隐形性能杀手廉价阴影减少投射物、缩小阴影贴图、静态阴影替代显存纪律纹理压缩、图集、mipmap切换场景时 dispose 资源技能还建议在window上挂一个诊断对象暴露renderer.info.render.calls、triangles、memory.geometries、memory.textures等字段让性能数据一眼可见详见 debug-profile-checklists.md 的 Renderer Diagnostics 一节。五、快速上手两步用起来1️⃣ 安装技能包git clone https://gitcode.com/gh_mirrors/th/threejs-game-skills克隆后运行./install.sh --all或用官方一键安装npx skills add majidmanzarpour/threejs-game-skills --skill * -a codex -g -yClaude Code 将-a codex换成-a claude-code。2️⃣ 让 Agent 按清单排查技能自带可直接复用的 prompt-templates.md三类问题各有一套模板场景调试描述症状黑屏/冻结/resize 异常→ 要求本地复现、检查相机与画布尺寸、截图像素采样验证性能剖析给出帧率目标与瓶颈 → 要求只实施有测量依据的修改移动端输入列出目标设备 → 要求检查安全区、DPR、pointer 释放路径 也可以不指定技能名直接说帮我调试这个 Three.js 游戏——总入口threejs-game-director会自动把调试剖析技能拉进来。六、配套资源速查资源路径用途调试技能入口skills/threejs-debug-profiler/SKILL.md双工作流总纲综合排查清单debug-profile-checklists.md黑屏/资源/音频/物理/性能全覆盖场景调试清单checklists/scene-debugging.md渲染与运行时错误性能剖析清单checklists/performance-profile.md基线测量与复测移动端输入清单checklists/mobile-input.md触控与画布缩放画布检查脚本inspect-threejs-canvas.mjs验证画布非空、采样像素指标内置游戏脚手架assets/threejs-vite-game/含测试钩子的 Vite TS Three.js 模板总结threejs-debug-profiler 的价值不在于更多工具而在于把调试从玄学变成流程黑屏按 11 项清单逐项过卡顿先测基线再单次优化移动端错位对照触控检查清单逐项验证。配合仓库中的 QA 与调试清单即使是新手也能按图索骥地把一个黑屏卡顿的 demo变成可交付的浏览器游戏。【免费下载链接】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），仅供参考