@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/save/serializer.js

@@ -0,0 +1,139 @@
+import { getColumnValue } from "../ecs/archetype.js";
+import { getComponentName } from "../ecs/component.js";
+/** Maximum number of entities allowed in a deserialized scene. */
+const MAX_ENTITY_COUNT = 1_000_000;
+/** Maximum number of components per entity in a deserialized scene. */
+const MAX_COMPONENTS_PER_ENTITY = 256;
+export class Serializer {
+    serialize(world, sceneName) {
+        const entities = [];
+        const binaryBlobs = {};
+        for (let i = 1; i < world.entities.length; i++) {
+            const meta = world.entities[i];
+            if (!meta.alive)
+                continue;
+            const arch = world.archetypeById.get(meta.archetypeId);
+            if (!arch)
+                continue;
+            const entity = { index: i, generation: meta.generation };
+            const components = [];
+            for (const [cid, col] of arch.columns.entries()) {
+                const row = arch.entities.findIndex((e) => e.index === entity.index && e.generation === entity.generation);
+                if (row >= 0) {
+                    const data = getColumnValue(col, row);
+                    if (data instanceof ArrayBuffer) {
+                        const blobKey = `blob_${i}_${cid}`;
+                        binaryBlobs[blobKey] = data;
+                        components.push({ id: cid, data: { __blobRef: blobKey } });
+                    }
+                    else if (data instanceof Float32Array || data instanceof Float64Array ||
+                        data instanceof Int32Array || data instanceof Uint32Array ||
+                        data instanceof Uint8Array || data instanceof Int8Array ||
+                        data instanceof Int16Array || data instanceof Uint16Array) {
+                        const blobKey = `blob_${i}_${cid}`;
+                        const buf = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+                        binaryBlobs[blobKey] = buf instanceof ArrayBuffer ? buf : new ArrayBuffer(buf.byteLength);
+                        new Uint8Array(binaryBlobs[blobKey]).set(new Uint8Array(buf));
+                        components.push({ id: cid, data: { __blobRef: blobKey } });
+                    }
+                    else {
+                        components.push({ id: cid, data });
+                    }
+                }
+            }
+            entities.push({ index: i, generation: meta.generation, components });
+        }
+        return {
+            schemaVersion: 1,
+            scene: { name: sceneName, entities },
+            binaryBlobs: Object.keys(binaryBlobs).length > 0 ? binaryBlobs : undefined,
+        };
+    }
+    deserialize(data, world, schemaRegistry) {
+        const migrated = schemaRegistry.migrate(data, data.schemaVersion);
+        const blobs = migrated.binaryBlobs ?? {};
+        // Bounds validation — prevent OOM / integer overflow from malformed saves.
+        const entityCount = migrated.scene.entities.length;
+        if (entityCount > MAX_ENTITY_COUNT) {
+            throw new RangeError(`deserialize: entity count ${entityCount} exceeds maximum ${MAX_ENTITY_COUNT}`);
+        }
+        for (let i = 0; i < world.entities.length; i++) {
+            const meta = world.entities[i];
+            if (meta.alive) {
+                world.despawn({ index: i, generation: meta.generation });
+            }
+        }
+        world.flushCommands();
+        for (let i = 0; i < migrated.scene.entities.length; i++) {
+            const entry = migrated.scene.entities[i];
+            // Validate component count per entity.
+            if (entry.components.length > MAX_COMPONENTS_PER_ENTITY) {
+                throw new RangeError(`deserialize: entity ${i} has ${entry.components.length} components, exceeds maximum ${MAX_COMPONENTS_PER_ENTITY}`);
+            }
+            const components = new Map();
+            for (let j = 0; j < entry.components.length; j++) {
+                const comp = entry.components[j];
+                // Validate component ID exists in the component registry.
+                const compName = getComponentName(comp.id);
+                if (compName.startsWith("Unknown(")) {
+                    throw new Error(`deserialize: entity ${i} references unregistered component ID ${comp.id}`);
+                }
+                if (comp.data && typeof comp.data === "object" && "__blobRef" in comp.data) {
+                    const ref = comp.data.__blobRef;
+                    components.set(comp.id, blobs[ref] ?? new ArrayBuffer(0));
+                }
+                else {
+                    components.set(comp.id, comp.data);
+                }
+            }
+            world.spawn(components);
+        }
+    }
+    toJSON(data) {
+        return JSON.stringify(data, (_key, value) => {
+            if (value instanceof ArrayBuffer) {
+                return { __type: "ArrayBuffer", __data: arrayBufferToBase64(value) };
+            }
+            if (typeof value === "object" && value !== null && value.buffer instanceof ArrayBuffer && !Array.isArray(value)) {
+                return { __type: "TypedArray", __data: arrayBufferToBase64(value.buffer) };
+            }
+            return value;
+        }, 2);
+    }
+    fromJSON(json) {
+        return JSON.parse(json, (_key, value) => {
+            if (value && typeof value === "object" && value.__type === "ArrayBuffer" && typeof value.__data === "string") {
+                return base64ToArrayBuffer(value.__data);
+            }
+            if (value && typeof value === "object" && value.__type === "TypedArray" && typeof value.__data === "string") {
+                return base64ToArrayBuffer(value.__data);
+            }
+            return value;
+        });
+    }
+    toBinary(data) {
+        const json = this.toJSON(data);
+        const encoder = new TextEncoder();
+        return encoder.encode(json).buffer;
+    }
+    fromBinary(buffer) {
+        const decoder = new TextDecoder();
+        return this.fromJSON(decoder.decode(buffer));
+    }
+}
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function base64ToArrayBuffer(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}

package/dist/core/src/scene/builder.js

@@ -0,0 +1,31 @@
+export function c(def, overrides) {
+    return { def, overrides };
+}
+export function spawn(world, ...specs) {
+    const components = new Map();
+    specs.forEach((spec) => {
+        const data = spec.def.create(spec.overrides);
+        components.set(spec.def.id, data);
+    });
+    return world.spawn(components);
+}
+export function spawnChild(world, hierarchy, parent, ...specs) {
+    const entity = spawn(world, ...specs);
+    hierarchy.setParent(entity, parent);
+    return entity;
+}
+export function batch(world, count, factory) {
+    const entities = [];
+    for (let i = 0; i < count; i++) {
+        const specs = factory(i);
+        entities.push(spawn(world, ...specs));
+    }
+    return entities;
+}
+export function builderToPrefab(name, specs, tags) {
+    const components = specs.map((spec) => ({
+        componentId: spec.def.id,
+        data: { ...spec.def.defaults, ...spec.overrides },
+    }));
+    return { name, components, tags };
+}

package/dist/core/src/scene/camera.js

@@ -0,0 +1,118 @@
+import { mat4, vec3 } from "wgpu-matrix";
+export class Camera {
+    position = [0, 5, 10];
+    target = [0, 0, 0];
+    up = [0, 1, 0];
+    fov = 60;
+    aspect = 1;
+    near = 0.1;
+    far = 1000;
+    yaw = 0;
+    pitch = 0.3;
+    distance = 10;
+    viewMatrix = mat4.identity();
+    projMatrix = mat4.identity();
+    viewProjMatrix = mat4.identity();
+    viewDirty = true;
+    projDirty = true;
+    setPosition(x, y, z) {
+        this.position = [x, y, z];
+        this.viewDirty = true;
+    }
+    setTarget(x, y, z) {
+        this.target = [x, y, z];
+        this.viewDirty = true;
+    }
+    setAspect(width, height) {
+        this.aspect = width / height;
+        this.projDirty = true;
+    }
+    setFov(degrees) {
+        this.fov = degrees;
+        this.projDirty = true;
+    }
+    orbit(deltaYaw, deltaPitch) {
+        this.yaw += deltaYaw;
+        this.pitch += deltaPitch;
+        const maxPitch = Math.PI / 2 - 0.01;
+        if (this.pitch > maxPitch)
+            this.pitch = maxPitch;
+        if (this.pitch < -maxPitch)
+            this.pitch = -maxPitch;
+        this.updatePosition();
+    }
+    zoom(delta) {
+        this.distance -= delta;
+        if (this.distance < 0.1)
+            this.distance = 0.1;
+        if (this.distance > 500)
+            this.distance = 500;
+        this.updatePosition();
+    }
+    pan(deltaX, deltaY) {
+        const forward = vec3.normalize(vec3.subtract(this.target, this.position));
+        const right = vec3.normalize(vec3.cross(forward, this.up));
+        const panAmount = this.distance * 0.001;
+        this.target = vec3.subtract(this.target, vec3.scale(right, deltaX * panAmount));
+        this.target = vec3.add(this.target, vec3.scale(this.up, deltaY * panAmount));
+        this.updatePosition();
+    }
+    updatePosition() {
+        const cosPitch = Math.cos(this.pitch);
+        const sinPitch = Math.sin(this.pitch);
+        const cosYaw = Math.cos(this.yaw);
+        const sinYaw = Math.sin(this.yaw);
+        this.position = [
+            this.target[0] + this.distance * cosPitch * sinYaw,
+            this.target[1] + this.distance * sinPitch,
+            this.target[2] + this.distance * cosPitch * cosYaw,
+        ];
+        this.viewDirty = true;
+    }
+    isViewDirty() {
+        return this.viewDirty;
+    }
+    isProjDirty() {
+        return this.projDirty;
+    }
+    getViewMatrix() {
+        if (this.viewDirty || this.projDirty)
+            this.updateMatrices();
+        return this.viewMatrix;
+    }
+    getProjectionMatrix() {
+        if (this.viewDirty || this.projDirty)
+            this.updateMatrices();
+        return this.projMatrix;
+    }
+    getViewProjectionMatrix() {
+        if (this.viewDirty || this.projDirty)
+            this.updateMatrices();
+        return this.viewProjMatrix;
+    }
+    updateMatrices() {
+        if (this.viewDirty) {
+            this.viewMatrix = mat4.lookAt(this.position, this.target, this.up);
+            this.viewDirty = false;
+        }
+        if (this.projDirty) {
+            this.projMatrix = mat4.perspective(this.fov * (Math.PI / 180), this.aspect, this.near, this.far);
+            this.projDirty = false;
+        }
+        this.viewProjMatrix = mat4.multiply(this.projMatrix, this.viewMatrix);
+    }
+    getData() {
+        return {
+            position: [this.position[0], this.position[1], this.position[2]],
+            target: [this.target[0], this.target[1], this.target[2]],
+            up: [this.up[0], this.up[1], this.up[2]],
+            fov: this.fov,
+            aspect: this.aspect,
+            near: this.near,
+            far: this.far,
+            yaw: this.yaw,
+            pitch: this.pitch,
+            distance: this.distance,
+        };
+    }
+}

package/dist/core/src/scene/checkpoint.js

@@ -0,0 +1,84 @@
+import { findEntityRow, getColumnValue } from "../ecs/archetype.js";
+export class CheckpointManager {
+    checkpoints = new Map();
+    history = [];
+    maxHistory = 50;
+    create(name, world) {
+        const entities = [];
+        for (let i = 1; i < world.entities.length; i++) {
+            const meta = world.entities[i];
+            if (!meta.alive)
+                continue;
+            const arch = world.archetypeById.get(meta.archetypeId);
+            if (!arch)
+                continue;
+            const entity = { index: i, generation: meta.generation };
+            const components = [];
+            for (const [cid, col] of arch.columns.entries()) {
+                const row = findEntityRow(arch, entity);
+                if (row >= 0) {
+                    components.push({ id: cid, data: getColumnValue(col, row) });
+                }
+            }
+            entities.push({ entity, components });
+        }
+        const cp = {
+            name,
+            timestamp: Date.now(),
+            entities,
+        };
+        this.checkpoints.set(name, cp);
+        this.history.push(name);
+        if (this.history.length > this.maxHistory) {
+            const old = this.history.shift();
+            this.checkpoints.delete(old);
+        }
+        return cp;
+    }
+    restore(name, world) {
+        const cp = this.checkpoints.get(name);
+        if (!cp)
+            return false;
+        // Despawn all existing alive entities (including root) to prevent duplicates
+        for (let i = 0; i < world.entities.length; i++) {
+            const meta = world.entities[i];
+            if (meta.alive) {
+                const entity = { index: i, generation: meta.generation };
+                world.despawn(entity);
+            }
+        }
+        world.flushCommands();
+        // Spawn entities from checkpoint
+        for (let i = 0; i < cp.entities.length; i++) {
+            const entry = cp.entities[i];
+            const components = new Map();
+            for (let j = 0; j < entry.components.length; j++) {
+                components.set(entry.components[j].id, entry.components[j].data);
+            }
+            world.spawn(components);
+        }
+        return true;
+    }
+    list() {
+        return [...this.checkpoints.values()];
+    }
+    diff(a, b) {
+        const cpA = this.checkpoints.get(a);
+        const cpB = this.checkpoints.get(b);
+        if (!cpA || !cpB)
+            return null;
+        const entitiesA = new Set(cpA.entities.map((e) => `${e.entity.index}.${e.entity.generation}`));
+        const entitiesB = new Set(cpB.entities.map((e) => `${e.entity.index}.${e.entity.generation}`));
+        const added = [];
+        const removed = [];
+        for (const id of entitiesB.values()) {
+            if (!entitiesA.has(id))
+                added.push(id);
+        }
+        for (const id of entitiesA.values()) {
+            if (!entitiesB.has(id))
+                removed.push(id);
+        }
+        return { added, removed, changed: [] };
+    }
+}

package/dist/core/src/scene/game-loop.js

@@ -0,0 +1,155 @@
+/**
+ * Unified game loop that coordinates fixed-timestep simulation with rendering.
+ *
+ * Uses an accumulator pattern:
+ * 1. Each frame, measure wall-clock delta time.
+ * 2. Accumulate delta into the accumulator.
+ * 3. While the accumulator >= fixedDt, run a simulation step.
+ * 4. Cap steps at maxStepsPerFrame to prevent the spiral of death.
+ * 5. Compute interpolation alpha = accumulator / fixedDt.
+ * 6. Render once per frame, passing alpha for interpolation.
+ *
+ * The render callback (if provided) is invoked once per frame after
+ * simulation steps, receiving the interpolation alpha.
+ */
+export class GameLoop {
+    gameWorld;
+    renderCb;
+    fixedDt;
+    maxSteps;
+    running = false;
+    rafId = 0;
+    accumulator = 0;
+    alpha = 0;
+    lastTime = 0;
+    frameCount = 0;
+    fpsTimer = 0;
+    fps = 0;
+    lastSimSteps = 0;
+    constructor(gameWorld, config) {
+        this.gameWorld = gameWorld;
+        this.renderCb = config.onRender ?? null;
+        this.fixedDt = config.fixedDt;
+        this.maxSteps = config.maxStepsPerFrame;
+    }
+    /** Start the unified game loop. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.accumulator = 0;
+        this.lastTime = performance.now();
+        // Only start the RAF loop if requestAnimationFrame is available
+        // (not in test environments like bun test).
+        if (typeof requestAnimationFrame !== "undefined") {
+            this.loop();
+        }
+    }
+    /** Stop the unified game loop. */
+    stop() {
+        this.running = false;
+        if (this.rafId) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = 0;
+        }
+    }
+    /** Interpolation alpha for the current frame (0.0 to 1.0). */
+    getAlpha() {
+        return this.alpha;
+    }
+    /** Current FPS estimate. */
+    getFPS() {
+        return this.fps;
+    }
+    /** Number of simulation steps executed in the last frame. */
+    getLastSimSteps() {
+        return this.lastSimSteps;
+    }
+    /** Current accumulator value (remaining un-simulated time). */
+    getAccumulator() {
+        return this.accumulator;
+    }
+    isRunning() {
+        return this.running;
+    }
+    /** Get the fixed simulation timestep. */
+    getFixedDt() {
+        return this.fixedDt;
+    }
+    /** Update the fixed simulation timestep. */
+    setFixedDt(dt) {
+        this.fixedDt = dt;
+        this.accumulator = 0;
+    }
+    /** Update the max steps per frame. */
+    setMaxStepsPerFrame(max) {
+        this.maxSteps = max;
+    }
+    /** Get the max steps per frame. */
+    getMaxStepsPerFrame() {
+        return this.maxSteps;
+    }
+    /** Attach or detach a render callback at runtime. */
+    setRenderCallback(cb) {
+        this.renderCb = cb;
+    }
+    getStats() {
+        return {
+            fps: this.fps,
+            simSteps: this.lastSimSteps,
+            alpha: this.alpha,
+            accumulator: this.accumulator,
+        };
+    }
+    /**
+     * Run one frame of simulation + rendering with a given delta time (seconds).
+     * Returns the number of simulation steps executed.
+     *
+     * Can be called directly for testing or external loop driving (no RAF).
+     */
+    runFrame(frameDt) {
+        if (!Number.isFinite(frameDt) || frameDt < 0)
+            return 0;
+        // Cap frame delta at 250ms to avoid huge jumps after tab switches.
+        const dt = Math.min(frameDt, 0.25);
+        // FPS counter
+        this.frameCount++;
+        this.fpsTimer += dt;
+        if (this.fpsTimer >= 1) {
+            this.fps = this.frameCount;
+            this.frameCount = 0;
+            this.fpsTimer = 0;
+        }
+        // Fixed-timestep simulation with catch-up
+        this.accumulator += dt;
+        let steps = 0;
+        while (this.accumulator >= this.fixedDt && steps < this.maxSteps) {
+            this.gameWorld.step(this.fixedDt);
+            this.accumulator -= this.fixedDt;
+            steps++;
+        }
+        // Spiral-of-death protection: if we still have too much accumulated time,
+        // drop it to prevent unbounded catch-up.
+        if (this.accumulator > this.fixedDt * this.maxSteps) {
+            this.accumulator = 0;
+        }
+        this.lastSimSteps = steps;
+        // Interpolation alpha: how far between sim steps we are (0.0 to ~1.0)
+        this.alpha = this.fixedDt > 0 ? this.accumulator / this.fixedDt : 0;
+        this.gameWorld.resources.alpha = this.alpha;
+        // Render once per frame
+        if (this.renderCb) {
+            this.renderCb(this.alpha);
+        }
+        return steps;
+    }
+    loop = () => {
+        if (!this.running)
+            return;
+        this.rafId = requestAnimationFrame(this.loop);
+        const now = performance.now();
+        const frameDt = (now - this.lastTime) / 1000;
+        this.lastTime = now;
+        this.runFrame(frameDt);
+    };
+}

package/dist/core/src/scene/index.js

@@ -0,0 +1,14 @@
+// Scene sub-barrel — re-exports all scene-related items.
+export { batch, builderToPrefab, c, spawn, spawnChild } from "./builder.js";
+export { Camera } from "./camera.js";
+export { CheckpointManager } from "./checkpoint.js";
+export { GameLoop } from "./game-loop.js";
+export { RenderLayer } from "./layer.js";
+export { createPrefabFromComponentDefs, PrefabFactory, PrefabRegistry } from "./prefab.js";
+export { Scene } from "./scene.js";
+export { SceneManager } from "./scene-manager.js";
+export { computeSkyColor, DayNightCycle, DEFAULT_ATMOSPHERE_CONFIG, DEFAULT_DAY_NIGHT_CONFIG, DEFAULT_FOG_CONFIG, FogSystem } from "./sky.js";
+export { SpatialGrid } from "./spatial-grid.js";
+export { chunkKey, WorldStreamer, worldToChunk } from "./streaming.js";
+export { generateInstances, packInstanceData, VegetationPatch, VegetationWindSystem } from "./vegetation.js";
+export { GameWorld } from "./world.js";

package/dist/core/src/scene/layer.js

@@ -0,0 +1,7 @@
+export var RenderLayer;
+(function (RenderLayer) {
+    RenderLayer[RenderLayer["Opaque"] = 0] = "Opaque";
+    RenderLayer[RenderLayer["Transparent"] = 1] = "Transparent";
+    RenderLayer[RenderLayer["UI"] = 2] = "UI";
+    RenderLayer[RenderLayer["Debug"] = 3] = "Debug";
+})(RenderLayer || (RenderLayer = {}));

package/dist/core/src/scene/prefab.js

@@ -0,0 +1,97 @@
+import { ROOT_ENTITY } from "../ecs/entity.js";
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export class PrefabRegistry {
+    prefabs = new Map();
+    register(prefab) {
+        if (this.prefabs.has(prefab.name)) {
+            log.warn("prefab-registry", `Overwriting prefab "${prefab.name}"`);
+        }
+        this.prefabs.set(prefab.name, prefab);
+    }
+    unregister(name) {
+        this.prefabs.delete(name);
+    }
+    get(name) {
+        return this.prefabs.get(name);
+    }
+    has(name) {
+        return this.prefabs.has(name);
+    }
+    list() {
+        return [...this.prefabs.keys()];
+    }
+    clear() {
+        this.prefabs.clear();
+    }
+}
+export class PrefabFactory {
+    world;
+    registry;
+    hierarchy;
+    constructor(world, registry, hierarchy) {
+        this.world = world;
+        this.registry = registry;
+        this.hierarchy = hierarchy;
+    }
+    spawn(prefabName, parent) {
+        const prefab = this.registry.get(prefabName);
+        if (!prefab)
+            throw new Error(`Prefab "${prefabName}" not found`);
+        const components = new Map();
+        prefab.components.forEach((entry) => {
+            components.set(entry.componentId, { ...entry.data });
+        });
+        const entity = this.world.spawn(components);
+        this.hierarchy.setParent(entity, parent ?? ROOT_ENTITY);
+        if (prefab.children) {
+            prefab.children.forEach((child) => {
+                this.spawnChild(child, entity);
+            });
+        }
+        return entity;
+    }
+    spawnChild(child, parent) {
+        const components = new Map();
+        if (child.components) {
+            child.components.forEach((entry) => {
+                components.set(entry.componentId, { ...entry.data });
+            });
+        }
+        if (child.prefab) {
+            const prefab = this.registry.get(child.prefab);
+            if (prefab) {
+                prefab.components.forEach((entry) => {
+                    if (!components.has(entry.componentId)) {
+                        components.set(entry.componentId, { ...entry.data });
+                    }
+                });
+            }
+        }
+        const entity = this.world.spawn(components);
+        this.hierarchy.setParent(entity, parent);
+        if (child.prefab) {
+            const prefab = this.registry.get(child.prefab);
+            if (prefab?.children) {
+                prefab.children.forEach((grandchild) => {
+                    this.spawnChild(grandchild, entity);
+                });
+            }
+        }
+        return entity;
+    }
+    spawnMany(prefabName, count, parent) {
+        const entities = [];
+        for (let i = 0; i < count; i++) {
+            entities.push(this.spawn(prefabName, parent));
+        }
+        return entities;
+    }
+}
+export function createPrefabFromComponentDefs(name, defs, tags) {
+    const components = defs.map(({ def, overrides }) => ({
+        componentId: def.id,
+        data: { ...def.defaults, ...overrides },
+    }));
+    return { name, components, tags };
+}