@netforge/engine 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,285 @@
+/**
+ * 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 { BufferAttribute, BoxGeometry, NearestFilter, PlaneGeometry, Quaternion, Vector3 } from "three/webgpu";
+import { toCreasedNormals } from "three/addons/utils/BufferGeometryUtils.js";
+import { cameraProjectionMatrix, context, diffuseColor, emissive, float, floor, materialEmissive, materialMetalness, mix, positionView, uniform, varying, vec3, vec4 } from "three/tsl";
+import { imageAverage, matchTint } from "./surfaces.js";
+/** Lit material types (lit per vertex); basic ones only snap and map affinely. */
+const LIT = /^Mesh(Standard|Physical|Lambert|Phong|Toon)(Node)?Material$/;
+const UNLIT = /^MeshBasic(Node)?Material$/;
+/** Longest texture edge kept as is; larger ones are shrunk to SHRINK_TO. */
+const MAX_TEXTURE = 256;
+const SHRINK_TO = 128;
+/** Big flat cells are cut to about this size, m. */
+const MAX_CELL = 3;
+/** Share of the diffuse light a fully metallic surface loses (the physical renderer's metal draws darker). */
+const METAL_DIM = 0.75;
+/** Faces meeting at less than this angle share a smooth (Gouraud) normal. */
+const CREASE = (55 * Math.PI) / 180;
+export class Ps1Patcher {
+    lights;
+    resolution;
+    surfaces;
+    /** 0 = perspective-correct textures, 1 = full affine (the console). */
+    affine = uniform(1);
+    /** Vertex snap grid as a fraction of the low-res pixel grid (1 = one pixel). */
+    snap = uniform(1);
+    seenMaterials = new WeakSet();
+    seenGeometry = new WeakSet();
+    seenTextures = new WeakSet();
+    seenMeshes = new WeakSet();
+    irradianceVarying = null;
+    /** Meshes and materials patched so far (tests and stats). */
+    counts = { meshes: 0, materials: 0, geometries: 0, surfaces: 0, textures: 0 };
+    constructor(lights, resolution, surfaces) {
+        this.lights = lights;
+        this.resolution = resolution;
+        this.surfaces = surfaces;
+    }
+    /** Snap a clip-space position to the low-res pixel grid. */
+    snapClip(clip) {
+        const half = this.resolution.mul(0.5).mul(this.snap);
+        const w = clip.w;
+        const ndc = clip.xy.div(w);
+        const snapped = floor(ndc.mul(half).add(0.5)).div(half).mul(w);
+        return vec4(w.greaterThan(1e-4).select(snapped, clip.xy), clip.z, w);
+    }
+    /** Screen-linear (affine) UVs: interpolate uv*w and w, divide per pixel. */
+    affineUV(base) {
+        const uv0 = base;
+        const w = cameraProjectionMatrix.mul(vec4(positionView, 1)).w;
+        const a = varying(vec3(uv0.mul(w), w));
+        return mix(uv0, a.xy.div(a.z), this.affine);
+    }
+    light() {
+        this.irradianceVarying ??= varying(this.lights.irradiance(), "v_ps1Light");
+        return this.irradianceVarying;
+    }
+    /** Walk the scene and patch what is new. Cheap after the first pass (weak sets). */
+    scan(root) {
+        root.traverse((o) => {
+            const mesh = o;
+            if (!mesh.isMesh || this.seenMeshes.has(mesh))
+                return;
+            this.seenMeshes.add(mesh);
+            this.patchMesh(mesh);
+        });
+    }
+    patchMesh(mesh) {
+        const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        const lit = mats.some((m) => LIT.test(m.type));
+        const role = typeof mesh.userData.surface === "string" ? mesh.userData.surface : null;
+        const surface = role && lit ? this.surfaces(role) : null;
+        if (surface) {
+            this.surface(mesh, surface);
+            this.counts.surfaces++;
+        }
+        else if (lit)
+            this.smooth(mesh.geometry);
+        for (const m of mats)
+            this.patchMaterial(m);
+        this.counts.meshes++;
+    }
+    /** Smooth normals below the crease angle, in place (Gouraud on organic shapes, hard edges on boxes). */
+    smooth(g) {
+        if (this.seenGeometry.has(g))
+            return;
+        this.seenGeometry.add(g);
+        const pos = g.getAttribute("position");
+        if (!pos || pos.count < 3 || pos.count > 200_000)
+            return;
+        // Skinned and morphed meshes keep their own normals (the bind pose would need re-skinning to crease safely).
+        if (g.morphAttributes.position)
+            return;
+        const out = toCreasedNormals(g, CREASE);
+        if (out !== g) {
+            // An indexed source came back as a new, non-indexed geometry: move its attributes onto the original.
+            g.setIndex(null);
+            for (const name of Object.keys(out.attributes)) {
+                const a = out.getAttribute(name);
+                if (a)
+                    g.setAttribute(name, a);
+            }
+        }
+        this.counts.geometries++;
+    }
+    /** A surface: tessellate big flat cells, world-space box UVs every `metres`, the style's texture. */
+    surface(mesh, src) {
+        const { texture, metres } = src;
+        mesh.updateWorldMatrix(true, false);
+        const s = new Vector3();
+        mesh.matrixWorld.decompose(new Vector3(), new Quaternion(), s);
+        let g = tessellate(mesh.geometry, s);
+        g = g.index ? g.toNonIndexed() : g.clone();
+        const pos = g.getAttribute("position");
+        const n = pos.count;
+        const uv = new Float32Array(n * 2);
+        const m = mesh.matrixWorld;
+        const a = new Vector3();
+        const b = new Vector3();
+        const c = new Vector3();
+        const fn = new Vector3();
+        const wp = new Vector3();
+        for (let t = 0; t + 2 < n; t += 3) {
+            a.fromBufferAttribute(pos, t).applyMatrix4(m);
+            b.fromBufferAttribute(pos, t + 1).applyMatrix4(m);
+            c.fromBufferAttribute(pos, t + 2).applyMatrix4(m);
+            fn.subVectors(c, b).cross(a.clone().sub(b)).normalize();
+            const ax = Math.abs(fn.x);
+            const ay = Math.abs(fn.y);
+            const az = Math.abs(fn.z);
+            for (let k = 0; k < 3; k++) {
+                wp.fromBufferAttribute(pos, t + k).applyMatrix4(m);
+                let u;
+                let v;
+                if (ay >= ax && ay >= az)
+                    [u, v] = [wp.x, wp.z];
+                else if (ax >= az)
+                    [u, v] = [wp.z, wp.y];
+                else
+                    [u, v] = [wp.x, wp.y];
+                uv[(t + k) * 2] = u / metres;
+                uv[(t + k) * 2 + 1] = v / metres;
+            }
+        }
+        g.setAttribute("uv", new BufferAttribute(uv, 2));
+        const smooth = toCreasedNormals(g, CREASE);
+        mesh.geometry = smooth;
+        this.seenGeometry.add(smooth);
+        // The texture in place of the template's colour, on the template's own material (it may fade it later),
+        // tinted to the brightness and roughly the hue the template drew there, so the scene keeps its mood
+        // and the actors keep standing out against it.
+        for (const mat of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+            const m = mat;
+            if (m.map === texture)
+                continue;
+            const c = m.color;
+            const base = c ? [c.r, c.g, c.b] : [1, 1, 1];
+            const mapAvg = m.map ? imageAverage(m.map.image) : null;
+            const want = mapAvg ? [base[0] * mapAvg[0], base[1] * mapAvg[1], base[2] * mapAvg[2]] : base;
+            m.map = texture;
+            src.onAverage((avg) => {
+                const t = matchTint(want, avg);
+                m.color?.setRGB(t[0], t[1], t[2]);
+            });
+        }
+    }
+    patchTexture(t) {
+        if (!t || this.seenTextures.has(t))
+            return;
+        this.seenTextures.add(t);
+        t.magFilter = NearestFilter;
+        t.minFilter = NearestFilter;
+        t.generateMipmaps = false;
+        t.anisotropy = 1;
+        const img = t.image;
+        const w = img?.width ?? 0;
+        const h = img?.height ?? 0;
+        if (w > MAX_TEXTURE || h > MAX_TEXTURE) {
+            const shrunk = shrink(t.image, w, h);
+            if (shrunk)
+                t.image = shrunk;
+        }
+        t.needsUpdate = true;
+        this.counts.textures++;
+    }
+    patchMaterial(mat) {
+        if (this.seenMaterials.has(mat))
+            return;
+        this.seenMaterials.add(mat);
+        const lit = LIT.test(mat.type);
+        if (!lit && !UNLIT.test(mat.type))
+            return;
+        const m = mat;
+        if (m.__ps1)
+            return;
+        m.__ps1 = true;
+        this.patchTexture(m.map);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        m.setupModelViewProjection = function (builder) {
+            const base = Object.getPrototypeOf(this).setupModelViewProjection.call(this, builder);
+            return self.snapClip(base);
+        };
+        m.customProgramCacheKey = function () {
+            return `${Object.getPrototypeOf(this).customProgramCacheKey.call(this)}|ps1`;
+        };
+        if (m.contextNode === undefined || m.contextNode === null) {
+            m.contextNode = context({ getUV: (tex) => self.affineUV(tex.getDefaultUV()) });
+        }
+        if (lit) {
+            // Gouraud needs vertex normals; flat shading would derive face normals per pixel.
+            m.flatShading = false;
+            m.setupLighting = function () {
+                // Metal has little diffuse light: glTF models default to fully metallic, and without the dimming
+                // they would glow white where the physical renderer draws them dark (no environment map to reflect).
+                const metal = typeof this.metalness === "number" ? (this.metalnessNode ?? materialMetalness) : float(0);
+                let out = diffuseColor.rgb.mul(self.light()).mul(float(1).sub(metal.mul(METAL_DIM)));
+                const e = this.emissiveNode ?? (this.emissive?.isColor === true ? materialEmissive : null);
+                if (e) {
+                    emissive.assign(vec3(e));
+                    out = out.add(emissive);
+                }
+                return out;
+            };
+        }
+        m.needsUpdate = true;
+        this.counts.materials++;
+    }
+}
+/** Tessellate a PlaneGeometry or BoxGeometry whose cells are larger than MAX_CELL world metres. */
+export function tessellate(g, worldScale) {
+    const cells = (len, scale) => Math.max(1, Math.min(160, Math.ceil((len * Math.abs(scale)) / MAX_CELL)));
+    if (g.type === "PlaneGeometry") {
+        const p = g.parameters;
+        const sx = cells(p.width, worldScale.x);
+        const sy = cells(p.height, worldScale.y);
+        if (sx > p.widthSegments || sy > p.heightSegments)
+            return new PlaneGeometry(p.width, p.height, sx, sy);
+    }
+    else if (g.type === "BoxGeometry") {
+        const p = g.parameters;
+        const sx = cells(p.width, worldScale.x);
+        const sy = cells(p.height, worldScale.y);
+        const sz = cells(p.depth, worldScale.z);
+        if (sx > p.widthSegments || sy > p.heightSegments || sz > p.depthSegments)
+            return new BoxGeometry(p.width, p.height, p.depth, sx, sy, sz);
+    }
+    return g;
+}
+/** Shrink an image to SHRINK_TO on its long edge (a console-sized texture). */
+function shrink(src, w, h) {
+    if (typeof document === "undefined")
+        return null;
+    const k = SHRINK_TO / Math.max(w, h);
+    const c = document.createElement("canvas");
+    c.width = Math.max(1, Math.round(w * k));
+    c.height = Math.max(1, Math.round(h * k));
+    const g = c.getContext("2d");
+    if (!g)
+        return null;
+    g.imageSmoothingEnabled = true;
+    g.imageSmoothingQuality = "high";
+    try {
+        g.drawImage(src, 0, 0, c.width, c.height);
+    }
+    catch {
+        return null;
+    }
+    return c;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * The PS1 frame: the scene draws into a small target (about 240 lines on
+ * the short side of the screen, no anti-aliasing), then one full-screen pass
+ * grades it, converts it to display colour, and quantises it to 15-bit
+ * colour (5 bits a channel) through the console's 4x4 ordered dither,
+ * sampling each low-res pixel as a crisp block. An optional faint scanline
+ * darkens the last device row of each block.
+ *
+ * The internal resolution follows the canvas: lines = short side / k, where
+ * k is the whole number of device pixels per block nearest to the target,
+ * so every block is the same size on screen.
+ */
+import { RenderPipeline, Vector2 } from "three/webgpu";
+import type { Camera, Scene, WebGPURenderer } from "three/webgpu";
+import type { PostFX } from "../../render/post.js";
+export interface Ps1PipelineOptions {
+    /** Target lines on the short side of the screen. Default 240. */
+    readonly lines?: number;
+    /** Colour levels per channel after quantising (31 = the PS1's 15-bit framebuffer). */
+    readonly levels?: number;
+    /** Ordered-dither strength in quantisation steps (1 = the console's matrix). */
+    readonly dither?: number;
+    /** Scanline darkening on the last device row of each block, 0..1. Default 0.1. */
+    readonly scanline?: number;
+}
+export declare class Ps1Pipeline {
+    private readonly renderer;
+    readonly pipeline: RenderPipeline;
+    /** Internal resolution in pixels (the vertex-snap grid). */
+    readonly resolution: import("three/webgpu").UniformNode<"vec2", Vector2>;
+    /** Device pixels per low-res block (for the scanline). */
+    readonly block: import("three/webgpu").UniformNode<"float", number>;
+    readonly levels: import("three/webgpu").UniformNode<"float", number>;
+    readonly dither: import("three/webgpu").UniformNode<"float", number>;
+    readonly scanline: import("three/webgpu").UniformNode<"float", number>;
+    private readonly grade;
+    private readonly scenePass;
+    private readonly lines;
+    private readonly size;
+    constructor(renderer: WebGPURenderer, scene: Scene, camera: Camera, post: PostFX | undefined, opts?: Ps1PipelineOptions);
+    private build;
+    /** Fit the small target to the canvas: whole device pixels per block, about `lines` on the short side. */
+    private fit;
+    render(): void;
+    dispose(): void;
+}
+/** For tests: the block grid for a canvas size and a line target. */
+export declare function blockGrid(width: number, height: number, lines: number): {
+    k: number;
+    w: number;
+    h: number;
+};

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

@@ -0,0 +1,111 @@
+/**
+ * The PS1 frame: the scene draws into a small target (about 240 lines on
+ * the short side of the screen, no anti-aliasing), then one full-screen pass
+ * grades it, converts it to display colour, and quantises it to 15-bit
+ * colour (5 bits a channel) through the console's 4x4 ordered dither,
+ * sampling each low-res pixel as a crisp block. An optional faint scanline
+ * darkens the last device row of each block.
+ *
+ * The internal resolution follows the canvas: lines = short side / k, where
+ * k is the whole number of device pixels per block nearest to the target,
+ * so every block is the same size on screen.
+ */
+import { RenderPipeline, Vector2, Vector3 } from "three/webgpu";
+import { dot, float, floor, fract, length, max, mix, pass, pow, renderOutput, screenUV, smoothstep, uniform, vec3, vec4 } from "three/tsl";
+/** 4x4 Bayer threshold in [0, 1) for an integer pixel coordinate. */
+function bayer4(p) {
+    const b2 = (a) => fract(a.x.mul(0.5).add(a.y.mul(a.y).mul(0.75)));
+    return b2(floor(p.mul(0.5))).mul(0.25).add(b2(floor(p)));
+}
+export class Ps1Pipeline {
+    renderer;
+    pipeline;
+    /** Internal resolution in pixels (the vertex-snap grid). */
+    resolution = uniform(new Vector2(320, 240));
+    /** Device pixels per low-res block (for the scanline). */
+    block = uniform(3);
+    levels = uniform(31);
+    dither = uniform(1);
+    scanline = uniform(0.1);
+    grade;
+    scenePass;
+    lines;
+    size = new Vector2();
+    constructor(renderer, scene, camera, post, opts = {}) {
+        this.renderer = renderer;
+        this.lines = opts.lines ?? 240;
+        this.levels.value = opts.levels ?? 31;
+        this.dither.value = opts.dither ?? 1;
+        this.scanline.value = opts.scanline ?? 0.1;
+        this.grade = post ?? {
+            exposure: uniform(1),
+            contrast: uniform(1),
+            saturation: uniform(1),
+            shadowTint: uniform(new Vector3(1, 1, 1)),
+            highlightTint: uniform(new Vector3(1, 1, 1)),
+            vignette: uniform(0.25),
+            hurt: uniform(0),
+        };
+        this.pipeline = new RenderPipeline(renderer);
+        this.pipeline.outputColorTransform = false;
+        // No MSAA in the small target: hard polygon edges are part of the look.
+        this.scenePass = pass(scene, camera, { samples: 0 });
+        this.build();
+    }
+    build() {
+        const g = this.grade;
+        const res = this.resolution;
+        const color = this.scenePass.getTextureNode("output");
+        // Sample the centre of the low-res pixel this screen pixel falls in: crisp blocks on any backend.
+        const px = floor(screenUV.mul(res));
+        const uv = px.add(0.5).div(res);
+        let c = color.sample(uv).rgb;
+        // The stack's grade, in linear light before tone mapping (same maths as PostFX).
+        c = c.mul(g.exposure);
+        const luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+        c = mix(vec3(luma), c, g.saturation);
+        c = pow(max(c, vec3(1e-5)).div(0.18), vec3(g.contrast)).mul(0.18);
+        c = c.mul(mix(g.shadowTint, g.highlightTint, smoothstep(0.0, 1.0, luma)));
+        // Vignette and the hurt pulse on the block grid, so they step like the rest of the frame.
+        const d = length(uv.sub(0.5)).mul(1.414);
+        c = c.mul(float(1).sub(smoothstep(0.35, 1.05, d).mul(g.vignette)));
+        const hurtEdge = smoothstep(0.45, 1.15, d).mul(g.hurt).mul(0.85);
+        c = mix(c, c.mul(vec3(1.25, 0.35, 0.3)).add(vec3(0.22, 0.0, 0.0)), hurtEdge);
+        // Tone map and convert to display colour once, then quantise in display space like the console's DAC.
+        const display = renderOutput(vec4(c, 1)).rgb;
+        const t = bayer4(px).sub(0.5).mul(this.dither);
+        let q = floor(display.mul(this.levels).add(0.5).add(t)).div(this.levels);
+        q = q.clamp(0, 1);
+        // A faint scanline: the last device row of each block, only when blocks are 3+ device pixels tall.
+        const row = fract(screenUV.y.mul(res.y));
+        const lastRow = row.greaterThan(float(1).sub(float(1).div(max(this.block, float(1)))));
+        const scan = lastRow.and(this.block.greaterThanEqual(3)).select(float(1).sub(this.scanline), float(1));
+        this.pipeline.outputNode = vec4(q.mul(scan), 1);
+        this.pipeline.needsUpdate = true;
+    }
+    /** Fit the small target to the canvas: whole device pixels per block, about `lines` on the short side. */
+    fit() {
+        const s = this.renderer.getDrawingBufferSize(this.size);
+        const { k, w, h } = blockGrid(s.x, s.y, this.lines);
+        if (w !== this.resolution.value.x || h !== this.resolution.value.y) {
+            this.resolution.value.set(w, h);
+            this.block.value = k;
+            // A hair over 1/k so floor(size x scale) lands on w and h exactly.
+            this.scenePass.setResolutionScale((1 + 1e-4) / k);
+        }
+    }
+    render() {
+        this.fit();
+        this.pipeline.render();
+    }
+    dispose() {
+        this.pipeline.dispose();
+        this.scenePass.dispose();
+    }
+}
+/** For tests: the block grid for a canvas size and a line target. */
+export function blockGrid(width, height, lines) {
+    const short = Math.max(1, Math.min(width, height));
+    const k = Math.max(1, Math.round(short / lines));
+    return { k, w: Math.max(1, Math.floor(width / k)), h: Math.max(1, Math.floor(height / k)) };
+}

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

@@ -0,0 +1,44 @@
+import type { Texture } from "three/webgpu";
+export interface SurfaceRole {
+    /** Library name after "style.ps1.". */
+    readonly id: string;
+    /** Metres one repeat of the texture covers. */
+    readonly metres: number;
+    /** Fallback: base colour and speckle colours of the procedural texture. */
+    readonly base: string;
+    readonly speckle: readonly string[];
+}
+/**
+ * The roles templates tag. Aliases map the words a template is likely to
+ * use onto the same texture (a "floor" in a yard is concrete).
+ */
+export declare const SURFACES: Readonly<Record<string, SurfaceRole>>;
+/** The role a tag names, or null. */
+export declare function surfaceRole(tag: string): SurfaceRole | null;
+/** A muted copy of an image (saturation and contrast pulled in), or null when it cannot be read. */
+export declare function muted(img: unknown): HTMLCanvasElement | null;
+/** Linear RGB. */
+export type Rgb = readonly [number, number, number];
+/** Mean linear colour of an sRGB image (drawn down to 8x8), or null when it cannot be read. */
+export declare function imageAverage(img: unknown): Rgb | null;
+export declare function matchTint(want: Rgb, avg: Rgb): Rgb;
+/** A role's texture, its repeat, and its mean colour (now, and again when the library file arrives). */
+export interface SurfaceTexture {
+    readonly texture: Texture;
+    readonly metres: number;
+    onAverage(cb: (avg: Rgb) => void): void;
+}
+/**
+ * Loads and caches one texture per role. `resolve` maps a library id to a
+ * URL (or null when there is no library), from the template's LibraryClient.
+ */
+export declare class Ps1Surfaces {
+    private readonly resolve;
+    private readonly cache;
+    private readonly averages;
+    private readonly listeners;
+    private readonly loader;
+    constructor(resolve: ((id: string) => string | null) | undefined);
+    get(tag: string): SurfaceTexture | null;
+    dispose(): void;
+}