API Reference

Complete reference for all packages in the Oroya Animate ecosystem.

Tabla de contenidos

• Visión general de la arquitectura
• @joroya/core
  • Scene
  • Node
  • Component (base)
  • Transform
  • Geometry
  • Material
  • Camera
  • Interactive
  • EventEmitter
  • InteractionEvent
  • Factory Functions
  • Serialization
  • Math  EMatrix4
  • Math  EBoundingBox
• @joroya/renderer-three
  • ThreeRenderer
• @joroya/renderer-svg
  • renderToSVG
  • renderToSVGElement
• @joroya/loader-gltf
  • loadGLTF
• Mapa completo de tipos

Visión general de la arquitectura

graph TD
    subgraph "@joroya/core"
        Scene --> Node
        Node --> Transform
        Node --> Geometry
        Node --> Material
        Node --> Camera
        Node -->|"children[]"| Node
        
        Geometry -.->|"uses"| GeometryDef["GeometryDef (union)"]
        Material -.->|"uses"| MaterialDef
        Camera -.->|"uses"| CameraDef["CameraDef (union)"]
        Transform -.->|"uses"| Matrix4
    end

    subgraph "@joroya/renderer-three"
        ThreeRenderer -->|"reads"| Scene
        ThreeRenderer -->|"produces"| WebGL["WebGL Canvas"]
    end

    subgraph "@joroya/renderer-svg"
        renderToSVG -->|"reads"| Scene
        renderToSVG -->|"produces"| SVGStr["SVG String"]
    end

    subgraph "@joroya/loader-gltf"
        loadGLTF -->|"produces"| Scene
    end

Flujo de datos

sequenceDiagram
    participant User as User Code
    participant Scene as Scene Graph
    participant Node as Node + Components
    participant Renderer as Renderer

    User->>Scene: new Scene()
    User->>Node: new Node('box')
    User->>Node: addComponent(createBox(...))
    User->>Node: addComponent(new Material(...))
    User->>Scene: scene.add(node)
    User->>Renderer: renderer.mount(scene)
    
    loop Animation Frame
        User->>Node: transform.rotation = {...}
        User->>Node: transform.updateLocalMatrix()
        User->>Renderer: renderer.render()
        Renderer->>Scene: scene.updateWorldMatrices()
        Scene->>Node: node.updateWorldMatrix(parentMatrix)
        Renderer->>Renderer: Draw frame
    end

@joroya/core

Exports completos

// Scene
export { Scene } from './scene/Scene';

// Nodes
export { Node } from './nodes/Node';

// Components
export { Component, ComponentType } from './components/Component';
export { Transform } from './components/Transform';
export type { Vec3, Quat } from './components/Transform';
export { Geometry, GeometryPrimitive } from './components/Geometry';
export type { BoxGeometryDef, SphereGeometryDef, Path2DGeometryDef, Path2DCommand, GeometryDef } from './components/Geometry';
export { Material } from './components/Material';
export type { ColorRGB, MaterialDef } from './components/Material';
export { Camera, CameraType } from './components/Camera';
export type { PerspectiveCameraDef, OrthographicCameraDef, CameraDef } from './components/Camera';
export { Animation } from './components/Animation';
export type { SvgAnimateDef, SvgAnimateTransformDef, SvgAnimationDef } from './components/Animation';
export type {
  SvgFilterDef, SvgFilterEffect, SvgBlurEffect, SvgDropShadowEffect,
  SvgClipPathDef, SvgMaskDef,
} from './components/Material';

// Primitives
export { createBox, createSphere, createPath2D } from './geometry/primitives';

// Serialization
export { serialize, deserialize } from './serialization/json';

// Math
export { Matrix4Identity, composeMatrix, multiplyMatrices } from './math/Matrix4';
export type { Matrix4 } from './math/Matrix4';

Scene

El contenedor de nivel superior del scene graph.

Archivo fuente: Scene.ts

import { Scene } from '@joroya/core';
const scene = new Scene();

Constructor

Propiedades

Métodos

Ejemplo

const scene = new Scene();

const parent = new Node('group');
const child = new Node('child');

scene.add(parent);
scene.add(child, parent); // child es hijo de parent, no del root

scene.traverse(node => console.log(node.name));
// 'root', 'group', 'child'

const found = scene.findNodeByName('child');
console.log(found?.parent?.name); // 'group'

Node

Un elemento del scene graph. Soporta jerarquía padre-hijo y un sistema de componentes ECS.

Archivo fuente: Node.ts

classDiagram
    class Node {
        +readonly id: string
        +name: string
        +parent: Node | null
        +readonly children: Node[]
        +readonly components: Map~ComponentType, Component~
        +get transform(): Transform
        +constructor(name: string, id?: string)
        +addComponent(component: Component): void
        +getComponent~T~(type: ComponentType): T | undefined
        +hasComponent(type: ComponentType): boolean
        +add(node: Node): void
        +remove(node: Node): void
        +updateWorldMatrix(parentMatrix?: Matrix4): void
        +traverse(callback: Function): void
        +findNodeById(id: string): Node | undefined
        +findNodeByName(name: string): Node | undefined
    }

Constructor

Nota: Cada nodo recibe automáticamente un componente Transform al crearse.

Propiedades

Métodos

Ejemplo completo

const player = new Node('player');
player.addComponent(createBox(0.5, 1, 0.5));
player.addComponent(new Material({ color: { r: 0.3, g: 0.8, b: 0.5 } }));

// Composición jerárquica
const weapon = new Node('weapon');
weapon.addComponent(createBox(0.1, 0.1, 0.8));
weapon.transform.position = { x: 0.3, y: 0.5, z: 0 };
player.add(weapon); // weapon es hijo de player

// Consultar componentes
const geo = player.getComponent<Geometry>(ComponentType.Geometry);
console.log(geo?.definition); // { type: 'Box', width: 0.5, ... }
console.log(player.hasComponent(ComponentType.Camera)); // false

// Re-parenting: mover weapon a otro nodo
const chest = new Node('chest');
chest.add(weapon); // se remueve automáticamente de player
console.log(weapon.parent?.name); // 'chest'

Component (base abstracta)

Clase base para todos los componentes del sistema ECS.

Archivo fuente: Component.ts

classDiagram
    class Component {
        <<abstract>>
        +abstract readonly type: ComponentType
        +node: Node | null
    }
    class Transform {
        +type = ComponentType.Transform
        +position: Vec3
        +rotation: Quat
        +scale: Vec3
        +localMatrix: Matrix4
        +worldMatrix: Matrix4
        +isDirty: boolean
        +updateLocalMatrix(): void
    }
    class Geometry {
        +type = ComponentType.Geometry
        +definition: GeometryDef
    }
    class Material {
        +type = ComponentType.Material
        +definition: MaterialDef
    }
    class Camera {
        +type = ComponentType.Camera
        +definition: CameraDef
    }
    class Animation {
        +type = ComponentType.Animation
        +animations: SvgAnimationDef[]
    }
    Component <|-- Transform
    Component <|-- Geometry
    Component <|-- Material
    Component <|-- Camera
    Component <|-- Animation

ComponentType (Enum)

Regla ECS: Cada nodo puede tener máximo un componente de cada tipo. Agregar un segundo componente del mismo tipo reemplaza al anterior.

Transform (Componente)

Define la posición, rotación y escala de un nodo en espacio 3D. Se crea automáticamente con cada Node.

Archivo fuente: Transform.ts

Propiedades

Métodos

Pipeline de transformación

graph LR
    A["position + rotation + scale"] -->|"updateLocalMatrix()"| B["localMatrix"]
    B -->|"ÁEparent.worldMatrix"| C["worldMatrix"]
    C -->|"renderer reads"| D["Posición final en pantalla"]

Guía rápida de quaterniones

Los quaterniones { x, y, z, w } representan rotaciones 3D sin gimbal lock.

Fórmula: Para rotar θ radianes alrededor del eje unitario (ax, ay, az): { x: ax * sin(θ/2), y: ay * sin(θ/2), z: az * sin(θ/2), w: cos(θ/2) }

Geometry (Componente)

Define la forma geométrica de un nodo.

Archivo fuente: Geometry.ts

Constructor

new Geometry(definition: GeometryDef)

GeometryPrimitive (Enum)

GeometryDef (Union type)

graph TD
    GD["GeometryDef"] -->|"type = 'Box'"| Box["BoxGeometryDef"]
    GD -->|"type = 'Sphere'"| Sphere["SphereGeometryDef"]
    GD -->|"type = 'Path2D'"| Path["Path2DGeometryDef"]
    GD -->|"type = 'Text'"| Text["TextGeometryDef"]

BoxGeometryDef

SphereGeometryDef

Tip: Más segmentos = esfera más suave. Valores comunes: 16 (baja calidad), 32 (estándar), 64 (alta calidad).

Path2DGeometryDef

Path2DCommand

Comandos SVG soportados:

TextGeometryDef

Compatibilidad con renderers

Material (Componente)

Define la apariencia visual de un nodo.

Archivo fuente: Material.ts

Constructor

new Material(definition?: MaterialDef)  // default: {}

ColorRGB

Conversión: Para convertir de hex #3399ff a RGB normalizado: { r: 0x33/255, g: 0x99/255, b: 0xff/255 } -> { r: 0.2, g: 0.6, b: 1.0 }

MaterialDef

GradientDef (Union type)

type GradientDef = LinearGradientDef | RadialGradientDef;

SVG Filters (SvgFilterDef)

Permite aplicar filtros SVG nativos a un nodo.

interface SvgFilterDef {
  effects: SvgFilterEffect[];
}

type SvgFilterEffect = SvgBlurEffect | SvgDropShadowEffect;

SvgBlurEffect

SvgDropShadowEffect

SvgClipPathDef

Recorta el nodo a una región vectorial definida por un path SVG.

SvgMaskDef

Aplica una máscara de luminancia al nodo.

Ejemplo: Filtros, clip-path y máscara

// Blur
const blurred = new Material({
  fill: { r: 1, g: 0, b: 0 },
  filter: { effects: [{ type: 'blur', stdDeviation: 3 }] },
});

// Drop shadow con color personalizado
const shadowed = new Material({
  fill: { r: 0, g: 0.5, b: 1 },
  filter: {
    effects: [{ type: 'dropShadow', dx: 4, dy: 4, stdDeviation: 2, floodColor: '#333', floodOpacity: 0.6 }],
  },
});

// Clip path
const clipped = new Material({
  fill: { r: 0, g: 1, b: 0 },
  clipPath: {
    path: [
      { command: 'M', args: [0, 0] },
      { command: 'L', args: [100, 0] },
      { command: 'L', args: [50, 100] },
      { command: 'Z', args: [] },
    ],
  },
});

LinearGradientDef

RadialGradientDef

GradientStop

Ejemplo: Material para ambos renderers

// Material que funciona en 3D y SVG
const material = new Material({
  color: { r: 0.2, g: 0.6, b: 1.0 },    // Three.js lo usa como diffuse color
  fill: { r: 0.2, g: 0.6, b: 1.0 },      // SVG lo usa como fill
  stroke: { r: 0.1, g: 0.3, b: 0.8 },    // SVG lo usa como stroke
  strokeWidth: 2,
  opacity: 0.9,
});

Cómo lo interpretan los renderers

graph LR
    MD["MaterialDef"] --> TH{"Three.js Renderer"}
    MD --> SV{"SVG Renderer"}
    TH --> M1["MeshStandardMaterial"]
    TH -->|"color"| M1
    TH -->|"opacity + transparent"| M1
    SV --> M2["style attributes"]
    SV -->|"fill / fillGradient"| M2
    SV -->|"stroke / strokeGradient"| M2
    SV -->|"opacity"| M2

Camera (Componente)

Define un punto de vista para renderizar la escena. El ThreeRenderer busca automáticamente el primer nodo con Camera al montar la escena.

Archivo fuente: Camera.ts

Constructor

new Camera(definition: CameraDef)

CameraType (Enum)

PerspectiveCameraDef

Diagrama de frustum (perspectiva)

              far plane
          ┌─────────────────━E
         /                   \
        /     Visible         \
       /      Volume           \
      /      (frustum)          \
     /                           \
    └─────────────────────────────━E
     ├── near plane ──┤
              △
           Camera
          position

Ejemplo de uso

const cam = new Node('main-camera');
cam.addComponent(new Camera({
  type: CameraType.Perspective,
  fov: 75,
  aspect: 16 / 9,
  near: 0.1,
  far: 1000,
}));
cam.transform.position = { x: 0, y: 5, z: 10 };
scene.add(cam);

OrthographicCameraDef

SVG: Cuando una escena tiene un nodo con OrthographicCameraDef, el renderer SVG calcula automáticamente el viewBox a partir de left, right, top y bottom, más el offset de posición de la cámara. Un viewBox explícito en las opciones tiene prioridad.

Ejemplo: Cámara ortográfica para SVG

const cam = new Node('ortho-cam');
cam.addComponent(new Camera({
  type: CameraType.Orthographic,
  left: -400, right: 400,
  top: -300, bottom: 300,
  near: 0.1, far: 1000,
}));
cam.transform.position = { x: 50, y: 25, z: 0 };
scene.add(cam);

// viewBox se calcula como "-350 -275 800 600" (offset por posición de cámara)
const svg = renderToSVG(scene, { width: 800, height: 600 });

Nota: Si no se agrega ninguna cámara, ThreeRenderer crea un fallback en (0, 0, 5) con FOV 75.

Interactive (componente)

Archivo fuente: Interactive.ts

Marca un nodo como interactivo, permitiendo que responda a eventos de puntero (click, hover, drag, etc.).

Animation (componente)

Archivo fuente: Animation.ts

Permite agregar animaciones SVG nativas (<animate> y <animateTransform>) a un nodo. Estas animaciones se ejecutan directamente en el navegador sin JavaScript.

Constructor

new Animation(animations: SvgAnimationDef[])

SvgAnimationDef (Union type)

type SvgAnimationDef = SvgAnimateDef | SvgAnimateTransformDef;

SvgAnimateDef

Genera un elemento <animate> que anima un atributo escalar.

SvgAnimateTransformDef

Genera un elemento <animateTransform> que anima una transformación geométrica.

Ejemplo

const circle = new Node('pulse');
circle.addComponent(createSphere(30));
circle.addComponent(new Material({ fill: { r: 1, g: 0, b: 0 } }));
circle.addComponent(new Animation([
  // Pulsar opacidad
  {
    type: 'animate',
    attributeName: 'opacity',
    values: '1;0.3;1',
    dur: '2s',
    repeatCount: 'indefinite',
  },
  // Rotar continuamente
  {
    type: 'animateTransform',
    transformType: 'rotate',
    from: '0 50 50',
    to: '360 50 50',
    dur: '4s',
    repeatCount: 'indefinite',
  },
]));
scene.add(circle);

Genera:

<circle cx="0" cy="0" r="30" fill="rgb(255, 0, 0)">
  <animate attributeName="opacity" values="1;0.3;1" dur="2s" repeatCount="indefinite" />
  <animateTransform attributeName="transform" type="rotate"
    from="0 50 50" to="360 50 50" dur="4s" repeatCount="indefinite" />
</circle>

Nota: Las animaciones SVG nativas solo tienen efecto en el renderer SVG. El renderer Three.js las ignora.

Definición

interface InteractiveDef {
  enabled: boolean;
  cursor: string;
  blocksRaycast: boolean;
}

Uso

import { Node, Interactive, createBox } from '@joroya/core';

const button = new Node('button');
button.addComponent(createBox(2, 1, 0.2));
button.addComponent(new Interactive({ cursor: 'pointer' }));

// Registrar event handlers
button.on('click', (e) => {
  console.log('Clicked!', e.target.name);
});

button.on('pointerenter', (e) => {
  console.log('Hover started');
});

button.on('pointerleave', (e) => {
  console.log('Hover ended');
});

Integración con renderers

• ThreeRenderer: Requiere llamar renderer.enableInteraction() después de mount(). Usa THREE.Raycaster para hit-testing 3D.
• SVG Renderer: Usa renderToSVGElement() (no renderToSVG()) para obtener un DOM element con event listeners.

EventEmitter

Archivo fuente: EventEmitter.ts

Sistema de eventos genérico con tipado fuerte. Cada Node tiene un EventEmitter interno para manejar InteractionEvents.

API

class EventEmitter<EventMap extends Record<string, any>> {
  on<K extends keyof EventMap>(
    eventType: K,
    handler: (payload: EventMap[K]) => void
  ): void;

  off<K extends keyof EventMap>(
    eventType: K,
    handler: (payload: EventMap[K]) => void
  ): void;

  emit<K extends keyof EventMap>(
    eventType: K,
    payload: EventMap[K]
  ): void;

  removeAllListeners(eventType?: keyof EventMap): void;

  hasListeners(eventType: keyof EventMap): boolean;
}

Ejemplo de uso directo

import { EventEmitter } from '@joroya/core';

type MyEvents = {
  'data-loaded': { id: string; data: any };
  'error': { message: string };
};

const emitter = new EventEmitter<MyEvents>();

emitter.on('data-loaded', (payload) => {
  console.log('Data:', payload.data);
});

emitter.emit('data-loaded', { id: '123', data: { foo: 'bar' } });

Uso en Node

Los nodos exponen shortcuts on() y off() que delegan al EventEmitter interno:

const node = new Node('my-node');

node.on('click', (e: InteractionEvent) => {
  console.log('Clicked at', e.screenPosition);
});

InteractionEvent

Archivo fuente: InteractionEvent.ts

Eventos de interacción que se disparan cuando el usuario interactúa con nodos marcados como Interactive.

Tipos de eventos

enum InteractionEventType {
  Click = 'click',
  PointerDown = 'pointerdown',
  PointerUp = 'pointerup',
  PointerMove = 'pointermove',
  PointerEnter = 'pointerenter',
  PointerLeave = 'pointerleave',
  PointerCancel = 'pointercancel',
  Wheel = 'wheel',
  DragStart = 'dragstart',
  DragEnd = 'dragend',
}

Interfaz

interface InteractionEvent {
  type: InteractionEventType;
  target: Node;                    // Nodo que recibió el evento originalmente
  currentTarget: Node;             // Nodo actual durante bubbling
  point?: { x: number; y: number; z: number };  // Posición 3D en world space
  localPoint?: { x: number; y: number; z: number };  // Posición en local space del nodo
  screenPosition: { x: number; y: number };  // Posición en pantalla (clientX/Y)
  nativeEvent: unknown;            // Evento DOM original (PointerEvent, MouseEvent, etc.)
  propagationStopped: boolean;
  stopPropagation(): void;
}

Event Bubbling

Los eventos se propagan hacia arriba en el scene graph (de hijo a padre), similar al DOM:

const parent = new Node('parent');
const child = new Node('child');
parent.add(child);

parent.on('click', (e) => {
  console.log('Parent clicked, target:', e.target.name);  // "child"
  console.log('Current target:', e.currentTarget.name);   // "parent"
});

child.on('click', (e) => {
  console.log('Child clicked');
  e.stopPropagation();  // Detiene el bubbling
});

Factory

function createInteractionEvent(
  type: InteractionEventType,
  target: Node,
  nativeEvent: unknown,
  screenPosition: { x: number; y: number },
  options?: {
    point?: { x: number; y: number; z: number };
    localPoint?: { x: number; y: number; z: number };
  }
): InteractionEvent;

Factory Functions

Funciones helper para crear componentes Geometry de forma concisa.

Archivo fuente: primitives.ts

createBox

function createBox(width?: number, height?: number, depth?: number): Geometry

const cube = createBox();          // Cubo 1ÁEÁE
const plank = createBox(5, 0.2, 1); // Tabla plana

createSphere

function createSphere(radius?: number, widthSegments?: number, heightSegments?: number): Geometry

const ball = createSphere(1, 32, 32); // Esfera suave
const lowpoly = createSphere(1, 8, 6); // Esfera facetada

createPath2D

function createPath2D(path: Path2DCommand[]): Geometry

const triangle = createPath2D([
  { command: 'M', args: [50, 0] },
  { command: 'L', args: [100, 100] },
  { command: 'L', args: [0, 100] },
  { command: 'Z', args: [] },
]);

createText

function createText(text: string, options?: {
  fontSize?: number;
  fontFamily?: string;
  fontWeight?: string;
  textAnchor?: string;
  dominantBaseline?: string;
}): Geometry

const title = createText('Hello', { fontSize: 32, fontFamily: 'monospace', textAnchor: 'middle' });

Serialización

Funciones para convertir escenas a JSON y reconstruirlas.

Archivo fuente: json.ts

serialize

function serialize(scene: Scene): string

Convierte todo el scene graph a una cadena JSON formateada con indentación de 2 espacios.

Componentes soportados en serialización:

deserialize

function deserialize(jsonString: string): Scene

Reconstruye una Scene funcional desde un string JSON.

Comportamiento:

• Los UUIDs de los nodos se preservan (mismo ID que el original).
• Los campos cssClass y cssId se serializan y restauran.
• Todos los componentes (Transform, Geometry, Material, Camera, Animation) se serializan y deserializan correctamente.
• El nodo raíz deserializado transfiere sus hijos al raíz de la nueva escena.

Formato del JSON

graph TD
    Root["SerializableScene"] -->|"root"| RN["SerializableNode"]
    RN -->|"id"| ID["string (UUID)"]
    RN -->|"name"| Name["string"]
    RN -->|"components"| Comps["SerializableComponent[]"]
    RN -->|"children"| Children["SerializableNode[]"]
    Comps --> SC["{ type: ComponentType, ...data }"]

{
  "root": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "root",
    "components": [
      {
        "type": "Transform",
        "position": { "x": 0, "y": 0, "z": 0 },
        "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
        "scale": { "x": 1, "y": 1, "z": 1 }
      }
    ],
    "children": [
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "my-box",
        "components": [
          { "type": "Transform", "..." : "..." },
          { "type": "Geometry", "definition": { "type": "Box", "width": 2, "height": 2, "depth": 2 } },
          { "type": "Material", "definition": { "color": { "r": 1, "g": 0.5, "b": 0 } } }
        ],
        "children": []
      }
    ]
  }
}

Math  EMatrix4

Utilidades matemáticas para transformaciones 3D con matrices 4ÁE.

Archivo fuente: Matrix4.ts

Matrix4 (Type)

Tupla de 16 números en column-major order (compatible con WebGL/Three.js):

type Matrix4 = [
  number, number, number, number,  // Columna 0 (Right)
  number, number, number, number,  // Columna 1 (Up)
  number, number, number, number,  // Columna 2 (Forward)
  number, number, number, number   // Columna 3 (Position)
];

Layout de la matriz:

Índice:  [ 0]  [ 4]  [ 8]  [12]
         [ 1]  [ 5]  [ 9]  [13]
         [ 2]  [ 6]  [10]  [14]
         [ 3]  [ 7]  [11]  [15]

Significado:
         [Rx]  [Ux]  [Fx]  [Tx]     R = Right (eje X)
         [Ry]  [Uy]  [Fy]  [Ty]     U = Up (eje Y)
         [Rz]  [Uz]  [Fz]  [Tz]     F = Forward (eje Z)
         [ 0]  [ 0]  [ 0]  [ 1]     T = Translation

Matrix4Identity

const Matrix4Identity: Readonly<Matrix4> = [
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  0, 0, 0, 1
];

composeMatrix

function composeMatrix(position: Vec3, quaternion: Quat, scale: Vec3): Matrix4

Construye una matriz de transformación a partir de posición, rotación (quaternion) y escala. Esta es la función usada internamente por Transform.updateLocalMatrix().

multiplyMatrices

function multiplyMatrices(a: Matrix4, b: Matrix4): Matrix4

Multiplica dos matrices 4ÁE. El orden es importante: result = A ÁEB (A se aplica después de B).

Usada internamente por Node.updateWorldMatrix():

worldMatrix = multiplyMatrices(parent.worldMatrix, this.localMatrix)

Math  EBoundingBox

Archivo fuente: BoundingBox.ts

Utilidades para calcular y manipular Axis-Aligned Bounding Boxes (AABB).

Tipos

interface AABB {
  min: { x: number; y: number; z: number };
  max: { x: number; y: number; z: number };
}

Funciones

computeLocalAABB

Calcula el AABB local basado en la definición de la geometría.

function computeLocalAABB(def: GeometryDef): AABB

• Soporta Box, Sphere y Path2D.
• Para Path2D, calcula el bounding box exacto de los puntos de control.

transformAABB

Transforma un AABB local al espacio de mundo usando una matriz de transformación.

function transformAABB(localAABB: AABB, matrix: Matrix4): AABB

pointInAABB

Verifica si un punto está dentro de un AABB.

function pointInAABB(point: { x: number; y: number; z: number }, aabb: AABB): boolean

@joroya/renderer-three

ThreeRenderer

Renderer WebGL basado en Three.js.

Archivo fuente: ThreeRenderer.ts

classDiagram
    class ThreeRenderer {
        -renderer: THREE.WebGLRenderer
        -scene: THREE.Scene
        -activeCamera: THREE.Camera | null
        -oroyaScene: OroyaScene | null
        -nodeMap: Map~string, THREE.Object3D~
        +constructor(options: ThreeRendererOptions)
        +mount(scene: OroyaScene): void
        +render(): void
        +enableInteraction(): void
        +disableInteraction(): void
        +dispose(): void
    }

    class ThreeRendererOptions {
        +canvas: HTMLCanvasElement
        +width: number
        +height: number
        +dpr?: number
    }

ThreeRendererOptions

Métodos

Traducción de componentes

Iluminación automática

Al montar una escena, el renderer agrega automáticamente:

Ejemplo

const renderer = new ThreeRenderer({
  canvas: document.getElementById('canvas') as HTMLCanvasElement,
  width: window.innerWidth,
  height: window.innerHeight,
  dpr: 2, // Retina display
});

renderer.mount(scene);

function animate() {
  // ... mutate scene ...
  renderer.render();
  requestAnimationFrame(animate);
}
animate();

// Cleanup
renderer.dispose();

@joroya/renderer-svg

renderToSVG

Función pura que genera un string SVG a partir de una escena.

Archivo fuente: renderSVG.ts

function renderToSVG(scene: Scene, options: SvgRenderOptions): string

SvgRenderOptions

renderToSVGElement

Genera un elemento SVG del DOM (SVGSVGElement) con event listeners para interactividad.

Archivo fuente: renderSVG.ts

function renderToSVGElement(
  scene: Scene,
  options: SvgElementRenderOptions
): { svg: SVGSVGElement; dispose: () => void }

SvgElementRenderOptions

Extiende SvgRenderOptions con:

Retorno

Retorna un objeto con:

• svg: El elemento DOM SVG creado.
• dispose(): Función para limpiar event listeners y remover el elemento del DOM.

Ejemplo

const { dispose } = renderToSVGElement(scene, {
  width: 800,
  height: 600,
  container: document.body
});

// Más tarde...
dispose();

Comportamiento

1. Llama a scene.update(dt) y luego scene.updateWorldMatrices() para sincronizar estado y transforms.
2. Recorre recursivamente el árbol de nodos generando <g> para la jerarquía.
3. Geometrías soportadas: Path2D -> <path>, Box -> <rect>, Sphere -> <circle>, Text -> <text>, y proyecciones 2D para varias primitivas 3D.
4. Si el nodo tiene un Material, aplica fill, stroke, stroke-width, opacity, fillGradient y strokeGradient.
5. Los gradientes generan un bloque <defs> al inicio del SVG con <linearGradient> / <radialGradient>.
6. El localMatrix de cada nodo se aplica como transform="matrix(a,b,c,d,e,f)".
7. Los colores se convierten de RGB normalizado (0 E) a rgb(R, G, B) con valores 0 E55.

Ejemplo

import { renderToSVG } from '@joroya/renderer-svg';

const svg = renderToSVG(scene, {
  width: 800,
  height: 600,
  viewBox: '0 0 800 600',
});

// Insertar en el DOM
document.body.innerHTML = svg;

// O guardar como archivo en Node.js
import { writeFileSync } from 'fs';
writeFileSync('output.svg', svg);

Ventaja clave: Esta función es pura y no requiere DOM. Funciona en Node.js para server-side rendering.

@joroya/loader-gltf

loadGLTF

Carga un archivo glTF/GLB y lo traduce al scene graph de Oroya.

Archivo fuente: loadGLTF.ts

async function loadGLTF(url: string): Promise<GLTFLoadResult>

interface GLTFLoadResult {
  scene: Scene;
  animations: AnimationClip[];
}

Traducción

Nota: El loader devuelve una Scene independiente. Para mezclar el modelo con otra escena, mueve o clona los hijos de result.scene.root hacia tu escena principal.

Mapa completo de tipos

graph TD
    subgraph "Tipos base"
        Vec3["Vec3 {x, y, z}"]
        Quat["Quat {x, y, z, w}"]
        ColorRGB["ColorRGB {r, g, b}"]
        M4["Matrix4 (16-tuple)"]
    end

    subgraph "Geometry types"
        GD["GeometryDef (union)"]
        GD --> BGD["BoxGeometryDef"]
        GD --> SGD["SphereGeometryDef"]
        GD --> PGD["Path2DGeometryDef"]
        PGD --> P2DC["Path2DCommand"]
    end

    subgraph "Material types"
        MatD["MaterialDef"]
        MatD -.-> ColorRGB
    end

    subgraph "Camera types"
        CD["CameraDef (union)"]
        CD --> PCD["PerspectiveCameraDef"]
        CD --> OCD["OrthographicCameraDef"]
    end

    subgraph "Animation types"
        AD["SvgAnimationDef (union)"]
        AD --> SAD["SvgAnimateDef"]
        AD --> SATD["SvgAnimateTransformDef"]
    end

    subgraph "Filter types"
        FD["SvgFilterDef"]
        FD --> FE["SvgFilterEffect (union)"]
        FE --> BL["SvgBlurEffect"]
        FE --> DS["SvgDropShadowEffect"]
        CPD["SvgClipPathDef"]
        MKD["SvgMaskDef"]
    end

    subgraph "Enums"
        CT["ComponentType"]
        GP["GeometryPrimitive"]
        CamT["CameraType"]
    end

    subgraph "Serialization"
        SScene["SerializableScene"]
        SNode["SerializableNode"]
        SComp["SerializableComponent"]
        SScene --> SNode
        SNode --> SComp
        SNode -->|"children"| SNode
    end

Tabla resumen de todos los exports