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。编辑器处理两类资产：

Built-in / 内置物件

使用相对 transform 保留代码中原始摆放；支持停用、重新激活和可逆 GLB 外观替换。

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

Custom / 自定义资产

使用绝对 transform；可选择 decorative 或 interactive，并上传 GLB。

Uses absolute transforms; choose decorative or interactive behavior and upload a GLB.

Built-in controls / 内置物件控制

Relative placement / 相对摆放

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

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:

{
  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 / 拖动摆放事务

1. Start drag placement / 开始拖动摆放

   Select an enabled built-in or custom asset and choose Drag placement.

2. Choose a mode / 选择模式

   Use Plane for X/Z, Height for Y, or Heading for rotation around Y.

3. Drag in the room / 在房间中拖动

   The HUD shows current coordinates. Hold Shift in Heading mode to snap to 15° increments.

4. Confirm or cancel / 确认或取消

   Confirm placement merges changed axes into the Studio draft. Cancel restores the last confirmed transform.

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

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

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、切换选择和删除会被阻止或先取消，避免把预览误认为持久化结果。

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 生命周期

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 / 提交产物

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 and Content Studio.