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.

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.

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.

1. Add and upload / 新增并上传

   Add a custom asset and choose a valid, self-contained glTF 2.0 GLB.

2. Place it / 摆放

   Use Plane X/Z, Height Y, and Heading rotation. Hold Shift for 15° heading snapping; edit scale numerically.

3. Author both languages / 编辑双语内容

   Fill object label, title, intro, metrics, and text/media/links cards in Chinese and English.

4. Save / 保存

   Finish placement, then click Save to project to write JSON, generate scene source, and promote the final GLB.

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 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:

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 导出不包含二进制资源，也不会生成发布场景源码，因此不能替代完整保存流程。