> ## 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.

# Performance

> Understand the room renderer, GLB validation limits, loading phases, and practical performance budgets.

The Living Index favors a stable, legible room over a fixed frame-rate claim.
Measure on the devices you intend to support; geometry, materials, texture
memory, screen resolution, and GPU all affect the result.

The Living Index 以稳定、清晰的房间体验为目标，不承诺所有设备都达到固定帧率。
应在目标手机和电脑上进行实测。

## Built-in controls / 内置控制

| Control            | Current behavior                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| Device pixel ratio | Capped at `1.2` on screens up to 740 px wide and `1.6` otherwise                               |
| Antialiasing       | Disabled on the mobile breakpoint                                                              |
| Shadow map         | One directional shadow light; 512 px mobile, 1024 px desktop                                   |
| Post-processing    | No SSAO, depth of field, or bloom pipeline                                                     |
| Hidden tabs        | The animation callback exits while the document is hidden                                      |
| Cleanup            | Loaders, timers, controls, geometries, materials, renderer, and canvas are released on unmount |
| Loading feedback   | A retained native visual or placeholder reports fetch, processing, ready, and error states     |

## What loads when / 何时加载

Built-in room objects are native Three.js geometry. GLB references present in
the active scene configuration are loaded asynchronously while the scene is
synchronized; they are not deferred until a chapter is opened.

Content Studio keeps the selected local `File` in a short-lived prepared-upload
buffer. This can avoid an immediate second network read during the first local
preview. GLB parsing, texture upload, shader compilation, and fitting still
take time, so a brief placeholder is expected.

生产构建从 `public/uploads/models/` 读取已保存的 GLB。只有成功保存且被最终场景引用的
模型才会进入该目录。

## Hard upload limits / 上传硬限制

Content Studio rejects a model that exceeds any of these validator limits:

| Resource                |      Maximum |
| ----------------------- | -----------: |
| GLB file                |       24 MiB |
| 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 embedded texture    | 32 Mi pixels |
| All embedded textures   | 64 Mi pixels |

These are safety ceilings, not recommended targets. A model can pass validation
and still be too expensive for a phone.

The upload accepts embedded PNG, JPEG, and WebP images supported by the
validator. Keep the GLB self-contained; external resource URIs and extensions
that require unconfigured runtime decoders are rejected.

## Practical authoring budget / 实用制作预算

Use this as a starting point, then profile:

| Asset                                   | Suggested triangles |                 Suggested texture |
| --------------------------------------- | ------------------: | --------------------------------: |
| Hero object                             |              5k–20k |   1K; 2K only when visibly useful |
| Small prop                              |            Under 2k |                            512–1K |
| Mobile first view, all visible objects  |   Under roughly 80k |      Minimize unique texture sets |
| Desktop first view, all visible objects |  Under roughly 150k | Measure draw calls and GPU memory |

Prefer a few shared, opaque PBR materials. Transparent layers, many separate
materials, skinned animation, and large textures can cost more than triangle
count alone suggests.

## Diagnose a slow room / 卡顿排查

<Steps>
  <Step title="Separate loading from steady-state rendering">
    Record whether the slowdown occurs only during **fetching/processing** or
    continues after all models report **ready**.
  </Step>

  <Step title="Profile a representative device">
    Record 5–10 seconds in the browser Performance panel while orbiting and
    opening a chapter. Look for long animation frames, repeated network work,
    and texture/shader compilation.
  </Step>

  <Step title="Remove one expensive variable">
    Temporarily disable the suspected custom asset in Content Studio. If the
    problem disappears, reduce its textures, primitives, material count, or
    triangles and re-export.
  </Step>

  <Step title="Inspect renderer statistics in code">
    During a temporary local diagnostic, log `renderer.info.render.calls` and
    `renderer.info.render.triangles` inside the room renderer. Remove the log
    before committing; `renderer` is not a global Console variable.
  </Step>

  <Step title="Validate the complete experience">
    Test camera movement, day and night lighting, repeated panel open/close,
    background-tab behavior, WebGL fallback, and a throttled network.
  </Step>
</Steps>

For simple decorations, a native procedural asset often loads faster and is
easier to tune than a textured GLB. See [Native assets](/customization/native-assets)
and [GLB models](/customization/glb-models).