name: 3d-object
description: "three.js model, downloadable as OBJ or GLB"
user-invocable: true

3D object / 3D 对象

Model a 3D object the user can inspect from every angle and download,
built with three.js and presented in the three_d_stage starter.

构建一个用户可从任意角度查看并下载的 3D 对象模型，使用 three.js 构建，并以 three_d_stage 起始组件呈现。

START by calling copy_starter_component with kind: "three_d_stage.js" —
it is the whole viewer: studio lighting, ground shadow, orbit controls,
an auto-framed camera, and a toolbar that downloads the object as
OBJ + MTL or GLB. Read the copied file's usage block and follow its page
skeleton exactly. You only write the model-building module script.

首先调用 copy_starter_component，kind 取 "three_d_stage.js"——它就是整个查看器：影棚灯光、地面阴影、轨道控制、自动取景相机，以及一个可将对象下载为 OBJ + MTL 或 GLB 的工具栏。阅读复制出的文件中的用法块，并严格遵循其页面骨架。你只需编写构建模型的模块脚本。

Build the page as plain HTML — a .html file with ordinary

Build the model programmatically, as a THREE.Group composed of named
parts:

以编程方式构建模型，作为一个由命名部件组成的 THREE.Group：

• Compose primitives (BoxGeometry, CylinderGeometry, SphereGeometry,
  TorusGeometry, LatheGeometry, ExtrudeGeometry with Shape) before
  reaching for raw BufferGeometry; real objects decompose into far more
  primitives than you'd guess.
  先组合基元（BoxGeometry、CylinderGeometry、SphereGeometry、TorusGeometry、LatheGeometry、带 Shape 的 ExtrudeGeometry），再考虑原始 BufferGeometry；真实物体可分解出的基元远比你以为的多。
• NAME every mesh and every material ("hull", "walnut", "brass") — the
  names become the o / usemtl entries in the exported OBJ and the node
  names in the GLB, which is what makes the download usable in Blender.
  为每个网格和每个材质命名（"hull"、"walnut"、"brass"）——这些名称会成为导出 OBJ 中的 o / usemtl 条目和 GLB 中的节点名，这正是下载结果能在 Blender 中可用的关键。
• Use MeshStandardMaterial with a small curated palette (3-5 materials,
  shared across parts); set roughness/metalness deliberately. Textures
  don't survive the OBJ export — prefer geometry and material color over
  texture detail.
  使用 MeshStandardMaterial 配一个小而精的调色板（3-5 种材质，跨部件共享）；有意识地设置 roughness/metalness。纹理无法在 OBJ 导出后保留——优先用几何与材质颜色，而非纹理细节。
• Model in real-world meters, y-up, centered on the origin, base resting
  at the lowest y. Offset deliberately coplanar faces by ~0.001 so
  nothing z-fights.
  以真实世界的米为单位建模，y 轴向上，以原点为中心，底部落在最低的 y 处。对刻意共面的面做约 0.001 的偏移，避免任何 z-fighting。
• Curved surfaces need enough segments to read as smooth at full screen
  (32+ radial segments on feature surfaces), but don't tessellate what
  no one will see.
  曲面需要足够的分段才能在全屏下显得平滑（特征表面 32+ 个径向分段），但不要对没人会看的地方做细分。

The stage's toolbar gives the user OBJ + MTL (universal, geometry +
per-material colors) and GLB (the modern interchange format — keeps the
part hierarchy and PBR materials; imports cleanly into Blender, Maya,
Cinema 4D, Unity, Unreal). Those two are the export formats on offer —
when the user asks for something else (FBX, USDZ, STEP), say plainly
that the stage exports OBJ + MTL and GLB.

舞台的工具栏为用户提供 OBJ + MTL（通用格式，几何体 + 每材质颜色）和 GLB（现代交换格式——保留部件层级与 PBR 材质；可干净地导入 Blender、Maya、Cinema 4D、Unity、Unreal）。这两者就是可选的导出格式——当用户要求其他格式（FBX、USDZ、STEP）时，直说舞台只能导出 OBJ + MTL 和 GLB。

Iterate with screenshots: the stage keeps its last frame readable, so
the ordinary screenshot tools capture the live canvas — no extra steps.
After editing a module file, reload with show_html before screenshotting
(the iframe caches already-loaded modules). Look at the object from the
default framing and refine silhouette, proportion, and material
separation — the silhouette carries the object.

通过截图迭代：舞台会保持最后一帧可读，因此普通截图工具即可捕捉活动画布——无需额外步骤。编辑模块文件后，先用 show_html 重新加载再截图（iframe 会缓存已加载的模块）。从默认取景观察对象，打磨轮廓、比例和材质区分——轮廓决定对象的观感。
【评论】该技能对 three.js 的版本、URL 与 SRI 完整性哈希做了锁定，是防止依赖被篡改的供应链安全措施；封闭的 import map 则进一步保证不会意外加载未校验的脚本。