@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/sab/core-input-channel.js

@@ -0,0 +1,22 @@
+import { defineChannel } from "./define.js";
+export const CoreInputChannel = defineChannel({
+    name: "core-input",
+    magic: 0x434f4950,
+    // v2: gamepadButtons → u32 bitmask pair [lo, hi] (W3C standard order,
+    // GP_BTN_* in gamepad-devices.ts); gamepadAxes → 8 (lx ly rx ry lt rt
+    // dpadX dpadY). Mirrors the multi-input v2 upgrade.
+    version: 2,
+    mode: "record",
+    header: { size: 64, fields: {} },
+    fields: {
+        keys: { type: "i32", count: 8 },
+        mouseX: { type: "f32" },
+        mouseY: { type: "f32" },
+        mouseDeltaX: { type: "f32" },
+        mouseDeltaY: { type: "f32" },
+        mouseButtons: { type: "i32", count: 3 },
+        wheelDelta: { type: "f32" },
+        gamepadButtons: { type: "u32", count: 2 },
+        gamepadAxes: { type: "f32", count: 8 },
+    },
+});

package/dist/core/src/sab/define.js

@@ -0,0 +1,127 @@
+import { GridReader, GridWriter } from "./grid-buffer.js";
+import { computeLayout } from "./layout.js";
+import { RecordReader, RecordWriter } from "./record-buffer.js";
+import { SlotReader, SlotWriter } from "./slot-buffer.js";
+// --- Runtime implementation ---
+function buildOffsets(layout) {
+    const headerOffsets = {
+        magic: layout.header.magicIndex,
+        version: layout.header.versionIndex,
+        sequence: layout.header.sequenceIndex,
+    };
+    for (const [name, field] of Object.entries(layout.header.fields)) {
+        if (name === "magic" || name === "version" || name === "sequence")
+            continue;
+        headerOffsets[name] = field.index;
+    }
+    if (layout.mode === "record" && layout.fields) {
+        const fieldOffsets = {};
+        for (const [name, field] of Object.entries(layout.fields)) {
+            fieldOffsets[name] = field.index;
+        }
+        return { header: headerOffsets, fields: fieldOffsets };
+    }
+    if (layout.mode === "slots" && layout.sections) {
+        const sections = {};
+        layout.sections.forEach((section) => {
+            const fieldOffsets = {};
+            for (const [name, field] of Object.entries(section.fields)) {
+                fieldOffsets[name] = field.index;
+            }
+            sections[section.name] = {
+                sectionByteOffset: section.byteOffset,
+                slotStride: section.slotStride,
+                fields: fieldOffsets,
+            };
+        });
+        return { header: headerOffsets, sections };
+    }
+    if (layout.mode === "grid" && layout.grid) {
+        const grid = {};
+        for (const [name, layer] of Object.entries(layout.grid.layers)) {
+            grid[name] = { byteOffset: layer.byteOffset, length: layer.length };
+        }
+        return { header: headerOffsets, grid };
+    }
+    return { header: headerOffsets };
+}
+function createReader(sab, layout) {
+    switch (layout.mode) {
+        case "record": return new RecordReader(sab, layout);
+        case "slots": return new SlotReader(sab, layout);
+        case "grid": return new GridReader(sab, layout);
+    }
+}
+function createWriter(sab, layout) {
+    switch (layout.mode) {
+        case "record": {
+            const w = new RecordWriter(sab, layout);
+            w.init();
+            return w;
+        }
+        case "slots": {
+            const w = new SlotWriter(sab, layout);
+            w.init();
+            return w;
+        }
+        case "grid": {
+            const w = new GridWriter(sab, layout);
+            w.init();
+            return w;
+        }
+    }
+}
+export function defineChannel(def) {
+    const layout = computeLayout(def);
+    const offsets = buildOffsets(layout);
+    const instance = {
+        def,
+        layout,
+        byteLength: layout.byteLength,
+        offsets,
+        allocate() {
+            const sab = new SharedArrayBuffer(layout.byteLength);
+            const u32 = new Uint32Array(sab);
+            u32[layout.header.magicIndex] = layout.magic;
+            u32[layout.header.versionIndex] = layout.version;
+            return sab;
+        },
+        reader(sab) {
+            return createReader(sab, layout);
+        },
+        writer(sab) {
+            return createWriter(sab, layout);
+        },
+    };
+    return instance;
+}
+// --- Manifest ---
+export function defineManifest(channels) {
+    return {
+        channels: channels,
+        allocate() {
+            const buffers = {};
+            for (const [name, ch] of Object.entries(channels)) {
+                buffers[name] = ch.allocate();
+            }
+            return buffers;
+        },
+        attach(buffers) {
+            const result = {};
+            for (const [name, ch] of Object.entries(channels)) {
+                const sab = buffers[name];
+                if (!sab) {
+                    throw new Error(`[SAB] Manifest attach: no buffer provided for channel "${name}"`);
+                }
+                if (sab.byteLength < ch.byteLength) {
+                    throw new Error(`[SAB] Manifest attach: buffer for channel "${name}" is ${sab.byteLength} bytes, need ${ch.byteLength}`);
+                }
+                result[name] = {
+                    reader: ch.reader(sab),
+                    writer: ch.writer(sab),
+                };
+            }
+            return result;
+        },
+    };
+}

package/dist/core/src/sab/errors.js

@@ -0,0 +1,60 @@
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+const warned = new Set();
+let debugMode = false;
+export function setDebug(enabled) {
+    debugMode = enabled;
+}
+export function isDebug() {
+    return debugMode;
+}
+export function warnOnce(key, msg) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    log.warn("sab", msg);
+}
+export function resetWarnings() {
+    warned.clear();
+}
+export class ValidationError extends Error {
+    constructor(message) {
+        super(`[SAB] ${message}`);
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Human-readable reason a SAB header fails validation, or `null` when valid.
+ * Distinguishes "not stamped yet" (readiness) from layout drift — callers
+ * polling `isValid()` would otherwise wait forever on a mismatched buffer.
+ */
+export function describeHeaderValidation(u32, magicIndex, versionIndex, expectedMagic, expectedVersion) {
+    const magic = u32[magicIndex];
+    const version = u32[versionIndex];
+    if (magic === 0)
+        return "buffer not initialized (writer has not stamped the header)";
+    if (magic !== expectedMagic) {
+        return `bad magic 0x${magic.toString(16)} (expected 0x${expectedMagic.toString(16)})`;
+    }
+    if (version !== expectedVersion) {
+        return `version mismatch (got ${version}, expected ${expectedVersion})`;
+    }
+    return null;
+}
+const TYPE_SIZES = {
+    f32: 4,
+    f64: 8,
+    i32: 4,
+    u32: 4,
+    bool: 4,
+};
+export function typeSize(type) {
+    const size = TYPE_SIZES[type];
+    if (size === undefined) {
+        throw new ValidationError(`Unknown field type: "${type}"`);
+    }
+    return size;
+}
+export function alignUp(offset, alignment) {
+    return (offset + alignment - 1) & ~(alignment - 1);
+}

package/dist/core/src/sab/game-input.js

@@ -0,0 +1,299 @@
+// ============================================================================
+// Game Input Buffer — SharedArrayBuffer for per-player input state
+// Multi-player slot-based input channel with keys, mouse, gamepad, and builder state.
+// ============================================================================
+import { defineChannel } from "./define.js";
+export const MAX_INPUT_PLAYERS = 4;
+export const InputChannel = defineChannel({
+    name: "game-input",
+    magic: 0x494e5054,
+    version: 1,
+    mode: "slots",
+    header: {
+        size: 64,
+        fields: {
+            playerCount: { type: "u32" },
+        },
+    },
+    sections: [
+        {
+            name: "players",
+            maxSlots: MAX_INPUT_PLAYERS,
+            slotSize: 128,
+            fields: {
+                keys: { type: "u32", count: 8 },
+                mouseX: { type: "f32" },
+                mouseY: { type: "f32" },
+                mouseBtn: { type: "u32" },
+                wheel: { type: "f32" },
+                gpAxes: { type: "f32", count: 8 },
+                gpBtn: { type: "u32" },
+                flags: { type: "u32" },
+                mouseDx: { type: "f32" },
+                mouseDy: { type: "f32" },
+                cameraZoom: { type: "f32" },
+                lookHeading: { type: "f32" },
+                lookPitch: { type: "f32" },
+                builderCellType: { type: "u32" },
+                builderRotation: { type: "u32" },
+            },
+        },
+    ],
+});
+export const INPUT_MAGIC = 0x494e5054;
+export const INPUT_VERSION = 1;
+export const INP_HDR = {
+    MAGIC: 0,
+    VERSION: 1,
+    PLAYER_COUNT: 3,
+    SEQUENCE: 2,
+};
+export const INP = {
+    KEYS: 0,
+    MOUSE_X: 8,
+    MOUSE_Y: 9,
+    MOUSE_BTN: 10,
+    WHEEL: 11,
+    GP_AXES: 12,
+    GP_BTN: 20,
+    FLAGS: 21,
+    MOUSE_DX: 22,
+    MOUSE_DY: 23,
+    CAMERA_ZOOM: 24,
+    LOOK_HEADING: 25,
+    LOOK_PITCH: 26,
+    BUILDER_CELL_TYPE: 27,
+    BUILDER_ROTATION: 28,
+};
+export const INP_FLAG = {
+    CONNECTED: 1 << 0,
+    HAS_GAMEPAD: 1 << 1,
+};
+export const KEY = {
+    W: 87, A: 65, S: 83, D: 68,
+    Q: 81, E: 69, R: 82, F: 70,
+    SHIFT: 16, CTRL: 17, ALT: 18, TAB: 9,
+    SPACE: 32, ENTER: 13, ESC: 27,
+    ONE: 49, TWO: 50, THREE: 51, FOUR: 52,
+    FIVE: 53, SIX: 54, SEVEN: 55, EIGHT: 56,
+    NINE: 57, ZERO: 48,
+    I: 73, B: 66, C: 67, M: 77, P: 80,
+    T: 84, V: 86, Z: 90, X: 88,
+    UP: 38, DOWN: 40, LEFT: 37, RIGHT: 39,
+    F1: 112, F2: 113, F3: 114, F4: 115, F5: 116, F6: 117,
+    F7: 118, F8: 119, F9: 120, F10: 121, F11: 122, F12: 123,
+    BRACKET_LEFT: 219,
+    BRACKET_RIGHT: 221,
+};
+export class InputBufferWriter {
+    writer;
+    slots;
+    constructor(sab) {
+        this.writer = InputChannel.writer(sab);
+        this.slots = this.writer.sections.players;
+    }
+    init() {
+        this.writer.header.u32[InputChannel.offsets.header.playerCount] = 0;
+    }
+    setPlayerCount(n) { this.writer.header.u32[InputChannel.offsets.header.playerCount] = n; }
+    incrementSequence() { this.writer.bumpSequence(); }
+    slot(playerIdx) {
+        return this.slots.slot(playerIdx);
+    }
+    setKey(playerIdx, keyCode, pressed) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        const wordIdx = Math.floor(keyCode / 32);
+        const bitIdx = keyCode % 32;
+        if (pressed) {
+            sv.u32[f.keys + wordIdx] |= (1 << bitIdx);
+        }
+        else {
+            sv.u32[f.keys + wordIdx] &= ~(1 << bitIdx);
+        }
+    }
+    setMousePos(playerIdx, x, y) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.f32[f.mouseX] = x;
+        sv.f32[f.mouseY] = y;
+    }
+    setMouseButton(playerIdx, button, pressed) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        if (pressed) {
+            sv.u32[f.mouseBtn] |= (1 << button);
+        }
+        else {
+            sv.u32[f.mouseBtn] &= ~(1 << button);
+        }
+    }
+    setWheel(playerIdx, delta) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        // Absolute per-flush value, not an accumulation — the reader never
+        // clears this field (single-writer rule); the writer owns it outright.
+        sv.f32[f.wheel] = delta;
+    }
+    setMouseDelta(playerIdx, dx, dy) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.f32[f.mouseDx] = dx;
+        sv.f32[f.mouseDy] = dy;
+    }
+    setGamepadAxis(playerIdx, axis, value) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.f32[f.gpAxes + axis] = value;
+    }
+    setGamepadButton(playerIdx, button, pressed) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        if (pressed) {
+            sv.u32[f.gpBtn] |= (1 << button);
+        }
+        else {
+            sv.u32[f.gpBtn] &= ~(1 << button);
+        }
+    }
+    setFlags(playerIdx, flags) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.u32[f.flags] = flags;
+    }
+    setCameraZoom(playerIdx, zoom) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.f32[f.cameraZoom] = zoom;
+    }
+    setLookHeading(playerIdx, heading) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.f32[f.lookHeading] = heading;
+    }
+    setLookPitch(playerIdx, pitch) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.f32[f.lookPitch] = pitch;
+    }
+    setBuilderCellType(playerIdx, cellTypeIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.u32[f.builderCellType] = cellTypeIdx;
+    }
+    setBuilderRotation(playerIdx, rotation) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        sv.u32[f.builderRotation] = rotation;
+    }
+}
+export class InputBufferReader {
+    reader;
+    slots;
+    constructor(sab) {
+        this.reader = InputChannel.reader(sab);
+        this.slots = this.reader.sections.players;
+    }
+    isValid() {
+        return this.reader.isValid();
+    }
+    validationError() {
+        return this.reader.validationError();
+    }
+    getSequence() { return this.reader.getSequence(); }
+    getPlayerCount() { return this.reader.header.u32[InputChannel.offsets.header.playerCount]; }
+    slot(playerIdx) {
+        return this.slots.slot(playerIdx);
+    }
+    isKeyDown(playerIdx, keyCode) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        const wordIdx = Math.floor(keyCode / 32);
+        const bitIdx = keyCode % 32;
+        return (sv.u32[f.keys + wordIdx] & (1 << bitIdx)) !== 0;
+    }
+    getMousePos(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return { x: sv.f32[f.mouseX], y: sv.f32[f.mouseY] };
+    }
+    isMouseDown(playerIdx, button) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return (sv.u32[f.mouseBtn] & (1 << button)) !== 0;
+    }
+    getWheel(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.f32[f.wheel];
+    }
+    // Sequence-gated consumption state. Transient fields (wheel, mouseDelta)
+    // are writer-owned: the reader must NEVER write into a slot (that would
+    // make the region two-writer — a lost-update race on real SAB and a
+    // protocol violation under the polyfill's whole-region sync). Instead the
+    // reader yields each written value exactly once per writer sequence bump.
+    lastWheelSeq = new Uint32Array(MAX_INPUT_PLAYERS).fill(0xffffffff);
+    lastMouseDeltaSeq = new Uint32Array(MAX_INPUT_PLAYERS).fill(0xffffffff);
+    consumeWheel(playerIdx) {
+        const seq = this.reader.getSequence();
+        if (seq === this.lastWheelSeq[playerIdx])
+            return 0;
+        this.lastWheelSeq[playerIdx] = seq;
+        const sv = this.slot(playerIdx);
+        return sv.f32[InputChannel.offsets.sections.players.fields.wheel];
+    }
+    getMouseDelta(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return { dx: sv.f32[f.mouseDx], dy: sv.f32[f.mouseDy] };
+    }
+    consumeMouseDelta(playerIdx) {
+        const seq = this.reader.getSequence();
+        if (seq === this.lastMouseDeltaSeq[playerIdx])
+            return { dx: 0, dy: 0 };
+        this.lastMouseDeltaSeq[playerIdx] = seq;
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return { dx: sv.f32[f.mouseDx], dy: sv.f32[f.mouseDy] };
+    }
+    getGamepadAxis(playerIdx, axis) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.f32[f.gpAxes + axis];
+    }
+    isGamepadButtonDown(playerIdx, button) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return (sv.u32[f.gpBtn] & (1 << button)) !== 0;
+    }
+    getFlags(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.u32[f.flags];
+    }
+    getCameraZoom(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.f32[f.cameraZoom];
+    }
+    getLookHeading(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.f32[f.lookHeading];
+    }
+    getLookPitch(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.f32[f.lookPitch];
+    }
+    getBuilderCellType(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.u32[f.builderCellType];
+    }
+    getBuilderRotation(playerIdx) {
+        const sv = this.slot(playerIdx);
+        const f = InputChannel.offsets.sections.players.fields;
+        return sv.u32[f.builderRotation];
+    }
+}