@jgengine/core 0.18.0 → 0.18.1

package/dist/vfx/particleDirector.d.ts

@@ -0,0 +1,68 @@
+import type { EmitterConfig, Vec3 } from "./particles.js";
+/** How a particle effect composites on screen: `additive` for sparks/fire/glow, `normal` for smoke/dust. */
+export type ParticleBlendHint = "additive" | "normal";
+/** A one-shot burst request — consumed once by the renderer, never serialized. */
+export interface ParticleBurst {
+    /** Monotonic sequence id so a renderer can consume each burst exactly once. */
+    seq: number;
+    config: EmitterConfig;
+    /** Particles to emit immediately. */
+    count: number;
+    blending?: ParticleBlendHint;
+}
+/** Options for {@link ParticleDirector.attach}. */
+export interface ParticleAttachOptions {
+    /** Scene entity id the emitter origin tracks each frame (plus `offset`). */
+    follow?: string;
+    /** World offset from the followed entity (or from the config position when unfollowed). */
+    offset?: Vec3;
+    blending?: ParticleBlendHint;
+}
+/** A keyed continuous emitter owned by the director until detached. */
+export interface ParticleEmitterSpec {
+    id: string;
+    config: EmitterConfig;
+    follow?: string;
+    offset?: Vec3;
+    blending?: ParticleBlendHint;
+}
+/** Serializable director state: the standing emitters (bursts are transient by nature). */
+export interface ParticleDirectorState {
+    nextSeq: number;
+    emitters: ParticleEmitterSpec[];
+}
+/**
+ * The game-side seam for particle effects. Game logic requests one-shot bursts and
+ * standing emitters as plain data; the shell renders them through
+ * `createParticleSystem`/`ParticleField`, applies the graphics-quality particle cap,
+ * and tracks `follow` entities. Nothing here touches a renderer, so commands and
+ * `onTick` systems can drive VFX headlessly and tests can assert the requested effects.
+ */
+export interface ParticleDirector {
+    /** Queue a one-shot burst (impact puff, debris, muzzle smoke). */
+    burst(config: EmitterConfig, count: number, blending?: ParticleBlendHint): void;
+    /** Create or replace a standing emitter under `id` (exhaust, dust plume, torch smoke). */
+    attach(id: string, config: EmitterConfig, options?: ParticleAttachOptions): void;
+    /** Patch a standing emitter's config in place (e.g. scale exhaust rate with speed). */
+    retune(id: string, patch: Partial<EmitterConfig>): void;
+    /** Remove a standing emitter. Unknown ids are ignored. */
+    detach(id: string): void;
+    /** Drop every standing emitter and any unconsumed bursts. */
+    clear(): void;
+    /** The standing emitters, for renderers and assertions. */
+    emitters(): readonly ParticleEmitterSpec[];
+    /** Return and forget the queued bursts — the renderer's consume-once read. */
+    drainBursts(): ParticleBurst[];
+    subscribe(listener: () => void): () => void;
+    snapshot(): ParticleDirectorState;
+    restore(state: ParticleDirectorState): void;
+}
+/**
+ * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
+ * State is data-only and serializable: standing emitters survive `snapshot`/`restore`,
+ * queued bursts are transient. The renderer subscribes, drains bursts, and mirrors
+ * the emitter list — the director never allocates particle pools itself.
+ *
+ * @capability particle-director game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+ */
+export declare function createParticleDirector(): ParticleDirector;

package/dist/vfx/particleDirector.js

@@ -0,0 +1,81 @@
+/**
+ * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
+ * State is data-only and serializable: standing emitters survive `snapshot`/`restore`,
+ * queued bursts are transient. The renderer subscribes, drains bursts, and mirrors
+ * the emitter list — the director never allocates particle pools itself.
+ *
+ * @capability particle-director game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+ */
+export function createParticleDirector() {
+    let nextSeq = 1;
+    let bursts = [];
+    const emitters = new Map();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        burst(config, count, blending) {
+            const wanted = Math.floor(count);
+            if (wanted <= 0)
+                return;
+            bursts.push({ seq: nextSeq++, config, count: wanted, ...(blending === undefined ? {} : { blending }) });
+            notify();
+        },
+        attach(id, config, options) {
+            emitters.set(id, {
+                id,
+                config,
+                ...(options?.follow === undefined ? {} : { follow: options.follow }),
+                ...(options?.offset === undefined ? {} : { offset: options.offset }),
+                ...(options?.blending === undefined ? {} : { blending: options.blending }),
+            });
+            notify();
+        },
+        retune(id, patch) {
+            const current = emitters.get(id);
+            if (current === undefined)
+                return;
+            emitters.set(id, { ...current, config: { ...current.config, ...patch } });
+            notify();
+        },
+        detach(id) {
+            if (!emitters.delete(id))
+                return;
+            notify();
+        },
+        clear() {
+            if (emitters.size === 0 && bursts.length === 0)
+                return;
+            emitters.clear();
+            bursts = [];
+            notify();
+        },
+        emitters() {
+            return Array.from(emitters.values());
+        },
+        drainBursts() {
+            if (bursts.length === 0)
+                return [];
+            const drained = bursts;
+            bursts = [];
+            return drained;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { nextSeq, emitters: Array.from(emitters.values()) };
+        },
+        restore(state) {
+            nextSeq = state.nextSeq;
+            bursts = [];
+            emitters.clear();
+            for (const spec of state.emitters)
+                emitters.set(spec.id, spec);
+            notify();
+        },
+    };
+}

package/dist/world/buildings.d.ts

@@ -108,6 +108,18 @@ export type BuildingPaletteOverrides = Partial<BuildingPalette>;
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
+/**
+ * Per-style facade-tone family: the wall colours a district spreads across its buildings so
+ * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's
+ * own `wall`; the rest fan warmer/cooler and lighter/darker around it.
+ */
+export declare const BUILDING_STYLE_WALL_TONES: Record<BuildingStyle, readonly string[]>;
+/**
+ * The facade-tone family for a style — the ramp {@link BUILDING_STYLE_WALL_TONES} keeps, falling
+ * back to the style's single palette wall when a style has no ramp.
+ * @internal
+ */
+export declare function resolveBuildingWallTones(style?: BuildingStyle): readonly string[];
 /** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
 /**

package/dist/world/buildings.js

@@ -181,6 +181,34 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/**
+ * Per-style facade-tone family: the wall colours a district spreads across its buildings so
+ * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's
+ * own `wall`; the rest fan warmer/cooler and lighter/darker around it.
+ */
+export const BUILDING_STYLE_WALL_TONES = {
+    generic: ["#9c8f80", "#736a60", "#b7a894", "#8b8a80", "#c3ac90", "#635c54", "#a1978c"],
+    capital: ["#cfc5ad", "#ac9878", "#e6e0cf", "#a8a698", "#c8b48d", "#847b68", "#ded2b3"],
+    village: ["#b59e7a", "#9c8360", "#c9b895", "#8d7a5f", "#c2a173", "#a8977f", "#d6c3a1"],
+    desert: ["#c9a877", "#b08f61", "#ddc396", "#a4855c", "#d3b98d", "#93764f", "#c6b189"],
+    industrial: ["#7c838f", "#565d69", "#96a0ac", "#68737a", "#8a8173", "#4a5058", "#a0a6ac"],
+    coastal: ["#e8e2d2", "#cfd6d3", "#f1ece0", "#c9c0ac", "#dbe0dc", "#b7b3a3", "#e5d9c4"],
+    neon: ["#1b1b26", "#262233", "#141a24", "#2c2030", "#181f2b", "#221d1f", "#101018"],
+    ruin: ["#6b6156", "#57503f", "#7d7266", "#4f4a44", "#736450", "#8a8072", "#5d5b53"],
+    frontier: ["#7f5539", "#6a462d", "#96684a", "#5c4331", "#8a6540", "#a07a55", "#6f523c"],
+    aerial: ["#dfe7ec", "#c6d2da", "#eef3f6", "#b6c3cb", "#d3dde2", "#a7b7c0", "#e7eef1"],
+};
+/**
+ * The facade-tone family for a style — the ramp {@link BUILDING_STYLE_WALL_TONES} keeps, falling
+ * back to the style's single palette wall when a style has no ramp.
+ * @internal
+ */
+export function resolveBuildingWallTones(style = DEFAULT_BUILDING_STYLE) {
+    const tones = BUILDING_STYLE_WALL_TONES[style];
+    if (tones !== undefined && tones.length > 0)
+        return tones;
+    return [resolveBuildingPalette(style).wall];
+}
 /** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
     const preset = BUILDING_STYLE_PALETTES[style];
@@ -413,9 +441,21 @@ function pushRoof(parts, config, width, depth) {
     for (let index = 0; index < roofCells; index += 1) {
         if (!chance(config.seed, `roof:prop:${index}`, config.probabilities.roofProp))
             continue;
-        const x = config.center[0] - width / 2 + config.bayWidth * ((index % config.baysWide) + 0.5);
-        const z = config.center[1] - depth / 2 + config.bayWidth * (Math.floor(index / config.baysWide) + 0.5);
-        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + config.floorHeight * 0.16, z], [config.bayWidth * 0.34, config.floorHeight * 0.32, config.bayWidth * 0.34], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
+        // Plant sized and nudged off its cell centre: props locked to the bay grid at one size read as
+        // a checkerboard of cubes rather than a roof of mechanical units.
+        const wide = hash01(config.seed, `roof:prop:${index}:w`);
+        const tall = hash01(config.seed, `roof:prop:${index}:h`);
+        const propW = config.bayWidth * (0.2 + wide * 0.4);
+        const propD = config.bayWidth * (0.18 + (1 - wide) * 0.36);
+        const propH = config.floorHeight * (0.14 + tall * 0.52);
+        const x = config.center[0] -
+            width / 2 +
+            config.bayWidth * ((index % config.baysWide) + 0.5 + (hash01(config.seed, `roof:prop:${index}:x`) - 0.5) * 0.5);
+        const z = config.center[1] -
+            depth / 2 +
+            config.bayWidth *
+                (Math.floor(index / config.baysWide) + 0.5 + (hash01(config.seed, `roof:prop:${index}:z`) - 0.5) * 0.5);
+        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + propH / 2, z], [propW, propH, propD], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
     }
 }
 function pushCorners(parts, config, width, depth) {

package/dist/world/cityContent.js

@@ -13,18 +13,18 @@ export const CITY_LOT_CLASSES = [
 /** All filler classes, for validation and interior-pass allow-lists. */
 export const CITY_FILLER_CLASSES = ["garage", "depot"];
 const CLASS_PROFILES = {
-    tower: { width: [16, 24], depth: [14, 20], setbackFactor: 0.3, spacingFactor: 1, floors: [12, 34], backRow: true },
-    slab: { width: [14, 20], depth: [11, 15], setbackFactor: 0.5, spacingFactor: 1, floors: [4, 9], backRow: true },
-    shop: { width: [10, 15], depth: [8, 12], setbackFactor: 0.2, spacingFactor: 0.6, floors: [1, 2], backRow: true },
-    rowhouse: { width: [6, 8.5], depth: [9, 12], setbackFactor: 0.5, spacingFactor: 0.12, floors: [2, 3], backRow: true },
+    tower: { width: [14, 22], depth: [12, 20], setbackFactor: 0.15, spacingFactor: 0.35, floors: [12, 34], backRow: true },
+    slab: { width: [12, 20], depth: [10, 16], setbackFactor: 0.2, spacingFactor: 0.4, floors: [4, 9], backRow: true },
+    shop: { width: [8, 14], depth: [8, 12], setbackFactor: 0.05, spacingFactor: 0.15, floors: [1, 2], backRow: true },
+    rowhouse: { width: [5.5, 8], depth: [9, 13], setbackFactor: 0.2, spacingFactor: 0.05, floors: [2, 3], backRow: true },
     house: { width: [9, 12], depth: [8, 11], setbackFactor: 1, spacingFactor: 1, floors: [1, 2], backRow: true },
     mansion: { width: [18, 26], depth: [14, 20], setbackFactor: 2, spacingFactor: 1.6, floors: [2, 3], backRow: false },
     farmhouse: { width: [11, 14], depth: [9, 12], setbackFactor: 2.8, spacingFactor: 4, floors: [2, 2], backRow: false },
     barn: { width: [12, 16], depth: [9, 13], setbackFactor: 3.6, spacingFactor: 5, floors: [1, 1], backRow: false },
     silo: { width: [5, 6], depth: [5, 6], setbackFactor: 4, spacingFactor: 3, floors: [1, 1], backRow: false },
     // Interior-fill fillers: broad, plain footprints that pack the backs of dense blocks.
-    garage: { width: [18, 26], depth: [16, 22], setbackFactor: 0.3, spacingFactor: 0.4, floors: [2, 6], backRow: true },
-    depot: { width: [20, 30], depth: [18, 26], setbackFactor: 0.4, spacingFactor: 0.5, floors: [1, 2], backRow: true },
+    garage: { width: [16, 24], depth: [14, 20], setbackFactor: 0.2, spacingFactor: 0.3, floors: [2, 6], backRow: true },
+    depot: { width: [18, 28], depth: [16, 24], setbackFactor: 0.25, spacingFactor: 0.35, floors: [1, 2], backRow: true },
 };
 /**
  * Natural frontage-width range (meters) of a class's massing — what the plot-size class bias reads
@@ -131,6 +131,59 @@ function box(offset, size, role, options = {}) {
 function gable(offset, size, rotationY = 0) {
     return { shape: "gable", offset, size, rotationY, role: "roof", grounded: false, banded: false };
 }
+/**
+ * Finish a flat roof at height `top`: a recessed dark deck, a parapet upstand on all four edges,
+ * and seeded rooftop plant (mechanical units, a stair bulkhead, a tank). A city skyline is mostly
+ * roofs seen from above, so every flat-capped class runs through here instead of a bare slab.
+ */
+function flatRoofTop(pieces, width, depth, top, rng) {
+    const rail = Math.min(1.15, 0.55 + rng() * 0.55);
+    const wall = Math.min(0.55, Math.max(0.18, Math.min(width, depth) * 0.035));
+    const innerW = Math.max(0.4, width - wall * 2);
+    const innerD = Math.max(0.4, depth - wall * 2);
+    pieces.push(box([0, top, 0], [innerW, 0.14, innerD], "roof"));
+    pieces.push(box([0, top, (depth - wall) / 2], [width, rail, wall], "trim"));
+    pieces.push(box([0, top, -(depth - wall) / 2], [width, rail, wall], "trim"));
+    pieces.push(box([(width - wall) / 2, top, 0], [wall, rail, innerD], "trim"));
+    pieces.push(box([-(width - wall) / 2, top, 0], [wall, rail, innerD], "trim"));
+    const deck = top + 0.14;
+    const units = innerW * innerD > 110 ? 1 + Math.floor(rng() * 3) : rng() < 0.7 ? 1 : 0;
+    for (let i = 0; i < units; i += 1) {
+        const uw = Math.min(innerW * 0.34, 1.6 + rng() * 2.4);
+        const ud = Math.min(innerD * 0.34, 1.4 + rng() * 2);
+        pieces.push(box([(rng() - 0.5) * Math.max(0, innerW - uw), deck, (rng() - 0.5) * Math.max(0, innerD - ud)], [uw, 0.6 + rng() * 0.9, ud], "roof"));
+    }
+    if (rng() < 0.55) {
+        const bw = Math.min(innerW * 0.34, 2.2 + rng() * 1.6);
+        const bd = Math.min(innerD * 0.36, 2 + rng() * 1.4);
+        pieces.push(box([(rng() - 0.5) * Math.max(0, innerW - bw), deck, (rng() - 0.5) * Math.max(0, innerD - bd)], [bw, 1.9 + rng() * 1.1, bd], "trim"));
+    }
+    if (rng() < 0.4) {
+        const r = Math.min(2.2, Math.min(innerW, innerD) * 0.26);
+        pieces.push({
+            shape: "cylinder",
+            offset: [(rng() - 0.5) * Math.max(0, innerW - r), deck, (rng() - 0.5) * Math.max(0, innerD - r)],
+            size: [r, 1.4 + rng() * 1.2, r],
+            rotationY: 0,
+            role: "trim",
+            grounded: false,
+            banded: false,
+        });
+    }
+}
+/**
+ * Street-level treatment for a commercial frontage: a plinth course wrapping the base, a recessed
+ * dark entrance on the street face, and a canopy over the sidewalk — so floor 1 never reads like
+ * floor 30. `overhang` is the plinth's outward step (0 keeps it flush for terraced classes).
+ */
+function streetLevel(pieces, width, depth, bandHeight, overhang, rng) {
+    pieces.push(box([0, 0, 0], [width + overhang, bandHeight, depth + overhang], "trim", { grounded: true }));
+    const doorW = Math.min(width * 0.32, 3.4);
+    const doorX = (rng() - 0.5) * Math.max(0, width - doorW * 1.6) * 0.5;
+    const face = depth / 2 + overhang / 2;
+    pieces.push(box([doorX, 0, face], [doorW, bandHeight * 0.76, 0.5], "roof", { grounded: true }));
+    pieces.push(box([doorX, bandHeight * 0.8, face + 0.6], [doorW * 1.5, 0.22, 1.3], "accent"));
+}
 /**
  * Compose the massing pieces for one lot. Deterministic per `rng` stream: the same class, size,
  * floors, and stream always yield the identical silhouette. Sizes are in meters, lot-local.
@@ -147,17 +200,22 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
                 const h2 = H * (0.24 + rng() * 0.08);
                 const h3 = H - h1 - h2;
                 pieces.push(box([0, 0, 0], [width, h1, depth], "wall", { grounded: true, banded: true }));
+                // Occasional attached wing breaks the identical-rect streetwall without replacing the shaft.
+                if (width >= 16 && depth >= 14 && rng() < 0.42) {
+                    const wingW = width * (0.34 + rng() * 0.1);
+                    const side = rng() < 0.5 ? 1 : -1;
+                    pieces.push(box([side * (width / 2 - wingW / 2), 0, depth * 0.28], [wingW, h1 * (0.55 + rng() * 0.2), depth * 0.42], "wall", { grounded: true, banded: true }));
+                }
                 const w2 = width * (0.78 + rng() * 0.08);
                 const d2 = depth * (0.78 + rng() * 0.08);
                 pieces.push(box([0, h1, 0], [w2, h2, d2], "wall", { banded: true }));
                 const w3 = width * (0.55 + rng() * 0.1);
                 const d3 = depth * (0.55 + rng() * 0.1);
                 pieces.push(box([0, h1 + h2, 0], [w3, h3, d3], "wall", { banded: true }));
-                pieces.push(box([0, H, 0], [w3 * 1.04, 0.5, d3 * 1.04], "trim"));
+                flatRoofTop(pieces, w3 * 1.04, d3 * 1.04, H, rng);
                 if (rng() < 0.35)
                     pieces.push(box([0, H + 0.5, 0], [1.2, 3 + rng() * 5, 1.2], "trim"));
-                else if (rng() < 0.5)
-                    pieces.push(box([0, H + 0.5, 0], [w3 * 0.4, 1.6, d3 * 0.4], "roof"));
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.1, H * 0.5), 0.35, rng);
             }
             else {
                 const h1 = H * (0.66 + rng() * 0.1);
@@ -165,32 +223,58 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
                 const w2 = width * (0.72 + rng() * 0.1);
                 const d2 = depth * (0.72 + rng() * 0.1);
                 pieces.push(box([0, h1, 0], [w2, H - h1, d2], "wall", { banded: true }));
-                pieces.push(box([0, H, 0], [w2 * 1.05, 0.45, d2 * 1.05], "trim"));
+                flatRoofTop(pieces, w2 * 1.05, d2 * 1.05, H, rng);
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.1, H * 0.5), 0.35, rng);
             }
             return pieces;
         }
         case "slab": {
-            pieces.push(box([0, 0, 0], [width, H, depth * 0.95], "wall", { grounded: true, banded: true }));
-            pieces.push(box([0, H, 0], [width * 1.02, 0.35, depth * 0.97], "trim"));
-            if (rng() < 0.6)
-                pieces.push(box([(rng() - 0.5) * width * 0.4, H + 0.35, 0], [width * 0.22, 2, depth * 0.3], "roof"));
+            // Full streetwall depth; irregular plans break the identical-cell silhouette.
+            if (width >= 14 && depth >= 12 && rng() < 0.55) {
+                const wing = width * (0.38 + rng() * 0.14);
+                const side = rng() < 0.5 ? 1 : -1;
+                const frontH = H * (0.92 + rng() * 0.12);
+                const wingH = H * (0.7 + rng() * 0.25);
+                pieces.push(box([0, 0, depth * 0.08], [width, frontH, depth * 0.62], "wall", { grounded: true, banded: true }));
+                pieces.push(box([side * (width / 2 - wing / 2), 0, -depth * 0.08], [wing, wingH, depth * 0.82], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 0.98, depth * 0.62, frontH, rng);
+                if (rng() < 0.45)
+                    flatRoofTop(pieces, wing * 1.02, depth * 0.78, wingH, rng);
+                streetLevel(pieces, width, depth * 0.62, Math.min(floorHeight * 1.05, frontH * 0.5), 0.25, rng);
+            }
+            else if (width >= 16 && depth >= 14 && rng() < 0.35) {
+                // Open mid-block court: street wall + two side wings, rear open as a service yard.
+                const wallT = Math.min(width, depth) * 0.28;
+                pieces.push(box([0, 0, (depth - wallT) / 2], [width, H, wallT], "wall", { grounded: true, banded: true }));
+                pieces.push(box([(width - wallT) / 2, 0, -wallT * 0.15], [wallT, H * (0.75 + rng() * 0.2), depth - wallT], "wall", { grounded: true, banded: true }));
+                pieces.push(box([-(width - wallT) / 2, 0, -wallT * 0.15], [wallT, H * (0.7 + rng() * 0.2), depth - wallT], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 1.01, wallT * 1.02, H, rng);
+                streetLevel(pieces, width, wallT, Math.min(floorHeight * 1.05, H * 0.5), 0.25, rng);
+            }
+            else {
+                pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 1.02, depth * 1.02, H, rng);
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.05, H * 0.5), 0.25, rng);
+            }
             return pieces;
         }
         case "shop": {
             pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true }));
-            pieces.push(box([0, H, 0], [width * 1.03, 0.5, depth * 1.03], "trim"));
+            flatRoofTop(pieces, width * 1.03, depth * 1.03, H, rng);
             // Front awning strip over the sidewalk face.
             pieces.push(box([0, Math.min(H - 0.4, 2.6), depth / 2 + 0.35], [width * 0.9, 0.35, 0.9], "accent"));
+            pieces.push(box([0, 0, depth / 2 - 0.05], [width * 0.82, Math.min(H * 0.62, 2.5), 0.4], "roof", { grounded: true }));
             return pieces;
         }
         case "rowhouse": {
-            pieces.push(box([0, 0, 0], [width * 0.96, H, depth * 0.85], "wall", { grounded: true, banded: true }));
+            pieces.push(box([0, 0, 0], [width * 0.98, H, depth * 0.92], "wall", { grounded: true, banded: true }));
             if (rng() < 0.55) {
-                pieces.push(gable([0, H, 0], [width * 0.96, 1.6 + rng() * 0.8, depth * 0.9]));
+                pieces.push(gable([0, H, 0], [width * 0.98, 1.6 + rng() * 0.8, depth * 0.96]));
             }
             else {
-                pieces.push(box([0, H, 0], [width * 1.0, 0.45, depth * 0.9], "trim"));
+                pieces.push(box([0, H, 0], [width * 1.0, 0.45, depth * 0.94], "trim"));
             }
+            streetLevel(pieces, width * 0.98, depth * 0.92, Math.min(floorHeight * 0.95, H * 0.5), 0.04, rng);
             return pieces;
         }
         case "house": {
@@ -273,13 +357,7 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
         case "garage": {
             // Parking structure: a plain banded box (the window bands read as deck slots) with a flat cap.
             pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true, banded: true }));
-            pieces.push(box([0, H, 0], [width * 1.02, 0.4, depth * 1.02], "trim"));
-            if (rng() < 0.6) {
-                // Stair/lift core poking above the roof deck.
-                const cx = (rng() - 0.5) * width * 0.5;
-                const cz = (rng() - 0.5) * depth * 0.4;
-                pieces.push(box([cx, H + 0.4, cz], [width * 0.16, 1.6 + rng() * 1.2, depth * 0.16], "accent"));
-            }
+            flatRoofTop(pieces, width * 1.02, depth * 1.02, H, rng);
             return pieces;
         }
         case "depot": {

package/dist/world/cityKind.d.ts

@@ -1,6 +1,7 @@
 import { type ParamSchema, type SceneKindObject, type SceneKindResolveContext, type WeightedParamEntry } from "../scene/sceneKinds.js";
 import { type BuildingStyle } from "./buildings.js";
 import { type CityLotClass, type CityLotPiece, type CityTreeSpecies, type CityZoneBand, type CityZoneProfile } from "./cityContent.js";
+import { type CircuitCorner, type CircuitGate, type CircuitSealKind } from "./raceCircuit.js";
 import type { RoadPoint } from "./roads.js";
 import { type StreetFeatureKind } from "./streetGenerator.js";
 import { type CityBlockKind } from "./cityBlocks.js";
@@ -29,6 +30,17 @@ export interface CityRules {
     minTurnAngle: number;
     /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
     maxTurnAngle: number;
+    /** Organic boundary clipping, 0..1. 0 fills the volume's rectangle; higher grows lobes and bays. */
+    outline: number;
+    /** Share of branch lanes grown as winding residential side streets, 0..1. */
+    residentialBranches: number;
+    /** Road-surface relief, 0..1. 0 is dead flat; 1 is ~22 m of rise and fall across a ~520 m district. */
+    elevation: number;
+    /** Steepest road grade (rise/run) the elevation pass allows on any street. */
+    maxGrade: number;
+    /** Circuit space-filling, 0..1. 0 is a flowing loop around an empty middle; higher folds the lap
+     * back through its own interior (switchbacks, hairpins, parallel runs). Circuit mode only. */
+    compactness: number;
     /** Lay parcels + buildings against the streets (city fabric). Off = bare roads/track, no plots. */
     fabric: boolean;
     /** Streets bore through ridges on tunnel decks instead of climbing over them. */
@@ -84,6 +96,10 @@ export interface CityRules {
     treeMix: WeightedParamEntry[];
     /** Street-light density along non-lane streets, 0..1. */
     lightDensity: number;
+    /** Parked-vehicle density along street curbs and inside parking pads, 0..1. */
+    parkedCars: number;
+    /** Junction control density, 0..1: mast-arm signals on arterial crossings, sign posts below them. */
+    signals: number;
     /** Ring estate lots (mansions) with perimeter hedges and a gated gap. */
     hedges: boolean;
     /** Connect houses/estates/farms to their street with driveways. */
@@ -104,6 +120,22 @@ export interface CityRules {
     sidewalks: boolean;
     /** Sidewalk band width in meters at "street" hierarchy (boulevards scale up, lanes down). */
     sidewalkWidth: number;
+    /** Lift an instanced street race out of the district's own streets (see {@link ResolvedRace}). */
+    race: boolean;
+    /** Target race lap length in meters — the search keeps the cycle closest to this. */
+    raceLapLength: number;
+    /** 0 races any street; 1 keeps the lap on avenues and boulevards only. */
+    raceArterial: number;
+    /** Ordered checkpoint gates placed around the lap. */
+    raceCheckpoints: number;
+    /** Laps the race runs. */
+    raceLaps: number;
+    /** Close every side street leaving the lap with barriers — what makes it an instanced event. */
+    raceSeals: boolean;
+    /** Starting grid slots behind the line (0 = no grid). */
+    raceGridSlots: number;
+    /** Radius (m) the racing line is worked toward at the lap's junction corners. */
+    raceCornerRadius: number;
     /** Building style palette id (see {@link BUILDING_STYLE_PALETTES}). */
     style: BuildingStyle;
     /**
@@ -132,6 +164,9 @@ export interface CityStreet {
     surface: "asphalt" | "gravel";
     /** Whether sidewalk ribbons flank this street. */
     sidewalk: boolean;
+    /** Grade-limited road-surface height per point, present only when `elevation` is above 0. This is
+     * ROAD relief, not the terrain the district stands on. */
+    heights?: readonly number[];
     /** Cul-de-sac turning bulb at a dangling end, when the lane never reconnected. */
     bulb?: RoadPoint;
     /** Bridge/tunnel spans along this street as `[from, to]` index windows into `points`. */
@@ -277,6 +312,97 @@ export interface CityParking {
     size: readonly [number, number];
     rotationY: number;
 }
+/** Silhouette class of a parked vehicle — sizes the body the renderer instances. */
+export type CityVehicleKind = "car" | "van" | "truck";
+/** One parked vehicle standing at a curb or nose-in inside a parking pad. */
+export interface CityVehicle {
+    x: number;
+    z: number;
+    /** Yaw the body points down (engine rotationY convention). */
+    rotationY: number;
+    kind: CityVehicleKind;
+    /** Seeded body-paint index; the renderer maps it into its own palette. */
+    paint: number;
+    /** Where it stands, so the renderer drapes it onto carriageway or pad height. */
+    stall: "curb" | "lot";
+}
+/** One junction control on an approach arm: an arterial mast-arm signal, or a plain sign post. */
+export interface CitySignal {
+    x: number;
+    z: number;
+    /** Yaw the head faces — into the traffic approaching down this arm. */
+    heading: number;
+    kind: "signal" | "sign";
+    /** How far the mast arm reaches over the carriageway, to the right of {@link CitySignal.heading}. */
+    reach: number;
+}
+/** One street closed off where it leaves the race lap: world XZ, the yaw down the sealed street, and
+ * the width the barrier run spans. */
+export interface CityRaceSeal {
+    x: number;
+    z: number;
+    heading: number;
+    width: number;
+    kind: CircuitSealKind;
+}
+/** One kerb strip hugging a corner's road edge, as a world-space polyline to stripe. */
+export interface CityRaceKerb {
+    points: readonly RoadPoint[];
+    /** Strip width across, meters. */
+    width: number;
+    /** Which side of travel the strip sits on: -1 left, 1 right. */
+    side: -1 | 1;
+    /** Alternating stripe length along the run, meters. */
+    stripe: number;
+    /** Corner this kerb belongs to (index into {@link ResolvedRace.corners}). */
+    corner: number;
+}
+/** The start/finish line: where it is, which way cars face, and the painted line across the road. */
+export interface CityRaceStart {
+    x: number;
+    z: number;
+    /** Yaw cars face on the grid (direction of travel). */
+    heading: number;
+    /** The two road-edge ends of the painted line. */
+    line: readonly [RoadPoint, RoadPoint];
+    /** Arc-length position of the line along the lap, meters. */
+    distance: number;
+    width: number;
+}
+/** One staggered spawn behind the start line. */
+export interface CityRaceGridSlot {
+    x: number;
+    z: number;
+    heading: number;
+}
+/**
+ * An instanced street race lifted out of the district's OWN streets: a closed lap through the city,
+ * with every side street leaving it sealed off. World space, like the rest of {@link ResolvedCity}.
+ */
+export interface ResolvedRace {
+    /** Closed lap centerline — the last point joins the first. */
+    centerline: readonly RoadPoint[];
+    /** Road width at each centerline point, inherited from the streets the lap follows. */
+    widths: readonly number[];
+    /** Road-surface height per point, present only when the district carries `elevation`. */
+    heights?: readonly number[];
+    /** Lap length, meters. */
+    length: number;
+    /** Ids of the district streets the lap runs on — style exactly these as track surface. */
+    streets: readonly string[];
+    seals: readonly CityRaceSeal[];
+    corners: readonly CircuitCorner[];
+    kerbs: readonly CityRaceKerb[];
+    /** Ordered gates, finish last — ready for `raceTrack({ checkpoints, laps })`. */
+    checkpoints: readonly CircuitGate[];
+    laps: number;
+    start: CityRaceStart;
+    grid: readonly CityRaceGridSlot[];
+    /** Arc-length fractions (0..1) where each timing sector begins; the first is always 0. */
+    sectors: readonly number[];
+    /** Tightest radius (m) the finished racing line actually holds. */
+    tightestRadius: number;
+}
 /** A resolved city district: world-space network, zoned lots, parks, and furniture. */
 export interface ResolvedCity {
     center: readonly [number, number, number];
@@ -299,6 +425,12 @@ export interface ResolvedCity {
     hedges: readonly CityHedge[];
     driveways: readonly CityDriveway[];
     parkingLots: readonly CityParking[];
+    /** Parked vehicles along the curbs and inside the parking pads. */
+    vehicles: readonly CityVehicle[];
+    /** Traffic signals and sign posts, one per controlled junction approach. */
+    signals: readonly CitySignal[];
+    /** The instanced street race through these streets, when `race` is on and a lap could be found. */
+    race?: ResolvedRace;
 }
 /** Extended resolve context: sibling `cityzone` volumes that override the band/mix locally. */
 export interface CityResolveContext extends SceneKindResolveContext {