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 中進行特殊處理。

形狀擠出

3D 元素可以通過擠出 2D 形狀來創建。當您在編輯器中將 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 Shading Language）函數進行應用，以獲得最佳性能。

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 元素。這些是編輯器生成的，無需手動構建。