Three.js: Load a glb and Assemble a Scene
/threejs-glb-scene-assembly
A GameSkill original: load a glb (Draco included) into three.js asynchronously and wire a small playable scene around it: loading bar, model normalisation, colliders, a water shader with matching buoyancy, lights, pooled particles and WebAudio sound.
- 许可证
- MIT
- 出品
- GameSkill 出品
我们测过
在 three.js r186 (0.186.1) in Chrome 156 headless 上通过 40/40 项检查（2026-10-28）：能触发、有可运行示例、有截图和自检清单、单一职责、中英文文档齐全。触发检查是把提示词和 skill 描述做匹配，不是真实 agent 运行。
测试报告GameSkill 测过的版本
GameSkill 为 gameskill.dev 原创编写并测过。ZIP 里是完整的 skill：SKILL.md 及中文版、脚本、可运行示例、测试、自检清单和我们的测试报告。
GameSkill 原创，协议 MIT。ZIP 保留 LICENSE 和 CREDITS.md，里面列出了流程灵感来源、CC0 测试素材和第三方库及其协议。
自检清单
- 通过 http 访问，DRACOLoader 解码器路径没有 404 / Served over http; the DRACOLoader decoder path has no 404
- 全部用 loadAsync + Promise.all 加载完再开始玩，加载失败在画面上提示 / Everything loads with loadAsync + Promise.all before play starts; load errors show on screen
- 模型缩放到已知高度、轴心在底部，碰撞体从模型算出来 / Model scaled to a known height, pivot at the base, colliders derived from the model
- 水面着色器和 CPU 浮力用同一张波浪表 / Water shader and CPU buoyancy share one wave table
- AudioContext 在用户操作里创建或恢复 / AudioContext created or resumed inside a user gesture
- npm test 和 npm run test:browser 都通过，没有控制台错误 / npm test and npm run test:browser pass with no console errors
中文指南
这个 skill 做什么
GameSkill 原创（MIT）。在 three.js 里异步加载 glb（包括 Draco 压缩过的），并围绕它搭一个能玩的小场景：带进度条和错误提示的 GLTFLoader + DRACOLoader、模型尺寸和轴心统一、球体/AABB 碰撞、正弦叠加的水面着色器加上一致的 CPU 浮力、太阳光加半球光和阴影、对象池粒子，以及用 WebAudio 实时合成的环境声、音乐和音效（不需要音频文件）。
什么时候用
- 想在 three.js 里加载 glb / gltf 模型
- 遇到
DRACOLoader、解码器 404、模型看不见、颜色发灰发黑这类问题 - 想搭第一个网页 3D 游戏场景：水面、漂浮物、简单碰撞、粒子、浏览器里合成的声音
怎么装
下载本页的 ZIP，把 threejs-glb-scene-assembly/ 整个文件夹放进 .claude/skills/（Claude Code）或 .agents/skills/（Codex、Cursor），重启 agent。three.js r186 和 Draco 解码器已经在 vendor/ 里，可以离线运行。
最小示例
示例叫 Bottle Cove（漂流瓶小岛）：在小岛上走动，捡起在浅滩里随浪漂浮的瓶子，撞到石头会被挡住。node test/serve.mjs 启动后打开 http://localhost:8766/。接线代码在 src/main.js（8 个编号小节），不依赖引擎的逻辑在 src/logic.js。换自己的模型：地址后面加 ?model=./assets/your.glb。瓶子模型是 Khronos 的 WaterBottle（CC0），用 multiview-to-web-3d-asset 压过。
我们怎么测的
npm test 跑 16 个 Node 测试：波浪高度有界、随时间连续变化、法线朝上；漂浮物落到水面并跟着浪走；球体被推出盒子、高速也不会穿过石头；移动限速、斜向归一、摩擦停下；粒子池复用；音乐只用五声音阶、排程窗口不漏不重。npm run test:browser 在无头 Chrome（SwiftShader WebGL）里做 10 项检查：异步解码 Draco glb（2,908 个三角形）、渲染循环在跑、画面里有水和沙子的颜色、按键后 AudioContext 变成 running、能捡到瓶子、石头挡住角色、没有控制台错误和失败请求、glb 缺失时画面上显示错误而不是抛异常。结果在 gameskill/test-report.json。
致谢
流程灵感来自 X 上 @gkxspace 分享的工作流。代码和文字是我们自己写的。three.js（MIT）和 Draco 解码器（Apache-2.0）连同各自的协议一起附带，详见 CREDITS.md。
搭配
multiview-to-web-3d-asset（进阶）：先把 glb 压到预算内（示例里的瓶子就是它的输出）threejs-game-skills：场景跑通后，用它的 Vite + TypeScript 脚手架做完整游戏game-feel：给捡瓶子加震屏和停顿
安装
告诉你的 AI
Install the skill from https://gameskill.dev/skills/threejs-glb-scene-assembly/install.md
GameSkill 测过的版本
mkdir -p .claude/skills
curl -fsSL https://gameskill.dev/dl/skills/threejs-glb-scene-assembly.zip -o /tmp/gameskill-threejs-glb-scene-assembly.zip
unzip -oq /tmp/gameskill-threejs-glb-scene-assembly.zip -d .claude/skills
rm /tmp/gameskill-threejs-glb-scene-assembly.zip包含内容
- Bottle Cove: a playable demo in one file of wiring (src/main.js, 8 numbered sections)
- GLTFLoader + DRACOLoader with a LoadingManager progress bar and an on-screen error overlay
- prepareModel: scale to a target height, pivot at the base, shadows on
- Sphere and AABB colliders, a sum-of-sines water shader with matching CPU buoyancy, pooled particles
- WebAudio ambience, music and SFX synthesised at runtime (no audio files)
- 16 Node logic tests and a 10-check headless Chrome test
适合
- A first 3D web game scene in three.js
- Fixing DRACOLoader decoder errors, invisible models and colour-space problems
- Water, floating objects, simple collisions and particles without a physics engine
不适合
- Large worlds or real physics: use a physics engine such as Rapier when the scene grows
- Making the glb itself small: run it through multiview-to-web-3d-asset first
试试这条提示词
Load my Draco glb in three.js with a loading bar and drop it into a small scene I can walk around.关于这个 Skill
A GameSkill original, written and tested for gameskill.dev under MIT. The demo, Bottle Cove: walk around an island, pick up bottles bobbing in the surf, bump into rocks. One file of wiring (src/main.js, 8 numbered sections) and one engine-free logic module (src/logic.js) that the Node tests cover.
Agent steps
- Loaders: one
LoadingManagerfor progress,DRACOLoader().setDecoderPath(...), thengltfLoader.setDRACOLoader(draco). Load withawait Promise.all([loader.loadAsync(url), ...]); start gameplay only after it resolves and show errors on screen. - Normalise the model (
prepareModel): measure withBox3, scale to a target height, put the pivot at the base centre, enable shadows. Never trust the file's scale. - Collider: derive it from the loaded model (bounding sphere; AABBs for static props).
- Water: a
ShaderMaterialwhose vertex shader andlogic.waveHeightshare one wave list, so floating objects ride the visible surface. - Lights: hemisphere fill plus one directional sun with a tight shadow camera; sRGB output and ACES tone mapping.
- Particles: one
Pointswith a fixed pool; no allocation in the loop. - Audio: create the
AudioContexton the first key or pointer event; surf, a pentatonic pluck loop on a look-ahead scheduler, one-shot chime and bump. - Loop: clamp
dtto 50 ms so a background tab doesn't teleport anything.
Common errors it fixes
THREE.DRACOLoaderdecoder errors or a 404 ondraco_decoder.wasm: wrong decoder path, or the page was opened fromfile://.- Invisible model: the scale (AI meshes arrive at 1 or 100 units) or a camera inside it;
prepareModelfixes both. - Black or washed-out custom shader: missing
#include <colorspace_fragment>, or tone mapping applied twice. - No sound: the context was created before a user gesture and stays
suspended.
Credits
Workflow inspiration: a post by @gkxspace on X. Code and text are ours. Model: Khronos WaterBottle (Microsoft, CC0-1.0), optimised with Multi-view to Web-ready 3D Asset. three.js r186 (MIT) and the Draco decoder (Apache-2.0) are vendored with their licences.
环境要求
- A static http server (node test/serve.mjs is included); glb and wasm do not load from file://
- Node.js 20+ to run the tests; Chrome for the browser check
相关主题
常见问题
搭配使用
作者标注的相关 Skills，或更适合相邻任务的 Skills。
Multi-view to Web-ready 3D Asset
A GameSkill original: front, side and back reference prompts, any image-to-3D provider, then a tested glTF Transform pass that simplifies, resizes textures, applies Draco and builds LODs inside a triangle and file-size budget.
Three.js Game Skills
Nine Agent Skills for Codex and Claude Code that build playable Three.js browser games, with a director skill, a Vite scaffold and Playwright QA.
img2threejs
An Agent Skill that rebuilds the object or character in a reference image as a code-only, animation-ready Three.js model, checked pass by pass.
相似 skills
Godogen
Autonomous game development with Claude Code and Codex. Publishes a ready game repo for Godot, Bevy, Babylon.js or three.js.
3AGameFactory (GameFactory-3A)
An Apache-2.0 framework of agent skills and pipelines that turns a game requirement into assets (image, 3D, motion, audio, CG video) and engine-ready code for UE5, Blender, Unity, Godot 4 and three.js.
Awesome Gamedev Agent Skills
76 portable SKILL.md skills across 12 engines (Godot, Unity, Unreal, Phaser, PixiJS, three.js, Bevy, pygame, LÖVE, Roblox, Defold, Ebitengine), with a router.
3dviz Pro Max
Turn an idea into a Three.js or Blender scene: 223 recipes, 440 knowledge records and runnable studio examples.