ecspresso 0.13.4 → 0.14.2

package/dist/plugins/rendering/renderer3D.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 3D Renderer Plugin for ECSpresso
+ *
+ * An opt-in Three.js-based 3D rendering plugin that automates scene graph wiring.
+ * Import from 'ecspresso/plugins/rendering/renderer3D'
+ *
+ * This plugin includes 3D transform propagation automatically.
+ */
+import type { WebGLRenderer, WebGLRendererParameters, Scene, Camera, Object3D, Mesh, Group, ColorRepresentation } from 'three';
+import { type Plugin } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../../type-utils';
+import { type LocalTransform3D, type WorldTransform3D, type Transform3DComponentTypes, type Transform3DPluginOptions } from 'ecspresso/plugins/spatial/transform3D';
+export type { LocalTransform3D, WorldTransform3D, Transform3DComponentTypes };
+export { createTransform3D, createLocalTransform3D, createWorldTransform3D, DEFAULT_LOCAL_TRANSFORM_3D, DEFAULT_WORLD_TRANSFORM_3D, } from 'ecspresso/plugins/spatial/transform3D';
+/**
+ * Visibility component for 3D entities.
+ */
+export interface Visible3D {
+    visible: boolean;
+}
+/**
+ * Aggregate component types for the 3D renderer plugin.
+ * Included automatically via `.withPlugin(createRenderer3DPlugin({ ... }))`.
+ */
+export interface Renderer3DComponentTypes extends Transform3DComponentTypes {
+    mesh: Mesh;
+    group: Group;
+    object3d: Object3D;
+    visible3d: Visible3D;
+    /** Controls Three.js Object3D.renderOrder for manual z-ordering */
+    renderOrder: number;
+}
+/**
+ * Events emitted by the 3D renderer plugin.
+ */
+export interface Renderer3DEventTypes {
+    hierarchyChanged: {
+        entityId: number;
+        oldParent: number | null;
+        newParent: number | null;
+    };
+}
+/**
+ * Resources provided by the 3D renderer plugin.
+ */
+export interface Renderer3DResourceTypes {
+    threeRenderer: WebGLRenderer;
+    scene: Scene;
+    camera: Camera;
+}
+/**
+ * Common options shared between both initialization modes.
+ */
+interface Renderer3DPluginCommonOptions<G extends string = 'renderer3d'> {
+    /** System group name (default: 'renderer3d') */
+    systemGroup?: G;
+    /** Priority for render sync system (default: 500) */
+    renderSyncPriority?: number;
+    /** Options for the included 3D transform plugin */
+    transform?: Transform3DPluginOptions;
+    /** When true, starts a requestAnimationFrame loop to drive ecs.update() automatically (default: true) */
+    startLoop?: boolean;
+}
+/**
+ * Options when providing pre-initialized Three.js objects.
+ */
+export interface Renderer3DPluginPreInitOptions<G extends string = 'renderer3d'> extends Renderer3DPluginCommonOptions<G> {
+    /** Pre-initialized WebGLRenderer */
+    renderer: WebGLRenderer;
+    /** Pre-initialized Scene */
+    scene: Scene;
+    /** Pre-initialized Camera */
+    camera: Camera;
+    container?: never;
+    background?: never;
+    width?: never;
+    height?: never;
+    antialias?: never;
+    shadows?: never;
+    cameraOptions?: never;
+    threeInit?: never;
+}
+/**
+ * Camera configuration for managed mode.
+ *
+ * Discriminated on `projection`. Defaults to `'perspective'` when omitted.
+ * Orthographic cameras use `viewSize` (world-unit height at zoom=1) to define
+ * the base frustum; `zoom` maps directly to Three.js's `OrthographicCamera.zoom`.
+ */
+export type CameraOptions = {
+    projection?: 'perspective';
+    fov?: number;
+    near?: number;
+    far?: number;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lookAt?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+} | {
+    projection: 'orthographic';
+    viewSize?: number;
+    zoom?: number;
+    near?: number;
+    far?: number;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lookAt?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * Options when letting the plugin create and manage Three.js objects.
+ */
+export interface Renderer3DPluginManagedOptions<G extends string = 'renderer3d'> extends Renderer3DPluginCommonOptions<G> {
+    renderer?: never;
+    scene?: never;
+    camera?: never;
+    /** Container element to append the canvas to (or CSS selector string). Defaults to `document.body`. */
+    container?: HTMLElement | string;
+    /** Scene background color. */
+    background?: ColorRepresentation;
+    /** Canvas width. When omitted, auto-sizes to container. */
+    width?: number;
+    /** Canvas height. When omitted, auto-sizes to container. */
+    height?: number;
+    /** Enable antialiasing (default: true) */
+    antialias?: boolean;
+    /** Enable shadow mapping (default: false) */
+    shadows?: boolean;
+    /** Camera configuration */
+    cameraOptions?: CameraOptions;
+    /** Escape hatch for raw WebGLRendererParameters not otherwise exposed. */
+    threeInit?: Partial<WebGLRendererParameters>;
+}
+/**
+ * Configuration options for the 3D renderer plugin.
+ *
+ * Supports two modes:
+ * 1. **Pre-initialized**: Pass already-initialized renderer, scene, camera
+ * 2. **Managed**: Omit them and the plugin creates everything during `ecs.initialize()`
+ *
+ * This plugin includes 3D transform propagation automatically.
+ *
+ * @example Pre-initialized mode
+ * ```typescript
+ * const renderer = new WebGLRenderer({ antialias: true });
+ * const scene = new Scene();
+ * const camera = new PerspectiveCamera(75, w / h, 0.1, 1000);
+ *
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createRenderer3DPlugin({ renderer, scene, camera }))
+ *   .build();
+ * ```
+ *
+ * @example Managed mode
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createRenderer3DPlugin({
+ *     container: '#game',
+ *     background: 0x1099bb,
+ *     antialias: true,
+ *     cameraOptions: { fov: 75, position: { x: 0, y: 5, z: 10 } },
+ *   }))
+ *   .build();
+ * await ecs.initialize();
+ * ```
+ */
+export type Renderer3DPluginOptions<G extends string = 'renderer3d'> = Renderer3DPluginPreInitOptions<G> | Renderer3DPluginManagedOptions<G>;
+interface PositionOption3D {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+interface TransformOptions3D {
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    scale?: number | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    visible?: boolean;
+}
+/**
+ * Create components for a mesh entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const player = ecs.spawn({
+ *   ...createMeshComponents(myMesh, { x: 10, y: 0, z: -5 }),
+ *   velocity: { x: 0, y: 0, z: 0 },
+ * });
+ * ```
+ */
+export declare function createMeshComponents(mesh: Mesh, position?: PositionOption3D, options?: TransformOptions3D): Pick<Renderer3DComponentTypes, 'mesh' | 'localTransform3D' | 'worldTransform3D' | 'visible3d'>;
+/**
+ * Create components for a group entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const enemies = ecs.spawn({
+ *   ...createGroupComponents(enemyGroup, { x: 50, y: 0, z: -30 }),
+ * });
+ * ```
+ */
+export declare function createGroupComponents(group: Group, position?: PositionOption3D, options?: TransformOptions3D): Pick<Renderer3DComponentTypes, 'group' | 'localTransform3D' | 'worldTransform3D' | 'visible3d'>;
+/**
+ * Create components for a generic Object3D entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const obj = ecs.spawn({
+ *   ...createObject3DComponents(myObject, { x: 0, y: 0, z: 0 }),
+ * });
+ * ```
+ */
+export declare function createObject3DComponents(object3d: Object3D, position?: PositionOption3D, options?: TransformOptions3D): Pick<Renderer3DComponentTypes, 'object3d' | 'localTransform3D' | 'worldTransform3D' | 'visible3d'>;
+type Renderer3DLabels = 'renderer3d-sync' | 'renderer3d-scene-graph' | 'renderer3d-render' | 'transform3d-propagation';
+type Renderer3DReactiveQueryNames = 'renderer3d-meshes' | 'renderer3d-groups' | 'renderer3d-objects';
+/**
+ * Create a 3D rendering plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - 3D transform propagation (localTransform3D -> worldTransform3D)
+ * - Render sync system (updates Three.js objects from ECS components)
+ * - Scene graph management (auto-adds/removes Three.js objects)
+ * - Render call (renderer.render(scene, camera) each frame)
+ * - Optional requestAnimationFrame loop
+ */
+export declare function createRenderer3DPlugin<G extends string = 'renderer3d'>(options: Renderer3DPluginOptions<G>): Plugin<WorldConfigFrom<Renderer3DComponentTypes, Renderer3DEventTypes, Renderer3DResourceTypes>, EmptyConfig, Renderer3DLabels, G, never, Renderer3DReactiveQueryNames>;