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 / 卡顿排查

1. Separate loading from steady-state rendering

   Record whether the slowdown occurs only during fetching/processing or continues after all models report ready.

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

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

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

5. Validate the complete experience

   Test camera movement, day and night lighting, repeated panel open/close, background-tab behavior, WebGL fallback, and a throttled network.

For simple decorations, a native procedural asset often loads faster and is easier to tune than a textured GLB. See Native assets and GLB models.