Build Native Three.js Assets with a Coding Agent

Generate lightweight furniture, props, signs, and decorations directly in the scene when a GLB would add unnecessary authoring and loading overhead.

原生资产是直接用 Three.js 几何体、材质和分组写进场景的物件。它们适合轮廓清晰、结构简单的家具、灯具、标牌和装饰，不需要外部 GLB 文件，也没有网络加载等待。

Native assets are scene objects composed directly from Three.js geometry, materials, and groups. They work well for simple furniture, lamps, signs, and decorations with clear silhouettes. They require no external GLB and add no model download delay.

Choose the right asset path / 选择合适的资产路径

需求 / Need	推荐方式 / Recommended path
替换一个内置物件的外观 / Replace a built-in object’s appearance	GLB visual replacement
放置复杂、有机或带纹理的模型 / Place a complex, organic, or textured model	Custom GLB
增加简单家具或场景装饰 / Add simple furniture or scene dressing	Native Three.js asset
增加新的可交互产品能力 / Add a new interaction or product capability	Agent-native development

如果物件只负责丰富房间，不要为它创建新的章节 ID、信号点或详情页。让它成为纯装饰，或把它挂到现有内置物件的根组下。

If an object only enriches the room, do not create a new chapter ID, signal marker, or detail page. Keep it decorative, or attach it to an existing built-in object’s root group.

Native asset contract / 原生资产约定

每个独立物件应放在一个 THREE.Group 根节点下。根节点负责场景位置，子节点只使用局部坐标。

Place each independent object under one THREE.Group root. The root owns scene placement; children use local coordinates.

function createNativeDecoration(scene: THREE.Scene) {
  const group = new THREE.Group();
  group.position.set(1.4, 0, 2.2);
  scene.add(group);

  addCylinder(group, 0.28, 0.34, 0.42, [0, 0.21, 0], "#6f5947", {
    segments: 20,
    roughness: 0.72,
  });
  addSphere(group, 0.32, [0, 0.62, 0], "#516b61", [1, 0.72, 1], 0.78);

  return group;
}

遵循以下规则：

Follow these rules:

• 使用房间现有的米制比例；落地物件以局部 Y = 0 为底面。 / Use the room’s meter-scale proportions; ground standing objects at local Y = 0.
• 默认使用 MeshStandardMaterial，让物件响应作者时区驱动的昼夜光照。 / Default to MeshStandardMaterial so the object responds to author-timezone lighting.
• 代码中的旋转使用弧度；Studio 保存的旋转使用角度。 / Use radians in factory code; Studio persists rotations in degrees.
• 对重要实体开启阴影；不要让大量微小零件投影。 / Enable shadows for important solids, not for many tiny details.
• 每件简单资产尽量少于 30 个 mesh 和 25,000 个三角面。 / Keep a simple asset under roughly 30 meshes and 25,000 triangles.
• 重复零件共享 geometry/material；超过八个实例时考虑 InstancedMesh。 / Share geometry and material for repeated parts; consider InstancedMesh above eight repetitions.

Decorative companions / 附属装饰

如果新装饰属于一个现有内置物件，把它添加到该物件的根组中。这样它会自动继承 Studio 对拥有者的位置、旋转和缩放覆盖。

If a decoration belongs to an existing built-in object, add it to that object’s root group. It will automatically inherit the owner’s Studio position, rotation, and scale overrides.

不要仅仅为了让附属装饰可移动就新增 CoreAssetId。只有真正需要独立内容、深链接、索引入口和键盘路径时，才应新增交互 ID。

Do not add a CoreAssetId merely to make a companion prop movable. Add an interactive ID only when the object genuinely needs independent content, a deep link, an index entry, and a keyboard path.

Interaction and animation / 交互与动画

纯装饰不要调用 addHitbox() 或 addSignal()。复用现有章节语义时，使用该章节已有 ID：

Do not call addHitbox() or addSignal() for decoration-only objects. When extending an existing chapter, retain that chapter’s current ID:

addHitbox(group, "growth", [1.2, 1.8, 1.2], [0, 0.9, 0], hitboxes);
addSignal(group, "growth", [0.46, 1.46, 0.38]);

动画必须加入场景现有的 animated 队列，不要创建第二个 renderer 或 animation loop。使用 delta 累积运动，使用 elapsed 计算有界摆动，并保留 reduced-motion 行为。

Add animation to the scene’s existing animated queue. Do not create a second renderer or animation loop. Use delta for accumulated motion and elapsed for bounded oscillation, while preserving reduced-motion behavior.

Ask a coding agent / 交给 coding agent

仓库内的 skills/living-index-native-assets/SKILL.md 定义了这个工作流。你可以直接描述形状、尺寸、材质、摆放位置、是否需要动画，以及它属于独立装饰还是某个现有物件。

The repository’s skills/living-index-native-assets/SKILL.md defines this workflow. Describe the shape, scale, materials, placement, optional animation, and whether the result is independent decoration or belongs to an existing object.

Use $living-index-native-assets to add a low-poly brass desk clock beside
the research computer. Keep it decorative, light-reactive, and under 20 meshes.

完成后至少验证：

After implementation, verify:

npm run typecheck
npm run lint
npm test
git diff --check

还要手工确认默认相机下轮廓清楚、昼夜都可读、不会挡住现有 hitbox，并且装饰物不能误开详情页。

Also confirm that the silhouette reads from the default camera, works in day and night lighting, does not block existing hitboxes, and cannot accidentally open a detail page.