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

# Edit Scene Layout and Asset Behavior

> Move, rotate, disable, reactivate, or visually replace built-in objects, and place decorative or interactive custom GLBs.

Open local `/?studio=1`, then select **Scene layout** in the left navigation. The editor works with two asset families:

在本地 `/?studio=1` 打开工作台，并从左侧进入 **Scene layout**。编辑器处理两类资产：

<CardGroup cols={2}>
  <Card title="Built-in / 内置物件" icon="house">
    使用相对 transform 保留代码中原始摆放；支持停用、重新激活和可逆 GLB 外观替换。

    Uses relative transforms over authored placement; supports disable/reactivate and reversible GLB visual replacement.
  </Card>

  <Card title="Custom / 自定义资产" icon="cube">
    使用绝对 transform；可选择 decorative 或 interactive，并上传 GLB。

    Uses absolute transforms; choose decorative or interactive behavior and upload a GLB.
  </Card>
</CardGroup>

## Built-in controls / 内置物件控制

### Relative placement / 相对摆放

`scene.placements[coreId]` stores optional position, rotation, and scale overrides relative to the authored object:

```ts theme={null}
scene: {
  placements: {
    photography: {
      position: [-0.14, 0, 1.01],
      rotation: [0, 20, 0],
      scale: [1, 1, 1],
    },
  },
}
```

Resetting placement removes the override and returns to the authored transform.

重置摆放会删除覆盖并恢复代码中的原始 transform。

### Disable and reactivate / 停用与重新激活

Disabling a built-in adds its ID to `scene.disabledCoreAssets`. It disappears from:

* visible scene interaction;
* hit targets and signal markers;
* content index;
* deep-link resolution;
* detail-page navigation.

Its code definition, content, placement, and replacement model remain available. Reactivate it to restore those surfaces.

停用不会破坏原始内容；重新激活即可恢复。

### Replace only the visual / 只替换视觉

`scene.coreAssetModels[coreId]` points to a Studio-managed GLB. The built-in keeps its ID, content, placement, hitbox, signal marker, and route.

Loading behavior:

* the native or previous visual stays visible while fetching and processing;
* the GLB is fitted to the native object's bounds and grounded;
* parse/compile failure keeps the existing visual;
* clearing the model path restores the native visual.

这不是新增章节，而是可逆的外观替换。

## Custom asset controls / 自定义资产控制

Custom assets live in `scene.customAssets` and use absolute transforms:

```ts theme={null}
{
  id: "custom-...",
  behavior: "decorative",
  modelSrc: "/uploads/models/<uuid>.glb",
  accent: "#C99A62",
  transform: {
    position: [0, 0, 0],
    rotation: [0, 0, 0],
    scale: [1, 1, 1]
  },
  content: {
    zh: {},
    en: {}
  }
}
```

| Behavior      | Scene | Signal/hitbox | Index, route, detail |
| ------------- | ----: | ------------: | -------------------: |
| `decorative`  |   Yes |            No |                   No |
| `interactive` |   Yes |           Yes |                  Yes |

Use interactive only when the object has meaningful bilingual content. Decorative dressing should not become an empty button.

只有真正有内容的物件才应设为 interactive。

## Drag-to-place transaction / 拖动摆放事务

<Steps>
  <Step title="Start drag placement / 开始拖动摆放">
    Select an enabled built-in or custom asset and choose **Drag placement**.
  </Step>

  <Step title="Choose a mode / 选择模式">
    Use **Plane** for X/Z, **Height** for Y, or **Heading** for rotation around Y.
  </Step>

  <Step title="Drag in the room / 在房间中拖动">
    The HUD shows current coordinates. Hold Shift in Heading mode to snap to 15° increments.
  </Step>

  <Step title="Confirm or cancel / 确认或取消">
    **Confirm placement** merges changed axes into the Studio draft. **Cancel** restores the last confirmed transform.
  </Step>
</Steps>

Scale remains numeric. Numeric controls also expose X/Y/Z rotation and per-axis scale.

缩放只通过数值输入；数值控件仍可精确编辑三轴位置、旋转和缩放。

<Warning>
  While placement is active, save, import, export, copy JSON, selection changes, and removal are blocked or require cancellation. This prevents an on-canvas preview from being mistaken for persisted state.

  摆放模式中，保存、导入、导出、复制 JSON、切换选择和删除会被阻止或先取消，避免把预览误认为持久化结果。
</Warning>

## Transform limits / Transform 限制

| Value         | Range             |
| ------------- | ----------------- |
| Position      | `-50` to `50`     |
| Rotation      | `-360°` to `360°` |
| Scale         | `0.05` to `20`    |
| Custom assets | Up to 24          |

## GLB lifecycle / GLB 生命周期

```mermaid theme={null}
flowchart LR
  A["Choose GLB"] --> B["Validate"]
  B --> C[".content-studio-cache/models"]
  C --> D["Local preview"]
  D --> E{"Still referenced at save?"}
  E -->|Yes| F["public/uploads/models"]
  E -->|No| G["Delete staged file"]
```

Removing or replacing an uncommitted model discards its staged cache when it is no longer shared. A successful save removes only previously published scene references absent from the next saved scene.

删除或替换未提交模型会清理未共享暂存；保存只精确删除上一份保存场景拥有、下一份不再引用的 GLB。

For a custom asset with no usable model, the runtime shows a wireframe placeholder. A built-in replacement failure instead keeps the native or previous visual.

自定义模型失败时显示 wireframe；内置替换失败时保留原生或上一个可用外观。

## Confirm versus save / 确认与保存

| Action                | Result                                                   |
| --------------------- | -------------------------------------------------------- |
| Drag                  | Scene-only preview                                       |
| **Confirm placement** | Updates React config and `?studio=1` browser draft       |
| **Save to project**   | Writes JSON, generates scene source, promotes final GLBs |
| Git commit + push     | Publishes through Actions and Cloudflare                 |

The browser draft is not a repository file. Normal routes ignore it.

浏览器草稿不是代码文件，普通发布路由不会读取它。

## Commit outputs / 提交产物

```bash theme={null}
git status --short
git add public/content/site-content.json app/generated/scene-config.ts
git add public/uploads/<specific-model-files>
git diff --cached --check
```

Do not hand-edit `app/generated/scene-config.ts`. Use the Studio save boundary to keep it synchronized with JSON.

不要手工编辑生成场景源码；通过 Studio 保存保持它与 JSON 同步。

See [GLB models](/customization/glb-models) and [Content Studio](/content/content-studio).