@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/inspectable/src/inspectable.js

@@ -0,0 +1,205 @@
+// ============================================================================
+// inspectable.ts — InspectableRegistry: a schema'd, hierarchical registry of
+// named game-state nodes that automation (MCP tools, devtools) can read and
+// write WITHOUT synthesizing user input.
+//
+// Why callbacks instead of field reflection: most interesting state isn't
+// live-bound — e.g. `CharacterCustomization.girth` only takes effect after
+// the game re-runs resolveCustomizationMeshes() and re-uploads meshes. A raw
+// `obj[key] = value` would silently desync the store, the rendered mesh, and
+// the sim. Each node therefore carries a `set()` that routes through the same
+// apply function the game's own UI calls.
+//
+// Hierarchy is derived from dot-separated `path`s ("player.customization.
+// girth") — no class hierarchy or decorator machinery required.
+//
+// Thread model: `set()` runs in whatever thread hosts the registry. For
+// sim-authoritative state, implement `set` as a dispatch over the game's
+// RendererToSimMessage channel and let `get` read the last received snapshot;
+// mark the node `thread: "sim"` so callers know the write isn't synchronous.
+//
+// When to use what:
+//   - inspectable_* tools (this registry) — semantic game state with schema
+//   - add_component (editor MCP)      — ECS component data
+//   - extraTools / set_test_state     — bespoke escape hatches
+//   - inject_input / dispatch_*       — exercising the real input pipeline
+// ============================================================================
+export class InspectableError extends Error {
+    reason;
+    constructor(message, 
+    /** Machine-readable hint for callers that want to distinguish failures. */
+    reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "InspectableError";
+    }
+}
+export class InspectableRegistry {
+    nodes = new Map();
+    listeners = new Set();
+    /** Register a node. Returns an unregister function. Throws on duplicate paths. */
+    register(node) {
+        if (!node.path)
+            throw new InspectableError("Node requires a path", "bad_type");
+        if (this.nodes.has(node.path)) {
+            throw new InspectableError(`Node "${node.path}" is already registered`, "bad_type");
+        }
+        this.nodes.set(node.path, node);
+        return () => { this.nodes.delete(node.path); };
+    }
+    registerAll(nodes) {
+        const unsubs = nodes.map((n) => this.register(n));
+        return () => { unsubs.forEach((u) => u()); };
+    }
+    unregister(path) {
+        return this.nodes.delete(path);
+    }
+    has(path) {
+        return this.nodes.has(path);
+    }
+    size() {
+        return this.nodes.size;
+    }
+    /** Node descriptors (schema only — no live reads), optionally filtered to
+     *  a path prefix ("player" matches "player.health" but not "players.x"). */
+    list(prefix) {
+        const out = [];
+        for (const node of this.nodes.values()) {
+            if (prefix && node.path !== prefix && !node.path.startsWith(prefix + "."))
+                continue;
+            out.push(this.describeNode(node));
+        }
+        return out.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    /** Nested tree of node descriptors — intermediate path segments become
+     *  grouping objects with `children` and a synthesized `type: "json"`. */
+    tree(prefix) {
+        const roots = new Map();
+        for (const info of this.list(prefix)) {
+            const segs = info.path.split(".");
+            let kids = roots;
+            for (let i = 0; i < segs.length; i++) {
+                const leaf = i === segs.length - 1;
+                let entry = kids.get(segs[i]);
+                if (!entry) {
+                    entry = {
+                        path: segs.slice(0, i + 1).join("."),
+                        type: "json",
+                        readOnly: true,
+                        children: [],
+                        _kids: new Map(),
+                    };
+                    kids.set(segs[i], entry);
+                }
+                if (leaf)
+                    Object.assign(entry, info, { children: entry.children, _kids: entry._kids });
+                kids = entry._kids;
+            }
+        }
+        const strip = (entries) => [...entries.values()].map(({ _kids, ...info }) => ({
+            ...info,
+            children: _kids.size ? strip(_kids) : undefined,
+        }));
+        return strip(roots);
+    }
+    /** Schema descriptor for a single node (throws on unknown path). */
+    describe(path) {
+        return this.describeNode(this.node(path));
+    }
+    /** Current value of a node. */
+    get(path) {
+        const node = this.node(path);
+        return { path, value: node.get() };
+    }
+    /** Validate and apply a write through the node's `set()`, then return a
+     *  fresh `get()` echo so callers see what actually landed. */
+    async set(path, value) {
+        const node = this.node(path);
+        if (node.readOnly || !node.set) {
+            throw new InspectableError(`Node "${path}" is read-only`, "read_only");
+        }
+        this.validate(node, value);
+        await node.set(value);
+        const result = { path, value: node.get() };
+        this.listeners.forEach((l) => {
+            try {
+                l(path, result.value);
+            }
+            catch { /* listener errors don't fail the write */ }
+        });
+        return result;
+    }
+    /** Subscribe to successful writes (path + resulting value). */
+    onChanged(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    node(path) {
+        const node = this.nodes.get(path);
+        if (node)
+            return node;
+        // Suggest likely targets: children of the queried path, ancestors, and
+        // siblings sharing the parent prefix ("player.heal" → "player.health").
+        const parent = path.slice(0, path.lastIndexOf("."));
+        const near = [...this.nodes.keys()].filter((k) => k.startsWith(path + ".") || path.startsWith(k + ".") ||
+            (parent && k.startsWith(parent + ".")));
+        throw new InspectableError(`Unknown inspectable path "${path}"` + (near.length ? `. Did you mean: ${near.slice(0, 8).join(", ")}?` : ""), "not_found");
+    }
+    validate(node, value) {
+        switch (node.type) {
+            case "number": {
+                if (typeof value !== "number" || !Number.isFinite(value)) {
+                    throw new InspectableError(`"${node.path}" expects a finite number, got ${typeof value}`, "bad_type");
+                }
+                if (node.min !== undefined && value < node.min || node.max !== undefined && value > node.max) {
+                    throw new InspectableError(`"${node.path}" must be within [${node.min ?? "-∞"}, ${node.max ?? "+∞"}], got ${value}`, "out_of_range");
+                }
+                return;
+            }
+            case "boolean":
+                if (typeof value !== "boolean") {
+                    throw new InspectableError(`"${node.path}" expects a boolean, got ${typeof value}`, "bad_type");
+                }
+                return;
+            case "string":
+                if (typeof value !== "string") {
+                    throw new InspectableError(`"${node.path}" expects a string, got ${typeof value}`, "bad_type");
+                }
+                return;
+            case "enum": {
+                const options = node.enum?.() ?? [];
+                if (typeof value !== "string" || !options.includes(value)) {
+                    throw new InspectableError(`"${node.path}" must be one of [${options.join(", ")}], got ${JSON.stringify(value)}`, "bad_enum");
+                }
+                return;
+            }
+            case "json":
+                if (!isJsonSerializable(value)) {
+                    throw new InspectableError(`"${node.path}" expects a JSON-serializable value`, "bad_type");
+                }
+                return;
+        }
+    }
+    describeNode(node) {
+        return {
+            path: node.path,
+            label: node.label,
+            description: node.description,
+            type: node.type,
+            min: node.min,
+            max: node.max,
+            options: node.type === "enum" ? (node.enum?.() ?? []) : undefined,
+            readOnly: node.readOnly ?? !node.set,
+            thread: node.thread,
+        };
+    }
+}
+function isJsonSerializable(value) {
+    try {
+        JSON.stringify(value);
+        return value === undefined ? false : true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/libraries/lighting/src/index.js

@@ -0,0 +1,4 @@
+export { LightSystem, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS } from "./light-system.js";
+export { LightingSystem } from "./lighting-system.js";
+// Engine library descriptor
+export { LightingLib, LightingTok } from "./library.js";

package/dist/libraries/lighting/src/library.js

@@ -0,0 +1,48 @@
+// ============================================================================
+// LightingLib — declarative engine library descriptor for @downdraft/engine/libraries/lighting
+//
+// Provides directional sun/moon lighting, ambient, bioluminescent blending, and
+// dynamic point/spot lights. LightSystem extends LightingSystem with a
+// read-only storage buffer shared across all entity pipelines, plus optional
+// debug gizmo rendering.
+//
+// Games declare `libraries: [LightingLib]` in their GameModule. The host
+// creates the LightSystem (renderer-side) during renderer init and exposes it
+// via the LightingTok token. Games inject LightingTok to call
+// getLightingParams(), addPointLight(), upload(), etc.
+//
+// Games that need full control can still import LightSystem directly
+// (escape hatch). Note: init() must be called after construction to allocate
+// the GPU storage buffer + bind group.
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { LightSystem } from "./light-system.js";
+// ── Typed tokens (DI) ──
+/** Token for the renderer-side LightSystem. Inject in renderer passes. */
+export const LightingTok = resourceToken("lighting:system");
+// ── Descriptor ──
+export const LightingLib = {
+    name: "lighting",
+    version: "1.0.0",
+    provides: [LightingTok],
+    // Renderer-side only — LightSystem owns GPU buffers for the light storage.
+    renderer: {
+        init(config, ctx) {
+            const lighting = new LightSystem(ctx.device);
+            lighting.init();
+            if (config.showDebugGizmos) {
+                lighting.showDebugGizmos = true;
+                lighting.initDebugGizmos(ctx.format);
+            }
+            ctx.provide(LightingTok, lighting);
+            return lighting;
+        },
+        dispose(lighting) {
+            lighting.destroy();
+        },
+    },
+    defaultConfig: {
+        blendDuration: 30,
+        showDebugGizmos: false,
+    },
+};

package/dist/libraries/lighting/src/light-system.js

@@ -0,0 +1,395 @@
+// ============================================================================
+// Light System — extends LightingSystem with dynamic point/spot lights
+// Uses a read-only storage buffer shared across all entity pipelines.
+// ============================================================================
+import { createValidatedShaderModule } from "@downdraft/engine";
+import { calculateViewProj, DEPTH_FORMAT, MSAA_SAMPLE_COUNT } from "@downdraft/engine";
+import { LightingSystem } from "./lighting-system.js";
+const DEBUG_WGSL = "struct Uniforms {\n  viewProj: mat4x4<f32>,\n};\n@group(0) @binding(0) var<uniform> uniforms: Uniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) instancePos: vec3<f32>,\n  @location(2) instanceRadius: f32,\n  @location(3) instanceColor: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) color: vec3<f32>,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let worldPos = input.position * input.instanceRadius + input.instancePos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.color = input.instanceColor;\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  return vec4<f32>(input.color, 0.4);\n}\n";
+export const MAX_POINT_LIGHTS = 32;
+export const MAX_SPOT_LIGHTS = 8;
+const CULL_MARGIN = 300; // world units beyond light radius for culling
+export class LightSystem extends LightingSystem {
+    lightStorageBuffer = null;
+    lightBindGroupLayout = null;
+    lightBindGroup = null;
+    pointLights = [];
+    spotLights = [];
+    pointLightCount = 0;
+    spotLightCount = 0;
+    // Pre-allocated light objects to avoid per-frame allocation
+    pointLightPool = [];
+    spotLightPool = [];
+    // Pre-allocated cull arrays to avoid per-frame allocation
+    culledPointIndices = [];
+    culledPointDistSq = [];
+    culledSpotIndices = [];
+    culledSpotDistSq = [];
+    // Packed data for GPU upload — matches WGSL LightStorage struct layout.
+    // Header: 4 floats (16 bytes)
+    // PointLight: 8 floats (32 bytes) each × MAX_POINT_LIGHTS
+    // SpotLight: 16 floats (64 bytes) each × MAX_SPOT_LIGHTS
+    lightDataArray;
+    lightDataU32;
+    prevNumPoints = 0;
+    prevNumSpots = 0;
+    // Debug gizmo rendering
+    showDebugGizmos = false;
+    debugPipeline = null;
+    debugBindGroupLayout = null;
+    debugBindGroup = null;
+    debugUniformBuffer = null;
+    debugSphereVerts = null;
+    debugSphereIndexCount = 0;
+    debugSphereIndexBuffer = null;
+    debugInstanceBuffer = null;
+    debugInstanceData = null;
+    constructor(device) {
+        super(device);
+        const totalFloats = 4 + MAX_POINT_LIGHTS * 8 + MAX_SPOT_LIGHTS * 16;
+        this.lightDataArray = new Float32Array(totalFloats);
+        this.lightDataU32 = new Uint32Array(this.lightDataArray.buffer);
+    }
+    init() {
+        const totalBytes = this.lightDataArray.byteLength;
+        const dev = this.device;
+        this.lightStorageBuffer = dev.createBuffer({
+            size: totalBytes,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.lightBindGroupLayout = dev.createBindGroupLayout({
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.FRAGMENT,
+                    buffer: { type: "read-only-storage", hasDynamicOffset: false },
+                },
+            ],
+        });
+        this.lightBindGroup = dev.createBindGroup({
+            layout: this.lightBindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: this.lightStorageBuffer } }],
+        });
+        // Zero-initialize the buffer so numPointLights/numSpotLights start at 0
+        dev.queue.writeBuffer(this.lightStorageBuffer, 0, this.lightDataArray);
+    }
+    getLightBindGroup() {
+        return this.lightBindGroup;
+    }
+    getLightBindGroupLayout() {
+        return this.lightBindGroupLayout;
+    }
+    beginFrame() {
+        this.pointLightCount = 0;
+        this.spotLightCount = 0;
+    }
+    addPointLight(pos, color, intensity, radius) {
+        if (this.pointLightCount >= MAX_POINT_LIGHTS)
+            return;
+        let light = this.pointLightPool[this.pointLightCount];
+        if (!light) {
+            light = { pos, color, intensity, radius };
+            this.pointLightPool[this.pointLightCount] = light;
+        }
+        else {
+            light.pos = pos;
+            light.color = color;
+            light.intensity = intensity;
+            light.radius = radius;
+        }
+        this.pointLights[this.pointLightCount] = light;
+        this.pointLightCount++;
+    }
+    addSpotLight(pos, dir, color, intensity, radius, cosInner, cosOuter) {
+        if (this.spotLightCount >= MAX_SPOT_LIGHTS)
+            return;
+        let light = this.spotLightPool[this.spotLightCount];
+        if (!light) {
+            light = { pos, dir, color, intensity, radius, cosInner, cosOuter };
+            this.spotLightPool[this.spotLightCount] = light;
+        }
+        else {
+            light.pos = pos;
+            light.dir = dir;
+            light.color = color;
+            light.intensity = intensity;
+            light.radius = radius;
+            light.cosInner = cosInner;
+            light.cosOuter = cosOuter;
+        }
+        this.spotLights[this.spotLightCount] = light;
+        this.spotLightCount++;
+    }
+    upload(cameraPos) {
+        if (!this.lightStorageBuffer)
+            return;
+        // Cull and sort point lights by distance to camera (nearest first)
+        const culledIndices = this.culledPointIndices;
+        const culledDistSq = this.culledPointDistSq;
+        culledIndices.length = 0;
+        culledDistSq.length = 0;
+        for (let i = 0; i < this.pointLightCount; i++) {
+            const pl = this.pointLights[i];
+            const dx = pl.pos[0] - cameraPos[0];
+            const dy = pl.pos[1] - cameraPos[1];
+            const dz = pl.pos[2] - cameraPos[2];
+            const distSq = dx * dx + dy * dy + dz * dz;
+            const maxDist = pl.radius + CULL_MARGIN;
+            if (distSq <= maxDist * maxDist) {
+                culledIndices.push(i);
+                culledDistSq.push(distSq);
+            }
+        }
+        // Simple insertion sort (small N, avoids sort closure allocation)
+        for (let i = 1; i < culledIndices.length; i++) {
+            const keyIdx = culledIndices[i];
+            const keyDist = culledDistSq[i];
+            let j = i - 1;
+            while (j >= 0 && culledDistSq[j] > keyDist) {
+                culledIndices[j + 1] = culledIndices[j];
+                culledDistSq[j + 1] = culledDistSq[j];
+                j--;
+            }
+            culledIndices[j + 1] = keyIdx;
+            culledDistSq[j + 1] = keyDist;
+        }
+        const numPoints = Math.min(culledIndices.length, MAX_POINT_LIGHTS);
+        // Cull and sort spot lights
+        const culledSpotIdx = this.culledSpotIndices;
+        const culledSpotDist = this.culledSpotDistSq;
+        culledSpotIdx.length = 0;
+        culledSpotDist.length = 0;
+        for (let i = 0; i < this.spotLightCount; i++) {
+            const sl = this.spotLights[i];
+            const dx = sl.pos[0] - cameraPos[0];
+            const dy = sl.pos[1] - cameraPos[1];
+            const dz = sl.pos[2] - cameraPos[2];
+            const distSq = dx * dx + dy * dy + dz * dz;
+            const maxDist = sl.radius + CULL_MARGIN;
+            if (distSq <= maxDist * maxDist) {
+                culledSpotIdx.push(i);
+                culledSpotDist.push(distSq);
+            }
+        }
+        for (let i = 1; i < culledSpotIdx.length; i++) {
+            const keyIdx = culledSpotIdx[i];
+            const keyDist = culledSpotDist[i];
+            let j = i - 1;
+            while (j >= 0 && culledSpotDist[j] > keyDist) {
+                culledSpotIdx[j + 1] = culledSpotIdx[j];
+                culledSpotDist[j + 1] = culledSpotDist[j];
+                j--;
+            }
+            culledSpotIdx[j + 1] = keyIdx;
+            culledSpotDist[j + 1] = keyDist;
+        }
+        const numSpots = Math.min(culledSpotIdx.length, MAX_SPOT_LIGHTS);
+        // Pack into Float32Array matching WGSL LightStorage struct layout
+        const data = this.lightDataArray;
+        // Zero only stale slots from the previous frame (not the entire array)
+        const pointStart = 4 + numPoints * 8;
+        const pointEnd = 4 + Math.max(numPoints, this.prevNumPoints) * 8;
+        if (pointEnd > pointStart)
+            data.fill(0, pointStart, pointEnd);
+        const spotBase = 4 + MAX_POINT_LIGHTS * 8;
+        const spotStart = spotBase + numSpots * 16;
+        const spotEnd = spotBase + Math.max(numSpots, this.prevNumSpots) * 16;
+        if (spotEnd > spotStart)
+            data.fill(0, spotStart, spotEnd);
+        this.prevNumPoints = numPoints;
+        this.prevNumSpots = numSpots;
+        // Header: numPointLights, numSpotLights, pad, pad (u32 values via Uint32Array view)
+        this.lightDataU32[0] = numPoints;
+        this.lightDataU32[1] = numSpots;
+        this.lightDataU32[2] = 0;
+        this.lightDataU32[3] = 0;
+        // Point lights: 8 floats each starting at offset 4
+        for (let i = 0; i < numPoints; i++) {
+            const pl = this.pointLights[culledIndices[i]];
+            const off = 4 + i * 8;
+            data[off] = pl.pos[0];
+            data[off + 1] = pl.pos[1];
+            data[off + 2] = pl.pos[2];
+            data[off + 3] = pl.radius;
+            data[off + 4] = pl.color[0];
+            data[off + 5] = pl.color[1];
+            data[off + 6] = pl.color[2];
+            data[off + 7] = pl.intensity;
+        }
+        // Spot lights: 16 floats each starting at offset 4 + MAX_POINT_LIGHTS * 8
+        for (let i = 0; i < numSpots; i++) {
+            const sl = this.spotLights[culledSpotIdx[i]];
+            const off = spotBase + i * 16;
+            data[off] = sl.pos[0];
+            data[off + 1] = sl.pos[1];
+            data[off + 2] = sl.pos[2];
+            data[off + 3] = sl.radius;
+            data[off + 4] = sl.dir[0];
+            data[off + 5] = sl.dir[1];
+            data[off + 6] = sl.dir[2];
+            data[off + 7] = sl.cosInner;
+            data[off + 8] = sl.color[0];
+            data[off + 9] = sl.color[1];
+            data[off + 10] = sl.color[2];
+            data[off + 11] = sl.cosOuter;
+            data[off + 12] = sl.intensity;
+            // off + 13, +14, +15 = padding (already zeroed)
+        }
+        this.device?.queue.writeBuffer(this.lightStorageBuffer, 0, data);
+    }
+    MAX_DEBUG_INSTANCES = MAX_POINT_LIGHTS + MAX_SPOT_LIGHTS;
+    initDebugGizmos(format) {
+        // Generate unit sphere wireframe (latitude/longitude lines)
+        const latSegments = 8;
+        const lonSegments = 16;
+        const verts = [];
+        for (let lat = 0; lat <= latSegments; lat++) {
+            const theta = (lat / latSegments) * Math.PI;
+            const y = Math.cos(theta);
+            const r = Math.sin(theta);
+            for (let lon = 0; lon <= lonSegments; lon++) {
+                const phi = (lon / lonSegments) * Math.PI * 2;
+                verts.push(r * Math.cos(phi), y, r * Math.sin(phi));
+            }
+        }
+        const indices = [];
+        // Latitude lines
+        for (let lat = 0; lat <= latSegments; lat++) {
+            for (let lon = 0; lon < lonSegments; lon++) {
+                const i = lat * (lonSegments + 1) + lon;
+                indices.push(i, i + 1);
+            }
+        }
+        // Longitude lines
+        for (let lon = 0; lon <= lonSegments; lon++) {
+            for (let lat = 0; lat < latSegments; lat++) {
+                const i = lat * (lonSegments + 1) + lon;
+                indices.push(i, i + (lonSegments + 1));
+            }
+        }
+        this.debugSphereIndexCount = indices.length;
+        const instanceFloats = this.MAX_DEBUG_INSTANCES * 8;
+        this.debugInstanceData = new Float32Array(instanceFloats);
+        const dev = this.device;
+        this.debugSphereVerts = dev.createBuffer({
+            size: verts.length * 4,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        dev.queue.writeBuffer(this.debugSphereVerts, 0, new Float32Array(verts));
+        this.debugSphereIndexBuffer = dev.createBuffer({
+            size: indices.length * 2,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        dev.queue.writeBuffer(this.debugSphereIndexBuffer, 0, new Uint16Array(indices));
+        this.debugInstanceBuffer = dev.createBuffer({
+            size: instanceFloats * 4,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.debugUniformBuffer = dev.createBuffer({
+            size: 64,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.debugBindGroupLayout = dev.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+            ],
+        });
+        this.debugBindGroup = dev.createBindGroup({
+            layout: this.debugBindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: this.debugUniformBuffer } }],
+        });
+        const shaderModule = createValidatedShaderModule(dev, { code: DEBUG_WGSL, label: "LightSystem.debug" });
+        this.debugPipeline = dev.createRenderPipeline({
+            layout: dev.createPipelineLayout({ bindGroupLayouts: [this.debugBindGroupLayout] }),
+            vertex: {
+                module: shaderModule,
+                entryPoint: "vs_main",
+                buffers: [
+                    { arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: "float32x3" }] },
+                    { arrayStride: 32, stepMode: "instance", attributes: [
+                            { shaderLocation: 1, offset: 0, format: "float32x3" },
+                            { shaderLocation: 2, offset: 12, format: "float32" },
+                            { shaderLocation: 3, offset: 16, format: "float32x3" },
+                        ] },
+                ],
+            },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "fs_main",
+                targets: [{ format: format, blend: {
+                            color: { srcFactor: "src-alpha", dstFactor: "one", operation: "add" },
+                            alpha: { srcFactor: "src-alpha", dstFactor: "one", operation: "add" },
+                        } }],
+            },
+            primitive: { topology: "line-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: "less",
+            },
+        });
+    }
+    renderDebugGizmos(passEncoder, camera) {
+        if (!this.showDebugGizmos || !this.debugPipeline || !this.debugBindGroup || !this.debugUniformBuffer)
+            return;
+        if (!this.debugInstanceBuffer || !this.debugInstanceData || !this.debugSphereVerts || !this.debugSphereIndexBuffer)
+            return;
+        const viewProj = calculateViewProj(camera);
+        this.device?.queue.writeBuffer(this.debugUniformBuffer, 0, viewProj);
+        // Collect instances from point lights + spot lights
+        const data = this.debugInstanceData;
+        data.fill(0);
+        let count = 0;
+        for (let i = 0; i < this.pointLightCount && count < this.MAX_DEBUG_INSTANCES; i++) {
+            const pl = this.pointLights[i];
+            const off = count * 8;
+            data[off] = pl.pos[0];
+            data[off + 1] = pl.pos[1];
+            data[off + 2] = pl.pos[2];
+            data[off + 3] = pl.radius;
+            data[off + 4] = pl.color[0];
+            data[off + 5] = pl.color[1];
+            data[off + 6] = pl.color[2];
+            count++;
+        }
+        for (let i = 0; i < this.spotLightCount && count < this.MAX_DEBUG_INSTANCES; i++) {
+            const sl = this.spotLights[i];
+            const off = count * 8;
+            data[off] = sl.pos[0];
+            data[off + 1] = sl.pos[1];
+            data[off + 2] = sl.pos[2];
+            data[off + 3] = sl.radius;
+            data[off + 4] = sl.color[0];
+            data[off + 5] = sl.color[1];
+            data[off + 6] = sl.color[2];
+            count++;
+        }
+        this.device?.queue.writeBuffer(this.debugInstanceBuffer, 0, data);
+        passEncoder.setPipeline(this.debugPipeline);
+        passEncoder.setBindGroup(0, this.debugBindGroup);
+        passEncoder.setVertexBuffer(0, this.debugSphereVerts);
+        passEncoder.setVertexBuffer(1, this.debugInstanceBuffer);
+        passEncoder.setIndexBuffer(this.debugSphereIndexBuffer, "uint16");
+        passEncoder.drawIndexed(this.debugSphereIndexCount, count);
+    }
+    /** Release all GPU resources. Call when the light system is no longer needed. */
+    destroy() {
+        this.lightStorageBuffer?.destroy();
+        this.lightStorageBuffer = null;
+        this.debugUniformBuffer?.destroy();
+        this.debugUniformBuffer = null;
+        this.debugSphereVerts?.destroy();
+        this.debugSphereVerts = null;
+        this.debugSphereIndexBuffer?.destroy();
+        this.debugSphereIndexBuffer = null;
+        this.debugInstanceBuffer?.destroy();
+        this.debugInstanceBuffer = null;
+        this.lightBindGroupLayout = null;
+        this.lightBindGroup = null;
+        this.debugPipeline = null;
+        this.debugBindGroupLayout = null;
+        this.debugBindGroup = null;
+        this.debugInstanceData = null;
+    }
+}