Overview

Element

Basic Element

View Element

Video

Effect

3D Element

A 3D element represents three-dimensional objects in your project, including imported 3D models, basic geometry primitives, extruded shapes from 2D shapes, 3D text, and boolean operation results.

3D elements share the common fields from Basic Element and View Element, while also introducing additional 3D-specific properties.

Basic Fields

Prop	Type	Required	Example	Value Range	Description
type	string	true	-	3D	The type of the element. For 3D elements, this is always "3D".
sourceId	string	false	-	-	Internal identifier for the 3D model or geometry resource.
ext	string	false	-	glb \| gltf \| fbx \| obj \| geometry \| text3d \| parametric \| topology \| curve	The file extension or node type of the 3D element.
externalUrl	string	false	-	-	Optional URL for loading external glTF/glb models. The engine will fetch and cache the model.
nodeType	string	false	-	geometry \| text3d \| model \| parametric \| topology \| curve	The type of 3D node. Determines the structure of additional properties.
category	string	false	-	For geometry: basic \| polyhedron. For parametric: extrusion \| lathe. For topology: boolean \| array \| mirror \| compound. For curve: helix \| torusKnot \| custom	Sub-category of the 3D node. Available values depend on nodeType.
geometryType	string	false	-	-	The type of basic geometry. See "Geometry Types" section below.
originalWidth	number	false	-	-	The original width of the 3D model in world units.
originalHeight	number	false	-	-	The original height of the 3D model in world units.
originalDepth	number	false	-	-	The original depth of the 3D model in world units.
animation	object	false	-	-	Animation settings for glTF models with animations. Contains currentIndex, speed, and loop properties.

3D Transform Fields

In addition to the standard 2D transform properties (x, y, rotation, scaleX, scaleY), 3D elements support additional transform properties for three-dimensional positioning and rotation:

Prop	Type	Required	Example	Value Range	Description
z	number	false	-	-	The depth position of the element in 3D space. Units are aligned with pixels, where z=0 corresponds to the canvas plane.
rotationX	number	false	-	-	Rotation around the X-axis, in degrees.
rotationY	number	false	-	-	Rotation around the Y-axis, in degrees.
scaleZ	number	false	-	> 0	Scaling factor along the Z-axis. Values > 1 enlarge, values between 0 and 1 shrink.

Geometry Types

The geometryType field specifies the type of basic 3D geometry. Available types are organized by category (specified via the category field when nodeType: "geometry"):

Basic Shapes (category: "basic"):

cube - Six-sided box
sphere - Spherical geometry
cylinder - Cylindrical geometry
cone - Conical geometry
torus - Donut-shaped geometry
capsule - Pill-shaped geometry
disc - Flat circular disc

Polyhedrons (category: "polyhedron"):

pyramid - Four-sided pyramid
octahedron - Eight-faced polyhedron
icosahedron - Twenty-faced polyhedron
dodecahedron - Twelve-faced polyhedron
hexPrism - Six-sided prism
triangle - Triangular prism

Parametric Node Types

Parametric nodes (nodeType: "parametric") generate geometry procedurally:

Extrusion (category: "extrusion"):

Extrudes 2D shapes along the Z-axis with depth and beveling

Lathe (category: "lathe"):

Revolves a 2D profile around an axis to create cylindrical objects

Curve Node Types

Curve nodes (nodeType: "curve") create 3D curves and paths:

Helix (category: "helix"):

Helical spiral curves with configurable radius and pitch

Torus Knot (category: "torusKnot"):

Mathematical knot curves on a torus surface

Custom (category: "custom"):

User-defined curve paths

Topology Node Types

Topology nodes (nodeType: "topology") perform operations on existing geometry:

Boolean (category: "boolean"):

Union, intersection, or subtraction of multiple 3D objects

Array (category: "array"):

Duplicate objects in linear, circular, or grid patterns

Mirror (category: "mirror"):

Mirror geometry across X, Y, or Z planes

Compound (category: "compound"):

Combine multiple operations in sequence

Shape Extrusion

3D elements can be created by extruding 2D shapes. When you convert a 2D Shape element to 3D in the editor, it generates a new type: "3D" element with the following additional fields:

Prop	Type	Required	Example	Value Range	Description
extrusionSource	object	false	-	-	The original 2D shape data used to create the 3D extrusion. Contains the complete ShapeNodeData.
shapeSizeX	number	false	-	-	Width of the extruded shape, in pixels.
shapeSizeY	number	false	-	-	Height of the extruded shape, in pixels.
shapeExtrusion	number	false	-	-	Depth of extrusion along the Z-axis, in pixels.
shapeCorner	string	false	-	round \| chamfer \| straight	Corner type for extruded shapes.
shapeRoundnessSmooth	number	false	-	0 - 1	Smoothness of rounded corners (0-1).
shapeRoundnessArc	number	false	-	-	Arc radius for rounded corners.
shapeBevel	number	false	-	-	Bevel depth for edges.
shapeBevelSides	number	false	-	-	Number of segments for beveled edges.

3D Text

3D elements can also represent three-dimensional text with depth and beveling:

Prop	Type	Required	Example	Value Range	Description
textContent	string	false	-	-	The text content to render in 3D.
textStyle3D	object	false	-	-	Text styling properties (font, size, weight, etc.). Reuses some 2D text style fields.
textDepth	number	false	-	-	Extrusion depth of the 3D text.
textBevelSize	number	false	-	-	Size of the bevel on text edges.
textBevelSegments	number	false	-	-	Number of segments for text beveling.
textCurveSegments	number	false	-	-	Number of segments for text curves.

Materials and Textures

3D elements use a PBR (Physically Based Rendering) material system with comprehensive texture support:

Prop	Type	Required	Example	Value Range	Description
material	object	false	-	-	Complete material configuration including PBR properties and texture maps.

The material object contains:

physicalMaterialData - PBR material properties:

color (string) - Base color in hex format, default: '#818cf8'
roughness (number) - Surface roughness, 0-1, default: 0.4
metalness (number) - Metallic property, 0-1, default: 0.0
opacity (number) - Material opacity, 0-1, default: 1.0
transmission (number) - Light transmission for glass-like materials, 0-1, default: 0.0
ior (number) - Index of refraction, typically 1.0-2.5, default: 1.5
clearcoat (number) - Clear coating layer intensity, 0-1, default: 0.0
clearcoatRoughness (number) - Clear coat roughness, 0-1, default: 0.0
sheen (number) - Fabric-like sheen effect, 0-1, default: 0.0
sheenRoughness (number) - Sheen roughness, 0-1, default: 0.0
sheenColor (string) - Sheen tint color
thickness (number) - Material thickness for transmission

materialXPath (string) - Optional MaterialX preset path:

Examples: 'StandardSurface/standard_surface_gold.mtlx', 'StandardSurface/standard_surface_brass_tiled.mtlx'
When loaded, overrides physicalMaterialData with preset values

Texture Maps - The material object can contain texture map URLs:

colorMap - Base color/diffuse texture
normalMap - Normal map for surface detail
roughnessMap - Roughness texture
metalnessMap - Metalness texture
aoMap - Ambient occlusion map
emissiveMap - Emissive/glow texture

Texture maps are applied using TSL (Three.js Shading Language) functions for optimal performance.

glTF Models and Animations

3D elements with nodeType: "model" represent imported 3D models:

Use source.url to specify the URL of the remote glTF/glb/FBX file
The engine will fetch and cache the model using sourceId
If the model contains animations, use animation.currentIndex to select which animation to play
Animation properties: currentIndex (number), speed (number, default 1.0), loop (boolean, default true)
Models support DRACO compression for smaller file sizes
sizeParams contains width, height, depth for model dimensions

Examples

Basic Cube

cubeElement.json

 
{
  "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
    }
  }
}

Extruded Shape

extrudedShapeElement.json

 
{
  "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 Model with Animation

gltfModelElement.json

 
{
  "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
}

Notes

3D elements fully integrate with the existing 2D rendering pipeline. You can mix 2D and 3D elements in the same project.
The camera uses pixel-perfect perspective projection, ensuring that at z=0, one world unit equals one pixel.
For 3D transforms, the coordinate system follows standard 3D conventions: X (right), Y (up), Z (toward viewer).
Material and texture properties are typically set by the editor. If you're hand-writing JSON, refer to MaterialX preset documentation for available materials.