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

# Choose How to Add or Replace an Asset

> Choose between built-in visual replacement, decorative or interactive custom GLBs, native Three.js props, and full cross-layer framework extensions.

“增加数字资产”可能代表四种不同需求。先选择正确路径，避免为了装饰物创建多余页面，也避免把复杂模型硬写成程序化几何。

“Add an asset” can mean four different things. Choose the correct path first so a decoration does not create an unnecessary page and a complex model is not forced into procedural geometry.

```mermaid theme={null}
flowchart TD
  A["Asset request"] --> B{"Replace an existing built-in visual?"}
  B -->|Yes| C["Core GLB replacement"]
  B -->|No| D{"Complex textured model?"}
  D -->|Yes| E{"Needs content?"}
  E -->|No| F["Custom decorative GLB"]
  E -->|Yes| G["Custom interactive GLB"]
  D -->|No| H{"Simple prop?"}
  H -->|Yes| I["Native Three.js asset"]
  H -->|No| J["Developer cross-layer extension"]
```

## 1. Replace a built-in visual / 替换内置外观

Use **Scene layout → Built-in assets → Replace visual**.

* Keeps the built-in ID and bilingual content.
* Keeps its hitbox, signal marker, deep link, and placement.
* Fits the GLB to the native bounds.
* Keeps the current visual during processing.
* Restores the native visual when cleared.

适合把相机、植物、留声机等程序化外观升级为 GLB，而不新增章节。

See [GLB models](/customization/glb-models).

## 2. Add a custom decorative GLB / 添加装饰 GLB

Use **Scene layout → Add new asset**, upload the GLB, and choose **Decorative**.

Decorative assets:

* appear in the room;
* support transform and accent editing;
* do not create a signal marker, hitbox, index entry, deep link, or detail page.

适合背景道具、家具、气氛物件和纯视觉陈列。

## 3. Add a custom interactive GLB / 添加交互 GLB

Choose **Interactive** only when the object deserves a complete content surface.

<Steps>
  <Step title="Add and upload / 新增并上传">
    Add a custom asset and choose a valid, self-contained glTF 2.0 GLB.
  </Step>

  <Step title="Place it / 摆放">
    Use Plane X/Z, Height Y, and Heading rotation. Hold Shift for 15° heading snapping; edit scale numerically.
  </Step>

  <Step title="Author both languages / 编辑双语内容">
    Fill object label, title, intro, metrics, and text/media/links cards in Chinese and English.
  </Step>

  <Step title="Save / 保存">
    Finish placement, then click **Save to project** to write JSON, generate scene source, and promote the final GLB.
  </Step>
</Steps>

Interactive custom assets automatically participate in:

* hover and click;
* semantic content index;
* keyboard navigation;
* `?section=custom-*` deep links;
* detail panels and related-content logic;
* derived camera focus.

## 4. Generate a native Three.js prop / 生成原生资产

Use [Native assets](/customization/native-assets) when the object is simple:

* boxes, cylinders, spheres, planes, and curves are sufficient;
* color and roughness matter more than authored textures;
* immediate load and low overhead are valuable;
* it can be decorative or extend an existing built-in group.

The repository includes `$living-index-native-assets` so a coding agent can generate the object using the scene's own helpers and material language.

仓库内的 `$living-index-native-assets` 可以让 coding agent 直接按现有场景风格生成轻量物件。

## 5. Add a new framework-level interaction / 新增框架级交互

A genuinely new core asset is not only a Three.js group. It may require changes to:

1. `CoreAssetId` and `CONTENT_ASSET_IDS`;
2. Chinese and English defaults;
3. schema normalization and limits;
4. runtime factory and placement registration;
5. focus, hitbox, signal, route, and semantic index;
6. Content Studio controls;
7. reduced-motion and WebGL fallback behavior;
8. unit and rendered-contract tests.

Route this work through `$living-index-developer`. Do not extend a fictional `AssetId` union; current custom interactive IDs are strings, while core IDs remain constrained separately.

这属于跨层框架开发，不是一次普通模型上传。

## Save and release / 保存与发布

Studio-managed GLBs stage outside `public` until save. After **Save to project**, commit:

```bash theme={null}
git status --short
git add public/content/site-content.json app/generated/scene-config.ts
git add public/uploads/<specific-final-files>
git diff --cached --check
git commit -m "Add scene asset"
git push origin main
```

JSON export is not a substitute for this flow because it does not include binaries or regenerate the published scene source.

JSON 导出不包含二进制资源，也不会生成发布场景源码，因此不能替代完整保存流程。