@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/libraries/models/src/vtk.js

@@ -0,0 +1,242 @@
+// ============================================================================
+// vtk.ts — VTK legacy format (.vtk) parser, ASCII POLYDATA
+//
+// Supports the classic serial format: POINTS, POLYGONS/LINES/VERTICES plus
+// POINT_DATA attributes (NORMALS, TEXTURE_COORDINATES, COLOR_SCALARS,
+// SCALARS+LOOKUP_TABLE). Binary legacy files and STRUCTURED/UNSTRUCTURED/
+// FIELD datasets are reported as warnings — the modern XML VTK family
+// (.vtp/.vtu/.vti) is a different container entirely.
+// ============================================================================
+import { assertCount, MAX_FACE_COUNT, MAX_VERTEX_COUNT } from "@downdraft/engine";
+export function parseVTK(data, name) {
+    const text = new TextDecoder().decode(data);
+    const lines = text.split("\n");
+    const warnings = [];
+    if (!lines[0]?.startsWith("# vtk DataFile")) {
+        throw new Error("VTK: not a legacy vtk file");
+    }
+    const encoding = (lines[2] ?? "").trim().toUpperCase();
+    if (encoding === "BINARY") {
+        throw new Error("VTK: binary legacy files are not supported (ASCII only)");
+    }
+    const datasetLine = (lines[3] ?? "").trim().toUpperCase();
+    const dataset = datasetLine.replace(/^DATASET\s+/, "");
+    if (dataset !== "POLYDATA") {
+        warnings.push(`VTK dataset ${dataset} — only POLYDATA geometry is loaded`);
+        if (dataset !== "UNSTRUCTURED_GRID") {
+            throw new Error(`VTK: unsupported dataset ${dataset}`);
+        }
+    }
+    // Tokenize the body after the DATASET line — VTK ASCII is whitespace-
+    // separated with keywords interleaved.
+    const body = lines.slice(4).join("\n");
+    const tokens = body.split(/\s+/).filter((t) => t.length > 0);
+    let ti = 0;
+    const positions = [];
+    const indices = [];
+    const normals = [];
+    const uvs = [];
+    const colors = [];
+    let pointDataCount = 0;
+    let colorComps = 0;
+    let scalarLookup = null;
+    let pendingScalars = null;
+    const pendingCells = [];
+    // VTK cell type → surface triangles (vertex order per the VTK spec).
+    const tri = (c, ...ts) => {
+        for (let i = 0; i + 2 < ts.length; i += 3)
+            indices.push(c[ts[i]], c[ts[i + 1]], c[ts[i + 2]]);
+    };
+    function emitCell(type, c) {
+        switch (type) {
+            case 5:
+                tri(c, 0, 1, 2);
+                break; // TRIANGLE
+            case 9:
+                tri(c, 0, 1, 2, 0, 2, 3);
+                break; // QUAD
+            case 10:
+                tri(c, 0, 1, 2, 0, 1, 3, 0, 2, 3, 1, 2, 3);
+                break; // TETRA
+            case 12: // HEXAHEDRON
+                tri(c, 0, 1, 2, 0, 2, 3, 4, 6, 5, 4, 7, 6, 0, 4, 5, 0, 5, 1, 1, 5, 6, 1, 6, 2, 2, 6, 7, 2, 7, 3, 3, 7, 4, 3, 4, 0);
+                break;
+            case 13: // WEDGE
+                tri(c, 0, 1, 2, 3, 5, 4, 0, 3, 4, 0, 4, 1, 1, 4, 5, 1, 5, 2, 2, 5, 3, 2, 3, 0);
+                break;
+            case 14: // PYRAMID
+                tri(c, 0, 1, 2, 0, 2, 3, 0, 1, 4, 1, 2, 4, 2, 3, 4, 3, 0, 4);
+                break;
+            default: break; // vertex/line/unknown cells aren't meshes
+        }
+    }
+    while (ti < tokens.length) {
+        const kw = tokens[ti++].toUpperCase();
+        if (kw === "POINTS") {
+            const n = parseInt(tokens[ti++], 10);
+            ti++; // datatype token
+            assertCount("vtk points", n, MAX_VERTEX_COUNT);
+            for (let i = 0; i < n * 3; i++)
+                positions.push(parseFloat(tokens[ti++]));
+        }
+        else if (kw === "POLYGONS" || kw === "TRIANGLE_STRIPS") {
+            const n = parseInt(tokens[ti++], 10);
+            ti++; // total index count
+            assertCount("vtk polygons", n, MAX_FACE_COUNT);
+            if (kw === "POLYGONS") {
+                for (let i = 0; i < n; i++) {
+                    const k = parseInt(tokens[ti++], 10);
+                    const face = [];
+                    for (let j = 0; j < k; j++)
+                        face.push(parseInt(tokens[ti++], 10));
+                    for (let j = 1; j < k - 1; j++) {
+                        indices.push(face[0], face[j], face[j + 1]);
+                    }
+                }
+            }
+            else {
+                // Triangle strips → triangle list.
+                for (let i = 0; i < n; i++) {
+                    const k = parseInt(tokens[ti++], 10);
+                    const strip = [];
+                    for (let j = 0; j < k; j++)
+                        strip.push(parseInt(tokens[ti++], 10));
+                    for (let j = 0; j + 2 < k; j++) {
+                        if (j % 2 === 0)
+                            indices.push(strip[j], strip[j + 1], strip[j + 2]);
+                        else
+                            indices.push(strip[j + 1], strip[j], strip[j + 2]);
+                    }
+                }
+            }
+        }
+        else if (kw === "VERTICES" || kw === "LINES") {
+            // Point/line cells — not renderable as triangles; skip.
+            const n = parseInt(tokens[ti++], 10);
+            const total = parseInt(tokens[ti++], 10);
+            ti += total;
+            if (n > 0)
+                warnings.push(`VTK ${kw.toLowerCase()} skipped (points/lines aren't meshes)`);
+        }
+        else if (kw === "CELLS") {
+            // UNSTRUCTURED_GRID cell connectivity — collect raw index lists;
+            // CELL_TYPES (next section) decides how each becomes triangles.
+            const n = parseInt(tokens[ti++], 10);
+            ti++; // total index count
+            assertCount("vtk cells", n, MAX_FACE_COUNT);
+            for (let i = 0; i < n; i++) {
+                const k = parseInt(tokens[ti++], 10);
+                const cell = [];
+                for (let j = 0; j < k; j++)
+                    cell.push(parseInt(tokens[ti++], 10));
+                pendingCells.push(cell);
+            }
+        }
+        else if (kw === "CELL_TYPES") {
+            const n = parseInt(tokens[ti++], 10);
+            for (let i = 0; i < n; i++) {
+                const type = parseInt(tokens[ti++], 10);
+                const cell = pendingCells[i] ?? [];
+                emitCell(type, cell);
+            }
+            pendingCells.length = 0;
+        }
+        else if (kw === "POINT_DATA" || kw === "CELL_DATA") {
+            pointDataCount = parseInt(tokens[ti++], 10);
+            if (kw === "CELL_DATA")
+                break; // cell attributes don't map to vertices
+        }
+        else if (kw === "NORMALS") {
+            ti++; // name
+            ti++; // datatype
+            for (let i = 0; i < pointDataCount * 3; i++)
+                normals.push(parseFloat(tokens[ti++]));
+        }
+        else if (kw === "TEXTURE_COORDINATES") {
+            ti++; // name
+            const dim = parseInt(tokens[ti++], 10);
+            ti++; // datatype
+            for (let i = 0; i < pointDataCount; i++) {
+                uvs.push(parseFloat(tokens[ti++]));
+                uvs.push(dim >= 2 ? parseFloat(tokens[ti++]) : 0);
+                if (dim >= 3)
+                    ti++;
+            }
+        }
+        else if (kw === "COLOR_SCALARS") {
+            ti++; // name
+            colorComps = parseInt(tokens[ti++], 10);
+            for (let i = 0; i < pointDataCount; i++) {
+                const c = [0, 0, 0, 1];
+                for (let j = 0; j < colorComps; j++)
+                    c[j] = parseFloat(tokens[ti++]);
+                colors.push(c[0], c[1], c[2], c[3]);
+            }
+        }
+        else if (kw === "SCALARS") {
+            const scalarName = tokens[ti++];
+            ti++; // datatype
+            if (tokens[ti] === "1")
+                ti++; // optional numComp
+            // Next keyword is usually LOOKUP_TABLE
+            if (tokens[ti]?.toUpperCase() === "LOOKUP_TABLE") {
+                ti++;
+                const tableName = tokens[ti++];
+                pendingScalars = { name: scalarName, values: new Float32Array(pointDataCount) };
+                for (let i = 0; i < pointDataCount; i++)
+                    pendingScalars.values[i] = parseFloat(tokens[ti++]);
+                scalarLookup = { name: tableName, table: new Float32Array(0), scalarName, values: pendingScalars.values };
+            }
+            else {
+                for (let i = 0; i < pointDataCount; i++)
+                    ti++;
+            }
+        }
+        else if (kw === "LOOKUP_TABLE") {
+            ti++; // name
+            const n = parseInt(tokens[ti++], 10);
+            const table = new Float32Array(n * 4);
+            for (let i = 0; i < n * 4; i++)
+                table[i] = parseFloat(tokens[ti++]);
+            if (scalarLookup && pendingScalars) {
+                scalarLookup.table = table;
+                // Apply table: scalar value [0,1] → rgba
+                for (let i = 0; i < pointDataCount; i++) {
+                    const t = Math.max(0, Math.min(1, pendingScalars.values[i]));
+                    const idx = Math.min(n - 1, Math.floor(t * (n - 1) + 0.5)) * 4;
+                    colors.push(table[idx], table[idx + 1], table[idx + 2], table[idx + 3]);
+                }
+            }
+        }
+        else {
+            // Unknown keyword — stop scanning; trailing sections (VECTORS,
+            // TENSORS, FIELD) are skipped to avoid misreading counts.
+            break;
+        }
+    }
+    const vertexCount = positions.length / 3;
+    if (vertexCount === 0)
+        throw new Error("VTK: no POINTS section");
+    const hasNormals = normals.length === vertexCount * 3;
+    const vertices = new Float32Array(vertexCount * 6);
+    for (let i = 0; i < vertexCount; i++) {
+        vertices[i * 6] = positions[i * 3];
+        vertices[i * 6 + 1] = positions[i * 3 + 1];
+        vertices[i * 6 + 2] = positions[i * 3 + 2];
+        vertices[i * 6 + 3] = hasNormals ? normals[i * 3] : 0;
+        vertices[i * 6 + 4] = hasNormals ? normals[i * 3 + 1] : 0;
+        vertices[i * 6 + 5] = hasNormals ? normals[i * 3 + 2] : 0;
+    }
+    const mesh = {
+        vertices,
+        indices: indices.length > 65535 ? new Uint32Array(indices) : new Uint16Array(indices),
+        vertexCount,
+        indexCount: indices.length,
+        uvs: uvs.length === vertexCount * 2 ? new Float32Array(uvs) : null,
+        colors: colors.length === vertexCount * 4 ? new Float32Array(colors) : null,
+    };
+    const model = { meshes: [mesh], name, format: "vtk" };
+    if (warnings.length > 0)
+        model.warnings = warnings;
+    return model;
+}

package/dist/libraries/navmesh/src/crowd-system.js

@@ -0,0 +1,207 @@
+import { Component } from "@downdraft/engine/ecs/component";
+import { Stage, system } from "@downdraft/engine/ecs/system";
+import { PhysicsTransform } from "@downdraft/engine/physics/body";
+import { SpatialGrid } from "@downdraft/engine/scene/spatial-grid";
+export const NavAgent = Component.register("NavAgent", {
+    radius: 0.4,
+    height: 1.8,
+    maxSpeed: 3.5,
+    acceleration: 10,
+    path: [],
+    pathIndex: 0,
+    velocity: [0, 0, 0],
+    target: null,
+    state: "idle",
+    avoidanceRadius: 2.0,
+    separationWeight: 1.0,
+    alignmentWeight: 0.5,
+    cohesionWeight: 0.3,
+    polyId: -1,
+    repathTimer: 0,
+});
+export class CrowdSystem {
+    navMesh;
+    pathfinder;
+    config;
+    spatialGrid;
+    query = null;
+    world = null;
+    constructor(navMesh, pathfinder, config) {
+        this.navMesh = navMesh;
+        this.pathfinder = pathfinder;
+        this.config = config;
+        this.spatialGrid = new SpatialGrid(config.spatialCellSize ?? 4);
+    }
+    register(world, query) {
+        this.world = world;
+        this.query = query;
+        const self = this;
+        const crowdSys = system("crowd-agents", Stage.Update, (ctx) => {
+            if (!self.query)
+                return;
+            self.spatialGrid.clear();
+            const agents = [];
+            self.query.iterate(ctx.tick, (entity, components) => {
+                const agent = components[0];
+                agents.push({ entity, data: agent });
+                const pos = self.getEntityPosition(entity);
+                if (pos) {
+                    self.spatialGrid.insert({ entity, position: pos, radius: agent.radius, layer: 0 });
+                }
+            });
+            agents.forEach(({ entity, data }) => {
+                self.updateAgent(entity, data, ctx.dt);
+            });
+        }, { queries: [query] });
+        world.schedule.add(crowdSys);
+    }
+    setTarget(entity, target) {
+        if (!this.world)
+            return;
+        const agent = this.world.getComponent(entity, NavAgent.id);
+        if (!agent)
+            return;
+        agent.target = target;
+        agent.state = "seeking";
+        agent.path = this.pathfinder.findPath(this.getEntityPosition(entity) ?? target, target);
+        agent.pathIndex = 0;
+        agent.repathTimer = 0;
+    }
+    updateAgent(entity, agent, dt) {
+        if (agent.state === "idle" || !agent.target)
+            return;
+        const pos = this.getEntityPosition(entity);
+        if (!pos)
+            return;
+        agent.polyId = this.navMesh.findClosestPoly(pos);
+        if (agent.path.length === 0 || agent.pathIndex >= agent.path.length) {
+            agent.state = "arrived";
+            agent.velocity = [0, 0, 0];
+            return;
+        }
+        const waypoint = agent.path[agent.pathIndex];
+        let dx = waypoint[0] - pos[0];
+        let dz = waypoint[2] - pos[2];
+        const distToWaypoint = Math.sqrt(dx * dx + dz * dz);
+        if (distToWaypoint < 0.3) {
+            agent.pathIndex++;
+            if (agent.pathIndex >= agent.path.length) {
+                agent.state = "arrived";
+                agent.velocity = [0, 0, 0];
+                return;
+            }
+            const nextWaypoint = agent.path[agent.pathIndex];
+            dx = nextWaypoint[0] - pos[0];
+            dz = nextWaypoint[2] - pos[2];
+        }
+        const desiredDir = this.normalize([dx, 0, dz]);
+        const desiredVel = [
+            desiredDir[0] * agent.maxSpeed,
+            0,
+            desiredDir[2] * agent.maxSpeed,
+        ];
+        const avoidance = this.computeAvoidance(entity, pos, agent);
+        const steer = [
+            desiredVel[0] * 0.7 + avoidance[0] * 0.3,
+            0,
+            desiredVel[2] * 0.7 + avoidance[2] * 0.3,
+        ];
+        const currentVel = agent.velocity;
+        const accel = agent.acceleration * dt;
+        const newVel = [
+            this.approach(currentVel[0], steer[0], accel),
+            0,
+            this.approach(currentVel[2], steer[2], accel),
+        ];
+        agent.velocity = newVel;
+        const newPos = [
+            pos[0] + newVel[0] * dt,
+            pos[1],
+            pos[2] + newVel[2] * dt,
+        ];
+        if (this.config.terrainSampleFn) {
+            newPos[1] = this.config.terrainSampleFn(newPos[0], newPos[2]);
+        }
+        this.setEntityPosition(entity, newPos);
+        agent.repathTimer += dt;
+        if (agent.repathTimer > 2.0) {
+            agent.repathTimer = 0;
+            const target = agent.target;
+            const distToTarget = Math.sqrt((target[0] - pos[0]) ** 2 + (target[2] - pos[2]) ** 2);
+            if (distToTarget > 1.0) {
+                agent.path = this.pathfinder.findPath(newPos, target);
+                agent.pathIndex = 0;
+            }
+        }
+    }
+    computeAvoidance(entity, pos, agent) {
+        const nearby = this.spatialGrid.queryRadius(pos, agent.avoidanceRadius);
+        let separation = [0, 0, 0];
+        let alignment = [0, 0, 0];
+        let cohesion = [0, 0, 0];
+        let count = 0;
+        for (let _i = 0, _it = nearby, _n = _it.length; _i < _n; _i++) {
+            const entry = _it[_i];
+            if (entry.entity.index === entity.index)
+                continue;
+            const otherAgent = this.world?.getComponent(entry.entity, NavAgent.id);
+            if (!otherAgent)
+                continue;
+            const dx = pos[0] - entry.position[0];
+            const dz = pos[2] - entry.position[2];
+            const distSq = dx * dx + dz * dz;
+            if (distSq < 0.01)
+                continue;
+            const dist = Math.sqrt(distSq);
+            const invDist = 1 / dist;
+            separation[0] += dx * invDist;
+            separation[2] += dz * invDist;
+            alignment[0] += otherAgent.velocity[0];
+            alignment[2] += otherAgent.velocity[2];
+            cohesion[0] += entry.position[0];
+            cohesion[2] += entry.position[2];
+            count++;
+        }
+        if (count === 0)
+            return [0, 0, 0];
+        separation[0] = (separation[0] / count) * agent.separationWeight;
+        separation[2] = (separation[2] / count) * agent.separationWeight;
+        alignment[0] = (alignment[0] / count) * agent.alignmentWeight;
+        alignment[2] = (alignment[2] / count) * agent.alignmentWeight;
+        cohesion[0] = ((cohesion[0] / count) - pos[0]) * agent.cohesionWeight;
+        cohesion[2] = ((cohesion[2] / count) - pos[2]) * agent.cohesionWeight;
+        return [
+            separation[0] + alignment[0] + cohesion[0],
+            0,
+            separation[2] + alignment[2] + cohesion[2],
+        ];
+    }
+    getEntityPosition(entity) {
+        if (!this.world)
+            return null;
+        const transform = this.world.getComponent(entity, PhysicsTransform.id);
+        if (transform)
+            return transform.position;
+        return null;
+    }
+    setEntityPosition(entity, pos) {
+        if (!this.world)
+            return;
+        const transform = this.world.getComponent(entity, PhysicsTransform.id);
+        if (transform) {
+            transform.position = pos;
+        }
+    }
+    normalize(v) {
+        const len = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+        if (len < 0.0001)
+            return [0, 0, 0];
+        return [v[0] / len, v[1] / len, v[2] / len];
+    }
+    approach(current, target, maxDelta) {
+        const diff = target - current;
+        if (Math.abs(diff) <= maxDelta)
+            return target;
+        return current + Math.sign(diff) * maxDelta;
+    }
+}

package/dist/libraries/navmesh/src/debug-viz.js

@@ -0,0 +1,52 @@
+export class NavMeshDebugViz {
+    navMesh;
+    constructor(navMesh) {
+        this.navMesh = navMesh;
+    }
+    getPolygonOutlines() {
+        const lines = [];
+        const color = [0, 1, 0, 0.5];
+        this.navMesh.polygons.forEach((poly) => {
+            const verts = poly.vertexIndices;
+            for (let i = 0; i < verts.length; i++) {
+                const v0 = this.navMesh.getVertex(verts[i]);
+                const v1 = this.navMesh.getVertex(verts[(i + 1) % verts.length]);
+                lines.push({ start: v0, end: v1, color });
+            }
+        });
+        return lines;
+    }
+    getPortalEdges() {
+        const lines = [];
+        const color = [1, 1, 0, 0.8];
+        const seen = new Set();
+        this.navMesh.polygons.forEach((poly) => {
+            for (let _i = 0, _it = poly.portalEdges, _n = _it.length; _i < _n; _i++) {
+                const pe = _it[_i];
+                const key = `${Math.min(pe.fromPoly, pe.toPoly)}:${Math.max(pe.fromPoly, pe.toPoly)}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                lines.push({ start: pe.left, end: pe.right, color });
+            }
+        });
+        return lines;
+    }
+    getPolyCenters() {
+        return this.navMesh.polygons.map((p) => p.centroid);
+    }
+    getAgentPath(path) {
+        const lines = [];
+        const color = [0, 0, 1, 0.9];
+        for (let i = 0; i < path.length - 1; i++) {
+            lines.push({ start: path[i], end: path[i + 1], color });
+        }
+        return lines;
+    }
+    getAllDebugData() {
+        return {
+            lines: [...this.getPolygonOutlines(), ...this.getPortalEdges()],
+            centers: this.getPolyCenters(),
+        };
+    }
+}

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

@@ -0,0 +1,7 @@
+export { CrowdSystem, NavAgent } from "./crowd-system.js";
+export { NavMeshDebugViz } from "./debug-viz.js";
+export { NavMesh } from "./navmesh.js";
+export { NavMeshGenerator } from "./navmesh-generator.js";
+export { Pathfinder } from "./pathfinder.js";
+// Declarative library descriptor
+export { NavmeshLib, NavmeshTok, PathfinderTok } from "./library.js";

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

@@ -0,0 +1,47 @@
+// ============================================================================
+// NavmeshLib — declarative engine library descriptor for @downdraft/engine/libraries/navmesh
+//
+// Games declare `libraries: [NavmeshLib]` (or with config override) in their
+// GameModule. The host creates the NavMesh + Pathfinder (sim-side) and
+// exposes them via typed tokens.
+//
+// Games that need full control can still import NavMesh, Pathfinder, and
+// CrowdSystem directly (escape hatch).
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { NavMesh } from "./navmesh.js";
+import { Pathfinder } from "./pathfinder.js";
+// ── Typed tokens (DI) ──
+/** Token for the sim-side navigation mesh. Inject in sim systems that need pathfinding. */
+export const NavmeshTok = resourceToken("navmesh:mesh");
+/** Token for the sim-side pathfinder. Inject in sim systems that need path queries. */
+export const PathfinderTok = resourceToken("navmesh:pathfinder");
+// ── Descriptor ──
+export const NavmeshLib = {
+    name: "navmesh",
+    version: "1.0.0",
+    provides: [NavmeshTok, PathfinderTok],
+    sim: {
+        create(config, ctx) {
+            const cellSize = config.spatialCellSize ?? 4;
+            const navMesh = new NavMesh(cellSize);
+            const pathfinder = new Pathfinder(navMesh);
+            ctx.provide(NavmeshTok, navMesh);
+            ctx.provide(PathfinderTok, pathfinder);
+            return { navMesh, pathfinder };
+        },
+        dispose(system) {
+            const { navMesh } = system;
+            // NavMesh holds only JS arrays/typed arrays — clear them to release memory.
+            navMesh.clear();
+        },
+        // tick is game-specific (calls crowdSystem.register() + setTarget() per
+        // agent, repathing, etc.) — games wire this via onReady.
+    },
+    tickPhase: "post-physics",
+    // No renderer setup — navmesh debug viz is game-specific (the game creates
+    // a NavMeshDebugViz pass if needed).
+    defaultConfig: {
+        spatialCellSize: 4,
+    },
+};