> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/customization/native-assets) instead.

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

## Recommended Studio workflow / 推荐流程

<Steps>
  <Step title="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.
  </Step>

  <Step title="Open local Content Studio">
    Run `npm run dev`, then open the loopback URL with `?studio=1`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Staging and cleanup / 暂存与清理

Upload does not immediately publish a model:

```text theme={null}
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](/faq/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`.