@netforge/engine 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,167 @@
+/**
+ * The pixel art style. The scene renders into a
+ * low-resolution target, one pixel of it per sprite texel at the camera's
+ * focus, and every pixel goes to the screen as a hard square block: no
+ * filtering, no blur, one pixel scale for the whole picture. The colour is
+ * then snapped to the style's 16-colour palette (the library build snaps
+ * the sprites to the same one) with a 4x4 ordered dither, so lit 3D ground,
+ * walls and effects read as one piece of pixel art with the sprites.
+ *
+ * Sprites (render/sprite.ts) are resized by `spriteScale` here each frame,
+ * so a sprite texel is exactly one low-resolution pixel.
+ */
+import { RenderPipeline, Vector2, Vector3 } from "three/webgpu";
+import { dot, float, floor, fract, length, mix, mrt, output, pass, renderOutput, screenUV, smoothstep, uniform, vec2, vec3, vec4 } from "three/tsl";
+import { SPRITE_TEXEL, spriteScale } from "../../render/sprite.js";
+/**
+ * The pixel style's palette (DawnBringer 16). The asset library's
+ * manifest/pixel.json carries the same list; its test keeps them equal.
+ */
+export const PIXEL_PALETTE = [
+    "#140c1c",
+    "#442434",
+    "#30346d",
+    "#4e4a4e",
+    "#854c30",
+    "#346524",
+    "#d04648",
+    "#757161",
+    "#597dce",
+    "#d27d2c",
+    "#8595a1",
+    "#6daa2c",
+    "#d2aa99",
+    "#6dc2ca",
+    "#dad45e",
+    "#deeed6",
+];
+/**
+ * The integer block size (screen pixels per low-res pixel) that puts
+ * `texelsPerMetre` low-res rows on each metre of a view `viewMetres` tall.
+ */
+export function pixelBlock(bufferHeight, viewMetres, texelsPerMetre, minRows = 120) {
+    const rows = Math.max(minRows, viewMetres * texelsPerMetre);
+    return Math.max(1, Math.round(bufferHeight / rows));
+}
+/** Height in metres the camera sees at the ground point it looks at (perspective cameras; orthographic: its frustum). */
+export function viewMetres(camera, forward, position) {
+    const cam = camera;
+    if (cam.isOrthographicCamera)
+        return (cam.top - cam.bottom) / (cam.zoom || 1);
+    const down = Math.max(0.15, -forward.y);
+    const dist = Math.max(1, position.y / down);
+    return 2 * dist * Math.tan(((cam.fov || 50) * Math.PI) / 360);
+}
+function hex(c) {
+    const n = parseInt(c.slice(1), 16);
+    return new Vector3(((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255);
+}
+/** 4x4 Bayer threshold, 0..1, for an integer pixel cell. */
+function bayer4(cell) {
+    const b2 = (a) => {
+        const f = floor(a);
+        return fract(dot(f, vec2(0.5, f.y.mul(0.75))));
+    };
+    return b2(cell.mul(0.5)).mul(0.25).add(b2(cell));
+}
+/** Nearest palette colour (weighted RGB), by a chain of compares. */
+function nearest(c, palette) {
+    const w = vec3(0.3, 0.59, 0.11);
+    let best = vec3(palette[0] ?? new Vector3());
+    let bestD = float(1e9);
+    for (const p of palette) {
+        const d = c.sub(vec3(p));
+        const dist = dot(d.mul(d), w);
+        const closer = dist.lessThan(bestD);
+        best = closer.select(vec3(p), best);
+        bestD = closer.select(dist, bestD);
+    }
+    return best;
+}
+class PixelSession {
+    ctx;
+    opts;
+    pipeline;
+    scenePass;
+    low = uniform(new Vector2(320, 180));
+    buffer = new Vector2();
+    forward = new Vector3();
+    position = new Vector3();
+    block = 0;
+    constructor(ctx, opts) {
+        this.ctx = ctx;
+        this.opts = opts;
+        this.pipeline = new RenderPipeline(ctx.renderer);
+        this.pipeline.outputColorTransform = false;
+        this.scenePass = pass(ctx.scene, ctx.camera);
+        // Sprites tag themselves (render/sprite.ts SPRITE_MRT); everything else is the 3D world.
+        this.scenePass.setMRT(mrt({ output, sprite: float(0) }));
+        const color = this.scenePass.getTextureNode("output");
+        const spriteTag = this.scenePass.getTextureNode("sprite");
+        // One sample at the centre of the low-res pixel under this screen pixel: hard square blocks.
+        const cell = floor(screenUV.mul(this.low));
+        const at = cell.add(0.5).div(this.low);
+        let c = color.sample(at).rgb;
+        // The stack's hurt pulse, in low-res pixel steps (no vignette: it would ring the field).
+        const post = ctx.post;
+        if (post) {
+            const d = length(at.sub(0.5)).mul(1.414);
+            const hurtEdge = smoothstep(0.45, 1.15, d).mul(post.hurt).mul(0.85);
+            c = mix(c, c.mul(vec3(1.25, 0.35, 0.3)).add(vec3(0.22, 0, 0)), hurtEdge);
+        }
+        const toned = renderOutput(vec4(c, 1)).rgb;
+        const luma = dot(toned, vec3(0.299, 0.587, 0.114));
+        // Sprites: their own palette colours, a little more saturated, no dither.
+        const vivid = mix(vec3(luma), toned, this.opts.saturation);
+        const sprite = nearest(vivid, PIXEL_PALETTE.map(hex));
+        // The world: a few flat light bands. The dark field is two calm, mossy tones; light pools step up
+        // in at most three warm bands; the band edges get a light ordered dither.
+        const chroma = toned.div(luma.max(0.02));
+        const l = luma.add(bayer4(cell).sub(0.5).mul(this.opts.dither));
+        const bands = this.opts.bands;
+        let level = float(bands[0] ?? 0.08);
+        for (let i = 1; i < bands.length; i++) {
+            const lo = bands[i - 1] ?? 0;
+            const hi = bands[i] ?? 1;
+            level = l.greaterThan((lo + hi) / 2).select(float(hi), level);
+        }
+        const lit = level.greaterThan(bands[1] ?? 0.16);
+        const fieldTint = vec3(0.86, 1, 0.9);
+        const hue = lit.select(mix(vec3(1), chroma, 1.15), mix(fieldTint, chroma, 0.25));
+        const world = hue.mul(level).min(vec3(1));
+        this.pipeline.outputNode = vec4(spriteTag.sample(at).r.greaterThan(0.5).select(sprite, world), 1);
+    }
+    /** Fit the block size to the canvas and the camera's view, and resize the sprites to match. */
+    fit() {
+        const { renderer, camera } = this.ctx;
+        renderer.getDrawingBufferSize(this.buffer);
+        camera.getWorldDirection(this.forward);
+        camera.getWorldPosition(this.position);
+        const metres = viewMetres(camera, this.forward, this.position);
+        const block = pixelBlock(this.buffer.y, metres, this.opts.texelsPerMetre, this.opts.minRows);
+        if (block !== this.block) {
+            this.block = block;
+            this.scenePass.setResolutionScale(1 / block);
+        }
+        // The same float steps PassNode takes, so the sampled cells match its target exactly.
+        const w = Math.max(1, Math.floor(this.buffer.x * (1 / block)));
+        const h = Math.max(1, Math.floor(this.buffer.y * (1 / block)));
+        this.low.value.set(w, h);
+        // A sprite texel is one low-res pixel at the focus.
+        spriteScale.value = metres / h / SPRITE_TEXEL;
+    }
+    render() {
+        this.fit();
+        this.pipeline.render();
+    }
+    dispose() {
+        spriteScale.value = 1;
+        this.pipeline.dispose();
+    }
+}
+/** The pixel style with its options. */
+export function createPixelStyle(o = {}) {
+    const opts = { texelsPerMetre: o.texelsPerMetre ?? 1 / SPRITE_TEXEL, dither: o.dither ?? 0.025, saturation: o.saturation ?? 1.25, bands: o.bands ?? [0.08, 0.14, 0.3, 0.52, 0.82], minRows: o.minRows ?? 120 };
+    return { id: "pixel", attach: (ctx) => new PixelSession(ctx, opts) };
+}
+export const pixelKit = createPixelStyle();

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

@@ -0,0 +1,29 @@
+/**
+ * PS1-retro: the 1996-1999 console look, through the normal runtime.
+ *
+ *  - The scene draws at about 240 lines (crisp blocks, whole device pixels
+ *    each), no anti-aliasing, and leaves the screen as 15-bit colour
+ *    through the console's 4x4 ordered dither (pipeline.ts).
+ *  - Vertices snap to that pixel grid, textures map affinely and sample
+ *    nearest at console sizes, lit materials light per vertex with smooth
+ *    Gouraud normals and no specular (materials.ts, lights.ts).
+ *  - Tagged template surfaces get CC0 128 px textures from the library
+ *    (surfaces.ts); fog comes in closer (a short draw distance).
+ *
+ * A template opts in by naming the style in createRenderStack (or calling
+ * `styleKit("ps1").attach(...)` when it draws with renderer.render).
+ */
+import type { StyleKit, StyleSession } from "../kit.js";
+import { VertexLights } from "./lights.js";
+import { Ps1Patcher } from "./materials.js";
+import { Ps1Pipeline } from "./pipeline.js";
+export { VertexLights, MAX_POINT_LIGHTS } from "./lights.js";
+export { Ps1Patcher, tessellate } from "./materials.js";
+export { Ps1Pipeline, blockGrid } from "./pipeline.js";
+export { Ps1Surfaces, SURFACES, surfaceRole } from "./surfaces.js";
+export interface Ps1Session extends StyleSession {
+    readonly pipeline: Ps1Pipeline;
+    readonly patcher: Ps1Patcher;
+    readonly lights: VertexLights;
+}
+export declare const ps1Kit: StyleKit;

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

@@ -0,0 +1,41 @@
+import { VertexLights } from "./lights.js";
+import { Ps1Patcher } from "./materials.js";
+import { Ps1Pipeline } from "./pipeline.js";
+import { Ps1Surfaces } from "./surfaces.js";
+export { VertexLights, MAX_POINT_LIGHTS } from "./lights.js";
+export { Ps1Patcher, tessellate } from "./materials.js";
+export { Ps1Pipeline, blockGrid } from "./pipeline.js";
+export { Ps1Surfaces, SURFACES, surfaceRole } from "./surfaces.js";
+/** Fog pulls in to this share of the template's distances (a short draw distance). */
+const FOG_PULL = 0.6;
+export const ps1Kit = {
+    id: "ps1",
+    attach(ctx) {
+        const { handle, scene, camera } = ctx;
+        const lights = new VertexLights();
+        const pipeline = new Ps1Pipeline(handle.renderer, scene, camera, ctx.post);
+        const surfaces = new Ps1Surfaces(ctx.resolve);
+        const patcher = new Ps1Patcher(lights, pipeline.resolution, (role) => surfaces.get(role));
+        if (ctx.atmosphere) {
+            ctx.atmosphere.near.value *= FOG_PULL;
+            ctx.atmosphere.far.value *= FOG_PULL;
+        }
+        const r = {
+            pipeline,
+            patcher,
+            lights,
+            // The pipeline draws the whole frame (the stack's own post only lends its grade).
+            render() {
+                patcher.scan(scene);
+                lights.update(scene, camera, performance.now());
+                pipeline.render();
+            },
+            // No setSize: the pipeline fits itself to the drawing buffer each frame.
+            dispose() {
+                pipeline.dispose();
+                surfaces.dispose();
+            },
+        };
+        return r;
+    },
+};

package/dist/runtime/styles/ps1/lights.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-vertex (Gouraud) lighting for the PS1 style. The scene's own lights
+ * (ambient, hemisphere, directional and point lights the templates and the
+ * LightingRig add) are gathered once a frame into a few shared uniforms, and
+ * every styled material lights its vertices from them in the vertex stage.
+ * Big triangles therefore light like a 1997 console: blotchy lantern pools
+ * on a coarse ground grid, smooth ramps across a character, no specular.
+ *
+ * The maths follows three.js's physical Lambert (irradiance x albedo / pi,
+ * same point-light falloff), so a scene keeps its brightness when it
+ * switches style.
+ */
+import { Vector3, Vector4 } from "three/webgpu";
+import type { Camera, Node, Scene } from "three/webgpu";
+/** Point lights each vertex sums (the nearest to the camera). */
+export declare const MAX_POINT_LIGHTS = 8;
+/** Directional lights (sun, moon, rim). */
+export declare const MAX_DIR_LIGHTS = 2;
+export declare class VertexLights {
+    /** Ambient irradiance (colour x intensity, summed). */
+    readonly ambient: import("three/webgpu").UniformNode<"vec3", Vector3>;
+    readonly hemiSky: import("three/webgpu").UniformNode<"vec3", Vector3>;
+    readonly hemiGround: import("three/webgpu").UniformNode<"vec3", Vector3>;
+    /** xyz: direction toward the light (world). */
+    readonly dirDir: import("three/webgpu").UniformNode<"vec4", Vector4>[];
+    /** rgb: colour x intensity. */
+    readonly dirColor: import("three/webgpu").UniformNode<"vec4", Vector4>[];
+    /** xyz: position (world), w: cutoff distance (0 = none). */
+    readonly pointPos: import("three/webgpu").UniformNode<"vec4", Vector4>[];
+    /** rgb: colour x intensity, w: decay exponent. */
+    readonly pointColor: import("three/webgpu").UniformNode<"vec4", Vector4>[];
+    /** Overall gain on the vertex light (1 = three.js's physical Lambert). */
+    readonly gain: import("three/webgpu").UniformNode<"float", number>;
+    /** Vertex light is clamped here (the console modulated textures up to 2x). */
+    readonly ceiling: import("three/webgpu").UniformNode<"float", number>;
+    private readonly points;
+    private nextScan;
+    private lights;
+    private node;
+    /**
+     * The lit colour multiplier for the current vertex: built once, shared by
+     * every styled material (wrapped in `varying()` so it runs per vertex).
+     */
+    irradiance(): Node<"vec3">;
+    /** Gather the scene's lights into the uniforms. Rescans the scene graph twice a second. */
+    update(scene: Scene, camera: Camera, nowMs: number): void;
+}

package/dist/runtime/styles/ps1/lights.js

@@ -0,0 +1,146 @@
+/**
+ * Per-vertex (Gouraud) lighting for the PS1 style. The scene's own lights
+ * (ambient, hemisphere, directional and point lights the templates and the
+ * LightingRig add) are gathered once a frame into a few shared uniforms, and
+ * every styled material lights its vertices from them in the vertex stage.
+ * Big triangles therefore light like a 1997 console: blotchy lantern pools
+ * on a coarse ground grid, smooth ramps across a character, no specular.
+ *
+ * The maths follows three.js's physical Lambert (irradiance x albedo / pi,
+ * same point-light falloff), so a scene keeps its brightness when it
+ * switches style.
+ */
+import { Vector3, Vector4 } from "three/webgpu";
+import { dot, float, max, mix, normalize, normalWorld, positionWorld, pow, saturate, uniform, vec3 } from "three/tsl";
+/** Point lights each vertex sums (the nearest to the camera). */
+export const MAX_POINT_LIGHTS = 8;
+/** Directional lights (sun, moon, rim). */
+export const MAX_DIR_LIGHTS = 2;
+const tmpA = new Vector3();
+const tmpB = new Vector3();
+const slots = (n, w = 0) => Array.from({ length: n }, () => uniform(new Vector4(0, 0, 0, w)));
+export class VertexLights {
+    /** Ambient irradiance (colour x intensity, summed). */
+    ambient = uniform(new Vector3());
+    hemiSky = uniform(new Vector3());
+    hemiGround = uniform(new Vector3());
+    /** xyz: direction toward the light (world). */
+    dirDir = slots(MAX_DIR_LIGHTS);
+    /** rgb: colour x intensity. */
+    dirColor = slots(MAX_DIR_LIGHTS);
+    /** xyz: position (world), w: cutoff distance (0 = none). */
+    pointPos = slots(MAX_POINT_LIGHTS);
+    /** rgb: colour x intensity, w: decay exponent. */
+    pointColor = slots(MAX_POINT_LIGHTS, 2);
+    /** Overall gain on the vertex light (1 = three.js's physical Lambert). */
+    gain = uniform(1);
+    /** Vertex light is clamped here (the console modulated textures up to 2x). */
+    ceiling = uniform(2.2);
+    points = [];
+    nextScan = 0;
+    lights = [];
+    node = null;
+    /**
+     * The lit colour multiplier for the current vertex: built once, shared by
+     * every styled material (wrapped in `varying()` so it runs per vertex).
+     */
+    irradiance() {
+        if (this.node)
+            return this.node;
+        const n = normalize(normalWorld);
+        const p = positionWorld;
+        let irr = vec3(this.ambient).add(mix(vec3(this.hemiGround), vec3(this.hemiSky), n.y.mul(0.5).add(0.5)));
+        for (let i = 0; i < MAX_DIR_LIGHTS; i++) {
+            const d = this.dirDir[i];
+            const c = this.dirColor[i];
+            if (!d || !c)
+                continue;
+            irr = irr.add(c.xyz.mul(max(dot(n, d.xyz), 0)));
+        }
+        for (let i = 0; i < MAX_POINT_LIGHTS; i++) {
+            const lp = this.pointPos[i];
+            const lc = this.pointColor[i];
+            if (!lp || !lc)
+                continue;
+            const toL = lp.xyz.sub(p);
+            const dist = max(toL.length(), float(1e-4));
+            const ndl = max(dot(n, toL.div(dist)), 0);
+            // three.js getDistanceAttenuation: 1 / d^decay, softened to zero at the cutoff.
+            const fall = float(1).div(max(pow(dist, lc.w), float(0.01)));
+            const edge = pow(saturate(float(1).sub(pow(dist.div(max(lp.w, float(1e-4))), 4))), 2);
+            const window = lp.w.greaterThan(0).select(edge, float(1));
+            irr = irr.add(lc.xyz.mul(ndl.mul(fall).mul(window)));
+        }
+        // Lambert: irradiance x albedo / pi (the material applies the albedo).
+        this.node = irr.mul(1 / Math.PI).mul(this.gain).min(vec3(this.ceiling));
+        return this.node;
+    }
+    /** Gather the scene's lights into the uniforms. Rescans the scene graph twice a second. */
+    update(scene, camera, nowMs) {
+        if (nowMs >= this.nextScan) {
+            this.nextScan = nowMs + 500;
+            this.lights = [];
+            scene.traverseVisible((o) => {
+                if (o.isLight)
+                    this.lights.push(o);
+            });
+        }
+        const amb = this.ambient.value.set(0, 0, 0);
+        const sky = this.hemiSky.value.set(0, 0, 0);
+        const gnd = this.hemiGround.value.set(0, 0, 0);
+        let dirs = 0;
+        this.points.length = 0;
+        for (const l of this.lights) {
+            if (!l.visible || l.intensity <= 0)
+                continue;
+            const k = l.intensity;
+            if (l.isAmbientLight) {
+                amb.x += l.color.r * k;
+                amb.y += l.color.g * k;
+                amb.z += l.color.b * k;
+            }
+            else if (l.isHemisphereLight) {
+                sky.x += l.color.r * k;
+                sky.y += l.color.g * k;
+                sky.z += l.color.b * k;
+                const g = l.groundColor ?? l.color;
+                gnd.x += g.r * k;
+                gnd.y += g.g * k;
+                gnd.z += g.b * k;
+            }
+            else if (l.isDirectionalLight && dirs < MAX_DIR_LIGHTS) {
+                l.getWorldPosition(tmpA);
+                if (l.target)
+                    l.target.getWorldPosition(tmpB);
+                else
+                    tmpB.set(0, 0, 0);
+                tmpA.sub(tmpB).normalize();
+                this.dirDir[dirs]?.value.set(tmpA.x, tmpA.y, tmpA.z, 0);
+                this.dirColor[dirs]?.value.set(l.color.r * k, l.color.g * k, l.color.b * k, 0);
+                dirs++;
+            }
+            else if (l.isPointLight)
+                this.points.push(l);
+        }
+        for (let i = dirs; i < MAX_DIR_LIGHTS; i++)
+            this.dirColor[i]?.value.set(0, 0, 0, 0);
+        // The nearest point lights to the camera (a top-down camera: the ones on screen).
+        camera.getWorldPosition(tmpB);
+        if (this.points.length > MAX_POINT_LIGHTS) {
+            const d = new Map();
+            for (const l of this.points)
+                d.set(l, l.getWorldPosition(tmpA).distanceToSquared(tmpB));
+            this.points.sort((a, b) => (d.get(a) ?? 0) - (d.get(b) ?? 0));
+        }
+        for (let i = 0; i < MAX_POINT_LIGHTS; i++) {
+            const l = this.points[i];
+            if (!l) {
+                this.pointColor[i]?.value.set(0, 0, 0, 2);
+                continue;
+            }
+            l.getWorldPosition(tmpA);
+            this.pointPos[i]?.value.set(tmpA.x, tmpA.y, tmpA.z, l.distance ?? 0);
+            this.pointColor[i]?.value.set(l.color.r * l.intensity, l.color.g * l.intensity, l.color.b * l.intensity, l.decay ?? 2);
+        }
+    }
+}

package/dist/runtime/styles/ps1/materials.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Turns whatever a template put in the scene into PS1 geometry and
+ * materials, without the template knowing: every mesh is found once, and
+ *  - its vertices snap to the low-res pixel grid (the wobble),
+ *  - its textures map affinely (no perspective correction: textures swim
+ *    on big polygons), sample nearest, and stay at console sizes,
+ *  - lit materials light per vertex from the shared VertexLights (Gouraud:
+ *    smooth below a crease angle, no specular, no shadow maps),
+ *  - big planes and boxes are tessellated (as console games did, to keep
+ *    the warping and the vertex lighting in check),
+ *  - meshes tagged `userData.surface = "<role>"` get the style's texture for
+ *    that role in world-space box UVs (ground, walls, pillars).
+ *
+ * Patching overrides three methods on the material instance itself
+ * (vertex output, lighting, cache key), so materials the template keeps
+ * and mutates (opacity fades, hit flashes, crowd motion) keep working.
+ */
+import { Vector3 } from "three/webgpu";
+import type { BufferGeometry, Object3D, UniformNode, Vector2 } from "three/webgpu";
+import type { VertexLights } from "./lights.js";
+import type { SurfaceTexture } from "./surfaces.js";
+/** A texture the patcher can resolve for a surface role (ground, wall...). */
+export type SurfaceSource = (role: string) => SurfaceTexture | null;
+export declare class Ps1Patcher {
+    private readonly lights;
+    private readonly resolution;
+    private readonly surfaces;
+    /** 0 = perspective-correct textures, 1 = full affine (the console). */
+    readonly affine: UniformNode<"float", number>;
+    /** Vertex snap grid as a fraction of the low-res pixel grid (1 = one pixel). */
+    readonly snap: UniformNode<"float", number>;
+    private readonly seenMaterials;
+    private readonly seenGeometry;
+    private readonly seenTextures;
+    private readonly seenMeshes;
+    private irradianceVarying;
+    /** Meshes and materials patched so far (tests and stats). */
+    readonly counts: {
+        meshes: number;
+        materials: number;
+        geometries: number;
+        surfaces: number;
+        textures: number;
+    };
+    constructor(lights: VertexLights, resolution: UniformNode<"vec2", Vector2>, surfaces: SurfaceSource);
+    /** Snap a clip-space position to the low-res pixel grid. */
+    private snapClip;
+    /** Screen-linear (affine) UVs: interpolate uv*w and w, divide per pixel. */
+    private affineUV;
+    private light;
+    /** Walk the scene and patch what is new. Cheap after the first pass (weak sets). */
+    scan(root: Object3D): void;
+    private patchMesh;
+    /** Smooth normals below the crease angle, in place (Gouraud on organic shapes, hard edges on boxes). */
+    private smooth;
+    /** A surface: tessellate big flat cells, world-space box UVs every `metres`, the style's texture. */
+    private surface;
+    private patchTexture;
+    private patchMaterial;
+}
+/** Tessellate a PlaneGeometry or BoxGeometry whose cells are larger than MAX_CELL world metres. */
+export declare function tessellate(g: BufferGeometry, worldScale: Vector3): BufferGeometry;