@ludra/three 0.0.0-stage → 0.92.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import * as THREE from "three";
+import { type Entity, type GameEvent, type RenderContext, type SceneDef } from "@ludra/core";
+import type { Renderer3D, Renderer3DFactory } from "@ludra/core/browser";
+/**
+ * The 3D renderer for Ludra: Three.js draws every entity with a `mesh` and lights the scene
+ * with its `light` entities, seen through a `camera3d`. It only reads the world, so it can
+ * never change what tests verified.
+ */
+/** The World as the renderer needs it: what to draw, its events, and its render hooks. */
+interface WorldView {
+    readonly entities: readonly Entity[];
+    readonly events?: readonly GameEvent[];
+    readonly time?: number;
+    callRenderHook?(entity: Entity, extras: Omit<RenderContext, "self" | "world" | "params">): void;
+}
+/** Creates the 3D renderer for a scene. Pass it to startGame as `loadRenderer3D`. */
+export declare const createRenderer3D: Renderer3DFactory;
+export declare class ThreeRenderer implements Renderer3D {
+    readonly canvas: HTMLCanvasElement;
+    debug: boolean;
+    /** Three.js itself, for render hooks and anything else (step 4 hands these to scripts). */
+    readonly renderer: THREE.WebGLRenderer;
+    readonly scene: THREE.Scene<THREE.Object3DEventMap>;
+    readonly camera: THREE.PerspectiveCamera;
+    private readonly objects;
+    private readonly lights;
+    private readonly textures;
+    /** Loaded glTF files by path; null when one failed to load (its entities fall back to a shape). */
+    private readonly gltfs;
+    private readonly gltfLoads;
+    private gltfLoader;
+    private readonly models;
+    /** Entities drawn with a placeholder while their model loads. */
+    private readonly waiting;
+    /**
+     * The clips each modelled entity played, recorded once per simulation step (not per frame), so a
+     * pose depends only on the simulation: a screenshot shows what the live game shows at that moment.
+     */
+    private readonly clipHistory;
+    private readonly debugGroup;
+    private readonly defaultLights;
+    private rig;
+    /** Each render-hook entity's own group, and its ctx.local. */
+    private readonly hookGroups;
+    private readonly hookLocals;
+    /** A render hook's own way of drawing the frame (an EffectComposer), if one set it. */
+    private customRender;
+    /** Addons render hooks are still loading. */
+    private readonly pending;
+    private readonly def;
+    private readonly assetBase;
+    constructor(def: SceneDef, width: number, height: number, assetBase: string);
+    /** Loads every texture and model the scene (and its prefabs) names, so the first frame (and screenshots) are complete. */
+    load(): Promise<void>;
+    /** Loads a glTF file once. Draco and meshopt compressed files work too. */
+    private loadModel;
+    private applyEnvironment;
+    step(world: WorldView): void;
+    reset(world: WorldView): void;
+    render(world: WorldView): void;
+    /** Waits for every addon render hooks asked for, and for what their callbacks start in turn. */
+    settle(): Promise<void>;
+    private track;
+    /** Scripts' render hooks: the real three.js, this entity's group, the scene, camera and renderer. */
+    private runRenderHooks;
+    dispose(): void;
+    /** Notes which clip every modelled entity should play now, and when that clip started. */
+    private recordClips;
+    /** Poses every model for this moment: a pure function of simulation time and the clip history. */
+    private poseModels;
+    private modelHandle;
+    /** Brings Three's scene in line with the world: new entities, removed ones, every transform. */
+    private sync;
+    private addDefaultLights;
+    private createMesh;
+    /**
+     * A copy of the model (bones included), turned, fitted to the entity and offset. The returned group
+     * is placed like any mesh; inside it a pivot holds the fit, so scripts can still move the root.
+     */
+    private createModel;
+    private placeLight;
+    /** Where the camera wants to be this step, eased by its smoothing. Deterministic per step. */
+    private updateRig;
+    /** Colliders as wireframes in their body's color, drawn over everything, and light positions. */
+    private syncDebug;
+}
+export {};