@jgengine/core 0.9.0 → 0.11.0

package/dist/world/authoredObjects.js

@@ -0,0 +1,69 @@
+function metaString(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function metaNumber(meta, key) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Catalog id for a marker: first-class `catalogId` field, else `meta.catalogId` migration alias.
+ * Returns null when the marker is not an authored catalog prop (spawn, mob, generator, …).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function markerCatalogId(marker) {
+    if (typeof marker.catalogId === "string" && marker.catalogId.length > 0)
+        return marker.catalogId;
+    return metaString(marker.meta, "catalogId");
+}
+function markerVerticalOffset(marker) {
+    const fromMeta = metaNumber(marker.meta, "verticalOffset") ??
+        metaNumber(marker.meta, "offsetY") ??
+        metaNumber(marker.meta, "yOffset");
+    return fromMeta ?? 0;
+}
+/**
+ * Every marker carrying a catalog id, as placeable props — pure, no terrain sample. Parallel to
+ * {@link resolveScatter}: games and headless tests read the same list `<AuthoredObjects>` places.
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function resolveAuthoredObjects(document) {
+    const out = [];
+    for (const marker of document.markers) {
+        const catalogId = markerCatalogId(marker);
+        if (catalogId === null)
+            continue;
+        out.push({
+            catalogId,
+            x: marker.position.x,
+            z: marker.position.z,
+            rotationY: marker.rotationY ?? 0,
+            instanceId: marker.id,
+            verticalOffset: markerVerticalOffset(marker),
+        });
+    }
+    return out;
+}
+/**
+ * Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus
+ * per-object and options vertical offsets. Returns the instance ids that were placed (or kept).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export function placeAuthoredObjects(store, objects, sampleHeight, options = {}) {
+    const lift = options.verticalOffset ?? 0;
+    const onExisting = options.onExisting;
+    const ids = [];
+    for (const object of objects) {
+        const y = sampleHeight(object.x, object.z) + object.verticalOffset + lift;
+        ids.push(store.place(object.catalogId, object.x, y, object.z, {
+            instanceId: object.instanceId,
+            rotation: object.rotationY,
+            ...(onExisting === undefined ? {} : { onExisting }),
+        }));
+    }
+    return ids;
+}
+/** Convenience: resolve a document then place every authored catalog prop. */
+export function placeAuthoredObjectsFromDocument(store, document, sampleHeight, options = {}) {
+    return placeAuthoredObjects(store, resolveAuthoredObjects(document), sampleHeight, options);
+}

package/dist/world/buildingGenerator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The building generator registered against the {@link registerAssetGenerator} seam — the one engine
+ * adopter, proving the seeded config→parts building generator ({@link generateBuilding}) drops into
+ * the parametric-asset catalog with a slider schema and nothing bespoke. Domain generators (bookcase,
+ * …) register the same way from example/game code.
+ *
+ * @capability building-generator seeded building as a placeable parametric asset
+ */
+import { type GeneratedAsset } from "../scene/assetGenerator.js";
+import type { ParamSchema, ParsedParams } from "../scene/sceneKinds.js";
+/** The generator id a catalog entry / placed marker references. */
+export declare const BUILDING_GENERATOR_ID = "building";
+/** The building generator's slider schema — drives the inspector via #809. */
+export declare const BUILDING_GENERATOR_SCHEMA: ParamSchema;
+/** Generate a building's parts from validated params + seed — the {@link registerAssetGenerator} hook. @internal */
+export declare function generateBuildingAsset(params: ParsedParams, seed: string): GeneratedAsset;
+/** Register the building generator asset. Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerBuildingGenerator(): void;

package/dist/world/buildingGenerator.js

@@ -0,0 +1,62 @@
+/**
+ * The building generator registered against the {@link registerAssetGenerator} seam — the one engine
+ * adopter, proving the seeded config→parts building generator ({@link generateBuilding}) drops into
+ * the parametric-asset catalog with a slider schema and nothing bespoke. Domain generators (bookcase,
+ * …) register the same way from example/game code.
+ *
+ * @capability building-generator seeded building as a placeable parametric asset
+ */
+import { registerAssetGenerator, partsBounds } from "../scene/assetGenerator.js";
+import { BUILDING_STYLE_PALETTES, DEFAULT_BUILDING_CONFIG, generateBuilding, resolveBuildingPalette } from "./buildings.js";
+/** The generator id a catalog entry / placed marker references. */
+export const BUILDING_GENERATOR_ID = "building";
+/** The building generator's slider schema — drives the inspector via #809. */
+export const BUILDING_GENERATOR_SCHEMA = {
+    fields: [
+        { type: "range", key: "floors", label: "floors", min: 1, max: 20, step: 1, default: DEFAULT_BUILDING_CONFIG.floors },
+        { type: "range", key: "baysWide", label: "bays wide", min: 1, max: 12, step: 1, default: DEFAULT_BUILDING_CONFIG.baysWide },
+        { type: "range", key: "baysDeep", label: "bays deep", min: 1, max: 12, step: 1, default: DEFAULT_BUILDING_CONFIG.baysDeep },
+        { type: "range", key: "bayWidth", label: "bay width", min: 1, max: 5, step: 0.1, default: DEFAULT_BUILDING_CONFIG.bayWidth, unit: "m" },
+        { type: "range", key: "floorHeight", label: "floor height", min: 2, max: 5, step: 0.1, default: DEFAULT_BUILDING_CONFIG.floorHeight, unit: "m" },
+        {
+            type: "select",
+            key: "style",
+            label: "style",
+            default: "generic",
+            options: Object.keys(BUILDING_STYLE_PALETTES).map((style) => ({ value: style })),
+        },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+/** Generate a building's parts from validated params + seed — the {@link registerAssetGenerator} hook. @internal */
+export function generateBuildingAsset(params, seed) {
+    const style = params["style"];
+    const palette = resolveBuildingPalette(style);
+    const building = generateBuilding({
+        seed,
+        center: [0, 0],
+        floors: params["floors"],
+        baysWide: params["baysWide"],
+        baysDeep: params["baysDeep"],
+        bayWidth: params["bayWidth"],
+        floorHeight: params["floorHeight"],
+    });
+    const parts = building.parts.map((part) => ({
+        id: part.id,
+        kind: part.kind,
+        position: part.position,
+        size: part.scale,
+        rotationY: part.rotationY,
+        color: palette[part.kind],
+    }));
+    return { parts, bounds: partsBounds(parts) };
+}
+/** Register the building generator asset. Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerBuildingGenerator() {
+    registerAssetGenerator({
+        id: BUILDING_GENERATOR_ID,
+        label: "Building",
+        schema: BUILDING_GENERATOR_SCHEMA,
+        generate: generateBuildingAsset,
+    });
+}

package/dist/world/buildings.d.ts

@@ -97,8 +97,13 @@ 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>;
+/** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
+/** @internal */
 export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
+/** @internal */
 export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
+/** @internal */
 export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];
+/** @internal */
 export declare function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[];

package/dist/world/buildings.js

@@ -176,6 +176,7 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
     const preset = BUILDING_STYLE_PALETTES[style];
     if (preset === undefined) {
@@ -228,6 +229,7 @@ function rangeInt(seed, key, min, max) {
     const hi = Math.max(min, max);
     return lo + Math.floor(hash01(seed, key) * (hi - lo + 1));
 }
+/** @internal */
 export function createBuildingConfig(input = {}) {
     return {
         id: input.id ?? DEFAULT_BUILDING_CONFIG.id,
@@ -406,6 +408,7 @@ function pushCorners(parts, config, width, depth) {
         parts.push(part(config, "corner", index < 2 ? "back" : "front", position, [config.facadeDepth * 1.35, height, config.facadeDepth * 1.35], `corner:${index}`, undefined, ["structure"]));
     });
 }
+/** @internal */
 export function generateBuilding(input = {}) {
     const config = createBuildingConfig(input);
     const width = config.baysWide * config.bayWidth;
@@ -429,6 +432,7 @@ export function generateBuilding(input = {}) {
         parts,
     };
 }
+/** @internal */
 export function createBuildingGrid(config) {
     const rows = positiveInt(config.rows, 1);
     const columns = positiveInt(config.columns, 1);
@@ -467,6 +471,7 @@ export function createBuildingGrid(config) {
     }
     return lots;
 }
+/** @internal */
 export function generateBuildingDistrict(config) {
     return createBuildingGrid(config).map((lot) => generateBuilding(lot.config));
 }

package/dist/world/catenary.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic sag/catenary curve → point string, ready to loft into a tube. Genre-agnostic — power lines,
+ * suspension-bridge cables, ziplines, ropes, hanging chains, festoon lights all hang the same way.
+ * `sagCurve` is a cheap quadratic-Bézier droop; `catenaryCurve` is the true cosh hyperbolic cable.
+ *
+ * @capability catenary sagging cable curve between two anchors
+ */
+export type { Vec3 } from "./geometry.js";
+import type { Vec3 } from "./geometry.js";
+/**
+ * Quadratic-Bézier sag between two anchors: the control point is pulled straight down so the mid-span
+ * lowest point droops by exactly `sag` meters below the chord. Cheap and stable; the go-to for cables
+ * where exact catenary physics don't matter. Returns `segments + 1` points.
+ */
+export declare function sagCurve(a: Vec3, b: Vec3, sag: number, segments: number): Vec3[];
+/**
+ * True hyperbolic catenary between two anchors — the shape a uniform cable actually takes under
+ * gravity. `slack` is the extra length beyond the straight-line distance, as a fraction (0.1 = 10%
+ * longer than taut); larger slack droops deeper. Falls back to {@link sagCurve} for a near-taut cable.
+ * Returns `segments + 1` points. Anchors may differ in height; the curve interpolates the chord.
+ */
+export declare function catenaryCurve(a: Vec3, b: Vec3, slack: number, segments: number): Vec3[];

package/dist/world/catenary.js

@@ -0,0 +1,69 @@
+/**
+ * Generic sag/catenary curve → point string, ready to loft into a tube. Genre-agnostic — power lines,
+ * suspension-bridge cables, ziplines, ropes, hanging chains, festoon lights all hang the same way.
+ * `sagCurve` is a cheap quadratic-Bézier droop; `catenaryCurve` is the true cosh hyperbolic cable.
+ *
+ * @capability catenary sagging cable curve between two anchors
+ */
+/**
+ * Quadratic-Bézier sag between two anchors: the control point is pulled straight down so the mid-span
+ * lowest point droops by exactly `sag` meters below the chord. Cheap and stable; the go-to for cables
+ * where exact catenary physics don't matter. Returns `segments + 1` points.
+ */
+export function sagCurve(a, b, sag, segments) {
+    const steps = Math.max(2, Math.round(segments));
+    const cx = (a[0] + b[0]) / 2;
+    const cy = (a[1] + b[1]) / 2 - 2 * sag;
+    const cz = (a[2] + b[2]) / 2;
+    const points = [];
+    for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const u = 1 - t;
+        const w0 = u * u;
+        const w1 = 2 * u * t;
+        const w2 = t * t;
+        points.push([w0 * a[0] + w1 * cx + w2 * b[0], w0 * a[1] + w1 * cy + w2 * b[1], w0 * a[2] + w1 * cz + w2 * b[2]]);
+    }
+    return points;
+}
+/**
+ * True hyperbolic catenary between two anchors — the shape a uniform cable actually takes under
+ * gravity. `slack` is the extra length beyond the straight-line distance, as a fraction (0.1 = 10%
+ * longer than taut); larger slack droops deeper. Falls back to {@link sagCurve} for a near-taut cable.
+ * Returns `segments + 1` points. Anchors may differ in height; the curve interpolates the chord.
+ */
+export function catenaryCurve(a, b, slack, segments) {
+    const steps = Math.max(2, Math.round(segments));
+    const dx = b[0] - a[0];
+    const dz = b[2] - a[2];
+    const horizontal = Math.hypot(dx, dz);
+    if (horizontal < 1e-4 || slack <= 0)
+        return sagCurve(a, b, Math.max(0, slack) * horizontal * 0.5, steps);
+    const length = horizontal * (1 + slack);
+    // Solve the catenary parameter `p` (= a in y=p·cosh(x/p)) for the required arc length via bisection.
+    const targetRatio = length / horizontal;
+    let lo = 1e-3;
+    let hi = 1e6;
+    for (let i = 0; i < 48; i += 1) {
+        const mid = (lo + hi) / 2;
+        const ratio = (2 * mid * Math.sinh(horizontal / (2 * mid))) / horizontal;
+        if (ratio > targetRatio)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const p = (lo + hi) / 2;
+    const edge = p * Math.cosh(horizontal / (2 * p));
+    const points = [];
+    for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const x = a[0] + dx * t;
+        const z = a[2] + dz * t;
+        // Local horizontal coordinate centered at mid-span → catenary drop below the chord (0 at ends).
+        const local = (t - 0.5) * horizontal;
+        const drop = p * Math.cosh(local / p) - edge;
+        const chordY = a[1] + (b[1] - a[1]) * t;
+        points.push([x, chordY + drop, z]);
+    }
+    return points;
+}

package/dist/world/environmentSummary.d.ts

@@ -1,5 +1,5 @@
 import { type BuildingPalette, type BuildingStyle, type GeneratedBuilding } from "./buildings.js";
-import type { BuildingEnvironmentDescriptor, EnvironmentWorldFeature, WorldBounds } from "./features.js";
+import type { BuildingEnvironmentDescriptor, EnvironmentArea, EnvironmentWorldFeature, WorldBounds } from "./features.js";
 import type { Aabb } from "./geometry.js";
 import { type TerrainPalette } from "./terrain.js";
 export declare function resolveStructureBuildings(descriptor: BuildingEnvironmentDescriptor): GeneratedBuilding[];
@@ -24,7 +24,7 @@ export interface StructureSummary {
     bounds: Aabb;
 }
 export interface VegetationSummary {
-    area: WorldBounds;
+    area: EnvironmentArea;
     density: number;
 }
 export interface WaterSummary {
@@ -33,8 +33,15 @@ export interface WaterSummary {
 }
 export interface WeatherSummary {
     kind: "rain" | "snow";
+    area: EnvironmentArea;
     density: number;
 }
+/** One road descriptor's resolved footprint: vertex count, width, and total centerline length. */
+export interface RoadSummary {
+    points: number;
+    width: number;
+    length: number;
+}
 export interface EnvironmentCounts {
     terrain: number;
     islands: number;
@@ -44,6 +51,7 @@ export interface EnvironmentCounts {
     vegetationFields: number;
     waterBodies: number;
     weatherSystems: number;
+    roads: number;
 }
 export interface IslandSummary extends TerrainSummary {
     origin: readonly [number, number];
@@ -55,6 +63,7 @@ export interface EnvironmentSummary {
     vegetation: readonly VegetationSummary[];
     water: readonly WaterSummary[];
     weather: readonly WeatherSummary[];
+    roads: readonly RoadSummary[];
     counts: EnvironmentCounts;
     isEmpty: boolean;
 }

package/dist/world/environmentSummary.js

@@ -1,4 +1,5 @@
 import { generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { pathLength } from "./roads.js";
 import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
 export function resolveStructureBuildings(descriptor) {
     const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
@@ -106,8 +107,14 @@ export function summarizeEnvironment(feature) {
     }));
     const weather = (feature.weather ?? []).map((entry) => ({
         kind: entry.kind,
+        area: entry.area,
         density: entry.density,
     }));
+    const roads = (feature.roads ?? []).map((entry) => ({
+        points: entry.path.length,
+        width: entry.width,
+        length: pathLength(entry.path),
+    }));
     const buildings = structures.reduce((sum, entry) => sum + entry.buildings, 0);
     const counts = {
         terrain: terrain === undefined ? 0 : 1,
@@ -118,13 +125,15 @@ export function summarizeEnvironment(feature) {
         vegetationFields: vegetation.length,
         waterBodies: water.length,
         weatherSystems: weather.length,
+        roads: roads.length,
     };
     const isEmpty = counts.terrain === 0 &&
         counts.islands === 0 &&
         buildings === 0 &&
         counts.vegetationFields === 0 &&
         counts.waterBodies === 0 &&
-        counts.weatherSystems === 0;
+        counts.weatherSystems === 0 &&
+        counts.roads === 0;
     return {
         ...(terrain === undefined ? {} : { terrain }),
         islands,
@@ -132,6 +141,7 @@ export function summarizeEnvironment(feature) {
         vegetation,
         water,
         weather,
+        roads,
         counts,
         isEmpty,
     };