Elemento 3D

Un elemento 3D representa objetos tridimensionales en tu proyecto, incluyendo modelos 3D importados, primitivas geométricas básicas, formas extruidas de formas 2D, texto 3D y resultados de operaciones booleanas.

Los elementos 3D comparten los campos comunes de Elemento Básico y Elemento de Vista, mientras que también introducen propiedades adicionales específicas de 3D.

Campos Básicos

Prop	Tipo	Requerido	Ejemplo	Rango de Valores	Descripción
type	string	true	-	3D	El tipo del elemento. Para elementos 3D, esto es siempre "3D".
sourceId	string	false	-	-	Identificador interno para el modelo 3D o recurso de geometría.
ext	string	false	-	glb \| gltf \| fbx \| obj \| geometry \| primitive \| text3d \| parametric \| curve	La extensión de archivo o tipo de nodo del elemento 3D.
externalUrl	string	false	-	-	URL opcional para cargar modelos glTF/glb externos. El motor recuperará y almacenará en caché el modelo.
nodeType	string	false	-	primitive \| geometry \| text3d \| import \| model \| parametric \| curve	El tipo de nodo 3D. Determina la estructura de propiedades adicionales.
category	string	false	-	For primitive/geometry: basic \| polyhedron. For parametric: extrusion \| lathe \| sweep. For curve: helix \| torusKnot \| custom	Subcategoría del nodo 3D. Los valores disponibles dependen de nodeType.
geometryType	string	false	-	-	El tipo de geometría básica. Consulta la sección "Tipos de Geometría" a continuación.
originalWidth	number	false	-	-	El ancho original del modelo 3D en unidades del mundo.
originalHeight	number	false	-	-	La altura original del modelo 3D en unidades del mundo.
originalDepth	number	false	-	-	La profundidad original del modelo 3D en unidades del mundo.
animation	object	false	-	-	Configuraciones de animación para modelos glTF con animaciones. Contiene propiedades currentIndex, speed y loop.

Campos de Transformación 3D

Además de las propiedades de transformación 2D estándar (x, y, rotación, escalaX, escalaY), los elementos 3D admiten propiedades de transformación adicionales para posicionamiento y rotación tridimensional:

Prop	Tipo	Requerido	Ejemplo	Rango de Valores	Descripción
z	number	false	-	-	La posición de profundidad del elemento en el espacio 3D. Las unidades están alineadas con píxeles, donde z=0 corresponde al plano del lienzo.
rotationX	number	false	-	-	Rotación alrededor del eje X, en grados.
rotationY	number	false	-	-	Rotación alrededor del eje Y, en grados.
scaleZ	number	false	-	> 0	Factor de escala a lo largo del eje Z. Valores > 1 aumentan, valores entre 0 y 1 disminuyen.

Tipos de Geometría

El campo geometryType especifica el tipo de geometría 3D básica. Los tipos disponibles están organizados por categoría (especificada a través del campo category cuando nodeType es "geometry" o "primitive"):

Nota: nodeType: "primitive" es un alias para "geometry". Ambos son compatibles y se comportan de manera idéntica.

Formas Básicas (category: "basic"):

cube - Caja de seis lados
sphere - Geometría esférica
cylinder - Geometría cilíndrica
cone - Geometría cónica
torus - Geometría en forma de dona
capsule - Geometría en forma de píldora
disc - Disco circular plano

Poliedros (category: "polyhedron"):

pyramid - Pirámide de cuatro lados
octahedron - Poliedro de ocho caras
icosahedron - Poliedro de veinte caras
dodecahedron - Poliedro de doce caras
hexPrism - Prisma de seis lados
triangle - Prisma triangular

Tipos de Nodos Paramétricos

Los nodos paramétricos (nodeType: "parametric") generan geometría de manera procedural:

Extrusión (category: "extrusion"):

Extruye formas 2D a lo largo del eje Z con profundidad y biselado

Torno (category: "lathe"):

Rota un perfil 2D alrededor de un eje para crear objetos cilíndricos

Barrido (category: "sweep"):

Barre un perfil 2D a lo largo de una trayectoria 3D para crear formas tubulares o basadas en rieles

Tipos de Nodos de Curva

Los nodos de curva (nodeType: "curve") crean curvas y trayectorias 3D:

Helice (category: "helix"):

Curvas en espiral helicoidal con radio y paso configurables

Nudo de Torus (category: "torusKnot"):

Curvas de nudos matemáticos en una superficie de torus

Personalizado (category: "custom"):

Trayectorias de curva definidas por el usuario

Tipos de Nodos de Topología

Las operaciones de topología (booleanas, de matriz, espejo, compuestas) se realizan dentro del editor y producen una salida de geometría estándar. Estas operaciones se aplican en el tiempo de edición y no requieren un manejo especial en la API de renderizado.

Extrusión de Formas

Los elementos 3D pueden ser creados extruyendo formas 2D. Cuando conviertes un elemento de forma 2D a 3D en el editor, genera un nuevo elemento type: "3D" con los siguientes campos adicionales:

Prop	Tipo	Requerido	Ejemplo	Rango de Valores	Descripción
extrusionSource	object	false	-	-	Los datos de forma 2D originales utilizados para crear la extrusión 3D. Contiene el ShapeNodeData completo.
shapeSizeX	number	false	-	-	Ancho de la forma extruida, en píxeles.
shapeSizeY	number	false	-	-	Altura de la forma extruida, en píxeles.
shapeExtrusion	number	false	-	-	Profundidad de la extrusión a lo largo del eje Z, en píxeles.
shapeCorner	string	false	-	round \| chamfer \| straight	Tipo de esquina para formas extruidas.
shapeRoundnessSmooth	number	false	-	0 - 1	Suavidad de las esquinas redondeadas (0-1).
shapeRoundnessArc	number	false	-	-	Radio del arco para esquinas redondeadas.
shapeBevel	number	false	-	-	Profundidad del bisel para los bordes.
shapeBevelSides	number	false	-	-	Número de segmentos para bordes biselados.

Texto 3D

Los elementos 3D también pueden representar texto tridimensional con profundidad y biselado:

Prop	Tipo	Requerido	Ejemplo	Rango de Valores	Descripción
textContent	string	false	-	-	El contenido de texto a renderizar en 3D.
textStyle3D	object	false	-	-	Propiedades de estilo de texto (fuente, tamaño, peso, etc.). Reutiliza algunos campos de estilo de texto 2D.
textDepth	number	false	-	-	Profundidad de extrusión del texto 3D.
textBevelSize	number	false	-	-	Tamaño del bisel en los bordes del texto.
textBevelSegments	number	false	-	-	Número de segmentos para el biselado del texto.
textCurveSegments	number	false	-	-	Número de segmentos para las curvas del texto.

Materiales y Texturas

Los elementos 3D utilizan un sistema de materiales PBR (Renderizado Basado en Física) con soporte integral para texturas:

Prop	Tipo	Requerido	Ejemplo	Rango de Valores	Descripción
material	object	false	-	-	Configuración completa del material que incluye propiedades PBR y mapas de textura.

El objeto material contiene:

physicalMaterialData - Propiedades del material PBR:

color (string) - Color base en formato hexadecimal, por defecto: '#818cf8'
roughness (number) - Rugosidad de la superficie, 0-1, por defecto: 0.4
metalness (number) - Propiedad metálica, 0-1, por defecto: 0.0
opacity (number) - Opacidad del material, 0-1, por defecto: 1.0
transmission (number) - Transmisión de luz para materiales similares al vidrio, 0-1, por defecto: 0.0
ior (number) - Índice de refracción, típicamente 1.0-2.5, por defecto: 1.5
clearcoat (number) - Intensidad de la capa de recubrimiento transparente, 0-1, por defecto: 0.0
clearcoatRoughness (number) - Rugosidad del recubrimiento transparente, 0-1, por defecto: 0.0
sheen (number) - Efecto de brillo similar a tela, 0-1, por defecto: 0.0
sheenRoughness (number) - Rugosidad del brillo, 0-1, por defecto: 0.0
sheenColor (string) - Color del tinte del brillo
thickness (number) - Grosor del material para transmisión

materialXPath (string) - Ruta de preset MaterialX opcional:

Ejemplos: 'StandardSurface/standard_surface_gold.mtlx', 'StandardSurface/standard_surface_brass_tiled.mtlx'
Al cargarse, sobrescribe physicalMaterialData con valores preestablecidos

Mapas de Textura - El objeto material puede contener URLs de mapas de textura:

colorMap - Textura de color base/difusa
normalMap - Mapa normal para detalle de superficie
roughnessMap - Textura de rugosidad
metalnessMap - Textura de metalicidad
aoMap - Mapa de oclusión ambiental
emissiveMap - Textura emisiva/brillante

Los mapas de textura se aplican utilizando funciones TSL (Three.js Shading Language) para un rendimiento óptimo.

Modelos y Animaciones glTF

Los elementos 3D con nodeType: "model" o nodeType: "import" representan modelos 3D importados:

Nota: nodeType: "import" es un alias para "model". Ambos son compatibles y se comportan de manera idéntica.

Usa source.url para especificar la URL del archivo glTF/glb/FBX remoto
El motor recuperará y almacenará en caché el modelo utilizando sourceId
Si el modelo contiene animaciones, usa animation.currentIndex para seleccionar qué animación reproducir
Propiedades de animación: currentIndex (número), speed (número, por defecto 1.0), loop (booleano, por defecto verdadero)
Los modelos admiten compresión DRACO para tamaños de archivo más pequeños
sizeParams contiene width, height, depth para las dimensiones del modelo

Ejemplos

Cubo Básico

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

Forma Extrudida

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

Modelo glTF con Animación

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
}

Notas

Los elementos 3D se integran completamente con la tubería de renderizado 2D existente. Puedes mezclar elementos 2D y 3D en el mismo proyecto.
La cámara utiliza proyección de perspectiva perfecta en píxeles, asegurando que en z=0, una unidad del mundo equivale a un píxel.
Para transformaciones 3D, el sistema de coordenadas sigue las convenciones 3D estándar: X (derecha), Y (arriba), Z (hacia el espectador).
Las propiedades de materiales y texturas generalmente son establecidas por el editor. Si estás escribiendo JSON a mano, consulta la documentación del preset MaterialX para materiales disponibles.
El editor también puede generar elementos Light3D y Particle3D dentro de escenas 3D. Estos son generados por el editor y no necesitan ser construidos manualmente.

Overview

Element

Effect