pelican-engine 0.0.0-stage → 0.3.1

package/lib/renderer/gameplay.js

@@ -0,0 +1,464 @@
+import * as THREE from "three/webgpu";
+import { createUIRenderer } from "./ui.js";
+import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+import { createGameServices } from "../runtime/game-services.js";
+import { createPhysicsFactory } from "../physics/index.js";
+import { createNavigationPlugin } from "../navigation/index.js";
+import { createModelLibrary } from "./models.js";
+import { resolveEntityDefinition } from "../runtime/prefabs.js";
+/** Private presentation ownership. Games receive only SDK services, never browser/library objects. */
+export async function prepareGameplay(ir, baseURL, renderer, materials = new Map()) {
+    const assetURL = (id) => {
+        const asset = ir.assets.find((entry) => entry.id === id);
+        if (!asset)
+            throw new Error("TC_ASSET_MISSING: " + id);
+        return new URL(asset.path, baseURL).href;
+    };
+    const models = createModelLibrary(ir.assets
+        .filter((a) => a.type === "model")
+        .map((a) => ({ id: a.id, url: assetURL(a.id) })), { material: id => materials.get(id) });
+    const textures = new Map();
+    let physics;
+    let environmentTarget;
+    const diagnostics = [];
+    let audio;
+    if ((ir.sounds?.length ?? 0) > 0) {
+        try {
+            if (typeof AudioContext !== "undefined")
+                audio = new AudioContext();
+            else
+                diagnostics.push("TC_AUDIO_UNAVAILABLE: AudioContext is unavailable.");
+        }
+        catch (error) {
+            diagnostics.push("TC_AUDIO_UNAVAILABLE: " + String(error));
+        }
+    }
+    const buffers = new Map();
+    let masterGain;
+    const busGains = new Map();
+    const busFadeKeys = new Map();
+    const voices = new Map();
+    let ui;
+    let uiInput;
+    let uiEmit;
+    let services;
+    let closed = false;
+    let audioRevision = -1;
+    const stopVoice = (id) => {
+        const voice = voices.get(id);
+        if (!voice)
+            return;
+        voice.source.onended = null;
+        try {
+            voice.source.stop();
+        }
+        catch {
+            /* A completed buffer source is already stopped. */
+        }
+        voice.source.disconnect();
+        voice.gain.disconnect();
+        voice.panner?.disconnect();
+        voices.delete(id);
+    };
+    const dispose = async () => {
+        if (closed)
+            return;
+        closed = true;
+        ui?.dispose();
+        for (const id of [...voices.keys()])
+            stopVoice(id);
+        for (const gain of busGains.values())
+            gain.disconnect();
+        busGains.clear();
+        busFadeKeys.clear();
+        masterGain?.disconnect();
+        environmentTarget?.dispose();
+        for (const texture of textures.values())
+            texture.dispose();
+        textures.clear();
+        buffers.clear();
+        await Promise.all([models.dispose(), audio?.close()]);
+    };
+    try {
+        await models.prepare();
+        if (ir.scene.environment.lighting === "studio") {
+            const room = new RoomEnvironment(), pmrem = new THREE.PMREMGenerator(renderer);
+            try {
+                environmentTarget = pmrem.fromScene(room, 0.04);
+            }
+            finally {
+                pmrem.dispose();
+                room.dispose();
+            }
+        }
+        for (const asset of ir.assets.filter((a) => a.type === "texture")) {
+            const texture = await new THREE.TextureLoader().loadAsync(assetURL(asset.id));
+            texture.colorSpace = asset.colorSpace === "linear" ? THREE.LinearSRGBColorSpace : THREE.SRGBColorSpace;
+            textures.set(asset.id, texture);
+        }
+        if (audio)
+            for (const sound of ir.sounds ?? []) {
+                if (buffers.has(sound.asset))
+                    continue;
+                const response = await fetch(assetURL(sound.asset));
+                if (!response.ok)
+                    throw new Error("TC_AUDIO_LOAD: " + sound.asset + " HTTP " + response.status);
+                const buffer = await audio.decodeAudioData(await response.arrayBuffer());
+                buffers.set(sound.asset, buffer);
+            }
+        services = createGameServices(ir, models.animation);
+        const modelBindings = (records) => records.filter((record) => resolveEntityDefinition(ir, record)?.model);
+        const modelDefinitions = (records) => modelBindings(records).map((record) => ({
+            entity: record.id,
+            definition: resolveEntityDefinition(ir, record).model,
+        }));
+        const validateModels = (value) => {
+            const saved = structuredClone(value);
+            if (!saved ||
+                saved.version !== 1 ||
+                !Array.isArray(saved.bindings) ||
+                saved.bindings.some((record) => !record ||
+                    typeof record.id !== "string" ||
+                    (record.prefab !== undefined && typeof record.prefab !== "string")) ||
+                new Set(saved.bindings.map((record) => record.id)).size !==
+                    saved.bindings.length)
+                throw new Error("TC_MODEL_BINDINGS_SNAPSHOT: Invalid model content identity.");
+            if (modelBindings(saved.bindings).length !== saved.bindings.length)
+                throw new Error("TC_MODEL_BINDINGS_SNAPSHOT: Unknown model content.");
+            const definitions = modelDefinitions(saved.bindings);
+            const animation = models.validateSnapshot(saved.animation, definitions);
+            if (JSON.stringify(animation.animations.map((item) => item.entity).sort()) !== JSON.stringify(saved.bindings.map((record) => record.id).sort()))
+                throw new Error("TC_MODEL_BINDINGS_SNAPSHOT: Active model bindings differ from animation state.");
+            return { animation, definitions };
+        };
+        const plugins = [
+            services.factory,
+            createNavigationPlugin,
+            (context) => ({
+                id: "$engine.models",
+                version: "2",
+                snapshot: () => {
+                    const bindings = modelBindings(context.world.records()).map(({ id, prefab }) => ({
+                        id,
+                        ...(prefab === undefined ? {} : { prefab }),
+                    }));
+                    models.reconcileBindings(modelDefinitions(bindings));
+                    return { version: 1, bindings, animation: models.snapshot() };
+                },
+                validateSnapshot: (value) => {
+                    validateModels(value);
+                },
+                validateWorld: (value, world) => {
+                    const bindings = value.bindings;
+                    const expected = modelBindings(world.entities)
+                        .map(({ id, prefab }) => JSON.stringify({
+                        id,
+                        ...(prefab === undefined ? {} : { prefab }),
+                    }))
+                        .sort();
+                    if (JSON.stringify(expected) !==
+                        JSON.stringify(bindings
+                            .map(({ id, prefab }) => JSON.stringify({
+                            id,
+                            ...(prefab === undefined ? {} : { prefab }),
+                        }))
+                            .sort()))
+                        throw new Error("TC_MODEL_BINDINGS_WORLD: Model identities must match the restored World.");
+                },
+                restore: (value) => {
+                    const { animation, definitions } = validateModels(value);
+                    models.restore(animation, definitions);
+                },
+                dispose() {
+                    /* Content owns async GPU/asset disposal. */
+                },
+                inspect: () => models.inspect(),
+                systems: [
+                    {
+                        id: "$engine.models",
+                        phase: "presentation",
+                        run: (dt) => {
+                            const records = context.world.records();
+                            models.reconcileBindings(modelDefinitions(records));
+                            models.tick(dt);
+                        },
+                    },
+                ],
+            }),
+        ];
+        if ([...ir.scene.entities, ...ir.prefabs].some((entity) => entity.rigidBody || entity.character)) {
+            const factory = await createPhysicsFactory();
+            plugins.push((context) => {
+                const plugin = factory(context);
+                physics = plugin.services?.physics;
+                return plugin;
+            });
+        }
+        ui = createUIRenderer(ir.ui ?? [], {
+            input: (key, pressed) => {
+                uiInput?.(key, pressed);
+                void audio
+                    ?.resume()
+                    .catch((error) => diagnostics.push("TC_AUDIO_RESUME: " + String(error)));
+            },
+            emit: (type, payload) => {
+                if (type === "ui.focus" &&
+                    payload &&
+                    typeof payload === "object" &&
+                    ir.ui?.some((element) => element.id === payload.id &&
+                        element.kind === "input"))
+                    for (const key of new Set(Object.values(ir.input ?? {}).flat()))
+                        uiInput?.(key, false);
+                uiEmit?.(type, payload);
+            },
+        });
+        return {
+            models,
+            async rebuildGpuResources(next) {
+                if (closed)
+                    throw new Error("TC_CONTENT_DISPOSED");
+                environmentTarget?.dispose();
+                environmentTarget = undefined;
+                if (ir.scene.environment.lighting === "studio") {
+                    const room = new RoomEnvironment(), generator = new THREE.PMREMGenerator(next);
+                    try {
+                        environmentTarget = generator.fromScene(room, 0.04);
+                    }
+                    finally {
+                        generator.dispose();
+                        room.dispose();
+                    }
+                }
+                return environmentTarget?.texture;
+            },
+            environment: environmentTarget?.texture,
+            textures,
+            plugins,
+            services,
+            dispose,
+            mount(input, emit) {
+                uiInput = input;
+                uiEmit = emit;
+                ui.mount();
+            },
+            consumesKeyboard(event) {
+                return ui?.consumesKeyboard(event) ?? false;
+            },
+            unlockAudio() {
+                void audio
+                    ?.resume()
+                    .catch((error) => diagnostics.push("TC_AUDIO_RESUME: " + String(error)));
+            },
+            present(camera, objects, dt, tick) {
+                const state = services.inspect();
+                if (state.camera) {
+                    const follow = state.camera, object = objects.get(follow.entity);
+                    if (object) {
+                        const at = object.getWorldPosition(new THREE.Vector3());
+                        const target = at
+                            .clone()
+                            .add(new THREE.Vector3(0, follow.lookHeight, 0));
+                        const position = at.add(new THREE.Vector3(Math.sin(follow.yaw) * follow.distance, follow.height, Math.cos(follow.yaw) * follow.distance));
+                        if (physics) {
+                            const direction = position.clone().sub(target), distance = direction.length();
+                            const hit = physics.raycast(target.toArray(), direction.toArray(), distance, { exclude: [follow.entity], includeTriggers: false });
+                            if (hit && hit.distance < distance)
+                                position
+                                    .copy(target)
+                                    .addScaledVector(direction.normalize(), Math.max(0.2, hit.distance - 0.25));
+                        }
+                        camera.position.lerp(position, dt > 0 && follow.smoothing > 0
+                            ? 1 - Math.pow(1 - follow.smoothing, dt * 60)
+                            : 1);
+                        if (physics) {
+                            const actual = camera.position.clone().sub(target), length = actual.length();
+                            if (length > 0) {
+                                const hit = physics.raycast(target.toArray(), actual.toArray(), length, { exclude: [follow.entity] });
+                                if (hit && hit.distance < length)
+                                    camera.position
+                                        .copy(target)
+                                        .addScaledVector(actual.normalize(), Math.max(0.2, hit.distance - 0.25));
+                            }
+                        }
+                        camera.lookAt(target);
+                        camera.updateMatrixWorld();
+                    }
+                }
+                const size = renderer.getSize(new THREE.Vector2());
+                const positions = new Map();
+                for (const definition of state.ui ?? []) {
+                    if (!definition.world)
+                        continue;
+                    const object = objects.get(definition.world.entity);
+                    if (!object) {
+                        positions.set(definition.id, {
+                            x: 0,
+                            y: 0,
+                            visible: false,
+                            occluded: false,
+                        });
+                        continue;
+                    }
+                    object.updateWorldMatrix(true, false);
+                    const point = object
+                        .getWorldPosition(new THREE.Vector3())
+                        .add(new THREE.Vector3().fromArray(definition.world.offset));
+                    const delta = point.clone().sub(camera.position), distance = delta.length(), projected = point.clone().project(camera), forward = new THREE.Vector3();
+                    camera.getWorldDirection(forward);
+                    let occluded = false;
+                    if (definition.world.occlude && distance > 0) {
+                        const raycaster = new THREE.Raycaster(camera.position, delta.clone().normalize(), 0.01, distance - 0.01);
+                        occluded = raycaster
+                            .intersectObjects([...objects.values()], true)
+                            .some((hit) => {
+                            for (let parent = hit.object; parent; parent = parent.parent)
+                                if (parent === object)
+                                    return false;
+                            return hit.object.visible;
+                        });
+                    }
+                    positions.set(definition.id, {
+                        x: ((projected.x + 1) * size.x) / 2,
+                        y: ((1 - projected.y) * size.y) / 2,
+                        visible: forward.dot(delta) > 0 &&
+                            projected.z >= -1 &&
+                            projected.z <= 1 &&
+                            Math.abs(projected.x) <= 1 &&
+                            Math.abs(projected.y) <= 1,
+                        occluded,
+                    });
+                }
+                ui?.present(state.ui ?? [], positions);
+                const clock = services.audioClock();
+                if (clock.revision !== audioRevision) {
+                    for (const id of [...voices.keys()])
+                        stopVoice(id);
+                    busFadeKeys.clear();
+                    for (const gain of busGains.values())
+                        gain.gain.cancelScheduledValues(audio?.currentTime ?? 0);
+                    audioRevision = clock.revision;
+                }
+                const wanted = new Set(state.audio.voices.filter((voice) => voice.pausedAt == null).map((voice) => voice.id));
+                for (const id of [...voices.keys()])
+                    if (!wanted.has(id))
+                        stopVoice(id);
+                if (audio) {
+                    if (!masterGain) {
+                        const master = audio.createGain();
+                        const created = new Map();
+                        try {
+                            master.connect(audio.destination);
+                            for (const bus of ir.audioBuses ?? []) {
+                                const gain = audio.createGain();
+                                created.set(bus.id, gain);
+                                gain.connect(master);
+                            }
+                        }
+                        catch (error) {
+                            for (const gain of created.values())
+                                gain.disconnect();
+                            master.disconnect();
+                            throw error;
+                        }
+                        masterGain = master;
+                        for (const [id, gain] of created)
+                            busGains.set(id, gain);
+                    }
+                    masterGain.gain.value = state.audio.volume;
+                    for (const bus of state.audio.busVolumes ?? []) {
+                        const gain = busGains.get(bus.id).gain;
+                        const fade = bus.fade;
+                        const key = fade && `${clock.revision}:${fade.startedAt}:${fade.from}:${fade.target}:${fade.duration}`;
+                        if (key && clock.fixedDt !== null) {
+                            if (busFadeKeys.get(bus.id) !== key) {
+                                gain.cancelScheduledValues(audio.currentTime);
+                                gain.setValueAtTime(bus.volume, audio.currentTime);
+                                gain.linearRampToValueAtTime(fade.target, audio.currentTime + Math.max(0, fade.duration - (clock.tick - fade.startedAt) * clock.fixedDt));
+                                busFadeKeys.set(bus.id, key);
+                            }
+                        }
+                        else {
+                            if (busFadeKeys.has(bus.id))
+                                gain.cancelScheduledValues(audio.currentTime);
+                            busFadeKeys.delete(bus.id);
+                            gain.value = bus.volume;
+                        }
+                    }
+                    audio.listener.positionX.value = camera.position.x;
+                    audio.listener.positionY.value = camera.position.y;
+                    audio.listener.positionZ.value = camera.position.z;
+                    const forward = new THREE.Vector3();
+                    camera.getWorldDirection(forward);
+                    audio.listener.forwardX.value = forward.x;
+                    audio.listener.forwardY.value = forward.y;
+                    audio.listener.forwardZ.value = forward.z;
+                    for (const voice of state.audio.voices) {
+                        if (voice.pausedAt != null)
+                            continue;
+                        let active = voices.get(voice.id);
+                        if (active && active.version !== clock.versions[voice.id]) {
+                            stopVoice(voice.id);
+                            active = undefined;
+                        }
+                        if (!active && audio.state === "running") {
+                            const definition = ir.sounds.find((sound) => sound.id === voice.sound);
+                            const buffer = buffers.get(definition.asset);
+                            const age = Math.max(0, (clock.tick - voice.startedAt - (voice.pausedTicks ?? 0)) * (clock.fixedDt ?? 0));
+                            if (buffer.duration <= 0 || (!voice.loop && age >= buffer.duration))
+                                continue;
+                            const source = audio.createBufferSource(), gain = audio.createGain();
+                            source.buffer = buffer;
+                            source.loop = voice.loop;
+                            let panner;
+                            if (voice.entity) {
+                                panner = audio.createPanner();
+                                panner.panningModel = "HRTF";
+                                panner.distanceModel = "inverse";
+                                source.connect(panner);
+                                panner.connect(gain);
+                            }
+                            else
+                                source.connect(gain);
+                            gain.connect(voice.bus === undefined ? masterGain : busGains.get(voice.bus));
+                            active = { source, gain, panner, version: clock.versions[voice.id] };
+                            voices.set(voice.id, active);
+                            source.onended = () => {
+                                source.disconnect();
+                                gain.disconnect();
+                                panner?.disconnect();
+                            };
+                            source.start(0, age % buffer.duration);
+                        }
+                        if (active) {
+                            active.gain.gain.value = voice.volume;
+                            const position = voice.entity
+                                ? objects
+                                    .get(voice.entity)
+                                    ?.getWorldPosition(new THREE.Vector3())
+                                : undefined;
+                            if (active.panner && position) {
+                                active.panner.positionX.value = position.x;
+                                active.panner.positionY.value = position.y;
+                                active.panner.positionZ.value = position.z;
+                            }
+                        }
+                    }
+                }
+            },
+            inspect() {
+                return {
+                    ...services.inspect(),
+                    models: models.inspect(),
+                    audioDevice: audio?.state ?? ((ir.sounds?.length ?? 0) > 0 ? "unavailable" : "unused"),
+                    decodedSounds: buffers.size,
+                    uiPlatform: ui?.inspect(),
+                    diagnostics: [...diagnostics],
+                };
+            },
+        };
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+}

package/lib/renderer/geometry.js

@@ -0,0 +1,103 @@
+import * as THREE from "three/webgpu";
+/** Private render adapter. Never exported by the game SDK. */
+export function extractTriangles(scene) {
+    scene.updateMatrixWorld(true);
+    const triangles = [];
+    scene.traverseVisible((object) => {
+        if (!(object instanceof THREE.Mesh) ||
+            !object.visible ||
+            object.userData.noTrace)
+            return;
+        if (object instanceof THREE.SkinnedMesh)
+            object.skeleton.update();
+        const material = (Array.isArray(object.material) ? object.material[0] : object.material);
+        const geometry = object.geometry;
+        const count = geometry.index?.count ?? geometry.getAttribute("position").count;
+        const points = [
+            new THREE.Vector3(),
+            new THREE.Vector3(),
+            new THREE.Vector3(),
+        ];
+        for (let i = 0; i < count; i += 3) {
+            for (let k = 0; k < 3; k++)
+                object
+                    .getVertexPosition(geometry.index?.getX(i + k) ?? i + k, points[k])
+                    .applyMatrix4(object.matrixWorld);
+            const color = material.color ?? new THREE.Color(0.6, 0.6, 0.6);
+            triangles.push({
+                a: points[0].toArray(),
+                b: points[1].toArray(),
+                c: points[2].toArray(),
+                color: color.toArray(),
+                emission: material.emissiveIntensity && material.emissive?.getHex()
+                    ? material.emissiveIntensity
+                    : 0,
+                roughness: material.roughness ?? 0.8,
+            });
+        }
+    });
+    return triangles;
+}
+/** Median-split CPU BVH prototype. Each upload is explicitly measured, not marketed as GPU refit. */
+export function buildBVH(input) {
+    const ordered = [];
+    const nodes = [];
+    const boundsOf = (triangles) => {
+        const low = [Infinity, Infinity, Infinity], high = [-Infinity, -Infinity, -Infinity];
+        for (const triangle of triangles)
+            for (const p of [triangle.a, triangle.b, triangle.c])
+                for (let i = 0; i < 3; i++) {
+                    low[i] = Math.min(low[i], p[i]);
+                    high[i] = Math.max(high[i], p[i]);
+                }
+        return { low, high };
+    };
+    const visit = (triangles) => {
+        const index = nodes.length;
+        nodes.push([]);
+        const { low, high } = boundsOf(triangles);
+        if (triangles.length <= 4) {
+            const offset = ordered.length;
+            ordered.push(...triangles);
+            nodes[index] = [...low, offset, ...high, triangles.length];
+        }
+        else {
+            const axis = high
+                .map((v, i) => v - low[i])
+                .indexOf(Math.max(...high.map((v, i) => v - low[i])));
+            triangles.sort((x, y) => x.a[axis] +
+                x.b[axis] +
+                x.c[axis] -
+                (y.a[axis] + y.b[axis] + y.c[axis]));
+            const middle = triangles.length >> 1;
+            const left = visit(triangles.slice(0, middle)), right = visit(triangles.slice(middle));
+            nodes[index] = [...low, left, ...high, -right];
+        }
+        return index;
+    };
+    if (!input.length)
+        throw new Error("TC_RENDER_EMPTY_GEOMETRY");
+    visit([...input]);
+    const packed = new Float32Array(ordered.length * 20);
+    ordered.forEach((t, i) => packed.set([
+        ...t.a,
+        t.emission,
+        ...t.b,
+        t.roughness,
+        ...t.c,
+        0,
+        ...t.color,
+        0,
+        0,
+        0,
+        0,
+        0,
+    ], i * 20));
+    return {
+        triangles: packed,
+        nodes: new Float32Array(nodes.flat()),
+        triangleCount: ordered.length,
+        nodeCount: nodes.length,
+        bounds: [...nodes[0].slice(0, 3), ...nodes[0].slice(4, 7)],
+    };
+}