@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/styles/voxel/geometry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Voxel meshes on the GPU: a greedy-meshed VoxelMesh as a three.js
+ * BufferGeometry (positions, flat normals, linear vertex colours with the
+ * occlusion baked in, and each vertex's rigid part), and the material every
+ * voxel thing in the style draws with.
+ */
+import { BufferGeometry, MeshStandardNodeMaterial } from "three/webgpu";
+import type { VoxelMesh } from "./core.js";
+/** A BufferGeometry from a greedy-meshed grid. `voxelPart` holds each vertex's part when there is more than one. */
+export declare function voxelGeometry(mesh: VoxelMesh, opts?: {
+    parts?: boolean;
+}): BufferGeometry;
+export interface VoxelMaterialOptions {
+    /** Glow colour (0 = none) and strength. */
+    readonly emissive?: number;
+    readonly emissiveIntensity?: number;
+    /** Default 0.85: voxel art reads matte. */
+    readonly roughness?: number;
+    readonly transparent?: boolean;
+    readonly opacity?: number;
+}
+/**
+ * The style's material: vertex colours (occlusion baked in), matte, no
+ * texture. A node material, so crowds and particles can drive its position
+ * and emissive nodes.
+ */
+export declare function voxelMaterial(opts?: VoxelMaterialOptions): MeshStandardNodeMaterial;

package/dist/runtime/styles/voxel/geometry.js

@@ -0,0 +1,40 @@
+/**
+ * Voxel meshes on the GPU: a greedy-meshed VoxelMesh as a three.js
+ * BufferGeometry (positions, flat normals, linear vertex colours with the
+ * occlusion baked in, and each vertex's rigid part), and the material every
+ * voxel thing in the style draws with.
+ */
+import { BufferAttribute, BufferGeometry, Color, MeshStandardNodeMaterial } from "three/webgpu";
+/** A BufferGeometry from a greedy-meshed grid. `voxelPart` holds each vertex's part when there is more than one. */
+export function voxelGeometry(mesh, opts = {}) {
+    const g = new BufferGeometry();
+    g.setAttribute("position", new BufferAttribute(mesh.positions, 3));
+    g.setAttribute("normal", new BufferAttribute(mesh.normals, 3));
+    g.setAttribute("color", new BufferAttribute(mesh.colors, 3));
+    if (opts.parts)
+        g.setAttribute("voxelPart", new BufferAttribute(new Float32Array(mesh.parts), 1));
+    const vertices = mesh.positions.length / 3;
+    g.setIndex(new BufferAttribute(vertices < 65536 ? new Uint16Array(mesh.indices) : mesh.indices, 1));
+    g.computeBoundingBox();
+    g.computeBoundingSphere();
+    return g;
+}
+/**
+ * The style's material: vertex colours (occlusion baked in), matte, no
+ * texture. A node material, so crowds and particles can drive its position
+ * and emissive nodes.
+ */
+export function voxelMaterial(opts = {}) {
+    const m = new MeshStandardNodeMaterial();
+    m.vertexColors = true;
+    m.roughness = opts.roughness ?? 0.85;
+    m.metalness = 0;
+    m.color = new Color(1, 1, 1);
+    m.emissive = new Color(opts.emissive ?? 0);
+    m.emissiveIntensity = opts.emissiveIntensity ?? 1;
+    if (opts.transparent) {
+        m.transparent = true;
+        m.opacity = opts.opacity ?? 1;
+    }
+    return m;
+}

package/dist/runtime/styles/voxel/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The voxel art style: chunky cube-built worlds and
+ * characters. Library models are rebuilt as voxels at library build time
+ * (rigid parts on their bones, occlusion baked per face); this module is the
+ * runtime half: the voxel core, voxel geometry and material, procedural
+ * pickups and scenery, the voxel world builders, cube particles with
+ * voxel-shatter deaths, rigid-part crowds, and the style's look.
+ */
+import type { BufferGeometry, MeshStandardNodeMaterial } from "three/webgpu";
+export * from "./core.js";
+export * from "./geometry.js";
+export * from "./shapes.js";
+export * from "./world.js";
+export * from "./props.js";
+export * from "./look.js";
+export { voxelKit } from "./kit.js";
+/** A procedural voxel pickup (library source `{ procedural: "voxel_<name>" }`): geometry centred on the origin and a glowing material. */
+export declare function voxelPickup(name: string): {
+    geometry: BufferGeometry;
+    material: MeshStandardNodeMaterial;
+} | null;

package/dist/runtime/styles/voxel/index.js

@@ -0,0 +1,23 @@
+import { greedyMesh } from "./core.js";
+import { voxelGeometry, voxelMaterial } from "./geometry.js";
+import { pickupGrid } from "./shapes.js";
+export * from "./core.js";
+export * from "./geometry.js";
+export * from "./shapes.js";
+export * from "./world.js";
+export * from "./props.js";
+export * from "./look.js";
+export { voxelKit } from "./kit.js";
+/** A procedural voxel pickup (library source `{ procedural: "voxel_<name>" }`): geometry centred on the origin and a glowing material. */
+export function voxelPickup(name) {
+    const p = pickupGrid(name);
+    if (!p)
+        return null;
+    const geometry = voxelGeometry(greedyMesh(p.grid, { splitParts: false }));
+    geometry.computeBoundingBox();
+    const box = geometry.boundingBox;
+    // Centre on the origin like the low-poly pickups (they bob around their middle).
+    if (box)
+        geometry.translate(0, -(box.min.y + box.max.y) / 2, 0);
+    return { geometry, material: voxelMaterial({ emissive: p.glow, emissiveIntensity: 0.9, roughness: 0.4 }) };
+}

package/dist/runtime/styles/voxel/kit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The voxel style's kit: what a template asks for when a game plays in
+ * `style: "voxel"`.
+ */
+import type { StyleKit } from "../kit.js";
+export declare const voxelKit: StyleKit;

package/dist/runtime/styles/voxel/kit.js

@@ -0,0 +1,11 @@
+import { voxelStack } from "./look.js";
+import { voxelShape } from "./props.js";
+import { voxelField, voxelPillar, terrainHeight } from "./world.js";
+export const voxelKit = {
+    id: "voxel",
+    stack: (preset) => voxelStack(preset),
+    field: (spec) => voxelField(spec, spec.pillars ?? []),
+    groundHeight: (spec, x, z) => terrainHeight(spec, x, z),
+    pillar: (spec, theme, index) => voxelPillar(spec, theme, index),
+    shape: (name) => voxelShape(name),
+};

package/dist/runtime/styles/voxel/look.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The voxel style's light and grade. Cubes read by their faces: a strong,
+ * lower key light makes tops bright and sides a step darker, a weaker sky
+ * fill keeps the shadow side from going flat, and a gentler exposure and
+ * saturation keep the saturated voxel palettes from blowing out to white
+ * under the night grade's bloom.
+ */
+import type { LookPreset } from "../../render/presets.js";
+import type { StyleStack } from "../kit.js";
+export declare function voxelStack(preset: LookPreset): StyleStack;

package/dist/runtime/styles/voxel/look.js

@@ -0,0 +1,16 @@
+export function voxelStack(preset) {
+    // The key comes from the camera's left and a little behind, so the faces a top-down camera sees are lit unevenly.
+    const sunDir = [-0.6, 0.72, 0.42];
+    switch (preset) {
+        case "night":
+            return {
+                shadows: true,
+                lighting: { hemi: 1.45, sky: 0x8ea0e6, ground: 0x2a2416, sun: 0xd2dcff, sunIntensity: 3.9, sunDir, ambient: 0.22, shadowStrength: 0.62 },
+                grade: { exposure: 1.1, saturation: 1.02, contrast: 1.1, bloomThreshold: 0.92 },
+            };
+        case "dusk":
+            return { shadows: true, lighting: { sunDir, shadowStrength: 0.6 }, grade: { saturation: 1.0, bloomThreshold: 0.92 } };
+        default:
+            return { shadows: true, lighting: { sunDir, shadowStrength: 0.55 } };
+    }
+}

package/dist/runtime/styles/voxel/props.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Template machinery shapes in voxels (StyleKit.shape): the debris chunk a
+ * kill throws (one cube, so a death reads as a model breaking into voxels),
+ * loose field rocks and cut stumps. Each is centred on the origin, like the
+ * primitives a template draws them with, and built once.
+ */
+import type { StyleShape, StyleShapeName } from "../kit.js";
+/** A machinery shape in voxels, or null to keep the template's own. */
+export declare function voxelShape(name: StyleShapeName): StyleShape | null;

package/dist/runtime/styles/voxel/props.js

@@ -0,0 +1,52 @@
+import { fillWhere, greedyMesh, hash3, jitter, VoxelGrid } from "./core.js";
+import { voxelGeometry, voxelMaterial } from "./geometry.js";
+/** Grid centred on the origin in all three axes. */
+function centred(nx, ny, nz, size) {
+    return new VoxelGrid(nx, ny, nz, size, [(-nx * size) / 2, (-ny * size) / 2, (-nz * size) / 2]);
+}
+/** One cube about as big as the unit dodecahedron it replaces; white, so the instance colour is the chunk's colour. */
+function chunk() {
+    const g = centred(1, 1, 1, 1.25);
+    g.set(0, 0, 0, 0xffffff);
+    return g;
+}
+/** A lumpy boulder (half size about 0.5 m) in warm field stone with a mossy cap. */
+function rock() {
+    const n = 8;
+    const g = centred(n, 7, n, 0.125);
+    const c = n / 2;
+    fillWhere(g, (x, y, z) => {
+        const dx = (x - c) / 4;
+        const dy = (y - 3.5) / 3.5;
+        const dz = (z - c) / 4;
+        return dx * dx + dy * dy * 1.1 + dz * dz < 1 - (hash3(Math.floor(x), Math.floor(y), Math.floor(z), 61) - 0.5) * 0.35;
+    }, (x, y, z) => (y >= 5 && hash3(x, y, z, 63) < 0.55 ? jitter(0x4f6f3a, x, y, z, 0.08, 65) : jitter(0x7c7466, x, y, z, 0.1, 67)));
+    return g;
+}
+/** A cut stump (radius about 0.36 m, 0.9 m tall): bark rings and a pale cut top. */
+function stump() {
+    const n = 6;
+    const g = centred(n, 7, n, 0.125);
+    const c = n / 2;
+    fillWhere(g, (x, _y, z) => Math.hypot(x - c, z - c) < 2.9, (x, y, z) => {
+        const r = Math.hypot(x + 0.5 - c, z + 0.5 - c);
+        if (y === 6)
+            return r < 1.6 ? jitter(0xc9a46c, x, y, z, 0.06, 71) : 0x8a6440;
+        return jitter((y & 1) === 0 ? 0x5c4430 : 0x4e3a28, x, y, z, 0.08, 73);
+    });
+    return g;
+}
+const BUILDERS = { chunk, rock, stump };
+const cache = new Map();
+/** A machinery shape in voxels, or null to keep the template's own. */
+export function voxelShape(name) {
+    const hit = cache.get(name);
+    if (hit)
+        return hit;
+    const build = BUILDERS[name];
+    if (!build)
+        return null;
+    const shape = { geometry: voxelGeometry(greedyMesh(build(), { splitParts: false })), material: voxelMaterial({ roughness: 0.8 }) };
+    cache.set(name, shape);
+    return shape;
+}

package/dist/runtime/styles/voxel/shapes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Procedural voxel models the style builds at load (no file): pickups and
+ * scenery. Pure: each returns a VoxelGrid, the caller meshes it. Every
+ * colour varies a little per voxel (a seeded hash), so faces read as stacked
+ * cubes rather than flat plastic.
+ */
+import { VoxelGrid } from "./core.js";
+declare const GEMS: {
+    readonly small: {
+        readonly r: 2;
+        readonly light: 16765803;
+        readonly dark: 14714396;
+        readonly size: 0.075;
+    };
+    readonly mid: {
+        readonly r: 3;
+        readonly light: 10478847;
+        readonly dark: 3112920;
+        readonly size: 0.07;
+    };
+    readonly large: {
+        readonly r: 4;
+        readonly light: 16754406;
+        readonly dark: 13052047;
+        readonly size: 0.085;
+    };
+};
+/** A faceted voxel gem: a double pyramid, light on its upper faces, dark below, one bright glint. */
+export declare function gemGrid(kind: keyof typeof GEMS): VoxelGrid;
+/** A chunky plus sign: the universal heal. */
+export declare function crossGrid(color?: number): VoxelGrid;
+/** An energy cell: a squat battery with a bright core band. */
+export declare function cellGrid(color?: number): VoxelGrid;
+/** A little cluster of flames for braziers and campfires: hot core, orange tongues, red tips. */
+export declare function flameGrid(seed?: number): VoxelGrid;
+/** Pickups by procedural library name (style.voxel.gem_small is `voxel_gem_small`). */
+export declare function pickupGrid(name: string): {
+    grid: VoxelGrid;
+    glow: number;
+} | null;
+export {};

package/dist/runtime/styles/voxel/shapes.js

@@ -0,0 +1,83 @@
+/**
+ * Procedural voxel models the style builds at load (no file): pickups and
+ * scenery. Pure: each returns a VoxelGrid, the caller meshes it. Every
+ * colour varies a little per voxel (a seeded hash), so faces read as stacked
+ * cubes rather than flat plastic.
+ */
+import { fillWhere, hash3, jitter, mixRgb, shadeRgb, VoxelGrid } from "./core.js";
+/** Grid centred on x and z, standing on y = 0. */
+function centred(nx, ny, nz, size) {
+    return new VoxelGrid(nx, ny, nz, size, [(-nx * size) / 2, 0, (-nz * size) / 2]);
+}
+const GEMS = {
+    small: { r: 2, light: 0xffd36b, dark: 0xe0861c, size: 0.075 },
+    mid: { r: 3, light: 0x9fe4ff, dark: 0x2f7fd8, size: 0.07 },
+    large: { r: 4, light: 0xffa6e6, dark: 0xc7288f, size: 0.085 },
+};
+/** A faceted voxel gem: a double pyramid, light on its upper faces, dark below, one bright glint. */
+export function gemGrid(kind) {
+    const g = GEMS[kind];
+    const n = g.r * 2 + 1;
+    const h = g.r * 2 + 3;
+    const grid = centred(n, h, n, g.size);
+    const cx = n / 2;
+    const cy = h / 2;
+    fillWhere(grid, (x, y, z) => Math.abs(x - cx) + Math.abs(z - cx) + Math.abs(y - cy) * (g.r / (h / 2)) <= g.r + 0.5, (x, y, z) => {
+        const up = y + 0.5 > cy;
+        const base = up ? g.light : g.dark;
+        const glint = up && x === Math.floor(cx) - 1 && z === Math.floor(cx) && y === Math.floor(cy) + 1;
+        return glint ? 0xffffff : jitter(base, x, y, z, 0.07, 3);
+    });
+    return grid;
+}
+/** A chunky plus sign: the universal heal. */
+export function crossGrid(color = 0x5dff7a) {
+    const grid = centred(7, 7, 3, 0.085);
+    fillWhere(grid, (x, y) => (x > 2 && x < 5) || (y > 2 && y < 5), (x, y, z) => {
+        if (x === 3 && y === 3)
+            return 0xeaffe8;
+        const end = x === 0 || x === 6 || y === 0 || y === 6;
+        return jitter(end ? shadeRgb(color, 0.82) : color, x, y, z, 0.06, 5);
+    });
+    return grid;
+}
+/** An energy cell: a squat battery with a bright core band. */
+export function cellGrid(color = 0x6fd3ff) {
+    const grid = centred(5, 7, 5, 0.075);
+    fillWhere(grid, (x, y, z) => (y < 6 ? Math.abs(x - 2.5) < 2.2 && Math.abs(z - 2.5) < 2.2 : Math.abs(x - 2.5) < 1 && Math.abs(z - 2.5) < 1), (x, y, z) => (y === 6 ? 0xd8dde4 : y === 2 || y === 3 ? mixRgb(color, 0xffffff, 0.45) : jitter(shadeRgb(color, 0.75), x, y, z, 0.06, 7)));
+    return grid;
+}
+/** A little cluster of flames for braziers and campfires: hot core, orange tongues, red tips. */
+export function flameGrid(seed = 1) {
+    const grid = centred(5, 7, 5, 0.12);
+    fillWhere(grid, (x, y, z) => {
+        const r = Math.hypot(x - 2.5, z - 2.5);
+        const reach = 2.4 - y * 0.34 + (hash3(Math.floor(x), 0, Math.floor(z), seed) - 0.5) * 1.2;
+        return r < reach;
+    }, (x, y, z) => {
+        const r = Math.hypot(x + 0.5 - 2.5, z + 0.5 - 2.5);
+        if (y < 2 && r < 1.2)
+            return 0xfff2b0;
+        if (y < 4)
+            return jitter(0xffa031, x, y, z, 0.08, seed);
+        return jitter(0xff5a1f, x, y, z, 0.08, seed);
+    });
+    return grid;
+}
+/** Pickups by procedural library name (style.voxel.gem_small is `voxel_gem_small`). */
+export function pickupGrid(name) {
+    switch (name) {
+        case "gem_small":
+            return { grid: gemGrid("small"), glow: 0xff9a1f };
+        case "gem_mid":
+            return { grid: gemGrid("mid"), glow: 0x2f8fff };
+        case "gem_large":
+            return { grid: gemGrid("large"), glow: 0xff3fb8 };
+        case "cell_heal":
+            return { grid: crossGrid(), glow: 0x2bff6a };
+        case "cell_spark":
+            return { grid: cellGrid(), glow: 0x1e9bff };
+        default:
+            return null;
+    }
+}

package/dist/runtime/styles/voxel/world.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Voxel worlds: the play field's floor, terraced ground past the wall, a
+ * stone (or steel) wall, pillars with a voxel flame, and ground clutter.
+ *
+ * Static voxel scenery is greedy-meshed with occlusion baked into vertex
+ * colours, and the material adds a per-voxel shade from the voxel's world
+ * cell (a hash), so large merged faces still read as stacked cubes without
+ * costing a quad per voxel. The floor is one plane painted per cell the same
+ * way, and every placement is seeded, so every client sees the same world.
+ */
+import { MeshStandardNodeMaterial } from "three/webgpu";
+import type { Object3D } from "three/webgpu";
+import type { FieldSpec, PillarSpec, StyledPillar, WorldTheme } from "../kit.js";
+/** Floor cell (and terrain voxel), m. */
+export declare const WORLD_CELL = 0.5;
+/** Palettes per theme (sRGB). */
+export interface WorldPalette {
+    readonly grass: readonly number[];
+    readonly dirt: readonly number[];
+    readonly stone: readonly number[];
+    readonly moss: number;
+    readonly path: readonly number[];
+    readonly flowers: readonly number[];
+}
+export declare function paletteFor(theme: WorldTheme): WorldPalette;
+/**
+ * The material for greedy-meshed static voxels: vertex colours (occlusion
+ * baked) times a per-voxel shade from the voxel's world cell, and a faint
+ * darkening along each voxel's edges so merged faces still show their cubes.
+ */
+export declare function voxelWorldMaterial(opts?: {
+    cell: number;
+    jitter?: number;
+    edge?: number;
+    roughness?: number;
+}): MeshStandardNodeMaterial;
+/**
+ * Height of the voxel ground at (x, z), m: flat inside the field and for a
+ * strip past the wall, then terraces that climb away from it in whole
+ * voxels. Scenery standing outside the wall uses it to stand on the ground.
+ */
+export declare function terrainHeight(spec: Pick<FieldSpec, "half" | "theme">, x: number, z: number): number;
+/**
+ * The whole field: the painted floor, terraced ground past the wall, the
+ * wall, and ground clutter. Returns meshes to add to the scene.
+ */
+export declare function voxelField(spec: FieldSpec, pillars?: readonly PillarSpec[]): Object3D[];
+/** A stone column of rough courses with a capital, an iron brazier and a voxel flame (meadow); a steel post with a lamp (yard). */
+export declare function voxelPillar(spec: PillarSpec, theme: WorldTheme, index: number): StyledPillar;