@jgengine/shell 0.18.0 → 0.19.0

package/dist/scene/cityWindowMaterial.d.ts

@@ -1,12 +1,14 @@
 import * as THREE from "three";
 /**
  * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
- * paints procedural window strips on the side faces of every instanced unit box — floor bands from
- * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
- * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
- * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
- * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
- * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * paints a real facade on the side faces of every instanced unit box — floor bands from the
+ * district's `floorHeight`, spandrels between floors, framed panes with mullions, a per-cell hash
+ * that lights a minority of windows (emissive), and a ground floor of plinth, storefront glazing
+ * and fascia so street level never repeats floor 30. Two instanced attributes drive it:
+ * `instanceGroundOffset` (buried foundation to skip) and `instanceFacade` (`x` = per-building seed,
+ * `y` = facade kind — 0 punched openings, 1 curtain wall, 2 open parking deck). Same
+ * `onBeforeCompile` idiom as the grass/terrain materials; instance colors keep tinting the wall
+ * exactly like the plain massing material.
  * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
  */
 export declare function createCityWindowMaterial(options: {

package/dist/scene/cityWindowMaterial.js

@@ -1,12 +1,14 @@
 import * as THREE from "three";
 /**
  * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
- * paints procedural window strips on the side faces of every instanced unit box — floor bands from
- * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
- * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
- * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
- * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
- * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * paints a real facade on the side faces of every instanced unit box — floor bands from the
+ * district's `floorHeight`, spandrels between floors, framed panes with mullions, a per-cell hash
+ * that lights a minority of windows (emissive), and a ground floor of plinth, storefront glazing
+ * and fascia so street level never repeats floor 30. Two instanced attributes drive it:
+ * `instanceGroundOffset` (buried foundation to skip) and `instanceFacade` (`x` = per-building seed,
+ * `y` = facade kind — 0 punched openings, 1 curtain wall, 2 open parking deck). Same
+ * `onBeforeCompile` idiom as the grass/terrain materials; instance colors keep tinting the wall
+ * exactly like the plain massing material.
  * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
  */
 export function createCityWindowMaterial(options) {
@@ -25,10 +27,12 @@ export function createCityWindowMaterial(options) {
             .replace("#include <common>", `
 #include <common>
 attribute float instanceGroundOffset;
+attribute vec2 instanceFacade;
 varying vec3 vCityLocal;
 varying vec3 vCityScale;
 varying vec3 vCityNormal;
 varying float vCityGround;
+varying vec2 vCityFacade;
 `)
             .replace("#include <begin_vertex>", `
 #include <begin_vertex>
@@ -36,6 +40,7 @@ vCityLocal = position;
 vCityScale = vec3(length(instanceMatrix[0].xyz), length(instanceMatrix[1].xyz), length(instanceMatrix[2].xyz));
 vCityNormal = normal;
 vCityGround = instanceGroundOffset;
+vCityFacade = instanceFacade;
 `);
         shader.fragmentShader = shader.fragmentShader
             .replace("#include <common>", `
@@ -46,6 +51,8 @@ varying vec3 vCityLocal;
 varying vec3 vCityScale;
 varying vec3 vCityNormal;
 varying float vCityGround;
+varying vec2 vCityFacade;
+float cityLit = 0.0;
 float cityHash(vec2 cell) {
   return fract(sin(dot(cell, vec2(127.1, 311.7))) * 43758.5453);
 }
@@ -55,25 +62,77 @@ float cityHash(vec2 cell) {
 {
   // Side faces only — roofs and undersides stay plain wall.
   if (abs(vCityNormal.y) < 0.5) {
-    float along = abs(vCityNormal.x) > 0.5 ? (vCityLocal.z + 0.5) * vCityScale.z : (vCityLocal.x + 0.5) * vCityScale.x;
-    float faceWidth = abs(vCityNormal.x) > 0.5 ? vCityScale.z : vCityScale.x;
+    bool sideX = abs(vCityNormal.x) > 0.5;
+    float along = sideX ? (vCityLocal.z + 0.5) * vCityScale.z : (vCityLocal.x + 0.5) * vCityScale.x;
+    float faceWidth = sideX ? vCityScale.z : vCityScale.x;
     float up = (vCityLocal.y + 0.5) * vCityScale.y - vCityGround;
-    float pitch = 2.4;
-    float floorT = fract(up / uFloorHeight);
-    float colT = fract(along / pitch);
-    float floorIndex = floor(up / uFloorHeight);
-    float colIndex = floor(along / pitch);
-    bool window = up > uFloorHeight * 1.05 && floorT > 0.32 && floorT < 0.78 && colT > 0.2 && colT < 0.8
-      && along > 0.7 && along < faceWidth - 0.7;
-    if (window) {
-      float cell = cityHash(vec2(floorIndex, colIndex) + vec2(vCityScale.x, vCityScale.z));
-      vec3 pane = uWindowColor * mix(0.55, 1.25, cell);
-      diffuseColor.rgb = mix(diffuseColor.rgb, pane, 0.88);
+    float fh = uFloorHeight;
+    float seed = vCityFacade.x;
+    float kind = vCityFacade.y;
+    float face = (sideX ? 2.0 : 0.0) + (vCityNormal.x + vCityNormal.z > 0.0 ? 1.0 : 0.0);
+    vec3 wall = diffuseColor.rgb;
+    float floorT = fract(up / fh);
+    float floorIndex = floor(up / fh);
+    // The facade is a procedural stripe pattern with no mip chain, so once a floor band shrinks
+    // toward a pixel it aliases into speckled static. Measure the on-screen footprint of one metre
+    // of facade and dissolve the detail into its own average before that happens.
+    float facadeFootprint = fwidth(up) + fwidth(along);
+    float detail = 1.0 - smoothstep(fh * 0.08, fh * 0.45, facadeFootprint);
+    if (kind > 1.5) {
+      // Open parking deck: shadowed slots between column bays, solid spandrel below each level.
+      float bay = fract(along / 6.0);
+      bool slot = up > fh * 0.55 && floorT > 0.22 && floorT < 0.82
+        && along > 1.4 && along < faceWidth - 1.4 && bay > 0.14;
+      diffuseColor.rgb = slot ? wall * 0.16 : wall * (floorT < 0.18 ? 0.86 : 1.0);
+    } else if (up > fh * 1.02) {
+      float curtain = step(0.5, kind);
+      float pitch = mix(2.45, 1.75, curtain);
+      float glassW = mix(0.46, 0.7, curtain);
+      float margin = mix(0.9, 0.55, curtain);
+      float sillT = mix(0.36, 0.24, curtain);
+      float headT = mix(0.8, 0.87, curtain);
+      float colIndex = floor(along / pitch);
+      float colC = abs(fract(along / pitch) - 0.5) * 2.0;
+      bool inBand = along > margin && along < faceWidth - margin;
+      if (inBand && floorT > sillT && floorT < headT && colC < glassW) {
+        float cell = cityHash(vec2(floorIndex, colIndex) + vec2(seed * 41.0, face * 7.0));
+        float lit = step(0.9, cell);
+        vec3 pane = uWindowColor * mix(0.34, 0.86, cell);
+        pane = mix(pane, vec3(1.0, 0.9, 0.7), lit * 0.5);
+        // Pane frame + a transom across tall curtain-wall bays: the grid that reads as glazing.
+        float frame = step(glassW - 0.14, colC) + curtain * step(abs(floorT - (sillT + headT) * 0.5), 0.022);
+        diffuseColor.rgb = mix(pane, wall * mix(0.7, 0.5, curtain), clamp(frame, 0.0, 1.0));
+        cityLit = lit * (1.0 - clamp(frame, 0.0, 1.0)) * 0.3;
+      } else if (inBand && (floorT <= sillT || floorT >= headT)) {
+        diffuseColor.rgb = wall * mix(0.9, 0.78, curtain);
+        // Sill lip under each opening catches the light and breaks the flat band.
+        if (colC < glassW && floorT > sillT - 0.055) diffuseColor.rgb = wall * mix(1.08, 0.9, curtain);
+      }
+    } else {
+      // Ground floor: plinth, pier-and-glass shopfront, fascia band under the first slab.
+      if (up < 0.55) {
+        diffuseColor.rgb = wall * 0.62;
+      } else if (faceWidth > 5.0) {
+        float pier = abs(fract(along / 3.1) - 0.5) * 2.0;
+        bool store = up > 0.75 && up < fh * 0.74 && pier < 0.78
+          && along > 1.1 && along < faceWidth - 1.1;
+        if (store) {
+          diffuseColor.rgb = uWindowColor * 0.17;
+          cityLit = 0.1;
+        } else if (up > fh * 0.78 && up < fh * 0.96) {
+          diffuseColor.rgb = wall * 0.75;
+        }
+      }
     }
-    // A thin darker plinth line right above grade grounds the facade.
-    if (up > 0.0 && up < 0.35) diffuseColor.rgb *= 0.8;
+    vec3 distant = mix(wall, uWindowColor * 0.5, 0.42);
+    diffuseColor.rgb = mix(distant, diffuseColor.rgb, detail);
+    cityLit *= detail;
   }
 }
+`)
+            .replace("#include <emissivemap_fragment>", `
+#include <emissivemap_fragment>
+totalEmissiveRadiance += mix(uWindowColor, vec3(1.0, 0.86, 0.6), 0.6) * cityLit;
 `);
     };
     material.customProgramCacheKey = () => `jgengine-city-windows`;

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,5 +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 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". */
@@ -9,12 +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): {
+/** 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,5 +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 { 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";
@@ -26,16 +28,18 @@ export function useSettingsRevision(store) {
     const getVersion = useCallback(() => versionRef.current, []);
     return useSyncExternalStore(subscribe, getVersion, getVersion);
 }
-export function useGraphicsSettings(store, shadowsDefault) {
+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 { quality, profile } = readGraphicsSettings(store, overrides);
     const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
     return {
         shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
-        dpr: GRAPHICS_QUALITY_DPR[quality],
+        dpr: profile.renderScale,
         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;