@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/render/rig.js

@@ -0,0 +1,107 @@
+import { AnimationClip, Bone, CylinderGeometry, Float32BufferAttribute, Quaternion, QuaternionKeyframeTrack, Skeleton, SkinnedMesh, Uint16BufferAttribute, Vector3, VectorKeyframeTrack, } from "three/webgpu";
+const q = (x, y, z) => {
+    const v = new Quaternion().setFromAxisAngle(new Vector3(x, y, z).normalize(), Math.hypot(x, y, z));
+    return [v.x, v.y, v.z, v.w];
+};
+/** A looping rotation track: samples of [x, y, z] axis-angle rotations evenly over `seconds`. */
+function rotTrack(bone, seconds, rots) {
+    const times = [];
+    const values = [];
+    rots.forEach((r, i) => {
+        times.push((seconds * i) / (rots.length - 1));
+        values.push(...(Math.hypot(...r) < 1e-9 ? [0, 0, 0, 1] : q(...r)));
+    });
+    return new QuaternionKeyframeTrack(`${bone}.quaternion`, times, values);
+}
+function posTrack(bone, seconds, base, ys) {
+    const times = [];
+    const values = [];
+    ys.forEach((y, i) => {
+        times.push((seconds * i) / (ys.length - 1));
+        values.push(0, base + y, 0);
+    });
+    return new VectorKeyframeTrack(`${bone}.position`, times, values);
+}
+/**
+ * A three-bone procedural character (hip, spine, head) skinned to a
+ * cylinder or any upright geometry, with a full animation set built in
+ * code: rest, idle, walk, run, hit, attack, die. Templates with procedural
+ * art get real skinned animation (and VAT crowds via bakeVertexAnimation)
+ * without any asset files.
+ */
+export function buildSegmentRig(material, opts = {}) {
+    const h = opts.height ?? 1.2;
+    const r = opts.radius ?? 0.35;
+    const geometry = opts.geometry ??
+        (() => {
+            const g = new CylinderGeometry(opts.topRadius ?? r * 0.75, r, h, opts.radialSegments ?? 10, opts.heightSegments ?? 6);
+            g.translate(0, h / 2, 0);
+            return g;
+        })();
+    const pos = geometry.getAttribute("position");
+    const idx = [];
+    const wts = [];
+    for (let i = 0; i < pos.count; i++) {
+        const y = Math.min(1, Math.max(0, pos.getY(i) / h));
+        // Hip owns the bottom half, spine the middle, head the top third.
+        if (y < 0.5) {
+            const w = y / 0.5;
+            idx.push(0, 1, 0, 0);
+            wts.push(1 - w, w, 0, 0);
+        }
+        else {
+            const w = Math.min(1, (y - 0.5) / 0.35);
+            idx.push(1, 2, 0, 0);
+            wts.push(1 - w, w, 0, 0);
+        }
+    }
+    geometry.setAttribute("skinIndex", new Uint16BufferAttribute(idx, 4));
+    geometry.setAttribute("skinWeight", new Float32BufferAttribute(wts, 4));
+    const hip = new Bone();
+    hip.name = "hip";
+    const spine = new Bone();
+    spine.name = "spine";
+    spine.position.y = h * 0.5;
+    const head = new Bone();
+    head.name = "head";
+    head.position.y = h * 0.35;
+    hip.add(spine);
+    spine.add(head);
+    const mesh = new SkinnedMesh(geometry, material);
+    mesh.add(hip);
+    mesh.bind(new Skeleton([hip, spine, head]));
+    const hb = 0;
+    const clips = [
+        new AnimationClip("rest", 1, [rotTrack("hip", 1, [[0, 0, 0], [0, 0, 0]])]),
+        new AnimationClip("idle", 2, [
+            posTrack("hip", 2, hb, [0, -0.02 * h, 0]),
+            rotTrack("spine", 2, [[0.02, 0, 0], [-0.03, 0, 0.02], [0.02, 0, 0]]),
+            rotTrack("head", 2, [[0, 0.05, 0], [0, -0.05, 0], [0, 0.05, 0]]),
+        ]),
+        new AnimationClip("walk", 0.8, [
+            posTrack("hip", 0.8, hb, [0, 0.05 * h, 0, 0.05 * h, 0]),
+            rotTrack("hip", 0.8, [[-0.08, 0, 0.12], [-0.08, 0, 0], [-0.08, 0, -0.12], [-0.08, 0, 0], [-0.08, 0, 0.12]]),
+            rotTrack("spine", 0.8, [[0, 0.12, -0.06], [0, 0, 0], [0, -0.12, 0.06], [0, 0, 0], [0, 0.12, -0.06]]),
+            rotTrack("head", 0.8, [[0.05, -0.08, 0], [0.05, 0, 0], [0.05, 0.08, 0], [0.05, 0, 0], [0.05, -0.08, 0]]),
+        ]),
+        new AnimationClip("run", 0.5, [
+            posTrack("hip", 0.5, hb, [0, 0.12 * h, 0, 0.12 * h, 0]),
+            rotTrack("hip", 0.5, [[-0.22, 0, 0.18], [-0.22, 0, 0], [-0.22, 0, -0.18], [-0.22, 0, 0], [-0.22, 0, 0.18]]),
+            rotTrack("spine", 0.5, [[-0.1, 0.2, -0.1], [-0.1, 0, 0], [-0.1, -0.2, 0.1], [-0.1, 0, 0], [-0.1, 0.2, -0.1]]),
+            rotTrack("head", 0.5, [[0.15, 0, 0], [0.1, 0, 0], [0.15, 0, 0], [0.1, 0, 0], [0.15, 0, 0]]),
+        ]),
+        new AnimationClip("hit", 0.3, [
+            rotTrack("spine", 0.3, [[0, 0, 0], [0.45, 0, 0.1], [0.1, 0, 0], [0, 0, 0]]),
+            rotTrack("head", 0.3, [[0, 0, 0], [0.3, 0, -0.1], [0, 0, 0], [0, 0, 0]]),
+        ]),
+        new AnimationClip("attack", 0.45, [
+            rotTrack("spine", 0.45, [[0, 0, 0], [0.15, -0.6, 0], [-0.3, 0.7, 0], [0, 0, 0]]),
+            posTrack("hip", 0.45, hb, [0, -0.04 * h, 0.02 * h, 0]),
+        ]),
+        new AnimationClip("die", 0.7, [
+            rotTrack("hip", 0.7, [[0, 0, 0], [0.4, 0, 0], [1.4, 0, 0.2]]),
+            new VectorKeyframeTrack("head.scale", [0, 0.7], [1, 1, 1, 1, 0.8, 1]),
+        ]),
+    ];
+    return { mesh, bones: [hip, spine, head], clips };
+}

package/dist/runtime/render/sprite.d.ts

@@ -0,0 +1,34 @@
+import type { Node } from "three/webgpu";
+/** Metres one source pixel covers at `spriteScale` 1. */
+export declare const SPRITE_TEXEL: number;
+/** The pixel style's resize for every billboard sprite (1 elsewhere). */
+export declare const spriteScale: import("three/webgpu").UniformNode<"float", number>;
+/**
+ * World position of a sprite vertex: `center` is the feet in world space,
+ * `x`/`y` the vertex in metres on the plane (x across, y up from the feet),
+ * `flip` -1 to mirror. The plane turns to the camera (its up is the camera's
+ * up, so a sprite under a high camera shows its full height).
+ */
+export declare function billboardWorld(center: Node<"vec3">, x: Node<"float">, y: Node<"float">, flip: Node<"float">): Node<"vec3">;
+/**
+ * positionNode for a single sprite mesh (a player, a boss): the plane
+ * faces the camera whatever the mesh's rotation, and mirrors when the
+ * mesh's forward (-z) points to screen left.
+ */
+export declare function spriteBillboardNode(): Node<"vec3">;
+/** Flag a sprite plane so AnimatedCrowd draws it as billboards (geometry.userData). */
+export declare function markSprite(geometry: {
+    userData: Record<string, unknown>;
+}): void;
+/** Whether a geometry is a sprite plane (markSprite). */
+export declare function isSprite(geometry: {
+    userData: Record<string, unknown>;
+}): boolean;
+/**
+ * A sprite material's extra output: the pixel style keeps sprites in their
+ * own palette colours and steps only the 3D world into light bands. Safe
+ * everywhere: a target without a "sprite" texture just takes the colour.
+ */
+export declare function markSpriteMaterial(material: {
+    mrtNode: unknown;
+}): void;

package/dist/runtime/render/sprite.js

@@ -0,0 +1,58 @@
+/**
+ * 2D sprites in the 3D scene (the pixel art style).
+ * A sprite is an upright plane with its feet at y = 0, built in metres at
+ * SPRITE_TEXEL metres per source pixel. Drawn as a billboard it always
+ * faces the camera, mirrors to face where it walks, and is resized by
+ * `spriteScale`, which the pixel style sets each frame so one sprite texel
+ * covers exactly one of its low-resolution pixels (one pixel scale for the
+ * whole picture). Without the pixel style `spriteScale` stays 1.
+ */
+import { Vector3 } from "three/webgpu";
+import { float, modelWorldMatrix, mrt, output, modelWorldMatrixInverse, positionGeometry, select, uniform, vec4 } from "three/tsl";
+/** Metres one source pixel covers at `spriteScale` 1. */
+export const SPRITE_TEXEL = 1 / 16;
+/** The pixel style's resize for every billboard sprite (1 elsewhere). */
+export const spriteScale = uniform(1);
+const camRight = uniform(new Vector3(1, 0, 0)).onObjectUpdate(({ camera }, self) => {
+    return camera ? self.value.setFromMatrixColumn(camera.matrixWorld, 0) : undefined;
+});
+const camUp = uniform(new Vector3(0, 1, 0)).onObjectUpdate(({ camera }, self) => {
+    return camera ? self.value.setFromMatrixColumn(camera.matrixWorld, 1) : undefined;
+});
+/**
+ * World position of a sprite vertex: `center` is the feet in world space,
+ * `x`/`y` the vertex in metres on the plane (x across, y up from the feet),
+ * `flip` -1 to mirror. The plane turns to the camera (its up is the camera's
+ * up, so a sprite under a high camera shows its full height).
+ */
+export function billboardWorld(center, x, y, flip) {
+    return center.add(camRight.mul(x.mul(flip).mul(spriteScale))).add(camUp.mul(y.mul(spriteScale)));
+}
+/**
+ * positionNode for a single sprite mesh (a player, a boss): the plane
+ * faces the camera whatever the mesh's rotation, and mirrors when the
+ * mesh's forward (-z) points to screen left.
+ */
+export function spriteBillboardNode() {
+    const center = modelWorldMatrix.mul(vec4(0, 0, 0, 1)).xyz;
+    const forward = modelWorldMatrix.mul(vec4(0, 0, -1, 0)).xyz;
+    const flip = select(forward.dot(camRight).lessThan(-0.05), float(-1), float(1));
+    const world = billboardWorld(center, positionGeometry.x, positionGeometry.y, flip);
+    return modelWorldMatrixInverse.mul(vec4(world, 1)).xyz;
+}
+/** Flag a sprite plane so AnimatedCrowd draws it as billboards (geometry.userData). */
+export function markSprite(geometry) {
+    geometry.userData.sprite = true;
+}
+/** Whether a geometry is a sprite plane (markSprite). */
+export function isSprite(geometry) {
+    return geometry.userData.sprite === true;
+}
+/**
+ * A sprite material's extra output: the pixel style keeps sprites in their
+ * own palette colours and steps only the 3D world into light bands. Safe
+ * everywhere: a target without a "sprite" texture just takes the colour.
+ */
+export function markSpriteMaterial(material) {
+    material.mrtNode = mrt({ output, sprite: float(1) });
+}

package/dist/runtime/render/stack.d.ts

@@ -0,0 +1,74 @@
+import type { Camera, Scene } from "three/webgpu";
+import type { RendererHandle } from "../renderer.js";
+import { Atmosphere } from "./atmosphere.js";
+import { GroundDecals, GroundRings } from "./decals.js";
+import { LightingRig } from "./lighting.js";
+import { GpuParticles } from "./particles.js";
+import { PostFX } from "./post.js";
+import type { GradePreset, LightingPreset, AtmospherePreset, LookPreset } from "./presets.js";
+import { QualityManager } from "./quality.js";
+import type { QualityTier } from "./quality.js";
+import type { StyleKit, StyleSession } from "../styles/kit.js";
+export interface RenderStackOptions {
+    /** Look preset: lighting, fog, sky and grade together. Default "night". */
+    readonly preset?: LookPreset;
+    /** The game's art style (game({ style }), or a template's ?style=). Its kit (runtime/styles) brings its look, post stages and session; low-poly and unknown names draw the stack's own picture. */
+    readonly style?: string;
+    /** "auto" detects from the device. Default "auto". */
+    readonly quality?: QualityTier | "auto";
+    readonly bloom?: boolean;
+    /** Toon outline (medium and high tiers only). Default false. */
+    readonly outline?: boolean;
+    /** Dynamic resolution (default true). */
+    readonly dynamicResolution?: boolean;
+    /** Half-size of the shadowed square around the focus, m. Default 26. */
+    readonly shadowExtent?: number;
+    readonly lighting?: Partial<LightingPreset>;
+    readonly atmosphere?: Partial<AtmospherePreset>;
+    readonly grade?: Partial<GradePreset>;
+    /** GPU particle slots (default from the tier). */
+    readonly particles?: number;
+    /** Build the particle system (an art style swaps in its own, e.g. the voxel style's cubes). Default GpuParticles. */
+    readonly makeParticles?: (scene: Scene, capacity: number) => GpuParticles;
+    readonly decals?: number;
+    /** Library id to URL, for an art style's own textures (the template's LibraryClient.url). */
+    readonly resolve?: (id: string) => string | null;
+}
+export interface RenderStack {
+    readonly lighting: LightingRig;
+    readonly atmosphere: Atmosphere;
+    readonly post: PostFX;
+    readonly particles: GpuParticles;
+    readonly decals: GroundDecals;
+    readonly rings: GroundRings;
+    readonly quality: QualityManager;
+    /** The art style drawing the frame (its kit is registered in runtime/styles), or null for the runtime's own low-poly look. */
+    readonly style: string | null;
+    /** That style's kit (world builders for the template), or null. */
+    readonly kit: StyleKit | null;
+    /** The style attached to this renderer (its surfaces, its state), or null. */
+    readonly session: StyleSession | null;
+    /** Seconds of render time accumulated by `frame` (drives particles and decals). */
+    readonly time: number;
+    /**
+     * Per frame: advance effect time by `dt` (already hit-stop scaled), move
+     * the shadow to the focus, step dynamic resolution, draw. Returns true
+     * when the pixel ratio changed (call your resize).
+     */
+    frame(dt: number, focus: {
+        x: number;
+        y: number;
+        z: number;
+    }, realNowMs?: number): boolean;
+    resize(width: number, height: number): void;
+    setPreset(preset: LookPreset): void;
+    setQuality(tier: QualityTier): void;
+    dispose(): void;
+}
+/**
+ * Everything a template needs for a good-looking frame, in one call:
+ * lighting with a following shadow, fog and sky, bloom and grade, GPU
+ * particles, decals and shockwave rings, quality tiers and dynamic
+ * resolution. Replace `renderer.render(scene, camera)` with `stack.frame(...)`.
+ */
+export declare function createRenderStack(handle: RendererHandle, scene: Scene, camera: Camera, opts?: RenderStackOptions): RenderStack;

package/dist/runtime/render/stack.js

@@ -0,0 +1,132 @@
+import { Atmosphere } from "./atmosphere.js";
+import { GroundDecals, GroundRings } from "./decals.js";
+import { LightingRig } from "./lighting.js";
+import { GpuParticles } from "./particles.js";
+import { PostFX } from "./post.js";
+import { browserHints, detectTier, QualityManager } from "./quality.js";
+import { styleKit } from "../styles/index.js";
+/**
+ * Everything a template needs for a good-looking frame, in one call:
+ * lighting with a following shadow, fog and sky, bloom and grade, GPU
+ * particles, decals and shockwave rings, quality tiers and dynamic
+ * resolution. Replace `renderer.render(scene, camera)` with `stack.frame(...)`.
+ */
+export function createRenderStack(handle, scene, camera, opts = {}) {
+    const { renderer } = handle;
+    const preset = opts.preset ?? "night";
+    const tier = opts.quality === undefined || opts.quality === "auto" ? detectTier(browserHints(handle.backend)) : opts.quality;
+    const dpr = globalThis.devicePixelRatio ?? 1;
+    const quality = new QualityManager(renderer, tier, { devicePixelRatio: dpr, dynamic: opts.dynamicResolution ?? true });
+    const s = quality.settings;
+    // The art style: the one place the stack looks a style up. Its look and stack overrides sit under the template's own options.
+    const kit = styleKit(opts.style);
+    const overrides = (p) => {
+        const look = kit?.look?.(p);
+        const st = kit?.stack?.(p);
+        const merge = (a, b, c) => a || b || c ? { ...a, ...b, ...c } : undefined;
+        return {
+            lighting: merge(look?.lighting, st?.lighting, opts.lighting),
+            atmosphere: merge(look?.atmosphere, st?.atmosphere, opts.atmosphere),
+            grade: merge(look?.grade, st?.grade, opts.grade),
+        };
+    };
+    const o = overrides(preset);
+    const lighting = new LightingRig(renderer, scene, {
+        preset,
+        shadowMapSize: s.shadowMapSize,
+        ...(o.lighting ? { overrides: o.lighting } : {}),
+        ...(opts.shadowExtent !== undefined ? { shadowExtent: opts.shadowExtent } : {}),
+    });
+    const atmosphere = new Atmosphere(scene, { preset, ...(o.atmosphere ? { overrides: o.atmosphere } : {}) });
+    const outlineWanted = (opts.outline ?? false) && kit?.outline !== false;
+    // A style whose look lives in post keeps post on at the low tier, without bloom.
+    const styledLow = (postOn) => kit?.needsPost === true && !postOn;
+    const bloomWanted = opts.bloom ?? kit?.bloom ?? true;
+    const post = new PostFX(renderer, scene, camera, {
+        preset,
+        bloom: bloomWanted && !styledLow(s.post),
+        outline: outlineWanted && s.outline,
+        enabled: s.post || styledLow(s.post),
+        bloomScale: s.bloomScale,
+        ...(o.grade ? { overrides: o.grade } : {}),
+    });
+    const session = kit?.attach?.({ handle, renderer, scene, camera, tier, preset, post, atmosphere, ...(opts.resolve ? { resolve: opts.resolve } : {}) }) ?? null;
+    if (session?.post)
+        post.setStyle(session.post);
+    const particleCap = opts.particles ?? s.particles;
+    const makeParticles = opts.makeParticles ?? kit?.stack?.(preset).makeParticles;
+    const particles = makeParticles
+        ? makeParticles(scene, particleCap)
+        : new GpuParticles(scene, { capacity: particleCap, ...(session?.particles ? { look: session.particles } : {}) });
+    const decals = new GroundDecals(scene, opts.decals ?? 256, Math.random, session?.decals);
+    const rings = new GroundRings(scene, 32, session?.rings);
+    quality.onChange((q) => {
+        lighting.setShadowMapSize(q.shadowMapSize);
+        post.setQuality(q.tier, outlineWanted && q.outline);
+        if (kit?.needsPost)
+            post.configure(styledLow(q.post) ? { enabled: true, bloom: false } : { bloom: bloomWanted });
+        session?.setQuality?.(q.tier);
+    });
+    let time = 0;
+    let w = 1;
+    let h = 1;
+    const stack = {
+        lighting,
+        atmosphere,
+        post,
+        particles,
+        decals,
+        rings,
+        quality,
+        style: kit?.id ?? null,
+        kit,
+        session,
+        get time() {
+            return time;
+        },
+        frame(dt, focus, realNowMs) {
+            time += Math.max(0, dt);
+            session?.frame?.((realNowMs ?? performance.now()) / 1000);
+            lighting.follow(focus.x, focus.y, focus.z);
+            particles.update(time);
+            decals.update(time);
+            rings.update(time);
+            if (session?.render)
+                session.render(() => post.render());
+            else
+                post.render();
+            const changed = quality.frame(realNowMs ?? performance.now());
+            if (changed)
+                stack.resize(w, h);
+            return changed;
+        },
+        resize(width, height) {
+            w = Math.max(1, width);
+            h = Math.max(1, height);
+            renderer.setSize(w, h, false);
+            post.setSize(w, h);
+            const pr = renderer.getPixelRatio();
+            session?.setSize?.(w * pr, h * pr);
+        },
+        setPreset(p) {
+            const n = overrides(p);
+            lighting.setPreset(p, n.lighting);
+            atmosphere.setPreset(p, n.atmosphere);
+            post.setPreset(p, n.grade);
+            session?.setPreset?.(p);
+        },
+        setQuality(t) {
+            quality.setTier(t);
+        },
+        dispose() {
+            session?.dispose();
+            particles.dispose();
+            decals.dispose();
+            rings.dispose();
+            post.dispose();
+            atmosphere.dispose();
+            lighting.dispose();
+        },
+    };
+    return stack;
+}

package/dist/runtime/render/vat.d.ts

@@ -0,0 +1,78 @@
+import { BufferGeometry, DataTexture, Mesh } from "three/webgpu";
+import type { AnimationClip, Material, Node, Object3D, SkinnedMesh } from "three/webgpu";
+export interface VatClip {
+    readonly name: string;
+    /** First frame of this clip in the texture. */
+    readonly start: number;
+    readonly frames: number;
+}
+/** A vertex animation texture: every vertex's skinned position (and normal) per frame. */
+export interface VertexAnimation {
+    readonly positions: DataTexture;
+    readonly normals: DataTexture | null;
+    readonly vertexCount: number;
+    /** Texture width (vertices per row) and rows per frame. */
+    readonly width: number;
+    readonly rowsPerFrame: number;
+    readonly totalFrames: number;
+    readonly fps: number;
+    readonly clips: readonly VatClip[];
+    /** The source geometry (index, uv) the crowd draws. */
+    readonly geometry: BufferGeometry;
+}
+export interface BakeOptions {
+    /** Sample rate, frames per second. Default 30. */
+    readonly fps?: number;
+    /** Frames per clip (default ceil(duration x fps), at least 1). */
+    readonly frames?: number;
+    /** Also bake per-frame normals (smooth-shaded crowds). Default true. */
+    readonly normals?: boolean;
+    /** Max texture width. Default 2048. */
+    readonly maxWidth?: number;
+}
+/**
+ * Bake one or more clips of a skinned mesh into a vertex animation texture
+ * (CPU, at load). Frames are laid out clip after clip; a crowd then plays
+ * any clip on thousands of instances in one draw (`VatCrowd`).
+ */
+export declare function bakeVertexAnimation(mesh: SkinnedMesh, clips: AnimationClip | readonly AnimationClip[], opts?: BakeOptions): VertexAnimation;
+export interface VatCrowdOptions {
+    /** Use baked normals (smooth shading). Off for flat-shaded materials. Default true when baked. */
+    readonly bakedNormals?: boolean;
+}
+/**
+ * Thousands of animated characters in one draw: every instance samples the
+ * VAT at its own clip, phase and rate, then is rotated, scaled and placed
+ * from per-instance attributes. CPU work per instance is one 12-float write.
+ */
+export declare class VatCrowd {
+    readonly vat: VertexAnimation;
+    readonly capacity: number;
+    readonly mesh: Mesh;
+    readonly time: import("three/webgpu").UniformNode<"float", number>;
+    count: number;
+    private readonly xform;
+    private readonly anim;
+    private readonly clip;
+    private readonly clipIndex;
+    constructor(vat: VertexAnimation, material: Material & {
+        positionNode: Node | null;
+        normalNode: Node | null;
+        emissiveNode?: Node | null;
+        flatShading?: boolean;
+    }, capacity: number, opts?: VatCrowdOptions);
+    clipNamed(name: string): VatClip | undefined;
+    begin(): void;
+    /** Add one instance this frame. `phase` offsets the clip in seconds; `rate` scales playback. */
+    push(x: number, y: number, z: number, yaw: number, opts?: {
+        clip?: string;
+        phase?: number;
+        rate?: number;
+        scale?: number;
+        flash?: number;
+    }): void;
+    /** Upload the instances written since `begin` and set the time (seconds). */
+    end(timeSeconds: number): void;
+    addTo(parent: Object3D): this;
+    dispose(): void;
+}