@jgengine/core 0.14.0 → 0.15.0

package/dist/world/sharedAnnotations.d.ts

@@ -0,0 +1,84 @@
+import type { AnnotationLayer } from "./mapAnnotations.js";
+import type { MapLayerTone, MapZoneShape } from "./mapLayers.js";
+import type { WorldXZ } from "./minimap.js";
+/** Feed action shared drawings ride by default (pair with the party feed, like pings). */
+export declare const ANNOTATION_FEED_ACTION = "map.annotation";
+/** A serializable map-annotation edit broadcast to other players. */
+export type AnnotationBroadcast = {
+    op: "stroke";
+    from: string;
+    id: string;
+    points: readonly WorldXZ[];
+    tone?: MapLayerTone;
+    width?: number;
+} | {
+    op: "shape";
+    from: string;
+    id: string;
+    shape: MapZoneShape;
+    tone?: MapLayerTone;
+    label?: string;
+} | {
+    op: "note";
+    from: string;
+    id: string;
+    position: WorldXZ;
+    text: string;
+    tone?: MapLayerTone;
+} | {
+    op: "remove";
+    from: string;
+    id: string;
+} | {
+    op: "clear";
+    from: string;
+};
+/** The feed sink shared annotations push to — an alias of the ping/feed `push` seam. */
+export interface AnnotationFeedSink {
+    push(action: string, entry: unknown): void;
+}
+/** Construction options for {@link createSharedAnnotations}. */
+export interface SharedAnnotationsDeps {
+    /** The local annotation layer edits apply to (and inbound edits mirror into). */
+    layer: AnnotationLayer;
+    /** Feed to broadcast local edits on (typically `ctx.game.feed`). */
+    feed: AnnotationFeedSink;
+    /** This player's id — stamped on broadcasts and used to drop our own echoes. */
+    from: string;
+    /** Feed action to publish/consume. Default {@link ANNOTATION_FEED_ACTION}. */
+    action?: string;
+}
+/**
+ * Local annotation edits that also broadcast, plus `apply` for inbound edits.
+ * `add*`/`remove`/`clear` mirror {@link AnnotationLayer} but return globally-unique
+ * ids so two clients never collide.
+ */
+export interface SharedAnnotations {
+    addStroke(points: readonly WorldXZ[], options?: {
+        tone?: MapLayerTone;
+        width?: number;
+    }): string;
+    addShape(shape: MapZoneShape, options?: {
+        tone?: MapLayerTone;
+        label?: string;
+    }): string;
+    addNote(position: WorldXZ, text: string, options?: {
+        tone?: MapLayerTone;
+    }): string;
+    remove(id: string): boolean;
+    clear(): void;
+    /** Mirror an inbound broadcast from another player; own echoes (matching `from`) are ignored. */
+    apply(payload: AnnotationBroadcast): void;
+    feedAction: string;
+}
+/**
+ * Make a map annotation layer collaborative: local `addStroke`/`addShape`/
+ * `addNote`/`remove`/`clear` apply then broadcast a serializable edit over the
+ * party feed (the same seam `createPingSystem` uses), and `apply` mirrors inbound
+ * edits from other players — dropping our own echoes. Ids are globally unique per
+ * client so two players' strokes never collide. Transport-agnostic: wire `feed`
+ * to any replicated feed and route received entries into `apply`.
+ *
+ * @capability shared-annotations broadcast local map-drawing edits over the party feed and mirror inbound edits — collaborative annotations over any replicated feed
+ */
+export declare function createSharedAnnotations(deps: SharedAnnotationsDeps): SharedAnnotations;

package/dist/world/sharedAnnotations.js

@@ -0,0 +1,76 @@
+/** Feed action shared drawings ride by default (pair with the party feed, like pings). */
+export const ANNOTATION_FEED_ACTION = "map.annotation";
+/**
+ * Make a map annotation layer collaborative: local `addStroke`/`addShape`/
+ * `addNote`/`remove`/`clear` apply then broadcast a serializable edit over the
+ * party feed (the same seam `createPingSystem` uses), and `apply` mirrors inbound
+ * edits from other players — dropping our own echoes. Ids are globally unique per
+ * client so two players' strokes never collide. Transport-agnostic: wire `feed`
+ * to any replicated feed and route received entries into `apply`.
+ *
+ * @capability shared-annotations broadcast local map-drawing edits over the party feed and mirror inbound edits — collaborative annotations over any replicated feed
+ */
+export function createSharedAnnotations(deps) {
+    const { layer, feed, from } = deps;
+    const action = deps.action ?? ANNOTATION_FEED_ACTION;
+    let counter = 0;
+    function nextId() {
+        counter += 1;
+        return `${from}:${counter}`;
+    }
+    function broadcast(payload) {
+        feed.push(action, payload);
+    }
+    return {
+        feedAction: action,
+        addStroke(points, options = {}) {
+            const id = nextId();
+            layer.addStroke(points, { id, ...options });
+            broadcast({ op: "stroke", from, id, points: points.map((p) => [p[0], p[1]]), ...options });
+            return id;
+        },
+        addShape(shape, options = {}) {
+            const id = nextId();
+            layer.addShape(shape, { id, ...options });
+            broadcast({ op: "shape", from, id, shape, ...options });
+            return id;
+        },
+        addNote(position, text, options = {}) {
+            const id = nextId();
+            layer.addNote(position, text, { id, ...options });
+            broadcast({ op: "note", from, id, position: [position[0], position[1]], text, ...options });
+            return id;
+        },
+        remove(id) {
+            const existed = layer.remove(id);
+            if (existed)
+                broadcast({ op: "remove", from, id });
+            return existed;
+        },
+        clear() {
+            layer.clear();
+            broadcast({ op: "clear", from });
+        },
+        apply(payload) {
+            if (payload.from === from)
+                return; // ignore our own echo
+            switch (payload.op) {
+                case "stroke":
+                    layer.addStroke(payload.points, { id: payload.id, tone: payload.tone, width: payload.width });
+                    return;
+                case "shape":
+                    layer.addShape(payload.shape, { id: payload.id, tone: payload.tone, label: payload.label });
+                    return;
+                case "note":
+                    layer.addNote(payload.position, payload.text, { id: payload.id, tone: payload.tone });
+                    return;
+                case "remove":
+                    layer.remove(payload.id);
+                    return;
+                case "clear":
+                    layer.clear();
+                    return;
+            }
+        },
+    };
+}

package/dist/world/spawnOverride.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-session player-spawn override — a capture-harness ergonomics seam that lets a single
+ * screenshot or drive run place the player somewhere other than the authored `player_spawn`
+ * marker *without mutating `editor.scene.json`*. The runner installs one from the `?spawn=` URL
+ * overlay (mirroring `?cam=`); {@link authoredSpawnPosition} consults it for the default
+ * player-spawn resolution only, so authored content is untouched and the override evaporates the
+ * moment the page reloads without the param.
+ *
+ * Genre-agnostic: it moves whatever a game treats as its player spawn. It never changes markers of
+ * other kinds or an explicit marker `id`, so an override taken for a close-up cannot perturb enemy
+ * or prop placement queries that share {@link authoredSpawnPosition}.
+ *
+ * Install-style module state is the established runner pattern here (`installAssetBase`,
+ * `installEditorHost`, `installSaveEndpoint`); the default is `null`, so nothing changes and every
+ * pure query stays deterministic until a runner explicitly installs an override.
+ */
+/** A spawn point that replaces the authored player spawn for one capture session. */
+export interface SpawnOverride {
+    x: number;
+    y: number;
+    z: number;
+    /** Optional facing (yaw radians); when omitted the authored/`0` rotation is kept. */
+    rotationY?: number;
+}
+/** Install (or, with `null`, clear) the active player-spawn override. Idempotent; last write wins. */
+export declare function installSpawnOverride(override: SpawnOverride | null): void;
+/** Clear any installed player-spawn override. */
+export declare function clearSpawnOverride(): void;
+/** The currently installed player-spawn override, or `null` when none is active. */
+export declare function readSpawnOverride(): SpawnOverride | null;
+/**
+ * Parse a `?spawn=` / `--spawn` value into a {@link SpawnOverride}, or `null` when it is absent or
+ * malformed. Accepts `"x,y,z"` and `"x,y,z,yaw"` (yaw in radians); whitespace around components is
+ * tolerated. A non-finite or short tuple yields `null` so a typo never silently teleports the
+ * player to `NaN`.
+ */
+export declare function parseSpawnOverride(raw: string | null | undefined): SpawnOverride | null;

package/dist/world/spawnOverride.js

@@ -0,0 +1,50 @@
+/**
+ * Per-session player-spawn override — a capture-harness ergonomics seam that lets a single
+ * screenshot or drive run place the player somewhere other than the authored `player_spawn`
+ * marker *without mutating `editor.scene.json`*. The runner installs one from the `?spawn=` URL
+ * overlay (mirroring `?cam=`); {@link authoredSpawnPosition} consults it for the default
+ * player-spawn resolution only, so authored content is untouched and the override evaporates the
+ * moment the page reloads without the param.
+ *
+ * Genre-agnostic: it moves whatever a game treats as its player spawn. It never changes markers of
+ * other kinds or an explicit marker `id`, so an override taken for a close-up cannot perturb enemy
+ * or prop placement queries that share {@link authoredSpawnPosition}.
+ *
+ * Install-style module state is the established runner pattern here (`installAssetBase`,
+ * `installEditorHost`, `installSaveEndpoint`); the default is `null`, so nothing changes and every
+ * pure query stays deterministic until a runner explicitly installs an override.
+ */
+let installed = null;
+/** Install (or, with `null`, clear) the active player-spawn override. Idempotent; last write wins. */
+export function installSpawnOverride(override) {
+    installed = override;
+}
+/** Clear any installed player-spawn override. */
+export function clearSpawnOverride() {
+    installed = null;
+}
+/** The currently installed player-spawn override, or `null` when none is active. */
+export function readSpawnOverride() {
+    return installed;
+}
+/**
+ * Parse a `?spawn=` / `--spawn` value into a {@link SpawnOverride}, or `null` when it is absent or
+ * malformed. Accepts `"x,y,z"` and `"x,y,z,yaw"` (yaw in radians); whitespace around components is
+ * tolerated. A non-finite or short tuple yields `null` so a typo never silently teleports the
+ * player to `NaN`.
+ */
+export function parseSpawnOverride(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const parts = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length < 3 || parts.length > 4)
+        return null;
+    const nums = parts.map((part) => Number(part));
+    if (nums.some((value) => !Number.isFinite(value)))
+        return null;
+    const [x, y, z, rotationY] = nums;
+    return rotationY === undefined ? { x, y, z } : { x, y, z, rotationY };
+}

package/dist/world/streetGenerator.d.ts

@@ -25,6 +25,10 @@ export interface StreetEdge {
     level: StreetLevel;
     /** True when this edge belongs to the main closed loop (circuit mode). */
     loop: boolean;
+    /** Per-point road-surface height (one per `points`), present only when `elevation > 0`. Raw
+     *  (uncapped) samples of {@link StreetNetwork.elevationAt}; the grade-limited profile lives on the
+     *  owning {@link Street.heights}. */
+    heights?: number[];
 }
 /** A feature span carried by a street: a `[from, to]` index window into the street's `points`. */
 export interface StreetFeatureSpan {
@@ -34,12 +38,19 @@ export interface StreetFeatureSpan {
     /** Ground height at each bank/portal — the deck/floor reference the renderer drapes to. */
     bankHeight: number;
 }
+/** Left/right pedestrian bands flanking a street's asphalt, as offset polylines. */
+export interface StreetSidewalks {
+    /** Polyline offset to the left of travel (parallel to `points`). */
+    left: StreetVec2[];
+    /** Polyline offset to the right of travel. */
+    right: StreetVec2[];
+}
 /** One chained through-street: a maximal run of edges through degree-2 nodes, for rendering + furniture. */
 export interface Street {
     id: number;
     /** Ordered node ids the chain visits; first === last when `loop`. */
     nodes: number[];
-    /** Smoothed, turn-clamped centerline. */
+    /** Smoothed, arc-filleted centerline. */
     points: StreetVec2[];
     width: number;
     level: StreetLevel;
@@ -49,6 +60,12 @@ export interface Street {
     bulb?: StreetVec2;
     /** Bridge/tunnel spans along this street, if any. */
     features: StreetFeatureSpan[];
+    /** Flanking pedestrian bands, present on boulevard/avenue/street levels (not lanes). */
+    sidewalks?: StreetSidewalks;
+    /** Per-point road-surface height (one per `points`), present only when `elevation > 0`. Grade-limited
+     *  so no consecutive pair exceeds `maxGrade`; a loop stays continuous (`heights[0] === heights.at(-1)`).
+     *  This is ROAD elevation, not the `context.heightAt` terrain that drives bridges/tunnels. */
+    heights?: number[];
 }
 /** One crossing of three or more streets: patch center/radius plus outgoing arm directions. */
 export interface StreetJunction {
@@ -92,36 +109,60 @@ export interface StreetNetwork {
     tunnels: StreetFeature[];
     /** Independent cycle count (E − V + components): 0 = pure tree, ≥1 = has loops. */
     loops: number;
+    /** The shared road-surface height FIELD (volume-local), present only when `elevation > 0`. Sample it
+     *  to drape junction welds, sidewalks, and building bases so every surface meets the road continuously
+     *  — the streets/edges sample this exact field. Distinct from the `context.heightAt` terrain sampler. */
+    elevationAt?: (x: number, z: number) => number;
 }
 /** Fully-defaulted slider set the generator reads. */
 export interface StreetNetworkRules {
     seed: string;
+    /** Organic boundary clipping amount, when supported by the caller. */
+    outline?: number;
     /** 1 = regular lattice nodes; 0 = organic scatter. */
     gridness: number;
     /** 0 = tree (dead-ends); 1 = a single closed circuit. */
     loopiness: number;
     /** Extra chord edges between neighbors → mesh density. */
     connectivity: number;
-    /** Spur-lane density forking off the mains. */
+    /** Spur-lane density forking off the mains (and, in a circuit, the pit-lane trigger). */
     branching: number;
+    /** Share of branch streets that use residential side-street rules. */
+    residentialBranches?: number;
     /** Fraction of dangling ends kept as cul-de-sacs (vs reconnected). */
     deadEnds: number;
     /** Target node spacing / block size, world units. */
     segmentLength: number;
     /** Cross-axis spacing multiplier (≥1 = long skinny Manhattan blocks). */
     aspect: number;
-    /** Sideways wander amplitude, 0..1. */
+    /** Sideways wander amplitude, 0..1 (and circuit corner-template density). */
     winding: number;
-    /** Minimum curve radius (m) — caps wander curvature and corner tightness. */
+    /** Minimum curve radius (m) — caps wander curvature and sets the corner-fillet radius. */
     minCurveRadius: number;
     /** Shallowest corner (degrees) a street keeps — gentler bends are straightened. */
     minTurnAngle: number;
-    /** Sharpest corner (degrees) a street may take — tighter ones are beveled away. */
+    /** Sharpest corner (degrees) between consecutive centerline samples — sharper corners are filleted. */
     maxTurnAngle: number;
     /** Base street width; the hierarchy scales off it. */
     width: number;
     /** Share of avenues upgraded to boulevards, 0..1. */
     boulevards: number;
+    /** Pedestrian band width paved on each side of boulevard/avenue/street levels. Default ~2. */
+    sidewalkWidth?: number;
+    /** Road-surface relief amplitude, 0..1. 0 (default) = dead flat and byte-identical to a pre-elevation
+     *  network; 1 ≈ 22 m of relief across a ~520 m volume (scaled to the footprint). */
+    elevation?: number;
+    /** Maximum road slope (rise/run) the grade cap enforces on every street's height sequence. Default 0.07. */
+    maxGrade?: number;
+    /** SPACE-FILLING circuit layout dial, 0..1. 0 (default) = the hull construction (a flowing loop around
+     *  an empty middle), BYTE-IDENTICAL to a pre-compactness network. Rising values switch the circuit
+     *  LAYOUT stage to a grid spanning-tree CYCLE that folds back through its own interior: parallel
+     *  adjacent runs one corridor pitch apart, switchback esses, consecutive hairpins, and long straights
+     *  from straight tree branches, with footprint coverage rising with the dial (~45% of grid cells at
+     *  0.5, ~85% at 1). Everything downstream — spline fit, curvature floor, straight designation,
+     *  self-clearance, edge distribution, elevation, pit lane — is reused unchanged. Only meaningful in
+     *  circuit mode; ignored by the street net. */
+    compactness?: number;
 }
 /** Ground sampler + feature toggles enabling bridges/tunnels; omit for a flat, feature-free network. */
 export interface StreetNetworkContext {
@@ -137,13 +178,21 @@ export interface StreetNetworkContext {
     tunnelClearance?: number;
 }
 /**
- * Hard turn-angle clamp on a polyline with fixed endpoints: interior corners gentler than `minRad`
- * are straightened away (deliberate winding only, no micro-wiggle) and corners sharper than `maxRad`
- * are beveled — the corner vertex is replaced by two points pulled back along each leg, which
- * strictly reduces the angle. Endpoints never move, so a graph node stays welded.
+ * Replace every real corner of a polyline with a sampled **circular-arc fillet** so bends read as
+ * smooth curves instead of polygonal notches, while enforcing two hard limits with fixed endpoints:
+ * interior corners gentler than `minRad` are straightened away (deliberate winding only, no
+ * micro-wiggle), and each remaining corner is rounded with an arc of radius `curveRadius` (clamped to
+ * half the shorter adjacent leg) sampled finely enough that no discrete turn between consecutive
+ * samples exceeds `maxRad` — a corner sharper than the ceiling is still reduced, now to a fillet
+ * rather than a bevel. Open-chain endpoints never move (a graph node stays welded); pass `closed` for
+ * a ring (first === last) so its wrap corner is filleted too and the loop stays closed.
+ *
+ * Pass `radiusFor` to vary the fillet radius PER CORNER (returning the target radius from the corner's
+ * deflection and adjacent leg lengths) instead of the single `curveRadius` — the circuit loop uses this
+ * to mix hairpins, standard corners, and sweepers; every other caller keeps the scalar radius.
  * @internal
  */
-export declare function clampTurns(points: readonly StreetVec2[], minRad: number, maxRad: number): StreetVec2[];
+export declare function clampTurns(points: readonly StreetVec2[], minRad: number, maxRad: number, curveRadius?: number, closed?: boolean, radiusFor?: (deflection: number, la: number, lb: number) => number): StreetVec2[];
 /** Decide which topology family the sliders call for. Circuit wins when loops dominate and both
  *  branching and mesh connectivity are low — exactly the "race track" corner of the slider space.
  *  @internal */
@@ -154,6 +203,6 @@ export declare function streetNetworkMode(rules: StreetNetworkRules): StreetNetw
  * water gaps into bridges and ridges into tunnels. Coordinates are volume-local; the caller maps to
  * world space.
  *
- * @capability street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, bridges, tunnels) from sliders
+ * @capability street-generator build a deterministic street/track graph (nodes, edges, streets, junctions, sidewalks, bridges, tunnels) from sliders
  */
 export declare function generateStreets(rules: StreetNetworkRules, hx: number, hz: number, context?: StreetNetworkContext): StreetNetwork;