@jgengine/core 0.18.0 → 0.18.1

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;