@ludra/three 0.0.0-stage → 0.92.0

package/dist/index.js

@@ -0,0 +1,713 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import * as THREE from "three";
+import { ConvexGeometry } from "three/addons/geometries/ConvexGeometry.js";
+import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
+import { clone as cloneSkinned } from "three/addons/utils/SkeletonUtils.js";
+import { FIXED_DT, } from "@ludra/core";
+const DEG = Math.PI / 180;
+const TONE_MAPPING = {
+    aces: THREE.ACESFilmicToneMapping,
+    neutral: THREE.NeutralToneMapping,
+    agx: THREE.AgXToneMapping,
+    none: THREE.NoToneMapping,
+};
+/** Collider colors in the debug view, as in 2D: static, dynamic, kinematic, sensor, player. */
+const DEBUG_COLORS = { static: 0x7fdbff, dynamic: 0xffdc00, kinematic: 0xff851b, sensor: 0x2ecc40, player: 0xff4136 };
+/** Creates the 3D renderer for a scene. Pass it to startGame as `loadRenderer3D`. */
+export const createRenderer3D = async (scene, options) => {
+    const renderer = new ThreeRenderer(scene, options.width, options.height, options.assetBase);
+    await renderer.load();
+    return renderer;
+};
+export class ThreeRenderer {
+    canvas;
+    debug = false;
+    /** Three.js itself, for render hooks and anything else (step 4 hands these to scripts). */
+    renderer;
+    scene = new THREE.Scene();
+    camera;
+    objects = new Map();
+    lights = new Map();
+    textures = new Map();
+    /** Loaded glTF files by path; null when one failed to load (its entities fall back to a shape). */
+    gltfs = new Map();
+    gltfLoads = new Map();
+    gltfLoader;
+    models = new Map();
+    /** Entities drawn with a placeholder while their model loads. */
+    waiting = new Set();
+    /**
+     * 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.
+     */
+    clipHistory = new Map();
+    debugGroup = new THREE.Group();
+    defaultLights = new THREE.Group();
+    rig;
+    /** Each render-hook entity's own group, and its ctx.local. */
+    hookGroups = new Map();
+    hookLocals = new Map();
+    /** A render hook's own way of drawing the frame (an EffectComposer), if one set it. */
+    customRender;
+    /** Addons render hooks are still loading. */
+    pending = new Set();
+    def;
+    assetBase;
+    constructor(def, width, height, assetBase) {
+        this.def = def;
+        this.assetBase = assetBase;
+        this.canvas = document.createElement("canvas");
+        this.canvas.width = width;
+        this.canvas.height = height;
+        // preserveDrawingBuffer: the frame is copied into the game's 2D canvas after drawing.
+        this.renderer = new THREE.WebGLRenderer({ canvas: this.canvas, antialias: true, preserveDrawingBuffer: true });
+        this.renderer.setPixelRatio(1);
+        this.renderer.setSize(width, height, false);
+        this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+        const env = def.environment ?? {};
+        this.renderer.toneMapping = TONE_MAPPING[env.toneMapping ?? "aces"];
+        this.renderer.toneMappingExposure = env.exposure ?? 1;
+        this.renderer.shadowMap.enabled = env.shadows ?? true;
+        this.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+        this.camera = new THREE.PerspectiveCamera(55, width / height, 0.05, 2000);
+        this.applyEnvironment(env);
+        this.scene.add(this.debugGroup, this.defaultLights);
+    }
+    /** Loads every texture and model the scene (and its prefabs) names, so the first frame (and screenshots) are complete. */
+    async load() {
+        const loader = new THREE.TextureLoader();
+        const meshes = [...this.def.entities, ...Object.values(this.def.prefabs ?? {})].map((e) => e.components?.mesh);
+        const named = (field) => new Set(meshes.map((m) => m?.[field]).filter((p) => typeof p === "string" && p !== ""));
+        const paths = named("texture");
+        const models = [...named("model")].map((path) => this.loadModel(path));
+        await Promise.all([
+            ...models,
+            ...[...paths].map(async (path) => {
+                try {
+                    const texture = await loader.loadAsync(this.assetBase + path);
+                    texture.colorSpace = THREE.SRGBColorSpace;
+                    texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+                    texture.anisotropy = 4;
+                    this.textures.set(path, texture);
+                }
+                catch {
+                    console.warn(`[ludra] could not load texture "${path}", using the mesh color instead.`);
+                }
+            }),
+        ]);
+    }
+    /** Loads a glTF file once. Draco and meshopt compressed files work too. */
+    loadModel(path) {
+        let load = this.gltfLoads.get(path);
+        if (load)
+            return load;
+        if (!this.gltfLoader) {
+            this.gltfLoader = new GLTFLoader();
+            const draco = new DRACOLoader();
+            // The decoder sits in three's addons, which the import map serves.
+            draco.setDecoderPath(new URL("../libs/draco/gltf/", import.meta.resolve("three/addons/loaders/DRACOLoader.js")).href);
+            this.gltfLoader.setDRACOLoader(draco);
+            this.gltfLoader.setMeshoptDecoder(MeshoptDecoder);
+        }
+        load = this.track(this.gltfLoader.loadAsync(this.assetBase + path).then((gltf) => void this.gltfs.set(path, gltf), (err) => {
+            console.warn(`[ludra] could not load model "${path}" (${err?.message ?? err}), drawing its shape instead.`);
+            this.gltfs.set(path, null);
+        }));
+        this.gltfLoads.set(path, load);
+        return load;
+    }
+    applyEnvironment(env) {
+        const sky = env.sky ?? ["#6fa8ff", "#dfeaff"];
+        if (typeof sky === "string")
+            this.scene.background = new THREE.Color(sky);
+        else {
+            // A vertical gradient: top of the sky to the horizon.
+            const c = document.createElement("canvas");
+            c.width = 2;
+            c.height = 256;
+            const g = c.getContext("2d");
+            const gradient = g.createLinearGradient(0, 0, 0, 256);
+            gradient.addColorStop(0, sky[0]);
+            gradient.addColorStop(1, sky[1]);
+            g.fillStyle = gradient;
+            g.fillRect(0, 0, 2, 256);
+            const texture = new THREE.CanvasTexture(c);
+            texture.colorSpace = THREE.SRGBColorSpace;
+            this.scene.background = texture;
+        }
+        if (env.fog) {
+            const color = env.fog.color ?? (typeof sky === "string" ? sky : sky[1]);
+            this.scene.fog = new THREE.Fog(color, env.fog.near ?? 30, env.fog.far ?? 150);
+        }
+    }
+    step(world) {
+        this.updateRig(world, FIXED_DT);
+        this.recordClips(world);
+    }
+    reset(world) {
+        this.rig = undefined;
+        this.clipHistory.clear();
+        this.recordClips(world);
+        // Things render hooks built belong to the old run.
+        for (const group of this.hookGroups.values())
+            group.removeFromParent();
+        this.hookGroups.clear();
+        this.hookLocals.clear();
+        this.customRender = undefined;
+        this.updateRig(world, 0);
+    }
+    render(world) {
+        if (!this.rig)
+            this.updateRig(world, 0);
+        this.sync(world);
+        const rig = this.rig;
+        this.camera.position.copy(rig.position);
+        this.camera.lookAt(rig.look);
+        this.poseModels(world);
+        this.runRenderHooks(world);
+        if (this.customRender)
+            this.customRender();
+        else
+            this.renderer.render(this.scene, this.camera);
+    }
+    /** Waits for every addon render hooks asked for, and for what their callbacks start in turn. */
+    async settle() {
+        for (let round = 0; round < 5 && this.pending.size > 0; round++) {
+            await Promise.allSettled([...this.pending]);
+            // Let .then callbacks run (they often load the next thing or set a custom render).
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+    track(promise) {
+        this.pending.add(promise);
+        void promise.finally(() => this.pending.delete(promise)).catch(() => { });
+        return promise;
+    }
+    /** Scripts' render hooks: the real three.js, this entity's group, the scene, camera and renderer. */
+    runRenderHooks(world) {
+        const live = new Set(world.entities);
+        for (const [entity, group] of this.hookGroups) {
+            if (live.has(entity))
+                continue;
+            group.removeFromParent();
+            this.hookGroups.delete(entity);
+            this.hookLocals.delete(entity);
+        }
+        if (!world.callRenderHook)
+            return;
+        for (const e of world.entities) {
+            if (!e.script?.module.render)
+                continue;
+            let group = this.hookGroups.get(e);
+            if (!group) {
+                group = new THREE.Group();
+                group.name = `${e.id}:render`;
+                this.hookGroups.set(e, group);
+                this.hookLocals.set(e, {});
+                this.scene.add(group);
+            }
+            placeObject(group, e);
+            world.callRenderHook(e, {
+                THREE,
+                scene: this.scene,
+                camera: this.camera,
+                renderer: this.renderer,
+                object: group,
+                model: this.modelHandle(e),
+                time: world.time ?? 0,
+                local: this.hookLocals.get(e),
+                view: { width: this.canvas.width, height: this.canvas.height },
+                recent: (name, seconds = 0.5) => recentEvents(world, name, seconds),
+                addon: (path) => this.track(import(__rewriteRelativeImportExtension(`three/addons/${path}`))),
+                setRender: (fn) => {
+                    this.customRender = fn;
+                },
+                random: Math.random,
+            });
+        }
+    }
+    dispose() {
+        this.scene.traverse((o) => {
+            const mesh = o;
+            mesh.geometry?.dispose();
+            const material = mesh.material;
+            if (Array.isArray(material))
+                material.forEach((m) => m.dispose());
+            else
+                material?.dispose();
+        });
+        for (const texture of this.textures.values())
+            texture.dispose();
+        this.renderer.dispose();
+    }
+    // ---------------------------------------------------------------- animation
+    /** Notes which clip every modelled entity should play now, and when that clip started. */
+    recordClips(world) {
+        const time = world.time ?? 0;
+        const live = new Set(world.entities);
+        for (const entity of this.clipHistory.keys())
+            if (!live.has(entity))
+                this.clipHistory.delete(entity);
+        for (const e of world.entities) {
+            if (!e.mesh?.model)
+                continue;
+            const { clip, once } = chooseClip(e);
+            const history = this.clipHistory.get(e) ?? [];
+            const last = history[history.length - 1];
+            if (last && last.clip === clip)
+                continue;
+            history.push({ clip, since: time, once });
+            // Only the newest two matter: the clip playing and the one it blends out of.
+            if (history.length > 2)
+                history.shift();
+            this.clipHistory.set(e, history);
+        }
+    }
+    /** Poses every model for this moment: a pure function of simulation time and the clip history. */
+    poseModels(world) {
+        const time = world.time ?? 0;
+        for (const [e, model] of this.models) {
+            if (model.actions.size === 0)
+                continue;
+            const spec = e.mesh;
+            const history = this.clipHistory.get(e) ?? [];
+            const current = history[history.length - 1];
+            const previous = history[history.length - 2];
+            const blend = !current || !previous || spec.fade <= 0 ? 1 : Math.min(1, (time - current.since) / spec.fade);
+            for (const [name, action] of model.actions) {
+                const entry = name === current?.clip ? current : name === previous?.clip && blend < 1 ? previous : undefined;
+                if (!entry) {
+                    action.setEffectiveWeight(0);
+                    continue;
+                }
+                const duration = action.getClip().duration;
+                const elapsed = Math.max(0, time - entry.since) * spec.animationSpeed;
+                action.time = duration <= 0 ? 0 : entry.once ? Math.min(elapsed, duration - 1e-4) : elapsed % duration;
+                action.setEffectiveWeight(entry === current ? blend : 1 - blend);
+            }
+            if (current && current.clip !== "" && !model.actions.has(current.clip) && !warnedClips.has(`${e.id}:${current.clip}`)) {
+                warnedClips.add(`${e.id}:${current.clip}`);
+                console.warn(`[ludra] entity "${e.id}" asked for the clip "${current.clip}", which its model doesn't have. Clips: ${[...model.actions.keys()].join(", ") || "none"}.`);
+            }
+            model.mixer.update(0);
+        }
+    }
+    modelHandle(e) {
+        const model = this.models.get(e);
+        return model && { root: model.root, clips: model.clips, mixer: model.mixer };
+    }
+    // ---------------------------------------------------------------- objects
+    /** Brings Three's scene in line with the world: new entities, removed ones, every transform. */
+    sync(world) {
+        const live = new Set(world.entities);
+        for (const [entity, object] of this.objects) {
+            // A model that finished loading replaces its placeholder.
+            const ready = this.waiting.has(entity) && this.gltfs.has(entity.mesh.model);
+            if (live.has(entity) && !ready)
+                continue;
+            object.removeFromParent();
+            this.objects.delete(entity);
+            this.models.get(entity)?.mixer.stopAllAction();
+            this.models.delete(entity);
+            this.waiting.delete(entity);
+        }
+        for (const [entity, light] of this.lights) {
+            if (live.has(entity))
+                continue;
+            light.removeFromParent();
+            this.lights.delete(entity);
+        }
+        let lit = false;
+        for (const e of world.entities) {
+            if (e.mesh) {
+                let object = this.objects.get(e);
+                if (!object) {
+                    object = this.createMesh(e);
+                    this.objects.set(e, object);
+                    this.scene.add(object);
+                }
+                object.visible = e.mesh.visible;
+                placeObject(object, e);
+            }
+            if (e.light) {
+                lit = true;
+                let light = this.lights.get(e);
+                if (!light) {
+                    light = createLight(e.light);
+                    this.lights.set(e, light);
+                    this.scene.add(light);
+                    if (light instanceof THREE.DirectionalLight || light instanceof THREE.SpotLight)
+                        this.scene.add(light.target);
+                }
+                this.placeLight(light, e);
+            }
+        }
+        // A scene without lights would be black: a soft sky and a sun until it has its own.
+        if (!lit && this.defaultLights.children.length === 0)
+            this.addDefaultLights();
+        this.defaultLights.visible = !lit;
+        if (!lit) {
+            const sun = this.defaultLights.children.find((c) => c instanceof THREE.DirectionalLight);
+            if (sun) {
+                sun.position.copy(this.rig.focus).add(new THREE.Vector3(8, 16, 6));
+                sun.target.position.copy(this.rig.focus);
+                sun.target.updateMatrixWorld();
+            }
+        }
+        this.syncDebug(world);
+    }
+    addDefaultLights() {
+        const sky = new THREE.HemisphereLight("#dfe9ff", "#4a4036", 1.1);
+        const sun = new THREE.DirectionalLight("#fff4e0", 2.4);
+        configureSun(sun, 40);
+        this.defaultLights.add(sky, sun, sun.target);
+    }
+    createMesh(e) {
+        const spec = e.mesh;
+        if (spec.model) {
+            const gltf = this.gltfs.get(spec.model);
+            if (gltf)
+                return this.createModel(e, gltf);
+            if (gltf === undefined) {
+                // Not loaded yet (a spawned entity whose model the scene never named): an empty stand-in until it is.
+                void this.loadModel(spec.model);
+                this.waiting.add(e);
+                const placeholder = new THREE.Group();
+                placeholder.name = e.id;
+                return placeholder;
+            }
+        }
+        const geometry = meshGeometry(spec, e.body);
+        const texture = spec.texture ? this.textures.get(spec.texture)?.clone() : undefined;
+        if (texture && spec.textureScale > 0) {
+            // Tile the image every textureScale metres over the mesh's two largest sides.
+            geometry.computeBoundingBox();
+            const size = geometry.boundingBox.getSize(new THREE.Vector3());
+            const [a, b] = [size.x, size.y, size.z].sort((p, q) => q - p);
+            texture.repeat.set(a / spec.textureScale, b / spec.textureScale);
+            texture.needsUpdate = true;
+        }
+        const material = new THREE.MeshStandardMaterial({
+            color: new THREE.Color(spec.color),
+            metalness: spec.metalness,
+            roughness: spec.roughness,
+            emissive: new THREE.Color(spec.emissive),
+            emissiveIntensity: spec.emissiveIntensity,
+            transparent: spec.opacity < 1,
+            opacity: spec.opacity,
+            map: texture ?? null,
+            flatShading: spec.flatShading,
+            wireframe: spec.wireframe,
+        });
+        const mesh = new THREE.Mesh(geometry, material);
+        mesh.castShadow = spec.castShadow;
+        mesh.receiveShadow = spec.receiveShadow;
+        mesh.name = e.id;
+        return mesh;
+    }
+    /**
+     * 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.
+     */
+    createModel(e, gltf) {
+        const spec = e.mesh;
+        const root = cloneSkinned(gltf.scene);
+        root.traverse((o) => {
+            if (o.isMesh) {
+                o.castShadow = spec.castShadow;
+                o.receiveShadow = spec.receiveShadow;
+            }
+        });
+        root.rotation.set((spec.turn.x ?? 0) * DEG, (spec.turn.y ?? 0) * DEG, (spec.turn.z ?? 0) * DEG, "YXZ");
+        root.updateMatrixWorld(true);
+        const box = new THREE.Box3().setFromObject(root, true);
+        const size = box.isEmpty() ? new THREE.Vector3(1, 1, 1) : box.getSize(new THREE.Vector3());
+        const center = box.isEmpty() ? new THREE.Vector3() : box.getCenter(new THREE.Vector3());
+        const w = spec.width || e.body?.width || 0;
+        const h = spec.height || e.body?.height || 0;
+        const d = spec.depth || e.body?.depth || e.body?.width || 0;
+        const fitted = (target, own) => (target > 0 && own > 0 ? target / own : 1);
+        const scale = new THREE.Vector3(1, 1, 1);
+        if (spec.fit === "height")
+            scale.setScalar(fitted(h, size.y));
+        else if (spec.fit === "box")
+            scale.set(fitted(w, size.x), fitted(h, size.y), fitted(d, size.z));
+        scale.multiplyScalar(spec.scale);
+        const pivot = new THREE.Group();
+        pivot.scale.copy(scale);
+        pivot.add(root);
+        if (spec.fit !== "none") {
+            // Centred on the entity, standing on the bottom of its body (or on its origin without a height).
+            root.position.sub(new THREE.Vector3(center.x, box.isEmpty() ? 0 : box.min.y, center.z));
+            pivot.position.y = h > 0 ? -h / 2 : 0;
+        }
+        pivot.position.add(new THREE.Vector3(spec.offset.x ?? 0, spec.offset.y ?? 0, spec.offset.z ?? 0));
+        const mixer = new THREE.AnimationMixer(root);
+        const actions = new Map();
+        for (const clip of gltf.animations) {
+            const action = mixer.clipAction(clip);
+            action.setEffectiveWeight(0);
+            action.play();
+            actions.set(clip.name, action);
+        }
+        this.models.set(e, { root, clips: gltf.animations, mixer, actions });
+        const group = new THREE.Group();
+        group.name = e.id;
+        group.add(pivot);
+        return group;
+    }
+    placeLight(light, e) {
+        const t = e.transform;
+        const spec = e.light;
+        const target = new THREE.Vector3(spec.target.x ?? 0, spec.target.y ?? 0, spec.target.z ?? 0);
+        if (light instanceof THREE.DirectionalLight) {
+            // Sunlight: keep its direction, but centre the shadow area on what the camera watches.
+            const direction = new THREE.Vector3(t.x, t.y, t.z).sub(target);
+            const focus = this.rig?.focus ?? target;
+            light.position.copy(focus).add(direction);
+            light.target.position.copy(focus);
+            light.target.updateMatrixWorld();
+        }
+        else {
+            light.position.set(t.x, t.y, t.z);
+            if (light instanceof THREE.SpotLight) {
+                light.target.position.copy(target);
+                light.target.updateMatrixWorld();
+            }
+        }
+    }
+    // ---------------------------------------------------------------- camera
+    /** Where the camera wants to be this step, eased by its smoothing. Deterministic per step. */
+    updateRig(world, dt) {
+        const cameraEntity = world.entities.find((e) => e.camera3d);
+        const spec = cameraEntity?.camera3d ?? DEFAULT_CAMERA;
+        const target = (spec.target ? world.entities.find((e) => e.id === spec.target) : undefined) ?? world.entities.find((e) => e.character) ?? undefined;
+        const yaw = (this.rig?.yaw ?? spec.yaw) + (spec.mode === "orbit" ? spec.orbitSpeed * dt : 0);
+        this.camera.fov = spec.fov;
+        this.camera.updateProjectionMatrix();
+        let position;
+        let look;
+        const center = target ? new THREE.Vector3(target.transform.x, target.transform.y, target.transform.z) : new THREE.Vector3();
+        if (spec.mode === "fixed") {
+            const t = cameraEntity?.transform ?? { x: 0, y: 10, z: 18 };
+            position = new THREE.Vector3(t.x, t.y, t.z);
+            look = new THREE.Vector3(spec.lookAt.x ?? 0, spec.lookAt.y ?? 0, spec.lookAt.z ?? 0);
+        }
+        else if (spec.mode === "firstPerson" && target) {
+            const eye = (target.body?.height ?? 1.8) * 0.4;
+            position = center.clone().add(new THREE.Vector3(0, eye, 0));
+            // Facing -z at a turn of 0; a turn of -90 faces +x.
+            const turn = target.transform.rotationY * DEG;
+            look = position.clone().add(new THREE.Vector3(-Math.sin(turn), 0, -Math.cos(turn)));
+        }
+        else if (target || spec.mode === "orbit") {
+            position = center.clone().add(new THREE.Vector3(Math.sin(yaw * DEG) * spec.distance, spec.height, Math.cos(yaw * DEG) * spec.distance));
+            look = center.clone().add(new THREE.Vector3(0, (target?.body?.height ?? 0) * 0.25, 0));
+        }
+        else {
+            // Nothing to follow: an overview of the origin.
+            position = new THREE.Vector3(0, 10, 18);
+            look = new THREE.Vector3();
+        }
+        if (!this.rig || dt === 0 || spec.smoothing === 0) {
+            this.rig = { position, look, focus: look.clone(), yaw };
+            return;
+        }
+        // Exponential easing toward the goal: frame-rate independent, the same every run.
+        const k = 1 - Math.exp(-dt / spec.smoothing);
+        this.rig.position.lerp(position, k);
+        this.rig.look.lerp(look, k);
+        this.rig.focus.copy(this.rig.look);
+        this.rig.yaw = yaw;
+    }
+    // ---------------------------------------------------------------- debug
+    /** Colliders as wireframes in their body's color, drawn over everything, and light positions. */
+    syncDebug(world) {
+        this.debugGroup.visible = this.debug;
+        if (!this.debug)
+            return;
+        for (const child of [...this.debugGroup.children]) {
+            child.removeFromParent();
+            child.geometry?.dispose();
+        }
+        for (const e of world.entities) {
+            const b = e.body;
+            if (b) {
+                const color = b.sensor ? DEBUG_COLORS.sensor : e.character ? DEBUG_COLORS.player : DEBUG_COLORS[b.type];
+                const shape = colliderGeometry(b);
+                const lines = new THREE.LineSegments(new THREE.EdgesGeometry(shape, 1), new THREE.LineBasicMaterial({ color, depthTest: false, transparent: true, opacity: 0.9 }));
+                shape.dispose();
+                placeObject(lines, e);
+                lines.renderOrder = 999;
+                this.debugGroup.add(lines);
+            }
+            if (e.light) {
+                const marker = new THREE.Mesh(new THREE.SphereGeometry(0.15, 8, 6), new THREE.MeshBasicMaterial({ color: 0xffee88, depthTest: false }));
+                marker.position.set(e.transform.x, e.transform.y, e.transform.z);
+                marker.renderOrder = 999;
+                this.debugGroup.add(marker);
+            }
+        }
+        const axes = new THREE.AxesHelper(1.5);
+        axes.renderOrder = 999;
+        axes.material.depthTest = false;
+        this.debugGroup.add(axes);
+    }
+}
+/** Events in the last `seconds`, as hooks see them. */
+function recentEvents(world, name, seconds) {
+    const events = world.events ?? [];
+    const since = (world.time ?? 0) - seconds;
+    const result = [];
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.time < since)
+            break;
+        const eventName = event.type === "custom" ? event.name : event.type;
+        if (name !== undefined && eventName !== name)
+            continue;
+        const { type: _type, frame: _frame, time, x, y, entity, ...details } = event;
+        result.push({ name: eventName, time, x, y, entity, data: event.type === "custom" ? event.data : details });
+    }
+    return result.reverse();
+}
+/** Clips already reported missing, so the console says it once. */
+const warnedClips = new Set();
+/**
+ * The clip an entity should play: a script's `state.animation`, then `mesh.animation`, then the
+ * clip its `animations` map gives the way it moves (in the air: jump while rising, fall after).
+ */
+function chooseClip(e) {
+    const spec = e.mesh;
+    const scripted = e.state.animation;
+    if (typeof scripted === "string" && scripted !== "")
+        return { clip: scripted, once: false };
+    if (spec.animation)
+        return { clip: spec.animation, once: false };
+    const map = spec.animations;
+    const pick = (...states) => states.map((s) => map[s]).find((c) => c) ?? "";
+    const b = e.body;
+    if (!b)
+        return { clip: pick("idle"), once: false };
+    if (!b.grounded && b.type === "dynamic") {
+        const clip = b.vy > 0 ? pick("jump", "fall", "idle") : pick("fall", "jump", "idle");
+        // A jump plays once and holds its last pose; a fall loops.
+        return { clip, once: clip === map.jump && clip !== map.fall };
+    }
+    const speed = Math.hypot(b.vx, b.vz);
+    if (speed > 0.3) {
+        const runFrom = (e.character?.speed ?? 5) * 0.6;
+        return { clip: speed < runFrom ? pick("walk", "run", "idle") : pick("run", "walk", "idle"), once: false };
+    }
+    return { clip: pick("idle"), once: false };
+}
+const DEFAULT_CAMERA = { mode: "follow", target: "", fov: 55, distance: 9, height: 4, yaw: 0, orbitSpeed: 20, lookAt: {}, smoothing: 0.12 };
+function placeObject(object, e) {
+    const t = e.transform;
+    object.position.set(t.x, t.y, t.z);
+    // Ludra's 3D rotations are applied y, then x, then z: Three's "YXZ" order.
+    object.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotation * DEG, "YXZ");
+}
+function configureSun(light, size) {
+    light.castShadow = true;
+    light.shadow.mapSize.set(2048, 2048);
+    const half = size / 2;
+    Object.assign(light.shadow.camera, { left: -half, right: half, top: half, bottom: -half, near: 0.5, far: size * 4 });
+    light.shadow.camera.updateProjectionMatrix();
+    light.shadow.bias = -0.0005;
+    light.shadow.normalBias = 0.02;
+}
+function createLight(spec) {
+    const color = new THREE.Color(spec.color);
+    switch (spec.type) {
+        case "ambient":
+            return new THREE.AmbientLight(color, spec.intensity);
+        case "hemisphere":
+            return new THREE.HemisphereLight(color, new THREE.Color(spec.groundColor), spec.intensity);
+        case "point": {
+            const light = new THREE.PointLight(color, spec.intensity, spec.distance, 2);
+            light.castShadow = spec.castShadow;
+            light.shadow.mapSize.set(512, 512);
+            light.shadow.bias = -0.002;
+            return light;
+        }
+        case "spot": {
+            const light = new THREE.SpotLight(color, spec.intensity, spec.distance, spec.angle * DEG, spec.penumbra, 2);
+            light.castShadow = spec.castShadow;
+            light.shadow.mapSize.set(1024, 1024);
+            light.shadow.bias = -0.001;
+            return light;
+        }
+        default: {
+            const light = new THREE.DirectionalLight(color, spec.intensity);
+            if (spec.castShadow)
+                configureSun(light, spec.shadowSize);
+            return light;
+        }
+    }
+}
+/** The mesh's geometry: its own shape and size, or its body's. */
+function meshGeometry(spec, body) {
+    const shape = spec.shape === "auto" ? (body ? bodyShape(body) : "box") : spec.shape;
+    if ((shape === "convex" || shape === "mesh") && body && spec.shape === "auto")
+        return colliderGeometry(body);
+    const w = spec.width || body?.width || 1;
+    const h = spec.height || body?.height || 1;
+    const d = spec.depth || (body ? body.depth || body.width : w);
+    switch (shape) {
+        case "sphere":
+            return new THREE.SphereGeometry(w / 2, 40, 24);
+        case "capsule":
+            return new THREE.CapsuleGeometry(w / 2, Math.max(0, h - w), 10, 24);
+        case "cylinder":
+            return new THREE.CylinderGeometry(w / 2, w / 2, h, 40);
+        case "cone":
+            return new THREE.ConeGeometry(w / 2, h, 40);
+        case "plane":
+            return new THREE.PlaneGeometry(w, d).rotateX(-Math.PI / 2);
+        case "torus":
+            return new THREE.TorusGeometry((w - h) / 2, h / 2, 20, 56);
+        default:
+            return new THREE.BoxGeometry(w, h, d);
+    }
+}
+function bodyShape(body) {
+    return body.shape === "box" || body.shape === "sphere" || body.shape === "capsule" || body.shape === "cylinder" || body.shape === "convex" || body.shape === "mesh" ? body.shape : "box";
+}
+/** The exact collider shape, for the debug view and convex meshes. */
+function colliderGeometry(b) {
+    const d = b.depth || b.width;
+    switch (b.shape) {
+        case "sphere":
+            return new THREE.SphereGeometry(b.width / 2, 16, 10);
+        case "capsule":
+            return new THREE.CapsuleGeometry(b.width / 2, Math.max(0, b.height - b.width), 4, 12);
+        case "cylinder":
+            return new THREE.CylinderGeometry(b.width / 2, b.width / 2, b.height, 16);
+        case "convex":
+            if (b.points.length >= 4)
+                return new ConvexGeometry(b.points.map(([x, y, z]) => new THREE.Vector3(x, y, z ?? 0)));
+            return new THREE.BoxGeometry(b.width, b.height, d);
+        case "mesh": {
+            if (b.points.length < 3 || b.triangles.length === 0)
+                return new THREE.BoxGeometry(b.width, b.height, d);
+            // Exactly the collider's triangles, so procedural terrain is drawn as it collides.
+            const geometry = new THREE.BufferGeometry();
+            geometry.setAttribute("position", new THREE.Float32BufferAttribute(b.points.flatMap(([x, y, z]) => [x, y, z ?? 0]), 3));
+            geometry.setIndex(b.triangles.flat());
+            geometry.computeVertexNormals();
+            return geometry;
+        }
+        default:
+            return new THREE.BoxGeometry(b.width, b.height, d);
+    }
+}