GLB Models

Validate, preview, place, save, replace, remove, optimize, and troubleshoot self-contained glTF 2.0 binary models.

Use a GLB when an object needs authored geometry, textures, or a silhouette that would be inefficient to reproduce with native Three.js primitives. For simple decorations, consider a native asset instead.

GLB 可以新建 decorative 或 interactive 资产，也可以可逆地替换某个内置物件的视觉模型。 内置程序化定义仍保留在代码中，因此移除替换后可以恢复原物件。

Recommended Studio workflow / 推荐流程

1. Prepare a self-contained glTF 2.0 binary

   Export one .glb with embedded PNG, JPEG, or WebP textures. Apply transforms, remove unused nodes, and avoid decoder-dependent extensions.

2. Open local Content Studio

   Run npm run dev, then open the loopback URL with ?studio=1.

3. Choose the role

   Replace an enabled built-in visual, or create a custom asset. Set a custom asset to Decorative when it should have no page, or Interactive when it needs bilingual content, index entry, and deep link.

4. Upload and wait for Ready

   The Studio validates and stages the GLB. Its status progresses through fetching, processing, ready, or error. The retained native object or a visible placeholder keeps placement editable during this phase.

5. Place and confirm

   Use Plane X/Z, Height Y, and Heading rotation. Hold Shift for 15° heading snapping and set scale numerically. Select Confirm all placement.

6. Save, validate, and push

   Select Save to project, inspect the JSON, generated scene module, and final upload in git status, run the validation commands, then commit and push.

Staging and cleanup / 暂存与清理

Upload does not immediately publish a model:

selected file
  -> validation
  -> .content-studio-cache/models/<uuid>.glb
  -> local preview as /uploads/models/<uuid>.glb
  -> Save to project
  -> public/uploads/models/<uuid>.glb

The cache is Git-ignored. Only a model referenced by the final saved scene is promoted. Replaced or removed staged files are eagerly discarded when possible; every successful save also clears unreferenced staged files. A previously published GLB omitted from the new saved scene is removed from public/uploads/models/.

This means the content document can retain one stable public URL before and after save, while the server changes which filesystem location supplies it.

Save products / 保存产物

A successful save updates all required scene artifacts:

• public/content/site-content.json records modelSrc, purpose, content, and transform;
• app/generated/scene-config.ts records the same normalized scene for the production bundle; and
• public/uploads/models/<uuid>.glb contains the final model bytes.

Commit the three categories together. Manually copying only a JSON reference cannot make an absent GLB deployable and cannot update the production scene snapshot.

Validator limits / 验证限制

Resource	Maximum
File size	24 MiB
GLB JSON chunk	1 MiB
Nodes	512
Node edges	2,048
Mesh definitions	256
Rendered mesh instances	256
Primitives	512
Rendered triangles	1,000,000
Embedded images	16
One texture edge	8,192 px
One texture	32 Mi pixels
All textures	64 Mi pixels

These are safety ceilings, not performance targets. Aim much lower for mobile devices. See Performance.

The validator rejects malformed GLB structure, out-of-range buffer access, external resource URIs, node cycles, unsupported embedded image formats, and runtime extensions that require unconfigured Draco, Meshopt, Basis/KTX2, or similar decoders.

Blender export checklist / Blender 导出检查

• Use metres and apply rotation and scale.
• Use Principled BSDF for lit PBR materials.
• Keep Base Color textures in sRGB and data maps in their intended non-color space.
• Use OpenGL normal-map orientation.
• Embed all textures.
• Remove cameras, lights, empty nodes, duplicate meshes, and hidden geometry that the page does not need.
• Combine static meshes where that reduces material and draw-call overhead.
• Keep a hero asset around 5k–20k triangles and a small prop below roughly 2k before device testing.
• Remove branded or copyrighted textures unless the licence permits their use.

Lighting behavior / 光照交互

The loader enables shadow participation for mesh materials, but the visible day/night response still depends on the exported material:

• standard lit PBR materials respond to the room’s hemisphere, sun, moon, and practical lights;
• unlit/basic materials do not respond to light;
• strong emissive values can flatten the day/night difference; and
• incorrect normals, metallic values, or color space can make a model appear unexpectedly dark.

The asset accent color styles interaction UI and markers. It does not convert or repair a GLB material.

When a placeholder remains / 占位符不消失

Check the Studio status and browser Network/Console panels:

1. Upload rejected: re-export a valid self-contained GLB within the limits.
2. Fetching fails: confirm the path is the same-origin /uploads/models/<uuid>.glb generated by the Studio.
3. Processing fails: inspect unsupported material/extension or empty-scene errors.
4. Slow first appearance: reduce textures, primitives, mesh instances, and materials. Parsing and GPU compilation still take time after bytes arrive.
5. Built-in replacement fails: the native object intentionally stays as fallback.
6. Custom model fails: the visible placeholder intentionally stays so you can replace or remove it.

The React warning Detected multiple renderers concurrently rendering the same context provider describes concurrent React renderer/provider trees, often during HMR. It does not prove that the GLB is invalid. Restart duplicate previews/dev servers and inspect React/provider duplication separately.

Direct code path / 代码直连

Studio-managed models belong in public/uploads/models/ and should be referenced through scene configuration. If a bespoke runtime feature needs a manually managed GLB, add it under a clearly documented public/ path, write the loading, timeout, cancellation, disposal, fallback, and accessibility logic in code, and record why it is outside the Studio transaction.

Do not hotlink a third-party model. Archive its source and licence, optimize it locally, self-host the permitted derivative, and update ASSET_CREDITS.md.