@jgengine/core 0.18.0 → 0.19.0

package/dist/world/features.d.ts

@@ -4,6 +4,7 @@ import type { AvoidZone } from "./geometry.js";
 import type { TerrainPathProfile } from "./pathTerrain.js";
 import type { PlaceWorldFeature } from "./place.js";
 import type { TerraformSnapshot } from "./terraform.js";
+import type { SpriteAtlas } from "../assets/spriteAtlas.js";
 import type { VolumetricCloudsConfig } from "./volumetricClouds.js";
 export interface WorldBounds {
     w: number;
@@ -48,6 +49,16 @@ export interface TerrainDetailConfig {
     roughness?: number;
     /** Overall detail intensity 0..1. Default 1. */
     strength?: number;
+    /**
+     * RGB multipliers for the two macro colour sweeps painted over the base ground. `dry` tints the
+     * sun-bleached patches, `wet` the cooler pockets between them. The defaults ([1.14, 1.05, 0.76]
+     * and [0.78, 1.0, 0.86]) suit temperate meadows; the green-leaning `wet` default paints mossy
+     * pockets onto any biome that keeps it, so arid/ashen worlds should supply warm or neutral tints.
+     */
+    sweeps?: {
+        dry?: readonly [number, number, number];
+        wet?: readonly [number, number, number];
+    };
     /** Real PBR texture maps blended over the procedural detail — the seam for `@jgengine/assets` `buildMaterialCatalog` output. Omit to keep the procedural-only look. */
     material?: TerrainDetailMaterialConfig;
 }
@@ -259,6 +270,14 @@ export interface GrassEnvironmentConfig {
     windStrength?: number;
     colors?: readonly string[];
     seed?: string;
+    /** Blade curl range (arc amount, min..max). Shell default [0.12, 0.42] — raise for wind-combed scrub, lower for stiff turf. */
+    bladeBend?: readonly [number, number];
+    /** Tuft spread radius in meters — how far a clump's blades splay from its root. Shell default 0.16; wider reads as bushy clumps rather than lone blades. */
+    tuftRadius?: number;
+    /** Per-tuft brightness jitter 0..1 (shell default 0.28) — higher breaks up the field so it never reads as one repeated blade. */
+    colorVariation?: number;
+    /** 0..1 blend of blade normals toward straight-up (shell default 0.6). Low values light each blade plane individually and go dark when side-lit; high values light the field like a soft carpet. */
+    normalLift?: number;
 }
 export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
@@ -277,16 +296,38 @@ export interface OceanEnvironmentConfig {
     waveSpeed?: number;
     color?: string;
 }
+/**
+ * Where the sun sits, as a compass bearing and a height above the horizon, both in degrees.
+ * `azimuth` 0 points toward -Z (north), 90 toward +X (east); `elevation` 90 is straight overhead.
+ */
+export interface SkySunConfig {
+    /** Compass bearing of the sun in degrees; 0 = -Z, 90 = +X. Default 0. */
+    azimuth?: number;
+    /** Height above the horizon in degrees; 0 sits on the horizon, 90 is overhead. Default 68. */
+    elevation?: number;
+}
 export interface SkyEnvironmentConfig {
     /** Fixed look used when `timeOfDay` is off (or no clock is available); default "day". */
     preset?: "day" | "dusk" | "night";
     /** Drive sun/sky from the world clock's `calendar().dayFraction` instead of the fixed `preset`. */
     timeOfDay?: boolean;
+    /**
+     * Horizon tint at noon. Under `timeOfDay` this only sets the noon keyframe; dawn, dusk, and night
+     * still crossfade through the engine presets, so an authored tint is visible for part of the day.
+     */
     horizonColor?: string;
+    /** Zenith tint at noon; same `timeOfDay` crossfade caveat as `horizonColor`. */
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
-    /** Sky-dome sphere radius in world units. Enlarge for a playfield sited far from the origin so the viewer never exits the dome. Default 260. */
+    /**
+     * Sun placement for the dome glow and the sky-owned sun light. With a fixed `preset` this is the
+     * sun's exact direction; under `timeOfDay` it is where the sun stands at noon and the day arc
+     * swings around that bearing. Unset with an authored `lighting.directional` light, the shell takes
+     * the first directional light's direction so the dome sun agrees with the shadows.
+     */
+    sun?: SkySunConfig;
+    /** Sky-dome sphere radius in world units. Enlarge for a playfield sited far from the origin so the viewer never exits the dome. Must stay below the camera far plane or the dome depth-clips to black. Default 260. */
     radius?: number;
     /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
     hazeStrength?: number;
@@ -358,6 +399,11 @@ export interface BuildingEnvironmentConfig {
      * untextured block; without a kit the whole facade stays blocks, as before.
      */
     kit?: BuildingKit;
+    /**
+     * Whether the buildings block movement and physics through `ctx.world.solids` (default `true`).
+     * `false` keeps them render-only, e.g. a distant skyline nobody can reach.
+     */
+    solid?: boolean;
 }
 export type PadSize = readonly [number, number] | {
     radius: number;
@@ -393,13 +439,13 @@ export type SnowEnvironmentDescriptor = {
 } & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity">>;
 export type GrassEnvironmentDescriptor = {
     kind: "grass";
-} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
+} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed" | "bladeBend" | "tuftRadius" | "colorVariation" | "normalLift">;
 export type OceanEnvironmentDescriptor = {
     kind: "ocean";
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;
 export type BuildingEnvironmentDescriptor = {
     kind: "building";
-} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit" | "solid">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
 } & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;
@@ -519,6 +565,13 @@ export interface PlotsWorldConfig extends WorldGridConfig {
 }
 export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
+    /** Atlas-backed tile rendering; cell glyphs map to atlas frame ids. */
+    tileSet?: {
+        atlas: SpriteAtlas;
+        tiles: Record<string, string>;
+    };
+    /** Render ordering key consumed by the shell tile renderer. */
+    sortingLayer?: string;
 }
 /**
  * A declared world shape passed to `defineGame`. The preferred model is the place feature from

package/dist/world/features.js

@@ -1,3 +1,4 @@
+import { warnOnce } from "../devtools/warnOnce.js";
 function list(value) {
     if (value === undefined) {
         return undefined;
@@ -110,6 +111,9 @@ export function terrain(config = {}) {
     });
 }
 export function sky(config = {}) {
+    if (config.timeOfDay === true && (config.zenithColor !== undefined || config.horizonColor !== undefined)) {
+        warnOnce("sky-timeofday-tint", "[jgengine] sky(): zenithColor/horizonColor only set the noon keyframe under timeOfDay; dawn, dusk, and night crossfade through the engine presets. Drop timeOfDay for a fixed tint.");
+    }
     return withOptional({
         kind: "sky",
         preset: config.preset ?? "day",
@@ -119,6 +123,7 @@ export function sky(config = {}) {
         ...(config.zenithColor === undefined ? {} : { zenithColor: config.zenithColor }),
         ...(config.sunIntensity === undefined ? {} : { sunIntensity: config.sunIntensity }),
         ...(config.ambientIntensity === undefined ? {} : { ambientIntensity: config.ambientIntensity }),
+        ...(config.sun === undefined ? {} : { sun: { ...config.sun } }),
         ...(config.radius === undefined ? {} : { radius: config.radius }),
         ...(config.hazeStrength === undefined ? {} : { hazeStrength: config.hazeStrength }),
         ...(config.sunGlowStrength === undefined ? {} : { sunGlowStrength: config.sunGlowStrength }),
@@ -183,7 +188,7 @@ export function snow(config = {}) {
 }
 /** Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors. */
 export function grass(config = {}) {
-    return withOptional({
+    return {
         kind: "grass",
         area: withAreaPosition(config.area ?? { w: 128, d: 128 }, config.position),
         density: config.density ?? 4,
@@ -191,7 +196,12 @@ export function grass(config = {}) {
         bladeWidth: config.bladeWidth ?? 0.035,
         windStrength: config.windStrength ?? 0.35,
         colors: config.colors ?? ["#3f7d2d", "#66a83f"],
-    }, config.seed === undefined ? undefined : { seed: config.seed });
+        ...(config.seed === undefined ? {} : { seed: config.seed }),
+        ...(config.bladeBend === undefined ? {} : { bladeBend: config.bladeBend }),
+        ...(config.tuftRadius === undefined ? {} : { tuftRadius: config.tuftRadius }),
+        ...(config.colorVariation === undefined ? {} : { colorVariation: config.colorVariation }),
+        ...(config.normalLift === undefined ? {} : { normalLift: config.normalLift }),
+    };
 }
 /** Declares an ocean water body for `environment()` — bounds, level, and wave tuning. */
 export function ocean(config = {}) {
@@ -248,6 +258,7 @@ export function building(config = {}) {
         ...(config.palette === undefined ? {} : { palette: config.palette }),
         ...(config.along === undefined ? {} : { along: config.along }),
         ...(config.kit === undefined ? {} : { kit: config.kit }),
+        ...(config.solid === undefined ? {} : { solid: config.solid }),
     });
 }
 export function pad(config) {

package/dist/world/footprintGrid.d.ts

@@ -16,6 +16,10 @@ export interface FootprintReservation {
     kind: string;
     cells: readonly GridCell[];
 }
+/** Plain JSON state of a {@link FootprintGrid}: live reservations in claim order. */
+export interface FootprintGridState {
+    reservations: FootprintReservation[];
+}
 /** Handle returned by {@link createFootprintGrid}. */
 export interface FootprintGrid {
     readonly cellSize: number;
@@ -30,6 +34,9 @@ export interface FootprintGrid {
     reservationOf(id: string): FootprintReservation | null;
     list(): readonly FootprintReservation[];
     clear(): void;
+    snapshot(): FootprintGridState;
+    /** Replaces every reservation with `next`'s and rebuilds cell occupancy from them. */
+    restore(next: FootprintGridState): void;
 }
 /**
  * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`

package/dist/world/footprintGrid.js

@@ -1,6 +1,9 @@
 function cellKey(cell) {
     return `${cell.col}:${cell.row}`;
 }
+function copyReservation(reservation) {
+    return { id: reservation.id, kind: reservation.kind, cells: reservation.cells.map((cell) => ({ col: cell.col, row: cell.row })) };
+}
 /**
  * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
  * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
@@ -70,6 +73,19 @@ export function createFootprintGrid(options = {}) {
             occupied.clear();
             reservations.clear();
         },
+        snapshot() {
+            return { reservations: Array.from(reservations.values(), copyReservation) };
+        },
+        restore(next) {
+            occupied.clear();
+            reservations.clear();
+            for (const reservation of next.reservations) {
+                const copy = copyReservation(reservation);
+                reservations.set(copy.id, copy);
+                for (const cell of copy.cells)
+                    occupied.set(cellKey(cell), copy.id);
+            }
+        },
     };
 }
 const CARDINAL_OFFSETS = [

package/dist/world/interiors.d.ts

@@ -32,4 +32,5 @@ export interface Interiors {
     toInterior(id: string, exterior: Vec2): Vec2 | null;
     toExterior(id: string, interior: Vec2): Vec2 | null;
 }
+/** Frame conversion and bounded movement across an exterior and its interiors; holds config only, no play state. */
 export declare function createInteriors(config?: InteriorsConfig): Interiors;

package/dist/world/interiors.js

@@ -14,12 +14,14 @@ function toExteriorFrame(interior, local) {
     const rotated = rotate(local, interior.rotation ?? 0);
     return [rotated[0] + interior.origin[0], rotated[1] + interior.origin[1]];
 }
+function indexInteriors(interiors) {
+    return new Map(interiors.map((interior) => [interior.id, interior]));
+}
+/** Frame conversion and bounded movement across an exterior and its interiors; holds config only, no play state. */
 export function createInteriors(config = {}) {
     const radius = config.radius ?? 0;
     const exterior = config.exterior ?? {};
-    const byId = new Map();
-    for (const interior of config.interiors ?? [])
-        byId.set(interior.id, interior);
+    const byId = indexInteriors(config.interiors ?? []);
     return {
         move(location, delta) {
             if (location.space.kind === "exterior") {

package/dist/world/lod.d.ts

@@ -7,11 +7,17 @@ export interface LodSchedulerConfig {
     beyondInterval?: number | null;
     stagger?: boolean;
 }
+/** Plain JSON state of a {@link LodScheduler}: each id's accumulated seconds. */
+export interface LodSchedulerState {
+    buckets: Record<string, number>;
+}
 export interface LodScheduler {
     bandIndex(distance: number): number;
     step(id: string, distance: number, dtSeconds: number): number;
     remove(id: string): void;
     clear(): void;
     size(): number;
+    snapshot(): LodSchedulerState;
+    restore(next: LodSchedulerState): void;
 }
 export declare function createLodScheduler(config: LodSchedulerConfig): LodScheduler;

package/dist/world/lod.js

@@ -62,5 +62,13 @@ export function createLodScheduler(config) {
         size() {
             return buckets.size;
         },
+        snapshot() {
+            return { buckets: Object.fromEntries(buckets) };
+        },
+        restore(next) {
+            buckets.clear();
+            for (const [id, seconds] of Object.entries(next.buckets))
+                buckets.set(id, seconds);
+        },
     };
 }

package/dist/world/placement.d.ts

@@ -12,6 +12,10 @@ export interface PlacementRules {
     bounds?: Aabb;
     obstacles?: readonly PlacementObstacle[];
     snap?: number;
+    /** Authoritative ownership/claim validation for this footprint. */
+    territory?: (aabb: Aabb) => {
+        ok: boolean;
+    };
 }
 export type PlacementResult = {
     status: "ok";
@@ -20,6 +24,9 @@ export type PlacementResult = {
 } | {
     status: "rejected";
     reason: "out-of-bounds";
+} | {
+    status: "rejected";
+    reason: "territory.blocked";
 } | {
     status: "rejected";
     reason: "overlap";

package/dist/world/placement.js

@@ -16,6 +16,8 @@ export function validatePlacement(request, rules = {}) {
             return { status: "rejected", reason: "overlap", obstacle, index };
         }
     }
+    if (rules.territory && !rules.territory(aabb).ok)
+        return { status: "rejected", reason: "territory.blocked" };
     return { status: "ok", center, aabb };
 }
 export function footprintObstacle(request, id) {

package/dist/world/placementController.d.ts

@@ -32,7 +32,7 @@ export interface PlacementPreview {
     footprint: Footprint;
     aabb: Aabb;
     valid: boolean;
-    reason?: "out-of-bounds" | "overlap" | "no-slot";
+    reason?: "out-of-bounds" | "overlap" | "no-slot" | "territory.blocked";
     snapMode: SnapMode;
     normal: PlacementVec3;
     /** Id of the resolved slot, when the controller is in slot mode and a slot matched. */

package/dist/world/placementController.js

@@ -59,6 +59,13 @@ export function createPlacementController(config) {
             normal: hit.normal,
             ...(slot === null ? { reason: "no-slot" } : { slotId: slot.id }),
         };
+        if (slot !== null) {
+            const result = validatePlacement({ center, footprint, quarterTurns }, { ...rules, snap: undefined });
+            if (result.status === "rejected") {
+                next.valid = false;
+                next.reason = result.reason;
+            }
+        }
         preview = next;
         return next;
     }

package/dist/world/raceCircuit.d.ts

@@ -0,0 +1,168 @@
+import type { StreetNetwork, StreetVec2 } from "./streetGenerator.js";
+/** How a sealed-off side street is closed: hard barriers, a cone line, or temporary fencing. */
+export type CircuitSealKind = "barrier" | "cones" | "fence";
+/** Fully-defaulted sliders the route search answers to. */
+export interface CircuitRouteRules {
+    seed: string;
+    /** Target lap length in meters — the search keeps the cycle closest to this. */
+    lapLength: number;
+    /** 0 races any street; 1 keeps the lap on avenues and boulevards only. */
+    arterialBias: number;
+    /**
+     * Radius (m) the corner-rounding pass works the racing line toward. Bounded by `cornerCut` and the
+     * road width — the line never leaves the street — so the achieved figure is reported back as
+     * {@link CircuitRoute.tightestRadius} rather than enforced here.
+     */
+    minCornerRadius: number;
+    /** Ordered checkpoint gates placed around the lap. */
+    checkpoints: number;
+    /** Laps the produced race runs. */
+    laps: number;
+    /** Half-height of a checkpoint gate volume (m) — how tall the trigger box reaches. */
+    gateHeight: number;
+    /** Starting grid slots behind the line (0 = no grid). */
+    gridSlots: number;
+    /** How the side streets leaving the lap are closed off. */
+    sealKind: CircuitSealKind;
+    /** Timing sectors the lap splits into. */
+    sectors: number;
+    /**
+     * Arc-length spacing (m) the lap is resampled to. City streets are sampled coarsely enough for a
+     * road ribbon but far too coarsely for a racing surface, corner analysis, or kerbs.
+     */
+    sampleStep: number;
+    /**
+     * How far the racing line may be pulled off the street centerline while rounding a junction, as a
+     * fraction of the local half-width. 0 keeps the hard kink; ~0.5 uses the full lane either side.
+     */
+    cornerCut: number;
+}
+/** Defaults: a ~2.4 km arterial street lap with 12 gates, 3 laps, and barriered side streets. */
+export declare const CIRCUIT_ROUTE_DEFAULTS: CircuitRouteRules;
+/**
+ * One street closed off where it leaves the lap — the thing that turns public roads into an
+ * instanced event. Stands just off the junction, spanning the sealed street's full width.
+ */
+export interface CircuitSeal {
+    /** Volume-local XZ of the barrier run's center. */
+    x: number;
+    z: number;
+    /** Yaw (radians) pointing down the sealed street, away from the lap. */
+    heading: number;
+    /** Width of the street being closed — the run spans it plus a shoulder. */
+    width: number;
+    kind: CircuitSealKind;
+    /** Graph node the seal stands at. */
+    node: number;
+}
+/** One analyzed corner: where the lap turns, how hard, and which way. */
+export interface CircuitCorner {
+    /** `centerline` index at the apex (tightest point). */
+    apex: number;
+    /** Radius of curvature at the apex, meters. */
+    radius: number;
+    /** Total turn through the corner, radians. */
+    angle: number;
+    /** -1 = left-hand, 1 = right-hand. */
+    direction: -1 | 1;
+    /** `centerline` index where the corner starts. */
+    entry: number;
+    /** `centerline` index where it ends. */
+    exit: number;
+}
+/** One checkpoint trigger volume, shaped to hand straight to `raceTrack({ checkpoints })`. */
+export interface CircuitGate {
+    id: string;
+    center: readonly [number, number, number];
+    half: readonly [number, number, number];
+}
+/** The start/finish line: where it is, which way cars face, and the painted line across the road. */
+export interface CircuitStart {
+    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 [StreetVec2, StreetVec2];
+    /** Arc-length position of the line along the lap, meters. */
+    distance: number;
+    /** Road width at the line. */
+    width: number;
+}
+/** One grid slot: a staggered spawn behind the start line. */
+export interface CircuitGridSlot {
+    x: number;
+    z: number;
+    /** Yaw facing down the start straight. */
+    heading: number;
+}
+/** One kerb strip on the outside or inside of a corner, as an offset polyline to stripe. */
+export interface CircuitKerb {
+    /** Polyline along the road edge the kerb hugs. */
+    points: StreetVec2[];
+    /** 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 CircuitRoute.corners}). */
+    corner: number;
+}
+/** A closed race lap lifted out of a street network, with everything a race needs hung off it. */
+export interface CircuitRoute {
+    /** Closed lap centerline in volume-local XZ. Implicitly closed: the last point joins the first. */
+    centerline: StreetVec2[];
+    /** Road width at each centerline point, inherited from the streets the lap follows. */
+    widths: number[];
+    /** Road-surface height per point, present only when the network carries elevation. */
+    heights?: number[];
+    /** Lap length, meters. */
+    length: number;
+    /** Graph edge ids the lap runs on — style exactly these streets as track surface. */
+    edges: number[];
+    /** Graph node ids the lap visits in order (no repeat of the closing node). */
+    nodes: number[];
+    /** Every street leaving the lap that is not part of it, closed off. */
+    seals: CircuitSeal[];
+    corners: CircuitCorner[];
+    /** Ordered gates, finish line last — ready for `raceTrack({ checkpoints, laps })`. */
+    checkpoints: CircuitGate[];
+    laps: number;
+    start: CircuitStart;
+    grid: CircuitGridSlot[];
+    /** Arc-length fractions (0..1) where each timing sector begins; `sectors[0]` is always 0. */
+    sectors: number[];
+    /** Share of lap length running on avenue-or-wider streets, 0..1. */
+    arterialShare: number;
+    /**
+     * Tightest radius (m) the finished racing line actually holds. `minCornerRadius` is a TARGET the
+     * rounding pass works toward, not a guarantee: rounding may not pull the line outside the street it
+     * inherited, so a 90° junction on a narrow road stays tighter than any target can ask for. Read
+     * this to report what the lap really is — widen `streetWidth` to buy a smoother one.
+     */
+    tightestRadius: number;
+}
+/** Kerb strips on the outside and inside of every real corner. */
+export interface CircuitKerbOptions {
+    /** Strip width across, meters. Defaults to 1.1. */
+    width?: number;
+    /** Alternating stripe length along the run, meters. Defaults to 2.2. */
+    stripe?: number;
+    /** Only kerb corners at or below this radius (m). Defaults to 6× the route's tightest corner. */
+    maxRadius?: number;
+}
+/**
+ * Red/white kerb strips hugging both road edges through each corner. Returns the polylines and
+ * stripe pitch as data; the renderer owns the mesh and the colors.
+ */
+export declare function circuitKerbs(route: CircuitRoute, options?: CircuitKerbOptions): CircuitKerb[];
+/**
+ * Lift a closed, sealed-off race lap out of an existing street network. Returns `null` when the
+ * network has no drivable cycle (a pure tree of dead-end streets), so callers can fall back or warn
+ * rather than render a broken race.
+ *
+ * On a `circuit`-mode network the generated loop is used directly. On a `net` (a city) the graph is
+ * searched for the cycle closest to `lapLength` that respects `arterialBias` and `minCornerRadius`.
+ */
+export declare function extractCircuitRoute(network: StreetNetwork, rules?: Partial<CircuitRouteRules>): CircuitRoute | null;