3D 元素

3D 元素表示您项目中的三维对象，包括导入的 3D 模型、基本几何原始体、从 2D 形状挤出的形状、3D 文本和布尔运算结果。

3D 元素共享 基本元素 和 视图元素 的公共字段，同时还引入了额外的 3D 特定属性。

基本字段

3D 变换字段

除了标准的 2D 变换属性（x、y、旋转、scaleX、scaleY）外，3D 元素还支持用于三维定位和旋转的额外变换属性：

几何类型

geometryType 字段指定基本 3D 几何的类型。可用类型按类别组织（在 nodeType 为 "geometry" 或 "primitive" 时通过 category 字段指定）：

注意：nodeType: "primitive" 是 "geometry" 的别名。两者都被支持并表现相同。

基本形状 (category: "basic"):

• cube - 六面体
• sphere - 球形几何
• cylinder - 圆柱形几何
• cone - 圆锥形几何
• torus - 圆环形几何
• capsule - 胶囊形几何
• disc - 平面圆盘

多面体 (category: "polyhedron"):

• pyramid - 四面体
• octahedron - 八面体
• icosahedron - 二十面体
• dodecahedron - 十二面体
• hexPrism - 六面棱柱
• triangle - 三角棱柱

参数化节点类型

参数化节点 (nodeType: "parametric") 以过程方式生成几何：

挤出 (category: "extrusion"):

• 沿 Z 轴挤出 2D 形状，具有深度和倒角

车床 (category: "lathe"):

• 围绕轴旋转 2D 轮廓以创建圆柱形对象

扫掠 (category: "sweep"):

• 沿 3D 路径扫掠 2D 轮廓以创建管状或轨道形状

曲线节点类型

曲线节点 (nodeType: "curve") 创建 3D 曲线和路径：

螺旋 (category: "helix"):

• 可配置半径和螺距的螺旋曲线

圆环结 (category: "torusKnot"):

• 在圆环表面上的数学结曲线

自定义 (category: "custom"):

• 用户定义的曲线路径

拓扑节点类型

拓扑操作（布尔、数组、镜像、复合）在编辑器内执行，并生成标准几何输出。这些操作在编辑时应用，无需在渲染 API 中进行特殊处理。

形状挤出

可以通过挤出 2D 形状来创建 3D 元素。当您在编辑器中将 2D 形状元素转换为 3D 时，它会生成一个新的 type: "3D" 元素，并具有以下附加字段：

3D 文本

3D 元素还可以表示具有深度和倒角的三维文本：

材料和纹理

3D 元素使用 PBR（物理基础渲染）材料系统，具有全面的纹理支持：

material 对象包含：

physicalMaterialData - PBR 材料属性：

• color (string) - 以十六进制格式表示的基础颜色，默认值：'#818cf8'
• roughness (number) - 表面粗糙度，0-1，默认值：0.4
• metalness (number) - 金属属性，0-1，默认值：0.0
• opacity (number) - 材料不透明度，0-1，默认值：1.0
• transmission (number) - 玻璃状材料的光传输，0-1，默认值：0.0
• ior (number) - 折射率，通常为 1.0-2.5，默认值：1.5
• clearcoat (number) - 清漆涂层强度，0-1，默认值：0.0
• clearcoatRoughness (number) - 清漆粗糙度，0-1，默认值：0.0
• sheen (number) - 类似织物的光泽效果，0-1，默认值：0.0
• sheenRoughness (number) - 光泽粗糙度，0-1，默认值：0.0
• sheenColor (string) - 光泽色调颜色
• thickness (number) - 材料的传输厚度

materialXPath (string) - 可选的 MaterialX 预设路径：

• 示例：'StandardSurface/standard_surface_gold.mtlx', 'StandardSurface/standard_surface_brass_tiled.mtlx'
• 加载时，用预设值覆盖 physicalMaterialData

纹理贴图 - 材料对象可以包含纹理贴图 URL：

• colorMap - 基础颜色/漫反射纹理
• normalMap - 表面细节的法线贴图
• roughnessMap - 粗糙度纹理
• metalnessMap - 金属度纹理
• aoMap - 环境遮蔽贴图
• emissiveMap - 发光/辉光纹理

纹理贴图使用 TSL（Three.js 着色语言）函数应用，以获得最佳性能。

glTF 模型和动画

具有 nodeType: "model" 或 nodeType: "import" 的 3D 元素表示导入的 3D 模型：

注意：nodeType: "import" 是 "model" 的别名。两者都被支持并表现相同。

• 使用 source.url 指定远程 glTF/glb/FBX 文件的 URL
• 引擎将使用 sourceId 获取并缓存模型
• 如果模型包含动画，使用 animation.currentIndex 选择要播放的动画
• 动画属性：currentIndex (number)、speed (number，默认 1.0)、loop (boolean，默认 true)
• 模型支持 DRACO 压缩以减小文件大小
• sizeParams 包含模型尺寸的 width、height、depth

示例

基本立方体

 
{
  "id": "3d-cube-001",
  "type": "3D",
  "start": 0,
  "duration": 5,
  "trackIndex": 0,
  "x": 540,
  "y": 540,
  "z": 0,
  "width": 200,
  "height": 200,
  "anchorX": 100,
  "anchorY": 100,
  "rotation": 0,
  "rotationX": 30,
  "rotationY": 45,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "alpha": 1,
  "ext": "geometry",
  "nodeType": "geometry",
  "category": "basic",
  "geometryType": "cube",
  "material": {
    "physicalMaterialData": {
      "color": "#4A90E2",
      "roughness": 0.4,
      "metalness": 0.0
    }
  }
}

挤出形状

 
{
  "id": "3d-extrusion-001",
  "type": "3D",
  "start": 0,
  "duration": 5,
  "trackIndex": 0,
  "x": 540,
  "y": 540,
  "z": 0,
  "width": 300,
  "height": 300,
  "anchorX": 150,
  "anchorY": 150,
  "rotation": 0,
  "rotationX": 0,
  "rotationY": 0,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "alpha": 1,
  "ext": "parametric",
  "nodeType": "parametric",
  "category": "extrusion",
  "shapeSizeX": 300,
  "shapeSizeY": 300,
  "shapeExtrusion": 100,
  "material": {
    "physicalMaterialData": {
      "color": "#FF6B6B",
      "roughness": 0.3,
      "metalness": 0.1
    }
  },
  "extrusionSource": {
    "shapeType": "SHAPE_STAR",
    "starPoints": 5,
    "starInnerRadius": 0.4
  }
}

带动画的 glTF 模型

 
{
  "id": "3d-model-001",
  "type": "3D",
  "start": 0,
  "duration": 10,
  "trackIndex": 0,
  "x": 540,
  "y": 540,
  "z": -200,
  "width": 400,
  "height": 400,
  "anchorX": 200,
  "anchorY": 200,
  "rotation": 0,
  "rotationX": 0,
  "rotationY": 0,
  "scaleX": 1,
  "scaleY": 1,
  "scaleZ": 1,
  "alpha": 1,
  "ext": "glb",
  "nodeType": "model",
  "sourceId": "cached-model-123",
  "source": {
    "url": "https://example.com/models/animated_character.glb"
  },
  "animation": {
    "currentIndex": 0,
    "speed": 1.0,
    "loop": true
  },
  "sizeParams": {
    "width": 2,
    "height": 2,
    "depth": 2
  },
  "originalWidth": 2,
  "originalHeight": 2,
  "originalDepth": 2
}

注意事项

• 3D 元素与现有的 2D 渲染管道完全集成。您可以在同一项目中混合 2D 和 3D 元素。
• 相机使用像素完美的透视投影，确保在 z=0 时，一个世界单位等于一个像素。
• 对于 3D 变换，坐标系统遵循标准 3D 约定：X（右）、Y（上）、Z（朝向观察者）。
• 材料和纹理属性通常由编辑器设置。如果您手动编写 JSON，请参考 MaterialX 预设文档以获取可用材料。
• 编辑器还可能在 3D 场景中生成 Light3D 和 Particle3D 元素。这些是编辑器生成的，无需手动构建。