@jgengine/shell 0.18.1 → 0.19.0

package/dist/render/useModelAnimation.d.ts

@@ -1,5 +1,29 @@
 import * as THREE from "three";
 import type { ModelAnimationConfig } from "@jgengine/core/game/playableGame";
+import { type AnimClipOutput, type AnimGraph } from "@jgengine/core/anim/animGraph";
+/**
+ * For a frame where a `rootMotion` state is current: pins the root bone's horizontal translation to
+ * its bind pose, so the clip plays in place, and returns that step's root travel as a world-space
+ * horizontal delta (through the rig's parent transform, so the entity's facing and the model's
+ * scale apply). The root bone's vertical motion stays in the clip.
+ */
+export declare function takeRootMotion(rootBone: THREE.Object3D, bind: THREE.Vector3, localDelta: readonly [number, number, number] | undefined, out: THREE.Vector3): THREE.Vector3;
+/** A mixer set up to show {@link AnimGraph} output on a rig; see {@link createGraphPose}. */
+export interface GraphPose {
+    /** Clip durations read from the rig, the `clips` argument `runtime.advance` expects. */
+    durations: Readonly<Record<string, {
+        duration: number;
+    }>>;
+    /** Poses the rig with one advance's clip weights and times. */
+    apply(clips: readonly AnimClipOutput[]): void;
+    dispose(): void;
+}
+/**
+ * Binds a graph's clips to a rig exactly as `useModelAnimation` does (masked layers get filtered
+ * clips, additive layers additive ones) so a host that runs its own `createAnimGraphRuntime`, such as
+ * the editor's graph preview, poses the rig from the runtime's output.
+ */
+export declare function createGraphPose(scene: THREE.Object3D, graph: AnimGraph, clips: THREE.AnimationClip[]): GraphPose;
 /**
  * The engine's model animation driver as a standalone hook — the same mixer `EntityModel` runs,
  * for games that render a cloned scene themselves (custom materials, procedural composition).

package/dist/render/useModelAnimation.js

@@ -3,7 +3,7 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
 import { ANIM_PARAMS_KEY, createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
-import { LOCOMOTION_SPEED_PARAM, locomotionGraph } from "@jgengine/core/anim/locomotionGraph";
+import { animGraphFromConfig, LOCOMOTION_SPEED_PARAM } from "@jgengine/core/anim/locomotionGraph";
 import { useOptionalGameContext } from "@jgengine/react/provider";
 function graphClipNames(graph) {
     const names = new Set();
@@ -66,6 +66,56 @@ function warnMissingClips(animation, clips) {
 function actionKey(layer, clip) {
     return `${layer}:${clip}`;
 }
+const rootTravel = new THREE.Vector3();
+const rootBasis = new THREE.Matrix3();
+/**
+ * For a frame where a `rootMotion` state is current: pins the root bone's horizontal translation to
+ * its bind pose, so the clip plays in place, and returns that step's root travel as a world-space
+ * horizontal delta (through the rig's parent transform, so the entity's facing and the model's
+ * scale apply). The root bone's vertical motion stays in the clip.
+ */
+export function takeRootMotion(rootBone, bind, localDelta, out) {
+    rootBone.position.x = bind.x;
+    rootBone.position.z = bind.z;
+    out.set(0, 0, 0);
+    if (localDelta === undefined || rootBone.parent === null)
+        return out;
+    rootBone.parent.updateWorldMatrix(true, false);
+    out.set(localDelta[0], localDelta[1], localDelta[2]).applyMatrix3(rootBasis.setFromMatrix4(rootBone.parent.matrixWorld));
+    out.y = 0;
+    return out;
+}
+function applyGraphClips(actions, clips) {
+    for (const action of actions.values())
+        action.weight = 0;
+    for (const entry of clips) {
+        const action = actions.get(actionKey(entry.layer, entry.clip));
+        if (action === undefined)
+            continue;
+        action.weight += entry.weight;
+        action.time = entry.time;
+    }
+}
+/**
+ * Binds a graph's clips to a rig exactly as `useModelAnimation` does (masked layers get filtered
+ * clips, additive layers additive ones) so a host that runs its own `createAnimGraphRuntime`, such as
+ * the editor's graph preview, poses the rig from the runtime's output.
+ */
+export function createGraphPose(scene, graph, clips) {
+    const mixer = new THREE.AnimationMixer(scene);
+    const playback = buildGraphPlayback(scene, mixer, graph, clips);
+    return {
+        durations: playback.durations,
+        apply(output) {
+            applyGraphClips(playback.actions, output);
+            mixer.update(0);
+        },
+        dispose() {
+            mixer.stopAllAction();
+            mixer.uncacheRoot(scene);
+        },
+    };
+}
 function buildGraphPlayback(scene, mixer, graph, clips) {
     const actions = new Map();
     const durations = {};
@@ -147,27 +197,8 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
     const graphRef = useRef(null);
     const states = animation?.states;
     const oneShots = animation?.oneShots;
-    const graph = useMemo(() => {
-        if (animation?.graph !== undefined)
-            return animation.graph;
-        if (states === undefined)
-            return undefined;
-        const graphOneShots = {};
-        for (const [event, spec] of Object.entries(oneShots ?? {})) {
-            const clip = typeof spec === "string" ? spec : spec[0];
-            if (clip !== undefined)
-                graphOneShots[event] = clip;
-        }
-        return locomotionGraph({
-            idle: states.idle,
-            walk: states.walk,
-            ...(states.run === undefined ? {} : { run: states.run }),
-            walkSpeed: states.walkSpeed,
-            runSpeed: states.runSpeed,
-            fadeSec: states.fadeSec,
-            ...(Object.keys(graphOneShots).length === 0 ? {} : { oneShots: graphOneShots }),
-        });
-    }, [animation?.graph, states, oneShots]);
+    const authoredGraph = animation?.graph;
+    const graph = useMemo(() => animGraphFromConfig({ graph: authoredGraph, states, oneShots }), [authoredGraph, states, oneShots]);
     useEffect(() => {
         if (animation === undefined || clips.length === 0) {
             mixerRef.current = null;
@@ -263,29 +294,19 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             }
             params[LOCOMOTION_SPEED_PARAM] = playback.smoothedSpeed;
             const out = playback.runtime.advance(delta * (animation?.timeScale ?? 1), params, playback.durations);
-            for (const action of playback.actions.values())
-                action.weight = 0;
-            for (const entry of out.clips) {
-                const action = playback.actions.get(actionKey(entry.layer, entry.clip));
-                if (action === undefined)
-                    continue;
-                action.weight += entry.weight;
-                action.time = entry.time;
-            }
+            applyGraphClips(playback.actions, out.clips);
             mixerRef.current.update(0);
-            const currentPlayback = graphRef.current;
-            if (currentPlayback !== null && currentPlayback.rootBone !== null && currentPlayback.rootBindPosition !== null) {
-                currentPlayback.rootBone.position.copy(currentPlayback.rootBindPosition);
-            }
-            if (ctx !== null && instanceId !== undefined) {
-                const rootDelta = out.rootDelta;
-                const entity = rootDelta === undefined ? null : ctx.scene.entity.get(instanceId);
-                if (entity !== null && rootDelta !== undefined) {
+            if (out.rootMotion === true && playback.rootBone !== null && playback.rootBindPosition !== null) {
+                const travel = takeRootMotion(playback.rootBone, playback.rootBindPosition, out.rootDelta, rootTravel);
+                const entity = ctx === null || instanceId === undefined || (travel.x === 0 && travel.z === 0) ? null : ctx.scene.entity.get(instanceId);
+                if (entity !== null && ctx !== null && instanceId !== undefined) {
                     ctx.scene.entity.setPose(instanceId, {
-                        position: [entity.position[0] + rootDelta[0], entity.position[1] + rootDelta[1], entity.position[2] + rootDelta[2]],
+                        position: [entity.position[0] + travel.x, entity.position[1], entity.position[2] + travel.z],
                         dt: delta,
                     });
                 }
+            }
+            if (ctx !== null && instanceId !== undefined) {
                 for (const event of out.events)
                     ctx.game.events.emit("animation.event", { instanceId, name: event.name, clip: event.clip });
             }

package/dist/scene/AuthoredScene.d.ts

@@ -40,6 +40,15 @@ export interface AuthoredObjectsProps {
  * headless twin: `resolveAuthoredObjects` / `placeAuthoredObjects`.
  */
 export declare function AuthoredObjects({ document, field, verticalOffset, onExisting, }: AuthoredObjectsProps): null;
+/**
+ * Writes the document's studio solids (city buildings and any kind with a `solids` hook) into
+ * `ctx.world.solids`, so what the studios draw also blocks the player, NPCs and physics.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function AuthoredSolids({ document, field }: {
+    document: EditorDocument;
+    field: TerrainField;
+}): null;
 /** Props for {@link AuthoredScene}: the document to render and the ground field to drape/ground on. */
 export interface AuthoredSceneProps {
     document: EditorDocument;

package/dist/scene/AuthoredScene.js

@@ -3,6 +3,7 @@ import { Fragment, useCallback, useEffect, useMemo, useSyncExternalStore } from
 import * as THREE from "three";
 import { getDocumentLiveSync, subscribeDocumentLiveSyncInstall, } from "@jgengine/core/editor/index";
 import { placeAuthoredObjects, resolveAuthoredObjects, } from "@jgengine/core/world/authoredObjects";
+import { syncAuthoredSolids } from "@jgengine/core/world/authoredSolids";
 import { buildRoadRibbon, GROUND_DECAL_LAYERS, roundPathCorners } from "@jgengine/core/world/roads";
 import { isScatterPath, resolveScatter } from "@jgengine/core/world/scatterRegion";
 import { getAssetGenerator } from "@jgengine/core/scene/assetGenerator";
@@ -143,6 +144,21 @@ export function AuthoredObjects({ document, field, verticalOffset = 0, onExistin
     }, [ctx.scene.object, field, objects, onExisting, verticalOffset]);
     return null;
 }
+/**
+ * Writes the document's studio solids (city buildings and any kind with a `solids` hook) into
+ * `ctx.world.solids`, so what the studios draw also blocks the player, NPCs and physics.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export function AuthoredSolids({ document, field }) {
+    const ctx = useGameContext();
+    useEffect(() => {
+        syncAuthoredSolids(ctx.world.solids, document, (x, z) => field.sampleHeight(x, z));
+    }, [ctx.world.solids, document, field]);
+    useEffect(() => () => {
+        syncAuthoredSolids(ctx.world.solids, { markers: [], volumes: [], paths: [] });
+    }, [ctx.world.solids]);
+    return null;
+}
 /**
  * Renders an editor document's scene content — draped paths plus GPU-instanced foliage — from one
  * mount, grounded on the live `field`. The runtime counterpart to authoring a scene in the editor:
@@ -164,5 +180,5 @@ export function AuthoredScene({ document, field, pathKinds, scatterModels, asset
                     field,
                     ...(assets === undefined ? {} : { assets }),
                     ...(groundColorAt === undefined ? {} : { groundColorAt }),
-                } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
+                } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), _jsx(AuthoredSolids, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
 }

package/dist/scene/CityRenderer.js

@@ -22,7 +22,7 @@ import { offsetPath } from "@jgengine/core/world/streets";
 import { triangulatePolygon, triangulateRingBand } from "@jgengine/core/world/cityGeometry";
 import { resolveCityObject, CITY_KIND, CITY_ZONE_KIND, } from "@jgengine/core/world/cityKind";
 import { zoneBand, zoneMetric } from "@jgengine/core/world/cityContent";
-import { generateBuilding, resolveBuildingPalette, resolveBuildingWallTones, } from "@jgengine/core/world/buildings";
+import { generateBuilding, buildingSurfaceColor, resolveBuildingPalette, resolveBuildingWallTones, } from "@jgengine/core/world/buildings";
 import { hashString } from "@jgengine/core/random/rng";
 import { buildScatterProxy } from "../scatter/scatterProxies.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
@@ -327,12 +327,12 @@ function unitGeometries() {
 const ROLE_JITTER = { wall: 1, roof: 0.5, trim: 0.35, accent: 0.6 };
 function roleColor(palette, role) {
     if (role === "wall")
-        return palette.wall;
+        return buildingSurfaceColor(palette.wall);
     if (role === "roof")
-        return palette.roof;
+        return buildingSurfaceColor(palette.roof);
     if (role === "trim")
-        return palette.corner;
-    return palette.awning;
+        return buildingSurfaceColor(palette.corner);
+    return buildingSurfaceColor(palette.awning);
 }
 const DETAIL_RADIUS = 95;
 const DETAIL_MAX = 12;
@@ -547,7 +547,7 @@ function OneCity({ object, context }) {
             return mesh;
         };
         const plain = new THREE.MeshStandardMaterial({ roughness: 0.85, metalness: 0.04 });
-        const banded = createCityWindowMaterial({ floorHeight: resolved.rules.floorHeight, windowColor: palette.window });
+        const banded = createCityWindowMaterial({ floorHeight: resolved.rules.floorHeight, windowColor: buildingSurfaceColor(palette.window) });
         const meshes = [
             makeMesh("box", units.box, plain),
             makeMesh("banded", units.box, banded),

package/dist/settings/QuickControls.js

@@ -14,7 +14,7 @@ function QuickToggle({ row }) {
 function QuickSelect({ row }) {
     const options = row.options ?? [];
     const current = String(row.value);
-    return (_jsxs("div", { className: "flex items-center justify-between gap-2 text-xs text-neutral-300", children: [_jsx("span", { className: "truncate", children: row.label }), _jsx("div", { className: "flex shrink-0 gap-1 rounded-md bg-neutral-950/60 p-0.5 ring-1 ring-white/10", children: options.map((option) => {
+    return (_jsxs("div", { className: "flex items-center justify-between gap-2 text-xs text-neutral-300", children: [_jsx("span", { className: "truncate", children: row.label }), _jsx("div", { className: "flex flex-wrap justify-end gap-1 rounded-md bg-neutral-950/60 p-0.5 ring-1 ring-white/10", children: options.map((option) => {
                     const selected = option.value === current;
                     return (_jsx("button", { type: "button", onClick: () => row.set(option.value), className: `rounded px-2 py-1 font-medium transition ${selected ? "bg-emerald-500 text-neutral-950" : "text-neutral-300 hover:bg-neutral-800"}`, children: option.label }, option.value));
                 }) })] }));

package/dist/settings/SettingsMenu.js

@@ -40,7 +40,7 @@ function ToggleRow({ row }) {
 function SelectRow({ row }) {
     const options = row.options ?? [];
     const current = String(row.value);
-    return (_jsx(RowShell, { label: row.label, control: _jsx("div", { className: "flex shrink-0 gap-1 rounded-lg p-1", style: { background: surfaceDeep }, children: options.map((option) => {
+    return (_jsx(RowShell, { label: row.label, control: _jsx("div", { className: "flex flex-wrap justify-end gap-1 rounded-lg p-1", style: { background: surfaceDeep }, children: options.map((option) => {
                 const selected = option.value === current;
                 return (_jsx("button", { type: "button", onClick: () => row.set(option.value), className: "min-h-[34px] rounded-md px-3 text-sm font-medium transition", style: selected ? { background: accent, color: onAccent } : { color: textDim }, children: option.label }, option.value));
             }) }) }));

package/dist/settings/appliedSettings.d.ts

@@ -1,6 +1,7 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
 import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
-import { type GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+import { type GraphicsProfileOverrides } from "@jgengine/core/settings/graphicsSettings";
 import { type TouchJoystickVariant, type TouchStyle } from "@jgengine/core/input/touchScheme";
 import type { AudioEngine } from "../audio/audioEngine.js";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
@@ -10,13 +11,18 @@ export declare function useTouchStyle(store: SettingsStore, fallback: TouchStyle
 /** Shell-internal: binds the SettingsStore joystick-variant choice (fixed vs floating) to the touch renderer. @internal */
 export declare function useTouchJoystickVariant(store: SettingsStore): TouchJoystickVariant;
 export declare function useSettingsRevision(store: SettingsStore): number;
-export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean, overrides?: Partial<Record<GraphicsQuality, Partial<GraphicsProfile>>>): {
+/** The player's graphics choices as the shell applies them. */
+export interface AppliedGraphicsSettings {
     shadows: boolean;
     dpr: number;
     uiScale: number;
     quality: GraphicsQuality;
     profile: GraphicsProfile;
-};
+    /** Frames-per-second cap; 0 renders every display refresh. */
+    frameRateLimit: number;
+    showFps: boolean;
+}
+export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean, overrides?: GraphicsProfileOverrides): AppliedGraphicsSettings;
 export declare function AudioSettingsBridge({ store, engine, buses, }: {
     store: SettingsStore;
     engine: AudioEngine;

package/dist/settings/appliedSettings.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
-import { busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
-import { resolveGraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+import { busVolumeSettingId, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { readGraphicsSettings } from "@jgengine/core/settings/graphicsSettings";
+import { readFrameRateLimit } from "@jgengine/core/settings/frameRateLimit";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANTS, TOUCH_STYLES, } from "@jgengine/core/input/touchScheme";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
 export const TOUCH_STYLE_AUTO = "auto";
@@ -29,9 +30,7 @@ export function useSettingsRevision(store) {
 }
 export function useGraphicsSettings(store, shadowsDefault, overrides) {
     useSettingsRevision(store);
-    const rawQuality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
-    const quality = GRAPHICS_QUALITY_DPR[rawQuality] !== undefined ? rawQuality : "high";
-    const profile = resolveGraphicsProfile(quality, overrides?.[quality]);
+    const { quality, profile } = readGraphicsSettings(store, overrides);
     const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
     return {
         shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
@@ -39,6 +38,8 @@ export function useGraphicsSettings(store, shadowsDefault, overrides) {
         uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
         quality,
         profile,
+        frameRateLimit: readFrameRateLimit(store),
+        showFps: store.get(SETTING_IDS.graphicsShowFps, false),
     };
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {

package/dist/settings/settingsController.d.ts

@@ -2,6 +2,7 @@ import { bindingLabel, type ActionCodesMap } from "@jgengine/core/input/actionBi
 import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
 import { type GameSettingDef, type SettingCategory, type SettingCategoryDef } from "@jgengine/core/settings/settingsModel";
+import { type GraphicsProfileOverrides } from "@jgengine/core/settings/graphicsSettings";
 import { type SettingsActionView, type SettingsKeybindRow, type SettingsCategoryView, type SettingsController, type SettingsRow } from "@jgengine/react/settings";
 export type { SettingsActionView, SettingsKeybindRow, SettingsCategoryView, SettingsController, SettingsRow };
 export interface SettingsControllerInput {
@@ -11,6 +12,8 @@ export interface SettingsControllerInput {
     categories: readonly SettingCategoryDef[];
     hide: readonly SettingCategory[];
     fovEnabled: boolean;
+    /** The game's per-tier profile overrides (`defineGame({ graphics })`), so tier defaults match what renders. */
+    graphics?: GraphicsProfileOverrides;
     hideBindings: readonly string[];
     /** Show the touch-controls skin selector in Controls (touch device with a dock). */
     touchStyle: boolean;

package/dist/settings/settingsController.js

@@ -1,5 +1,7 @@
 import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
-import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, GRAPHICS_POST_STAGES, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
+import { FRAME_RATE_LIMIT_DISPLAY, FRAME_RATE_LIMIT_OPTIONS } from "@jgengine/core/settings/frameRateLimit";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANT_OPTIONS, TOUCH_STYLE_OPTIONS, } from "@jgengine/core/input/touchScheme";
 import { TOUCH_STYLE_AUTO, useSettingsRevision } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
@@ -61,14 +63,42 @@ export function useSettingsCategories(config) {
         }),
         ...extrasFor("sound"),
     ];
+    const graphics = readGraphicsSettings(store, config.graphics);
     const graphicsRows = [
         {
             id: SETTING_IDS.graphicsQuality,
             label: "Quality",
             kind: "select",
-            value: store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY),
+            value: graphics.quality,
             options: GRAPHICS_QUALITY_OPTIONS,
-            set: (value) => store.set(SETTING_IDS.graphicsQuality, value),
+            set: (value) => applyGraphicsQuality(store, String(value), config.graphics),
+        },
+        {
+            id: SETTING_IDS.graphicsRenderScale,
+            label: "Render scale",
+            kind: "slider",
+            value: graphics.profile.renderScale,
+            min: RENDER_SCALE_MIN,
+            max: RENDER_SCALE_MAX,
+            step: RENDER_SCALE_STEP,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsRenderScale, value),
+        },
+        {
+            id: SETTING_IDS.graphicsFrameRateLimit,
+            label: "Frame rate limit",
+            kind: "select",
+            value: store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY),
+            options: FRAME_RATE_LIMIT_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsFrameRateLimit, String(value)),
+        },
+        {
+            id: SETTING_IDS.graphicsAnisotropy,
+            label: "Texture filtering",
+            kind: "select",
+            value: String(graphics.profile.anisotropy),
+            options: ANISOTROPY_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsAnisotropy, String(value)),
         },
         {
             id: SETTING_IDS.graphicsShadows,
@@ -77,6 +107,13 @@ export function useSettingsCategories(config) {
             value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
             set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
         },
+        ...GRAPHICS_POST_STAGES.map((stage) => ({
+            id: graphicsPostStageSettingId(stage),
+            label: GRAPHICS_POST_STAGE_LABELS[stage],
+            kind: "toggle",
+            value: graphics.profile.postStages[stage],
+            set: (value) => store.set(graphicsPostStageSettingId(stage), value),
+        })),
         {
             id: SETTING_IDS.graphicsUiScale,
             label: "UI scale",
@@ -88,6 +125,13 @@ export function useSettingsCategories(config) {
             format: percent,
             set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
         },
+        {
+            id: SETTING_IDS.graphicsShowFps,
+            label: "Show FPS",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShowFps, false),
+            set: (value) => store.set(SETTING_IDS.graphicsShowFps, value),
+        },
         ...extrasFor("graphics"),
     ];
     const gameplayRows = [

package/dist/structures/BuildingKitBatch.js

@@ -5,6 +5,7 @@ import * as THREE from "three";
 import { sharedGltfLoader } from "../render/modelLoad.js";
 import { buildScatterModelSources, disposeScatterModelSources, } from "../scatter/scatterModels.js";
 import { composeBuildingKitMatrix, measureBuildingKitModel, } from "./buildingKitFit.js";
+import { applyBuildingSurface, surfaceKey, useBuildingSurfaceTextures } from "./buildingSurface.js";
 function KitSourceInstances({ source, material, matrices, }) {
     const meshRef = useRef(null);
     useEffect(() => {
@@ -22,16 +23,21 @@ function KitSourceInstances({ source, material, matrices, }) {
     }, [matrices, source]);
     return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
 }
-function tintOne(material, color) {
+function styleOne(material, tint, surface, textures) {
     const clone = material.clone();
     const tintable = clone;
-    if (tintable.color !== undefined)
-        tintable.color.copy(color);
+    if (tint !== undefined && tintable.color !== undefined)
+        tintable.color.copy(tint);
+    if (surface !== undefined && clone.isMeshStandardMaterial === true) {
+        applyBuildingSurface(clone, surface, textures);
+    }
     return clone;
 }
-function tintMaterial(material, tint) {
-    const color = new THREE.Color(tint);
-    return Array.isArray(material) ? material.map((entry) => tintOne(entry, color)) : tintOne(material, color);
+function styleMaterial(material, tint, surface, textures) {
+    const color = tint === "" ? undefined : new THREE.Color(tint);
+    return Array.isArray(material)
+        ? material.map((entry) => styleOne(entry, color, surface, textures))
+        : styleOne(material, color, surface, textures);
 }
 function disposeMaterial(material) {
     if (Array.isArray(material))
@@ -52,27 +58,25 @@ export function BuildingKitBatch({ url, instances }) {
     useEffect(() => () => disposeScatterModelSources(root), [root]);
     const bounds = useMemo(() => measureBuildingKitModel(root), [root]);
     const groups = useMemo(() => {
-        const byTint = new Map();
+        const byKey = new Map();
         for (const instance of instances) {
             const matrix = composeBuildingKitMatrix(instance, bounds, new THREE.Matrix4());
             const tint = instance.part.tint ?? "";
-            const bucket = byTint.get(tint);
+            const surface = instance.part.material;
+            const key = `${tint}|${surfaceKey(surface)}`;
+            const bucket = byKey.get(key);
             if (bucket === undefined)
-                byTint.set(tint, [matrix]);
+                byKey.set(key, { key, tint, surface, matrices: [matrix] });
             else
-                bucket.push(matrix);
+                bucket.matrices.push(matrix);
         }
-        return [...byTint.entries()];
+        return [...byKey.values()];
     }, [instances, bounds]);
-    const tinted = useMemo(() => {
-        const map = new Map();
-        for (const [tint] of groups) {
-            if (tint === "")
-                continue;
-            map.set(tint, sources.map((source) => tintMaterial(source.material, tint)));
-        }
-        return map;
-    }, [groups, sources]);
-    useEffect(() => () => tinted.forEach((list) => list.forEach(disposeMaterial)), [tinted]);
-    return (_jsx(_Fragment, { children: groups.map(([tint, matrices]) => sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: tinted.get(tint)?.[index] ?? source.material, matrices: matrices }, `${tint}:${index}`)))) }));
+    return (_jsx(_Fragment, { children: groups.map((group) => group.tint === "" && group.surface === undefined ? (sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: source.material, matrices: group.matrices }, `${group.key}:${index}`)))) : (_jsx(StyledKitSources, { sources: sources, group: group }, group.key))) }));
+}
+function StyledKitSources({ sources, group }) {
+    const textures = useBuildingSurfaceTextures(group.surface);
+    const styled = useMemo(() => sources.map((source) => styleMaterial(source.material, group.tint, group.surface, textures)), [sources, group.tint, group.surface, textures]);
+    useEffect(() => () => styled.forEach(disposeMaterial), [styled]);
+    return (_jsx(_Fragment, { children: sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: styled[index], matrices: group.matrices }, index))) }));
 }

package/dist/structures/GeneratedBuilding.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { BuildingKitSlot } from "@jgengine/core/world/buildings";
+import { type BuildingKitSlot, type BuildingSurface } from "@jgengine/core/world/buildings";
 import type { BuildingKit } from "@jgengine/core/world/buildingKit";
 export type BuildingFacade = "front" | "back" | "left" | "right" | "roof";
 export type BuildingPartKind = "wall" | "window" | "awning" | "airConditioner" | "clothesline" | "storefront" | "shutter" | "storeSign" | "roof" | "roofProp" | "guardrail" | "corner";
@@ -17,20 +17,8 @@ export interface GeneratedBuildingData {
     id: string;
     parts: readonly BuildingPartPlacement[];
 }
-export interface BuildingMaterialPalette {
-    wall?: string;
-    window?: string;
-    awning?: string;
-    airConditioner?: string;
-    clothesline?: string;
-    storefront?: string;
-    shutter?: string;
-    storeSign?: string;
-    roof?: string;
-    roofProp?: string;
-    guardrail?: string;
-    corner?: string;
-}
+/** Per part kind: a hex colour, or a colour plus tiled PBR maps (`BuildingSurfaceMaterial`). */
+export type BuildingMaterialPalette = Partial<Record<BuildingPartKind, BuildingSurface>>;
 export interface BuildingKitRenderer {
     renderPart?: (part: BuildingPartPlacement) => ReactNode | undefined;
 }

package/dist/structures/GeneratedBuilding.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { buildingSurfaceColor, resolveBuildingSurface, } from "@jgengine/core/world/buildings";
 import { useDisposable } from "../render/useDisposable.js";
 import { BuildingKitBatch } from "./BuildingKitBatch.js";
 import { bucketBuildingParts, normalFor, outwardOffset } from "./buildingKitFit.js";
+import { applyBuildingSurface, useBuildingSurfaceTextures } from "./buildingSurface.js";
 const DEFAULT_PALETTE = {
     wall: "#83766a",
     window: "#8ecae6",
@@ -18,8 +20,12 @@ const DEFAULT_PALETTE = {
     guardrail: "#a8a29e",
     corner: "#6b6258",
 };
+function surfaceFor(kind, palette) {
+    const surface = resolveBuildingSurface(palette?.[kind] ?? DEFAULT_PALETTE[kind]);
+    return surface.color === undefined ? { ...surface, color: DEFAULT_PALETTE[kind] } : surface;
+}
 function colorFor(kind, palette) {
-    return palette?.[kind] ?? DEFAULT_PALETTE[kind];
+    return buildingSurfaceColor(palette?.[kind], DEFAULT_PALETTE[kind]);
 }
 function materialFor(part, palette) {
     const color = colorFor(part.kind, palette);
@@ -34,22 +40,22 @@ function materialFor(part, palette) {
     }
     return _jsx("meshStandardMaterial", { color: color, roughness: 0.88, metalness: 0 });
 }
-function batchMaterialFor(kind, palette) {
-    const color = colorFor(kind, palette);
-    if (kind === "window" || kind === "storefront") {
-        return new THREE.MeshPhysicalMaterial({ color, roughness: 0.12, metalness: 0, transparent: true, opacity: 0.56 });
-    }
-    if (kind === "storeSign") {
-        return new THREE.MeshStandardMaterial({ color, emissive: color, emissiveIntensity: 0.6, roughness: 0.5 });
-    }
-    if (kind === "roofProp") {
-        return new THREE.MeshStandardMaterial({ color, roughness: 0.65, metalness: 0.1 });
-    }
-    return new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
+function batchMaterialFor(kind, surface, textures) {
+    const color = surface.color ?? DEFAULT_PALETTE[kind];
+    const base = kind === "window" || kind === "storefront"
+        ? new THREE.MeshPhysicalMaterial({ color, roughness: 0.12, metalness: 0, transparent: true, opacity: 0.56 })
+        : kind === "storeSign"
+            ? new THREE.MeshStandardMaterial({ color, emissive: color, emissiveIntensity: 0.6, roughness: 0.5 })
+            : kind === "roofProp"
+                ? new THREE.MeshStandardMaterial({ color, roughness: 0.65, metalness: 0.1 })
+                : new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
+    return applyBuildingSurface(base, surface, textures);
 }
-function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
+function BuildingKindBatch({ kind, matrices, palette, geometry }) {
+    const surface = useMemo(() => surfaceFor(kind, palette), [kind, palette]);
+    const textures = useBuildingSurfaceTextures(surface);
     const meshRef = useRef(null);
-    const material = useDisposable(() => batchMaterialFor(kind, palette), [kind, palette]);
+    const material = useDisposable(() => batchMaterialFor(kind, surface, textures), [kind, surface, textures]);
     useLayoutEffect(() => {
         const mesh = meshRef.current;
         if (mesh === null)

package/dist/structures/buildingSurface.d.ts

@@ -0,0 +1,21 @@
+import * as THREE from "three";
+import type { BuildingSurfaceMaps, BuildingSurfaceMaterial } from "@jgengine/core/world/buildings";
+import type { MaterialOverrideTextures } from "../materialOverride.js";
+/** A surface that names at least one map URL. */
+export type TexturedBuildingSurface = BuildingSurfaceMaterial & {
+    maps: BuildingSurfaceMaps;
+};
+/** True when the surface names at least one map URL, so the batch needs the textured path. */
+export declare function surfaceHasMaps(surface: BuildingSurfaceMaterial | undefined): surface is TexturedBuildingSurface;
+/** A stable key for bucketing instances that share one surface (same colour, maps, tiling, and response). */
+export declare function surfaceKey(surface: BuildingSurfaceMaterial | undefined): string;
+/**
+ * Loads a surface's PBR maps and returns per-caller clones configured to tile `repeat` times per
+ * slot, or `undefined` until the first map arrives so the batch draws its flat colour meanwhile.
+ * Clones share the decoded image, so two kinds using one map at different repeats cost one
+ * download. Maps whose file is missing are skipped rather than failing the whole surface.
+ * @internal
+ */
+export declare function useBuildingSurfaceTextures(surface: BuildingSurfaceMaterial | undefined): MaterialOverrideTextures | undefined;
+/** Applies a surface's colour, response, and loaded maps onto a standard or physical material in place. @internal */
+export declare function applyBuildingSurface(material: THREE.MeshStandardMaterial, surface: BuildingSurfaceMaterial, textures: MaterialOverrideTextures | undefined): THREE.MeshStandardMaterial;