@jgengine/core 0.12.0 → 0.14.0

package/dist/world/buildingLots.js

@@ -0,0 +1,119 @@
+const DEFAULT_FOOTPRINT = { w: 12, d: 10 };
+/** Cumulative arc length of a polyline. */
+function polylineLength(path) {
+    let sum = 0;
+    for (let i = 0; i + 1 < path.length; i += 1) {
+        sum += Math.hypot(path[i + 1][0] - path[i][0], path[i + 1][1] - path[i][1]);
+    }
+    return sum;
+}
+/** Point + unit tangent at arc length `s` along a polyline (clamped to its ends). */
+function stationAt(path, s) {
+    let acc = 0;
+    for (let i = 0; i + 1 < path.length; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        if (len < 1e-9)
+            continue;
+        if (acc + len >= s || i + 2 === path.length) {
+            const t = Math.max(0, Math.min(1, (s - acc) / len));
+            return {
+                p: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t],
+                tangent: [(b[0] - a[0]) / len, (b[1] - a[1]) / len],
+            };
+        }
+        acc += len;
+    }
+    const a = path[0];
+    return { p: [a[0], a[1]], tangent: [1, 0] };
+}
+function inArea(area, x, z) {
+    if (area === undefined)
+        return true;
+    const [cx, cz] = area.center ?? [0, 0];
+    return Math.abs(x - cx) <= area.halfExtents[0] && Math.abs(z - cz) <= area.halfExtents[1];
+}
+/**
+ * Yaw that turns the building FRONT (local +z) to face the road. The lot center sits at
+ * `roadPoint + outwardNormal * d`, so the road lies along `-outwardNormal` from the center. In the
+ * engine's Y-rotation convention a local +z of `(0, 1)` maps to world `(sin y, cos y)`; setting
+ * that equal to `-outwardNormal` gives `y = atan2(-nx, -nz)`.
+ * @internal
+ */
+export function facingRotation(outwardNormal) {
+    return Math.atan2(-outwardNormal[0], -outwardNormal[1]);
+}
+/**
+ * Derive street-aligned building lots from road frontage. Lots are stepped along each road at
+ * `footprint.w + spacing`, offset to each side by `width / 2 + setback + footprint.d / 2`, and
+ * turned to face the road. Cross-road overlaps are rejected by a bounded nearest-neighbour test, so
+ * two roads meeting at a corner don't stack buildings. Deterministic: identical inputs (including
+ * seed) always yield the identical list.
+ * @capability building-lots derive street-facing building lots from road frontage
+ */
+export function deriveBuildingLots(options) {
+    const footprint = options.footprint ?? DEFAULT_FOOTPRINT;
+    const spacing = Math.max(0, options.spacing ?? 2);
+    const setback = Math.max(0, options.setback ?? 3);
+    const bothSides = options.bothSides ?? true;
+    const maxLots = Math.max(0, Math.floor(options.maxLots ?? 400));
+    const step = Math.max(1, footprint.w + spacing);
+    const sides = bothSides ? [1, -1] : [1];
+    // Minimum center separation for cross-road de-dup: half the footprint diagonal, a touch under
+    // the along-road step so same-road neighbours are never rejected.
+    const minSep = Math.min(step * 0.95, Math.hypot(footprint.w, footprint.d) * 0.5);
+    const minSep2 = minSep * minSep;
+    const lots = [];
+    const accepted = [];
+    for (let r = 0; r < options.roads.length && lots.length < maxLots; r += 1) {
+        const road = options.roads[r];
+        if (road.path.length < 2)
+            continue;
+        const total = polylineLength(road.path);
+        if (total < 1e-6)
+            continue;
+        const front = road.width / 2 + setback;
+        const offset = front + footprint.d / 2;
+        // Center the run so lots sit symmetrically and endpoints keep a half-step margin.
+        const count = Math.max(1, Math.floor(total / step));
+        const startS = (total - (count - 1) * step) / 2;
+        for (let i = 0; i < count && lots.length < maxLots; i += 1) {
+            const s = startS + i * step;
+            const station = stationAt(road.path, s);
+            const [tx, tz] = station.tangent;
+            // Left normal of the tangent (CCW): (-tz, tx). Right side negates it.
+            for (const side of sides) {
+                if (lots.length >= maxLots)
+                    break;
+                const nx = -tz * side;
+                const nz = tx * side;
+                const cx = station.p[0] + nx * offset;
+                const cz = station.p[1] + nz * offset;
+                if (!inArea(options.area, cx, cz))
+                    continue;
+                let clash = false;
+                for (const [ax, az] of accepted) {
+                    const dx = ax - cx;
+                    const dz = az - cz;
+                    if (dx * dx + dz * dz < minSep2) {
+                        clash = true;
+                        break;
+                    }
+                }
+                if (clash)
+                    continue;
+                lots.push({
+                    center: [cx, cz],
+                    rotationY: facingRotation([nx, nz]),
+                    footprint: { w: footprint.w, d: footprint.d },
+                    road: r,
+                    side,
+                    frontDistance: front,
+                });
+                accepted.push([cx, cz]);
+            }
+        }
+    }
+    return lots;
+}

package/dist/world/buildings.d.ts

@@ -72,6 +72,12 @@ export interface GeneratedBuilding {
     floorHeight: number;
     bounds: Aabb;
     parts: readonly BuildingPartPlacement[];
+    /**
+     * Optional building yaw (radians) about `center`, applied by the renderer to the whole massing —
+     * used by street-aware placement to turn a building's front to face its road. Absent/0 keeps the
+     * axis-aligned grid orientation.
+     */
+    rotationY?: number;
 }
 export interface BuildingLot {
     id: string;

package/dist/world/cityGenerator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The seed-driven procedural CITY GENERATOR — the composition seam over the two fabric engines:
+ * {@link generateStreets} grows the street network, and {@link deriveBuildingLots} lines its
+ * frontage with street-facing building lots. One call, one seed, one deterministic city: same rules
+ * ⇒ identical streets and identical lots, with both engines' bounded-work caps intact. Local
+ * (volume-centered) coords, same as the street generator; the caller translates into world space.
+ *
+ * Street dials default to a dense, gently-varied city net (high gridness/connectivity, light
+ * winding); pass any subset of {@link StreetNetworkRules} to override, and lot options pass through
+ * to the frontage engine untouched. Lanes are skipped as lot frontage by default — buildings line
+ * boulevards, avenues, and streets — so alleys stay service alleys; opt lanes in via
+ * `lots.laneFrontage`.
+ *
+ * @capability city-generator compose a deterministic city — street network plus street-facing building lots — from one seed
+ */
+import { type BuildingLotOptions, type PlacedBuildingLot } from "./buildingLots.js";
+import { type StreetNetwork, type StreetNetworkContext, type StreetNetworkRules } from "./streetGenerator.js";
+/** Options for {@link generateCity}: a seed, street-dial overrides, and lot pass-through options. */
+export interface CityGeneratorOptions {
+    /** Drives both the street network and downstream lot/floor variation. */
+    seed: string;
+    /** Street-dial overrides; anything omitted takes the city defaults above. */
+    streets?: Partial<Omit<StreetNetworkRules, "seed">>;
+    /** Frontage-lot options, minus `roads` (the generated streets are the roads). */
+    lots?: Omit<BuildingLotOptions, "roads" | "seed"> & {
+        /** Also line `lane`-level streets (alleys) with lots. Default false. */
+        laneFrontage?: boolean;
+    };
+    /** Ground sampler + bridge/tunnel toggles forwarded to the street generator. */
+    context?: StreetNetworkContext;
+}
+/** A generated city: the street network and the building lots lining its frontage. */
+export interface GeneratedCity {
+    network: StreetNetwork;
+    lots: PlacedBuildingLot[];
+}
+/**
+ * Grow a street network inside the `hx`/`hz` half-extents and line its frontage with building lots.
+ * Deterministic: identical options ⇒ identical city.
+ */
+export declare function generateCity(options: CityGeneratorOptions, hx: number, hz: number): GeneratedCity;

package/dist/world/cityGenerator.js

@@ -0,0 +1,58 @@
+/**
+ * The seed-driven procedural CITY GENERATOR — the composition seam over the two fabric engines:
+ * {@link generateStreets} grows the street network, and {@link deriveBuildingLots} lines its
+ * frontage with street-facing building lots. One call, one seed, one deterministic city: same rules
+ * ⇒ identical streets and identical lots, with both engines' bounded-work caps intact. Local
+ * (volume-centered) coords, same as the street generator; the caller translates into world space.
+ *
+ * Street dials default to a dense, gently-varied city net (high gridness/connectivity, light
+ * winding); pass any subset of {@link StreetNetworkRules} to override, and lot options pass through
+ * to the frontage engine untouched. Lanes are skipped as lot frontage by default — buildings line
+ * boulevards, avenues, and streets — so alleys stay service alleys; opt lanes in via
+ * `lots.laneFrontage`.
+ *
+ * @capability city-generator compose a deterministic city — street network plus street-facing building lots — from one seed
+ */
+import { deriveBuildingLots } from "./buildingLots.js";
+import { isOnRoad } from "./roads.js";
+import { generateStreets, } from "./streetGenerator.js";
+/** City-shaped defaults for every street dial except the seed. */
+const CITY_STREET_DEFAULTS = {
+    gridness: 0.85,
+    loopiness: 0.35,
+    connectivity: 0.6,
+    branching: 0.25,
+    deadEnds: 0.15,
+    segmentLength: 90,
+    aspect: 1.4,
+    winding: 0.15,
+    minCurveRadius: 18,
+    minTurnAngle: 12,
+    maxTurnAngle: 110,
+    width: 9,
+    boulevards: 0.2,
+};
+/**
+ * Grow a street network inside the `hx`/`hz` half-extents and line its frontage with building lots.
+ * Deterministic: identical options ⇒ identical city.
+ */
+export function generateCity(options, hx, hz) {
+    const { seed, streets: streetOverrides, lots: lotOptions, context } = options;
+    const rules = { seed, ...CITY_STREET_DEFAULTS, ...streetOverrides };
+    const network = generateStreets(rules, hx, hz, context ?? {});
+    const { laneFrontage = false, ...lotRest } = lotOptions ?? {};
+    const frontage = network.streets
+        .filter((street) => laneFrontage || street.level !== "lane")
+        .map((street) => ({ path: street.points, width: street.width }));
+    const candidates = deriveBuildingLots({
+        ...lotRest,
+        roads: frontage,
+        seed,
+        area: lotRest.area ?? { center: [0, 0], halfExtents: [hx, hz] },
+    });
+    // The frontage engine only avoids the roads it lines; streets excluded from frontage (lanes by
+    // default) are still pavement, so drop any lot whose footprint would straddle one.
+    const clearance = Math.min(lotRest.footprint?.w ?? 12, lotRest.footprint?.d ?? 10);
+    const lots = candidates.filter((lot) => network.streets.every((street) => !isOnRoad(street.points, street.width + clearance, lot.center[0], lot.center[1])));
+    return { network, lots };
+}

package/dist/world/cityKind.d.ts

@@ -2,7 +2,7 @@ import { type ParamSchema, type SceneKindObject, type SceneKindResolveContext, t
 import { type BuildingStyle } from "./buildings.js";
 import { type CityLotClass, type CityLotPiece, type CityTreeSpecies, type CityZoneBand, type CityZoneProfile } from "./cityContent.js";
 import type { RoadPoint } from "./roads.js";
-import { type PathFeatureKind } from "./pathNetwork.js";
+import { type StreetFeatureKind } from "./streetGenerator.js";
 import { type CityBlockKind } from "./cityBlocks.js";
 /** The editor volume kind marking a box as a procedural city district. */
 export declare const CITY_KIND = "city";
@@ -130,7 +130,7 @@ export interface CityStreet {
     bulb?: RoadPoint;
     /** Bridge/tunnel spans along this street as `[from, to]` index windows into `points`. */
     features?: readonly {
-        kind: PathFeatureKind;
+        kind: StreetFeatureKind;
         from: number;
         to: number;
         bankHeight: number;

package/dist/world/cityKind.js

@@ -3,7 +3,7 @@
  * the whole synthesis, from a rigid Manhattan grid (`gridness` 1, `curviness` 0) to winding
  * hillside estates, a two-road crossroads farm town, or — at the loopiness-high / branching-and-
  * connectivity-low corner — a closed RACE CIRCUIT. Streets come from the unified seed-driven
- * {@link buildPathNetwork} engine (city and track are the same generator at opposite slider
+ * {@link generateStreets} engine (city and track are the same generator at opposite slider
  * extremes), carry a visible hierarchy (boulevards with medians, avenues, streets, lanes —
  * optionally gravel), and connect or deliberately dead-end into cul-de-sac bulbs; water gaps become
  * styled bridge decks and ridges become tunnel bores, both path features on continuous streets so a
@@ -32,7 +32,8 @@ import { parseParams, registerSceneKind, } from "../scene/sceneKinds.js";
 import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_STYLE } from "./buildings.js";
 import { buildLotPieces, pickClass, pickSpecies, rollClassPlacement, zoneBand, zoneMetric, } from "./cityContent.js";
 import { furnitureSpots } from "./streets.js";
-import { buildPathNetwork, pathNetworkMode, } from "./pathNetwork.js";
+import { CITY_BUILDING_BUDGET, budgetWarning, placedCoverage } from "./scatterCoverage.js";
+import { generateStreets, streetNetworkMode, } from "./streetGenerator.js";
 import { buildablePolygon, carveCorridors, conformPolygonToRing, cutParcel, extractBlocks, isSliverBlock, pointsInPolygon, RingWalker, } from "./cityBlocks.js";
 import { fitRectInPolygon, rayDistanceToRing, pointInPolygon, polygonArea, polygonCentroid, polygonMeanWidth, polygonsOverlap, insetRingUniform, ringBounds, } from "./cityGeometry.js";
 /** The editor volume kind marking a box as a procedural city district. */
@@ -567,7 +568,8 @@ export function readCityRules(meta) {
 }
 /** Bounded-work caps so a huge volume can never generate unbounded content. */
 const MAX_STREETS = 320;
-const MAX_LOTS = 2600;
+/** Building budget — the shared scatterable cap so the inspector's "capped at N (budget)" note is truthful. */
+const MAX_LOTS = CITY_BUILDING_BUDGET;
 const MAX_INTERSECTIONS = 600;
 const MAX_TREES = 3200;
 const MAX_LIGHTS = 1200;
@@ -1215,7 +1217,7 @@ export function resolveCityObject(object, context) {
         width: rules.streetWidth,
         boulevards: rules.boulevards,
     };
-    const network = buildPathNetwork(netRules, hx, hz, {
+    const network = generateStreets(netRules, hx, hz, {
         heightAt: heightAt ?? undefined,
         minElevation: rules.minElevation,
         bridges: rules.bridges,
@@ -1530,6 +1532,7 @@ export function registerCityKind() {
         addCategory: "Studios",
         accent: "#8fa8c9",
         schema: CITY_SCHEMA,
+        coverage: { spec: "city", densityKey: "roadsideOccupancy" },
         resolve: (object, _params, context) => resolveCityObject(object, context),
         note: (object) => {
             const resolved = resolveCityObject(object);
@@ -1537,7 +1540,7 @@ export function registerCityKind() {
                 return "Give the volume a box footprint.";
             if (resolved.streets.length === 0)
                 return `Footprint too small — needs at least ${Math.ceil(resolved.rules.blockSize * 1.5)} m across.`;
-            const mode = pathNetworkMode({
+            const mode = streetNetworkMode({
                 seed: resolved.rules.seed,
                 gridness: resolved.rules.gridness,
                 loopiness: resolved.rules.loopiness,
@@ -1558,7 +1561,10 @@ export function registerCityKind() {
                 resolved.tunnels.length > 0 ? `${resolved.tunnels.length} tunnels` : "",
             ].filter((s) => s.length > 0);
             const head = mode === "circuit" ? `circuit · ${resolved.streets.length} streets` : `${resolved.streets.length} streets`;
-            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings · ${resolved.parks.length} parks` : " · no fabric";
+            // Shared clamp-and-warn: when the block/parcel pipeline hits the building budget, surface it in
+            // the same "capped at N (budget)" wording grass and scatter use.
+            const buildingCap = resolved.rules.fabric ? budgetWarning(placedCoverage("city", 0, resolved.lots.length)) : "";
+            const fabric = resolved.rules.fabric ? ` · ${resolved.lots.length} buildings${buildingCap} · ${resolved.parks.length} parks` : " · no fabric";
             return `${head}${fabric}${feats.length > 0 ? ` · ${feats.join(" · ")}` : ""}`;
         },
     });

package/dist/world/environmentSummary.js

@@ -1,7 +1,11 @@
-import { generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { DEFAULT_BUILDING_CONFIG, generateBuilding, generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { deriveBuildingLots } from "./buildingLots.js";
 import { pathLength } from "./roads.js";
 import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
 export function resolveStructureBuildings(descriptor) {
+    if (descriptor.along !== undefined) {
+        return resolveFrontageBuildings(descriptor, descriptor.along);
+    }
     const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
     const rows = Math.max(1, Math.ceil(descriptor.count / columns));
     const spacing = descriptor.spacing;
@@ -21,6 +25,58 @@ export function resolveStructureBuildings(descriptor) {
         ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
     }).slice(0, descriptor.count);
 }
+function hashU32(input) {
+    let hash = 2166136261;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 2246822507);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 3266489909);
+    hash ^= hash >>> 16;
+    return hash >>> 0;
+}
+/**
+ * Build one street-aware building per road-frontage lot: massed at the lot center, its `rotationY`
+ * set so the front faces the road (the renderer turns the whole building about `center`), floors
+ * rolled deterministically from the descriptor's `stories` and the lot's road/side/index.
+ */
+function resolveFrontageBuildings(descriptor, along) {
+    const seed = descriptor.seed ?? "buildings";
+    const lots = deriveBuildingLots({
+        roads: along.roads,
+        footprint: descriptor.footprint,
+        spacing: descriptor.spacing,
+        maxLots: descriptor.count,
+        seed: `${seed}:lots`,
+        ...(along.setback === undefined ? {} : { setback: along.setback }),
+        ...(along.bothSides === undefined ? {} : { bothSides: along.bothSides }),
+        ...(along.area === undefined ? {} : { area: along.area }),
+    });
+    const [floorsMin, floorsMax] = descriptor.stories;
+    const bayWidth = DEFAULT_BUILDING_CONFIG.bayWidth;
+    return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight));
+}
+function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight) {
+    const lo = Math.min(floorsMin, floorsMax);
+    const hi = Math.max(floorsMin, floorsMax);
+    const floors = lo + Math.floor((hashU32(`${seed}:floors:${index}`) / 4294967296) * (hi - lo + 1));
+    const baysWide = Math.max(1, Math.floor(lot.footprint.w / bayWidth));
+    const baysDeep = Math.max(1, Math.floor(lot.footprint.d / bayWidth));
+    const building = generateBuilding({
+        id: `frontage-${index}`,
+        seed: `${seed}:${index}`,
+        center: lot.center,
+        floors,
+        baysWide,
+        baysDeep,
+        bayWidth,
+        floorHeight: storyHeight,
+    });
+    return { ...building, rotationY: lot.rotationY };
+}
 const TERRAIN_SAMPLE_RESOLUTION = 16;
 function sampleTerrainHeights(descriptor) {
     const field = resolveTerrainField(descriptor);

package/dist/world/features.d.ts

@@ -291,6 +291,34 @@ export interface SkyEnvironmentConfig {
     /** Raymarched volumetric cloud layer over the sky dome. Off by default — omit for no clouds. */
     volumetricClouds?: VolumetricCloudsConfig;
 }
+/** One road a `building({ along })` frontage lines with buildings: centerline + full width. */
+export interface BuildingFrontageRoad {
+    /** Road centerline vertices in world XZ; at least two points. */
+    path: readonly EnvironmentVec2[];
+    /** Road full width in world units; lots set back from `width / 2`. */
+    width: number;
+}
+/**
+ * Street-aware placement for `building()`: instead of a grid scattered around `position`, lots are
+ * stepped along each road's frontage, offset by a consistent setback (a curb + sidewalk strip), and
+ * turned so every building FRONT faces its road. `footprint` (`w` = frontage width, `d` = depth) and
+ * `spacing` (along-road gap) are shared with the grid mode. Deterministic and bounded by `maxLots`.
+ */
+export interface BuildingFrontageConfig {
+    /** Roads whose frontage is lined with lots. */
+    roads: readonly BuildingFrontageRoad[];
+    /** Sidewalk strip between the curb (`width / 2`) and the building front, world units. Default 3. */
+    setback?: number;
+    /** Place lots on both sides of each road. Default true. */
+    bothSides?: boolean;
+    /** Clip region; lots whose center falls outside are dropped. Omit to keep every lot. */
+    area?: {
+        center?: EnvironmentVec2;
+        halfExtents: EnvironmentVec2;
+    };
+    /** Hard cap on emitted lots so a long network stays bounded. Default 400. */
+    maxLots?: number;
+}
 export interface BuildingEnvironmentConfig {
     count?: number;
     position?: EnvironmentVec2;
@@ -303,6 +331,11 @@ export interface BuildingEnvironmentConfig {
     /** Explicit per-part-kind hex colors; any part left unset falls back to the resolved `style` palette. */
     palette?: BuildingPaletteOverrides;
     seed?: string;
+    /**
+     * Street-aware placement: derive lots along the given roads' frontage (facing each street, set
+     * back by a sidewalk strip) instead of the grid around `position`. See {@link BuildingFrontageConfig}.
+     */
+    along?: BuildingFrontageConfig;
 }
 export type PadSize = readonly [number, number] | {
     radius: number;
@@ -344,7 +377,7 @@ export type OceanEnvironmentDescriptor = {
 } & 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">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
 } & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;
@@ -509,7 +542,7 @@ export declare function ocean(config?: OceanEnvironmentConfig): OceanEnvironment
 /** Declare a road ribbon for an `environment()` world; the shell drapes and renders it over the terrain. */
 export declare function road(config: RoadEnvironmentConfig): RoadEnvironmentDescriptor;
 export declare function island(config: TerrainIslandConfig): TerrainIslandDescriptor;
-/** Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. */
+/** Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`. */
 export declare function building(config?: BuildingEnvironmentConfig): BuildingEnvironmentDescriptor;
 export declare function pad(config: PadEnvironmentConfig): PadEnvironmentDescriptor;
 /** Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain. */

package/dist/world/features.js

@@ -228,11 +228,13 @@ export function island(config) {
     const { kind: _kind, ...descriptor } = terrain(terrainConfig);
     return { ...descriptor, kind: "island", origin };
 }
-/** Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. */
+/** Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`. */
 export function building(config = {}) {
     return withOptional({
         kind: "building",
-        count: config.count ?? 1,
+        // In frontage mode the road network sizes the district; `count` becomes an upper bound, so a
+        // caller that just says `along` gets a filled street rather than a single grid building.
+        count: config.count ?? (config.along === undefined ? 1 : config.along.maxLots ?? 400),
         footprint: config.footprint ?? { w: 8, d: 8 },
         stories: config.stories ?? [1, 4],
         storyHeight: config.storyHeight ?? 3,
@@ -242,6 +244,7 @@ export function building(config = {}) {
         ...(config.seed === undefined ? {} : { seed: config.seed }),
         ...(config.position === undefined ? {} : { position: config.position }),
         ...(config.palette === undefined ? {} : { palette: config.palette }),
+        ...(config.along === undefined ? {} : { along: config.along }),
     });
 }
 export function pad(config) {

package/dist/world/grassKind.js

@@ -8,6 +8,7 @@
  * @capability grass-field editor-authorable GPU grass patch
  */
 import { registerSceneKind } from "../scene/sceneKinds.js";
+import { budgetWarning, densityCoverage } from "./scatterCoverage.js";
 /** The editor volume kind marking a box as a GPU grass patch. */
 export const GRASS_FIELD_KIND = "grass_field";
 /** Grass defaults: a lush, lightly-swaying meadow. */
@@ -89,13 +90,15 @@ export function registerGrassKind() {
         addCategory: "Studios",
         accent: "#7fbf4d",
         schema: GRASS_SCHEMA,
+        coverage: { spec: "grass_field", densityKey: "density" },
         resolve: (object) => resolveGrassObject(object),
         note: (object) => {
             const resolved = resolveGrassObject(object);
             if (resolved === null)
                 return "Give the volume a box footprint.";
             const area = resolved.size[0] * resolved.size[1];
-            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈${Math.round(area * resolved.rules.density).toLocaleString()} blades`;
+            const coverage = densityCoverage("grass_field", area, resolved.rules.density);
+            return `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m · ≈ ${coverage.count.toLocaleString()} blades${budgetWarning(coverage)}`;
         },
     });
 }

package/dist/world/roads.d.ts

@@ -29,12 +29,29 @@ export interface RoadRibbonOptions {
  * into a mesh, and tests can assert on it directly.
  */
 export declare function buildRoadRibbon(path: readonly RoadPoint[], width: number, sampleHeight: (x: number, z: number) => number, options?: RoadRibbonOptions): RoadRibbon;
+/** A circular exclusion zone: dashes whose midpoint falls inside are dropped (e.g. junction patches). */
+export interface DashExclusion {
+    center: RoadPoint;
+    radius: number;
+}
+/**
+ * Build a flat, ground-draped disc patch centered on `center` — the welded junction surface that
+ * covers crossing road ribbons so they read as one intersection instead of stacking/z-fighting.
+ * A triangle fan of `segments` sides (default 16), every vertex draped at `sampleHeight + elevation`.
+ * Pure geometry; the shell meshes the result with the asphalt material.
+ */
+export declare function buildJunctionPatch(center: RoadPoint, radius: number, sampleHeight: (x: number, z: number) => number, options?: {
+    elevation?: number;
+    segments?: number;
+}): RoadRibbon;
 /**
  * Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line,
  * `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back
- * through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+ * through {@link buildRoadRibbon} with a thin width to mesh the dashes. Pass `exclude` circles
+ * (junction patches) to interrupt the center line through intersections — any dash whose midpoint
+ * lands inside an exclusion is dropped.
  */
-export declare function dashSegments(path: readonly RoadPoint[], dashLength?: number, gapLength?: number): readonly (readonly RoadPoint[])[];
+export declare function dashSegments(path: readonly RoadPoint[], dashLength?: number, gapLength?: number, exclude?: readonly DashExclusion[]): readonly (readonly RoadPoint[])[];
 /** Result of {@link nearestOnPath}: closest point on the centerline plus distance and tangent. */
 export interface RoadSample {
     /** Closest point on the centerline. */

package/dist/world/roads.js

@@ -102,12 +102,48 @@ export function buildRoadRibbon(path, width, sampleHeight, options = {}) {
     }
     return { positions, indices };
 }
+/**
+ * Build a flat, ground-draped disc patch centered on `center` — the welded junction surface that
+ * covers crossing road ribbons so they read as one intersection instead of stacking/z-fighting.
+ * A triangle fan of `segments` sides (default 16), every vertex draped at `sampleHeight + elevation`.
+ * Pure geometry; the shell meshes the result with the asphalt material.
+ */
+export function buildJunctionPatch(center, radius, sampleHeight, options = {}) {
+    const elevation = options.elevation ?? 0.08;
+    const segments = Math.max(3, Math.floor(options.segments ?? 16));
+    if (radius <= 0)
+        return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+    const [cx, cz] = center;
+    // Center vertex + one ring vertex per segment.
+    const positions = new Float32Array((segments + 1) * 3);
+    positions[0] = cx;
+    positions[1] = sampleHeight(cx, cz) + elevation;
+    positions[2] = cz;
+    for (let i = 0; i < segments; i += 1) {
+        const angle = (i / segments) * Math.PI * 2;
+        const x = cx + Math.cos(angle) * radius;
+        const z = cz + Math.sin(angle) * radius;
+        const base = (i + 1) * 3;
+        positions[base] = x;
+        positions[base + 1] = sampleHeight(x, z) + elevation;
+        positions[base + 2] = z;
+    }
+    const indices = new Uint32Array(segments * 3);
+    for (let i = 0; i < segments; i += 1) {
+        indices[i * 3] = 0;
+        indices[i * 3 + 1] = i + 1;
+        indices[i * 3 + 2] = ((i + 1) % segments) + 1;
+    }
+    return { positions, indices };
+}
 /**
  * Split a centerline into dash sub-polylines for lane markings: `dashLength` of painted line,
  * `gapLength` of asphalt, repeated along the path's arc length. Feed each returned sub-path back
- * through {@link buildRoadRibbon} with a thin width to mesh the dashes.
+ * through {@link buildRoadRibbon} with a thin width to mesh the dashes. Pass `exclude` circles
+ * (junction patches) to interrupt the center line through intersections — any dash whose midpoint
+ * lands inside an exclusion is dropped.
  */
-export function dashSegments(path, dashLength = 3, gapLength = 3) {
+export function dashSegments(path, dashLength = 3, gapLength = 3, exclude = []) {
     if (path.length < 2 || dashLength <= 0 || gapLength < 0)
         return [];
     const cumulative = [0];
@@ -136,7 +172,28 @@ export function dashSegments(path, dashLength = 3, gapLength = 3) {
         const end = Math.min(total, start + dashLength);
         if (end - start < 1e-6)
             break;
-        dashes.push([pointAt(start), pointAt(end)]);
+        const a = pointAt(start);
+        const b = pointAt(end);
+        if (exclude.length > 0) {
+            const mx = (a[0] + b[0]) / 2;
+            const mz = (a[1] + b[1]) / 2;
+            let excluded = false;
+            for (let e = 0; e < exclude.length; e += 1) {
+                const zone = exclude[e];
+                const dx = mx - zone.center[0];
+                const dz = mz - zone.center[1];
+                if (dx * dx + dz * dz <= zone.radius * zone.radius) {
+                    excluded = true;
+                    break;
+                }
+            }
+            if (excluded) {
+                if (period <= 0)
+                    break;
+                continue;
+            }
+        }
+        dashes.push([a, b]);
         if (period <= 0)
             break;
     }