@jgengine/shell 0.34.0 → 0.36.0

package/dist/play/run.js

@@ -0,0 +1,266 @@
+import { createHeadlessRunner } from "@jgengine/core/runtime/headlessRunner";
+import { resolveActivePrompt } from "@jgengine/core/interaction/proximityPrompt";
+import { dispatchBoundAction, RESERVED_INPUT_ACTIONS, shouldFireBoundAction } from "../boundActionDispatch.js";
+import { executeHotbarSlot, findHotbarSlotActions, hotbarIdFor } from "../hotbarActions.js";
+import { shellDrivesPlayerPose } from "../shellMovement.js";
+import { createPlayScript, PLAY_MOVE_ACTIONS, } from "./script.js";
+import { playTimelineDigest } from "./timeline.js";
+const RECORDED_EVENTS = [
+    "combat.damage",
+    "entity.died",
+    "stat.levelUp",
+    "quest.accepted",
+    "quest.updated",
+    "quest.completed",
+    "loot.granted",
+    "worldItem.dropped",
+    "feedback.cue",
+    "command.refused",
+];
+function stepLabel(step) {
+    if (step.label !== undefined)
+        return step.label;
+    switch (step.action) {
+        case "move":
+            return `move ${step.move} ×${step.ticks ?? 1}`;
+        case "fire":
+            return `fire ×${step.ticks ?? 1}`;
+        case "aim":
+            return `aim yaw=${step.yaw.toFixed(3)}${step.pitch === undefined ? "" : ` pitch=${step.pitch.toFixed(3)}`}`;
+        case "use":
+            return `use ${step.actionId}`;
+        case "wait":
+            return `wait ×${step.ticks ?? 1}`;
+        case "command":
+            return `command ${step.name}`;
+    }
+}
+function eventValues(name, payload) {
+    const record = payload;
+    switch (name) {
+        case "combat.damage":
+            return {
+                to: String(record.target ?? ""),
+                ...(record.source === undefined ? {} : { from: String(record.source) }),
+                amount: typeof record.amount === "number" ? Math.round(record.amount * 100) / 100 : null,
+                remaining: typeof record.remaining === "number" ? Math.round(record.remaining * 100) / 100 : null,
+                ...(record.lethal === true ? { lethal: true } : {}),
+            };
+        case "entity.died":
+            return { id: String(record.instanceId ?? ""), kind: String(record.catalogId ?? "") };
+        case "stat.levelUp":
+            return { user: String(record.userId ?? ""), stat: String(record.stat ?? "") };
+        case "quest.accepted":
+        case "quest.completed":
+            return { quest: String(record.questId ?? "") };
+        case "quest.updated":
+            return {
+                quest: String(record.questId ?? ""),
+                ...(record.objectiveId === undefined ? {} : { objective: String(record.objectiveId) }),
+                ...(record.progress === undefined ? {} : { progress: Number(record.progress) }),
+            };
+        case "loot.granted":
+            return { item: String(record.itemId ?? record.lootId ?? ""), ...(record.amount === undefined ? {} : { amount: Number(record.amount) }) };
+        case "worldItem.dropped":
+            return { item: String(record.itemId ?? "") };
+        case "feedback.cue":
+            return { cue: String(record.cue ?? "") };
+        case "command.refused":
+            return { command: String(record.command ?? ""), reason: String(record.reason ?? "") };
+    }
+}
+/**
+ * Play a real game without a browser: boot its `PlayableGame` through the headless runner, apply a
+ * tick-based {@link PlayScript}, and return what happened plus whether the script's assertions held.
+ *
+ * Runs the shell's own per-tick pipeline, not an imitation of it — held movement actions reach the walk
+ * controller, a held `fire` (or any game action) resolves to its bound command on the press tick and on
+ * its repeat cadence, `interact` picks the active proximity prompt, and a hotbar press activates the
+ * slot. So a script proves the same code path a player's hands prove, in seconds.
+ *
+ * @capability play-script play a real game from a deterministic script — spawn, move, aim, fire, command, and assert world state with no browser and no wall clock
+ */
+export function runPlayScript(playable, spec, options = {}) {
+    const script = createPlayScript(spec);
+    const definition = playable.game;
+    const dt = options.dt ?? script.dt;
+    const maxEvents = options.maxEvents ?? 1000;
+    let clockMs = 0;
+    const runner = createHeadlessRunner({
+        definition,
+        content: playable.content,
+        loop: playable.loop,
+        player: { userId: options.userId ?? "player", isNew: true },
+        seed: script.seed,
+        now: () => clockMs,
+        maxStepSeconds: dt,
+        playerMovement: shellDrivesPlayerPose(definition.input),
+        movement: playable.movement,
+        collision: playable.collision,
+    });
+    const ctx = runner.ctx;
+    const playerId = options.userId ?? "player";
+    const timeline = [];
+    let eventRows = 0;
+    let truncated = false;
+    const record = (entry) => {
+        if (entry.kind === "event") {
+            eventRows += 1;
+            if (eventRows > maxEvents) {
+                if (!truncated) {
+                    truncated = true;
+                    timeline.push({ tick: entry.tick, kind: "event", label: "timeline truncated", values: { maxEvents } });
+                }
+                return;
+            }
+        }
+        timeline.push(entry);
+    };
+    for (const name of RECORDED_EVENTS) {
+        ctx.game.events.on(name, (payload) => {
+            record({ tick: runner.tick(), kind: "event", label: name, values: eventValues(name, payload) });
+        });
+    }
+    /** Run a command and record its verdict once, at the tick it ran. */
+    const runCommand = (name, input, label = `command ${name}`) => {
+        const result = ctx.game.commands.run(name, input);
+        record({
+            tick: runner.tick(),
+            kind: "command",
+            label,
+            values: {
+                status: result.status,
+                ...(result.status === "rejected" && "reason" in result && result.reason !== undefined ? { reason: String(result.reason) } : {}),
+            },
+        });
+    };
+    let yaw = 0;
+    let pitch = 0;
+    const heldWindows = [];
+    const stepHolds = (step) => {
+        if (step.action === "move")
+            return PLAY_MOVE_ACTIONS[step.move];
+        if (step.action === "fire")
+            return "fire";
+        if (step.action === "use")
+            return step.actionId;
+        return null;
+    };
+    for (const step of script.steps) {
+        const action = stepHolds(step);
+        if (action !== null)
+            heldWindows.push({ action, from: step.tick, to: step.tick + (step.ticks ?? 1) });
+    }
+    if (script.setup !== undefined)
+        script.setup(ctx, runner);
+    const sample = (expectation, tick) => {
+        const value = expectation.read(ctx);
+        const initial = initialReadings.get(expectation.id) ?? value;
+        const pass = expectation.test === undefined ? Boolean(value) : expectation.test(value, initial);
+        record({
+            tick,
+            kind: "check",
+            label: expectation.id,
+            values: { value, initial, pass },
+        });
+        return { id: expectation.id, subject: expectation.subject ?? expectation.id, tick, pass, initial, value };
+    };
+    const initialReadings = new Map();
+    for (const expectation of script.expect) {
+        if (expectation.at === undefined || expectation.at > 0)
+            initialReadings.set(expectation.id, expectation.read(ctx));
+    }
+    const results = [];
+    for (const expectation of script.expect) {
+        if (expectation.at === 0)
+            results.push(sample(expectation, 0));
+    }
+    const repeatFiredAt = new Map();
+    const gameActions = Object.keys(definition.input ?? {});
+    const slotActions = findHotbarSlotActions(definition.input);
+    const hotbarId = hotbarIdFor(playable);
+    const sink = { run: (name, input) => runCommand(name, input, `action ${name}`) };
+    const commandAim = () => ({ yaw, pitch });
+    /** The shell's per-frame action phase: bound commands, prompts, hotbar — run after the tick it belongs to. */
+    const dispatchActions = () => {
+        const isDown = (action) => ctx.input.isDown(action);
+        const wasPressed = (action) => ctx.input.justPressed(action);
+        const tracker = { isDown, wasPressed };
+        for (const action of gameActions) {
+            if (action === "interact") {
+                if (!wasPressed(action))
+                    continue;
+                const prompts = playable.prompts?.(ctx) ?? [];
+                const focus = ctx.scene.entity.get(playerId);
+                if (prompts.length === 0 || focus === null)
+                    continue;
+                const active = resolveActivePrompt({ x: focus.position[0], z: focus.position[2] }, prompts);
+                if (active?.prompt.invoke != null)
+                    runCommand(active.prompt.invoke.name, active.prompt.invoke.input, `prompt ${active.id}`);
+                continue;
+            }
+            if (!shouldFireBoundAction(tracker, action, definition.input, repeatFiredAt, clockMs))
+                continue;
+            repeatFiredAt.set(action, clockMs);
+            dispatchBoundAction(ctx, action, yaw, pitch, commandAim(), RESERVED_INPUT_ACTIONS, sink);
+        }
+        if (hotbarId !== null) {
+            for (const { action, slot } of slotActions) {
+                if (!wasPressed(action))
+                    continue;
+                executeHotbarSlot(ctx, playerId, hotbarId, slot, yaw, pitch);
+            }
+            if (wasPressed("useAbility")) {
+                const slots = ctx.player.inventory.state(hotbarId).slots;
+                const preferred = playable.hotbarSelection?.() ?? -1;
+                const slot = preferred >= 0 && slots[preferred] != null ? preferred : slots.findIndex((stack) => stack != null);
+                if (slot >= 0)
+                    executeHotbarSlot(ctx, playerId, hotbarId, slot, yaw, pitch);
+            }
+        }
+    };
+    const stepsByTick = new Map();
+    for (const step of script.steps) {
+        const bucket = stepsByTick.get(step.tick) ?? [];
+        bucket.push(step);
+        stepsByTick.set(step.tick, bucket);
+    }
+    for (let tick = 0; tick < script.totalTicks; tick += 1) {
+        for (const step of stepsByTick.get(tick) ?? []) {
+            record({ tick, kind: "step", label: stepLabel(step), values: { action: step.action, ticks: step.ticks ?? 1 } });
+            if (step.action === "command")
+                runCommand(step.name, step.input);
+            if (step.action === "aim") {
+                yaw = step.yaw;
+                if (step.pitch !== undefined)
+                    pitch = step.pitch;
+                runner.aim({ heading: yaw, pitch });
+            }
+        }
+        const held = heldWindows.filter((window) => tick >= window.from && tick < window.to).map((window) => window.action);
+        clockMs = Math.round((tick + 1) * dt * 1000 * 1000) / 1000;
+        runner.step(dt, { held, pointer: null });
+        dispatchActions();
+        script.onTick?.(ctx, runner.tick());
+        options.onTick?.(runner.tick(), ctx);
+        const nowTick = runner.tick();
+        for (const expectation of script.expect) {
+            if (expectation.at === nowTick)
+                results.push(sample(expectation, nowTick));
+        }
+    }
+    const finalTick = runner.tick();
+    for (const expectation of script.expect) {
+        if (expectation.at === undefined)
+            results.push(sample(expectation, finalTick));
+    }
+    return {
+        seed: script.seed,
+        dt,
+        ticks: finalTick,
+        timeline,
+        expectations: results,
+        passed: results.every((result) => result.pass),
+        digest: playTimelineDigest(timeline),
+    };
+}

package/dist/play/script.d.ts

@@ -0,0 +1,103 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { HeadlessRunner } from "@jgengine/core/runtime/headlessRunner";
+/** A reading an assertion compares: a stat, a distance, a count, a phase id. */
+export type PlayValue = number | string | boolean | null;
+/** Direction a scripted step walks, using the shell's own movement actions. */
+export type PlayMove = "forward" | "back" | "left" | "right";
+/** Movement action ids a {@link PlayMove} holds, so a script walks through the same controller a player does. */
+export declare const PLAY_MOVE_ACTIONS: Readonly<Record<PlayMove, string>>;
+interface PlayStepBase {
+    /** Simulation tick the step starts on. Ticks, not seconds: the run advances one fixed step per tick. */
+    tick: number;
+    /** How many ticks the step lasts. Default 1 for every action. */
+    ticks?: number;
+    /** Shown in the timeline instead of the generated description. */
+    label?: string;
+}
+/** Hold a movement direction for `ticks` — the shell walk controller's own held actions. */
+export interface PlayMoveStep extends PlayStepBase {
+    action: "move";
+    move: PlayMove;
+}
+/** Point the walk controller and the aim payload at a yaw/pitch, in radians. */
+export interface PlayAimStep extends PlayStepBase {
+    action: "aim";
+    yaw: number;
+    pitch?: number;
+}
+/** Hold the `fire` action: the bound `fire` command runs on the press tick, then on its repeat cadence. */
+export interface PlayFireStep extends PlayStepBase {
+    action: "fire";
+}
+/** Press one bound action id once (default one tick) — `interact`, `reload`, `useAbility`, a game's own action. */
+export interface PlayUseStep extends PlayStepBase {
+    action: "use";
+    actionId: string;
+}
+/** Hold nothing for `ticks`, letting the world run. */
+export interface PlayWaitStep extends PlayStepBase {
+    action: "wait";
+    ticks: number;
+}
+/** Run a registered command directly, with whatever input it declares. */
+export interface PlayCommandStep extends PlayStepBase {
+    action: "command";
+    name: string;
+    input?: unknown;
+}
+/** One tick-based action in a script. */
+export type PlayStep = PlayMoveStep | PlayAimStep | PlayFireStep | PlayUseStep | PlayWaitStep | PlayCommandStep;
+/**
+ * One assertion about world state. Read happens twice — right after `setup` and on the assertion's own
+ * tick — so a script can prove change ("health dropped") as well as a level ("wave is 2").
+ */
+export interface PlayExpectation {
+    /** Stable name the CLI prints and exits on. */
+    id: string;
+    /** What is being measured, in the game's words. Defaults to {@link PlayExpectation.id}. */
+    subject?: string;
+    /** Tick to read at. Defaults to the run's final tick. */
+    at?: number;
+    /** Read the observed value off the live world. */
+    read: (ctx: GameContext) => PlayValue;
+    /** Passes when this is true. Receives the reading at `at` and the reading taken right after `setup`. Default: the reading is truthy. */
+    test?: (now: PlayValue, initial: PlayValue) => boolean;
+}
+/** A script to play against a real game: what to do, on which tick, and what must be true afterwards. */
+export interface PlayScript {
+    /** Seed for `ctx.rng` and the run's identity; the same seed and script replay to the same timeline. */
+    seed: string | number;
+    /** Fixed tick length in seconds. Default 1/60. */
+    dt: number;
+    /** Scripted actions, sorted by tick. */
+    steps: readonly PlayStep[];
+    /** Assertions sampled during the run. */
+    expect: readonly PlayExpectation[];
+    /** Run this many ticks even when no step or expectation needs them. Default 0. */
+    ticks: number;
+    /** Total ticks the run advances: steps, expectations and `ticks` folded together. */
+    totalTicks: number;
+    /** Boot work that must happen before the first tick: pick a class, open a wave, spawn the actors the script is about. */
+    setup?: (ctx: GameContext, runner: HeadlessRunner) => void;
+    /** Called after every tick — a game that needs a decision per tick (send a wave the moment it is ready) writes it as code instead of guessing the tick in advance. Keep it tick-based: read state, run commands, never a clock. */
+    onTick?: (ctx: GameContext, tick: number) => void;
+}
+/** What {@link createPlayScript} accepts: the same script with the derived fields optional. */
+export interface PlayScriptSpec {
+    seed: string | number;
+    /** Fixed tick length in seconds. Default 1/60. */
+    dt?: number;
+    steps?: readonly PlayStep[];
+    expect?: readonly PlayExpectation[];
+    /** Minimum run length in ticks. */
+    ticks?: number;
+    setup?: (ctx: GameContext, runner: HeadlessRunner) => void;
+    onTick?: (ctx: GameContext, tick: number) => void;
+}
+/**
+ * Validate and normalize a script: whole-tick timings, sorted steps, a derived run length.
+ *
+ * @capability play-script write a game's behaviour as a tick-based script with declarative assertions instead of playing it in a browser
+ */
+export declare function createPlayScript(spec: PlayScriptSpec): PlayScript;
+export {};

package/dist/play/script.js

@@ -0,0 +1,52 @@
+/** Movement action ids a {@link PlayMove} holds, so a script walks through the same controller a player does. */
+export const PLAY_MOVE_ACTIONS = {
+    forward: "moveForward",
+    back: "moveBack",
+    left: "moveLeft",
+    right: "moveRight",
+};
+function requireTick(value, what) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`play script: ${what} must be a non-negative whole tick, got ${String(value)}`);
+    }
+    return value;
+}
+/**
+ * Validate and normalize a script: whole-tick timings, sorted steps, a derived run length.
+ *
+ * @capability play-script write a game's behaviour as a tick-based script with declarative assertions instead of playing it in a browser
+ */
+export function createPlayScript(spec) {
+    if (typeof spec.seed !== "string" && typeof spec.seed !== "number") {
+        throw new Error("play script: seed must be a string or number so a run can be replayed");
+    }
+    const dt = spec.dt ?? 1 / 60;
+    if (!Number.isFinite(dt) || dt <= 0)
+        throw new Error(`play script: dt must be a positive number of seconds, got ${String(spec.dt)}`);
+    const steps = (spec.steps ?? []).map((step, index) => {
+        requireTick(step.tick, `step ${index + 1} (${step.action}) tick`);
+        const ticks = step.ticks === undefined ? 1 : step.ticks;
+        if (!Number.isInteger(ticks) || ticks < 1) {
+            throw new Error(`play script: step ${index + 1} (${step.action}) ticks must be a positive whole number, got ${String(step.ticks)}`);
+        }
+        if (step.action === "use" && step.actionId.trim() === "") {
+            throw new Error(`play script: step ${index + 1} needs a non-empty actionId`);
+        }
+        if (step.action === "command" && step.name.trim() === "") {
+            throw new Error(`play script: step ${index + 1} needs a non-empty command name`);
+        }
+        return { ...step, ticks };
+    });
+    steps.sort((left, right) => left.tick - right.tick);
+    const expect = (spec.expect ?? []).map((entry, index) => {
+        if (entry.id.trim() === "")
+            throw new Error(`play script: expectation ${index + 1} needs an id`);
+        if (entry.at !== undefined)
+            requireTick(entry.at, `expectation "${entry.id}" tick`);
+        return { ...entry };
+    });
+    const lastStep = steps.reduce((max, step) => Math.max(max, step.tick + (step.ticks ?? 1)), 0);
+    const lastExpect = expect.reduce((max, entry) => Math.max(max, entry.at ?? 0), 0);
+    const totalTicks = Math.max(lastStep, lastExpect, spec.ticks ?? 0, 1);
+    return { seed: spec.seed, dt, steps, expect, ticks: spec.ticks ?? 0, totalTicks, ...(spec.setup === undefined ? {} : { setup: spec.setup }), ...(spec.onTick === undefined ? {} : { onTick: spec.onTick }) };
+}

package/dist/play/timeline.d.ts

@@ -0,0 +1,43 @@
+import type { PlayValue } from "./script.js";
+/** What a timeline row records: a scripted action, a command result, a world event, or an assertion reading. */
+export type PlayTimelineKind = "step" | "command" | "event" | "check";
+/** One row of what happened, on the tick it happened. */
+export interface PlayTimelineEntry {
+    tick: number;
+    kind: PlayTimelineKind;
+    /** The action, command, event name or assertion id. */
+    label: string;
+    /** The numbers behind the row: a health, a distance, a wave number, a status. */
+    values?: Readonly<Record<string, PlayValue>>;
+}
+/** One assertion's verdict, with both readings so a failure says what changed and by how much. */
+export interface PlayExpectationResult {
+    id: string;
+    subject: string;
+    tick: number;
+    pass: boolean;
+    /** The reading taken right after `setup`, before the script's steps ran. */
+    initial: PlayValue;
+    /** The reading on the assertion's own tick. */
+    value: PlayValue;
+}
+/** Everything a scripted run produced: the timeline, the assertion verdicts, and a digest of the timeline for replay comparison. */
+export interface PlayRunResult {
+    seed: string | number;
+    /** Fixed tick length the run advanced in seconds. */
+    dt: number;
+    ticks: number;
+    timeline: readonly PlayTimelineEntry[];
+    expectations: readonly PlayExpectationResult[];
+    /** True when every expectation passed. */
+    passed: boolean;
+    /** Deterministic hash of the timeline — equal digests mean two runs played identically. */
+    digest: string;
+}
+/**
+ * FNV-1a over the timeline's canonical JSON. Cheap, dependency-free and stable across runs and
+ * machines, which is all a replay comparison needs.
+ */
+export declare function playTimelineDigest(timeline: readonly PlayTimelineEntry[]): string;
+/** One compact timeline line: `t=120 event combat.damage to=bruiser amount=12 remaining=54`. */
+export declare function formatPlayTimelineEntry(entry: PlayTimelineEntry): string;

package/dist/play/timeline.js

@@ -0,0 +1,27 @@
+/**
+ * FNV-1a over the timeline's canonical JSON. Cheap, dependency-free and stable across runs and
+ * machines, which is all a replay comparison needs.
+ */
+export function playTimelineDigest(timeline) {
+    const text = JSON.stringify(timeline.map((entry) => [entry.tick, entry.kind, entry.label, entry.values ?? null]));
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+function formatValue(value) {
+    if (value === undefined)
+        return "";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? String(value) : value.toFixed(3).replace(/\.?0+$/, "");
+    return String(value);
+}
+/** One compact timeline line: `t=120 event combat.damage to=bruiser amount=12 remaining=54`. */
+export function formatPlayTimelineEntry(entry) {
+    const values = Object.entries(entry.values ?? {})
+        .map(([key, value]) => `${key}=${formatValue(value)}`)
+        .join(" ");
+    return `t=${entry.tick} ${entry.kind} ${entry.label}${values === "" ? "" : ` ${values}`}`;
+}

package/dist/pointer/pointerService.d.ts

@@ -4,6 +4,8 @@ export declare const POINTER_ENTITY_KEY = "jgEntityId";
 export declare const POINTER_OBJECT_KEY = "jgObjectId";
 /** Object-store identities indexed by the current compacted GPU instance slot. @internal */
 export declare const POINTER_OBJECT_INSTANCES_KEY = "jgObjectInstances";
+/** Entity identities indexed by the current compacted GPU batch slot. @internal */
+export declare const POINTER_ENTITY_INSTANCES_KEY = "jgEntityInstances";
 export type PointerHitFilter = (object: THREE.Object3D) => boolean;
 interface PointerDeps {
     camera: THREE.Camera;

package/dist/pointer/pointerService.js

@@ -3,6 +3,8 @@ export const POINTER_ENTITY_KEY = "jgEntityId";
 export const POINTER_OBJECT_KEY = "jgObjectId";
 /** Object-store identities indexed by the current compacted GPU instance slot. @internal */
 export const POINTER_OBJECT_INSTANCES_KEY = "jgObjectInstances";
+/** Entity identities indexed by the current compacted GPU batch slot. @internal */
+export const POINTER_ENTITY_INSTANCES_KEY = "jgEntityInstances";
 function tagOf(object, key) {
     let cursor = object;
     while (cursor !== null) {
@@ -62,7 +64,8 @@ export function createPointerService() {
             return {
                 point,
                 normal,
-                entity: tagOf(hit.object, POINTER_ENTITY_KEY),
+                entity: hit.instanceId === undefined ? tagOf(hit.object, POINTER_ENTITY_KEY) :
+                    hit.object.userData[POINTER_ENTITY_INSTANCES_KEY]?.[hit.instanceId] ?? tagOf(hit.object, POINTER_ENTITY_KEY),
                 object: hit.instanceId === undefined ? tagOf(hit.object, POINTER_OBJECT_KEY) :
                     hit.object.userData[POINTER_OBJECT_INSTANCES_KEY]?.[hit.instanceId] ?? tagOf(hit.object, POINTER_OBJECT_KEY),
                 ...(uv !== undefined ? { uv } : {}),

package/dist/postfx/PostProcessing.d.ts

@@ -51,12 +51,20 @@ export interface PostfxStagePlan {
     grade: GradeConfig | null;
     /** The authored exposure the meter corrects around. */
     exposure: number;
+    /**
+     * Composer backing store as a fraction of the canvas. Every stage below `1` — AO, bloom, DOF,
+     * SMAA and the beauty pass itself — renders into a smaller target, and the OutputPass stretches it
+     * back over the canvas.
+     */
+    resolutionScale: number;
 }
 interface BuiltGraph {
     composer: EffectComposer;
     grade: ShaderPass | null;
     /** Stages this chain actually built, in pass order. A stage absent here costs no draw. */
     stages: readonly PostfxStage[];
+    /** The plan's {@link PostfxStagePlan.resolutionScale}, kept so a resize re-applies it. */
+    resolutionScale: number;
 }
 /**
  * Rounds an adapted exposure to 1/32 of a stop. Without it the sky's display-colour cache (which keys
@@ -66,7 +74,11 @@ interface BuiltGraph {
 export declare function quantizeExposure(value: number): number;
 /** Release each pass and the composer's owned targets. @internal */
 export declare function disposeGraph(built: BuiltGraph): void;
-/** Resize the composer and its passes at the renderer's pixel ratio. @internal */
+/**
+ * Resize the composer and its passes to the plan's share of the renderer's backing store. The
+ * scaled size is rounded to whole pixels: a fractional target size reaches `texImage2D` as one.
+ * @internal
+ */
 export declare function syncSize(built: BuiltGraph, width: number, height: number, pixelRatio: number): void;
 /** AO the chain runs: authored config, {@link DEFAULT_AO} when unset, null when off or the tier skips it. @internal */
 export declare function resolveAoStage(ao: PostProcessingConfig["ao"], tierAllowsAo: boolean): AoConfig | null;
@@ -102,6 +114,8 @@ export declare function buildPostGraph(gl: THREE.WebGLRenderer, scene: THREE.Sce
  * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
  * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages. A stage
  * that is off adds no pass at all, so it costs no draw and allocates no target.
+ * The tier also sets the composer's resolution scale, so the passes a lower tier
+ * keeps still cover fewer pixels.
  */
 export declare function PostProcessing({ config, quality, stages }: {
     config: PostProcessingConfig;

package/dist/postfx/PostProcessing.js

@@ -10,6 +10,7 @@ import { DEFAULT_AO, } from "@jgengine/core/render/postProcessing";
 import { adaptExposure, DEFAULT_AUTO_EXPOSURE, exposureForKey, keyLuminanceFromSamples, } from "@jgengine/core/render/colorPipeline";
 import { ExposureMeterPass } from "./autoExposure.js";
 import { createGradePass } from "./gradeShader.js";
+import { postfxTierPolicy } from "./postfxTierPolicy.js";
 import { releasePostfxOverlayTracking } from "./postfxOverlay.js";
 import { StylizePass } from "./stylizePass.js";
 import { renderShadowlessPrepass } from "./shadowPrepass.js";
@@ -70,10 +71,15 @@ export function disposeGraph(built) {
         pass.dispose();
     built.composer.dispose();
 }
-/** Resize the composer and its passes at the renderer's pixel ratio. @internal */
+/**
+ * Resize the composer and its passes to the plan's share of the renderer's backing store. The
+ * scaled size is rounded to whole pixels: a fractional target size reaches `texImage2D` as one.
+ * @internal
+ */
 export function syncSize(built, width, height, pixelRatio) {
-    built.composer.setPixelRatio(pixelRatio);
-    built.composer.setSize(width, height);
+    const scale = pixelRatio * built.resolutionScale;
+    built.composer.setPixelRatio(1);
+    built.composer.setSize(Math.max(1, Math.round(width * scale)), Math.max(1, Math.round(height * scale)));
 }
 /** AO the chain runs: authored config, {@link DEFAULT_AO} when unset, null when off or the tier skips it. @internal */
 export function resolveAoStage(ao, tierAllowsAo) {
@@ -84,7 +90,8 @@ export function resolveAoStage(ao, tierAllowsAo) {
 /** The stages one chain asks for, before any pass is built. Pure data. @internal */
 export function planPostStages(config, quality = "high", stages) {
     const aa = config.aa === undefined ? "smaa" : config.aa;
-    const tierStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
+    const policy = postfxTierPolicy(quality);
+    const tierStages = stages ?? policy.stages;
     const ao = resolveAoStage(config.ao, tierStages.ao);
     const authoredDof = tierStages.dof && config.dof !== undefined && config.dof !== false ? config.dof : null;
     const bloom = tierStages.bloom && config.bloom !== false ? (config.bloom ?? {}) : null;
@@ -92,7 +99,7 @@ export function planPostStages(config, quality = "high", stages) {
     return {
         samples: aa === false ? 0 : 2,
         ao,
-        aoSamples: quality === "ultra" ? 16 : quality === "high" ? 12 : 8,
+        aoSamples: policy.aoSamples,
         aoGbuffer: smaa || aa === false ? "beauty" : "prepass",
         bloom,
         dof: authoredDof === null ? null : { ...authoredDof, aperture: authoredDof.aperture ?? (quality === "high" ? 0.00025 : 0.00012) },
@@ -101,6 +108,7 @@ export function planPostStages(config, quality = "high", stages) {
         stylize: config.stylize !== undefined && config.stylize !== false ? config.stylize : null,
         grade: config.grade !== false ? (config.grade ?? {}) : null,
         exposure: config.exposure ?? 1,
+        resolutionScale: policy.resolutionScale,
     };
 }
 /**
@@ -198,7 +206,7 @@ export function buildPostGraph(gl, scene, camera, plan, width, height) {
         composer.addPass(grade);
         built.push("grade");
     }
-    return { composer, grade, stages: built };
+    return { composer, grade, stages: built, resolutionScale: plan.resolutionScale };
 }
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
@@ -210,6 +218,8 @@ export function buildPostGraph(gl, scene, camera, plan, width, height) {
  * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
  * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages. A stage
  * that is off adds no pass at all, so it costs no draw and allocates no target.
+ * The tier also sets the composer's resolution scale, so the passes a lower tier
+ * keeps still cover fewer pixels.
  */
 export function PostProcessing({ config, quality = "high", stages }) {
     const gl = useThree((s) => s.gl);

package/dist/postfx/postfxTierPolicy.d.ts

@@ -0,0 +1,25 @@
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+/** What one graphics tier may spend on the post chain. @internal */
+export interface PostfxTierPolicy {
+    /** Composer backing store as a fraction of the canvas; below 1 the OutputPass upscales the result. */
+    resolutionScale: number;
+    /** GTAO's sample count, when the chain runs AO at all. */
+    aoSamples: number;
+    /** The stages the tier offers before the player overrides them. */
+    stages: {
+        ao: boolean;
+        bloom: boolean;
+        dof: boolean;
+        smaa: boolean;
+    };
+}
+/**
+ * The post chain's quality tiers. `high` and `ultra` render at native size; the tiers below pay for
+ * their cheaper stage set twice, by building fewer passes and by rendering the ones left smaller.
+ * `stages` mirrors `DEFAULT_GRAPHICS_PROFILES.postStages`, so a plan built without the player's
+ * toggles spends the same passes the profile names.
+ * @internal
+ */
+export declare const POSTFX_TIER_POLICY: Record<GraphicsQuality, PostfxTierPolicy>;
+/** A tier's post-chain budget; `high` is the reference every lower tier is measured against. @internal */
+export declare function postfxTierPolicy(quality: GraphicsQuality): PostfxTierPolicy;