@jgengine/core 0.10.0 → 0.12.0

package/dist/scene/assetGenerator.js

@@ -0,0 +1,64 @@
+/**
+ * The generator-asset seam: register a parametric asset generator (`generate(params, seed) → parts`)
+ * so a slider-driven prop (a bookcase with width/shelves/book-density, a building with floors/bays)
+ * lives in the catalog alongside static GLBs. A placed instance stores only `{ assetId, params, seed }`
+ * — the geometry is re-resolved at runtime, never baked. Schema drives the inspector via #809. The
+ * generic seam is engine; concrete generators (building, bookcase) are adopters registered from
+ * game/example code — the building generator is the one engine adopter, as a proof it composes.
+ *
+ * @capability asset-generator seeded parametric geometry registered as a placeable asset
+ */
+import { parseParams } from "./sceneKinds.js";
+const generators = new Map();
+/** Register a parametric asset generator. Idempotent per id (last wins); call at module load. */
+export function registerAssetGenerator(definition) {
+    generators.set(definition.id, definition);
+}
+/** The registered generator for an id, or undefined. @internal */
+export function getAssetGenerator(id) {
+    return generators.get(id);
+}
+/** Every registered generator, in registration order. @internal */
+export function listAssetGenerators() {
+    return [...generators.values()];
+}
+/**
+ * Compute bounds from parts (each part is an axis-aligned box at its center) — a helper generators
+ * return so callers can frame/ground the asset without re-deriving it.
+ */
+export function partsBounds(parts) {
+    if (parts.length === 0)
+        return { min: [0, 0, 0], max: [0, 0, 0] };
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (const part of parts) {
+        minX = Math.min(minX, part.position[0] - part.size[0] / 2);
+        minY = Math.min(minY, part.position[1] - part.size[1] / 2);
+        minZ = Math.min(minZ, part.position[2] - part.size[2] / 2);
+        maxX = Math.max(maxX, part.position[0] + part.size[0] / 2);
+        maxY = Math.max(maxY, part.position[1] + part.size[1] / 2);
+        maxZ = Math.max(maxZ, part.position[2] + part.size[2] / 2);
+    }
+    return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}
+/**
+ * Re-resolve a placed generator instance from its stored `meta` (`{ assetId, seed, ...params }`): look
+ * up the generator, parse its params off `meta` against the schema, and generate. Returns null when
+ * `assetId` names no registered generator. This is what a runtime renderer calls per placed instance.
+ * @internal
+ */
+export function resolveGeneratorAsset(meta) {
+    const assetId = typeof meta?.["assetId"] === "string" ? meta["assetId"] : undefined;
+    if (assetId === undefined)
+        return null;
+    const generator = generators.get(assetId);
+    if (generator === undefined)
+        return null;
+    const seed = typeof meta?.["seed"] === "string" ? meta["seed"] : assetId;
+    const params = parseParams(generator.schema, meta);
+    return generator.generate(params, seed);
+}

package/dist/scene/assetSpace.d.ts

@@ -0,0 +1,137 @@
+import type { Aabb, Footprint, Vec2 } from "../world/geometry.js";
+/**
+ * Wrap `degrees` into `[0, 360)` — the canonical heading range every policy and conversion here works
+ * in. Non-finite input collapses to `0` so bad metadata never leaks a `NaN` heading downstream.
+ * @capability asset-heading normalize a placement heading into the engine's degree convention
+ */
+export declare function normalizeDegrees(degrees: number): number;
+/**
+ * Convert a compass heading (degrees, `0` = engine north, increasing clockwise) into the Three.js
+ * Y-rotation (radians, wrapped to `(-PI, PI]`) a renderer applies. Sign matches
+ * `world/placementController.quarterTurnsToRotationY`, so heading `90` equals one clockwise quarter
+ * turn. This is the one place degrees cross into the private radian space Three.js requires.
+ * @capability asset-heading turn a north-relative degree heading into a Three.js Y-rotation
+ */
+export declare function headingToRotationY(headingDegrees: number): number;
+/**
+ * Inverse of {@link headingToRotationY}: recover the `[0, 360)` compass heading from a Three.js
+ * Y-rotation. Lets a gizmo or inspector present radians as the degrees authors edit.
+ * @capability asset-heading read a Three.js Y-rotation back as a north-relative degree heading
+ */
+export declare function rotationYToHeading(rotationY: number): number;
+/** Bridge the legacy 0–3 quarter-turn placement model onto degrees (each turn is 90 degrees clockwise). @internal */
+export declare function quarterTurnsToHeading(quarterTurns: number): number;
+/**
+ * A per-asset/per-tool rotation constraint, authored as data instead of hardcoded in build code:
+ * `locked` pins every placement to one heading, `snap` quantizes to an increment (15, 45, …), and
+ * `free` allows any heading. Serializable — this is the shape stored on a catalog entry or a tool.
+ */
+export type PlacementRotationPolicy = {
+    readonly mode: "locked";
+    readonly degrees?: number;
+} | {
+    readonly mode: "snap";
+    readonly snapDegrees: number;
+} | {
+    readonly mode: "free";
+};
+/**
+ * Quantize `degrees` to the nearest multiple of `increment` (both in the `[0, 360)` convention). A
+ * non-positive increment is treated as free rotation and only normalizes. The math behind a
+ * `snap`-mode {@link PlacementRotationPolicy}.
+ * @capability placement-rotation snap a heading to a fixed degree increment
+ */
+export declare function snapHeading(degrees: number, increment: number): number;
+/**
+ * Resolve a raw drag/scroll heading through a {@link PlacementRotationPolicy} into the heading a
+ * placement should actually commit: `locked` ignores the input for its fixed heading, `snap` quantizes,
+ * `free` (or an absent policy) normalizes. Deterministic — the single interpreter preview, editor
+ * placement, and runtime spawning share instead of each re-implementing the modes.
+ * @capability placement-rotation apply a rotation policy to a candidate placement heading
+ */
+export declare function applyRotationPolicy(degrees: number, policy: PlacementRotationPolicy | undefined): number;
+/**
+ * Where a model's pivot sits within its footprint: `center` (origin at the footprint center),
+ * `corner` (origin at the min-X/min-Z corner), or a normalized `{ x, z }` fraction in `[-0.5, 0.5]`.
+ */
+export type AssetAnchor = "center" | "corner" | {
+    readonly x: number;
+    readonly z: number;
+};
+/**
+ * Catalog-level asset-space metadata: how a model is authored relative to the engine, owned by the
+ * catalog entry rather than re-derived per game. Every field is optional so an unmeasured asset stays
+ * valid; {@link resolveFacingRotationY}/{@link assetUnitScale}/{@link resolveAnchorOffset} supply the
+ * documented defaults.
+ */
+export interface AssetSpace {
+    /** Compass heading (degrees, `0` = north) the model's front visually points at `rotationY = 0`. Default `0`. */
+    forwardDegrees?: number;
+    /** Multiply source-space lengths by this to reach engine meters (a kit's native tile size correction). Default `1`. */
+    unitScale?: number;
+    /** Authored footprint in engine meters — the grid/placement extent, independent of the raw mesh bounds. */
+    footprint?: Footprint;
+    /** Authored grid cell size in engine meters this asset snaps to. */
+    gridSize?: number;
+    /** Where the model origin sits within {@link footprint}. Default `center`. */
+    anchor?: AssetAnchor;
+    /** Optional asset-local placement bounds (XZ) a tool clamps a drop position into. */
+    bounds?: Aabb;
+    /** Default rotation constraint when this asset is placed. Absent means free rotation. */
+    rotation?: PlacementRotationPolicy;
+}
+/**
+ * The Three.js Y-rotation that makes a model whose front is authored at `forwardDegrees` visually point
+ * `headingDegrees` (engine north = `0`). This is the catalog-owned replacement for per-game corrective
+ * yaw: a model authored facing south (`forwardDegrees: 180`) placed toward north resolves to `Math.PI`.
+ * @capability asset-facing resolve a placement heading into a Three.js Y-rotation using canonical forward
+ */
+export declare function resolveFacingRotationY(headingDegrees: number, space?: Pick<AssetSpace, "forwardDegrees">): number;
+/** The effective, guarded unit scale for an asset — a finite positive `unitScale`, else `1`. @internal */
+export declare function assetUnitScale(space?: Pick<AssetSpace, "unitScale">): number;
+/**
+ * Convert a source-space length to engine meters through the asset's {@link AssetSpace.unitScale} — the
+ * data-owned replacement for per-game scale constants (a native ~4-unit kit tile down to a 1-unit grid).
+ * @capability asset-units convert a source-space length to engine meters via catalog unit scale
+ */
+export declare function toEngineUnits(sourceValue: number, space?: Pick<AssetSpace, "unitScale">): number;
+/**
+ * The pivot's offset from the footprint center, in engine meters, implied by {@link AssetSpace.anchor}
+ * and {@link AssetSpace.footprint}. `center` yields `[0, 0]`; `corner` yields the min corner; a
+ * normalized `{ x, z }` scales by the footprint. Subtract it to seat a footprint centered on a point.
+ * @capability asset-anchor resolve a model's pivot offset from its footprint center
+ */
+export declare function resolveAnchorOffset(space?: Pick<AssetSpace, "anchor" | "footprint">): Vec2;
+/**
+ * The axis-aligned footprint extent after rotating a rectangular {@link Footprint} by `headingDegrees`
+ * — footprint-aware placement: a 90-degree turn swaps width/depth, and arbitrary headings grow the
+ * bounding box so overlap and snap checks see the space the rotated asset truly occupies.
+ * @capability asset-footprint rotate a rectangular footprint into its axis-aligned extent
+ */
+export declare function rotatedFootprint(footprint: Footprint, headingDegrees: number): Footprint;
+/** One problem found by {@link validateAssetSpace}: which metadata field and why it is invalid. */
+export interface AssetSpaceIssue {
+    field: string;
+    message: string;
+}
+/**
+ * Report contradictory or malformed asset-space metadata so catalog generation can reject it before it
+ * reaches a tool: non-finite headings, non-positive scales/sizes, inverted bounds, unknown anchors, and
+ * ill-formed rotation policies (a `snap` with a non-positive increment, an unknown `mode`). An empty
+ * array means valid. Validation lives here so tools consume resolved metadata instead of reinterpreting.
+ * @capability asset-space validate catalog asset-space metadata during index generation
+ */
+export declare function validateAssetSpace(raw: unknown): AssetSpaceIssue[];
+/**
+ * Parse an untrusted rotation policy (from a scene document or catalog JSON) into a valid
+ * {@link PlacementRotationPolicy}, defaulting to `free` when absent or malformed. The lenient companion
+ * to {@link validateAssetSpace} for the read path.
+ * @capability placement-rotation parse a serialized rotation policy, defaulting to free
+ */
+export declare function parseRotationPolicy(raw: unknown): PlacementRotationPolicy;
+/**
+ * Parse untrusted JSON into an {@link AssetSpace}, dropping malformed fields, or `undefined` when
+ * nothing valid remains — the round-trippable read path for serialized catalog/scene metadata.
+ * @capability asset-space parse serialized asset-space metadata into a validated shape
+ */
+export declare function parseAssetSpace(raw: unknown): AssetSpace | undefined;

package/dist/scene/assetSpace.js

@@ -0,0 +1,257 @@
+import { clamp } from "../math/scalar.js";
+/**
+ * Asset-space metadata + placement rotation policy: the catalog-owned description of how a model sits
+ * in its source space and how a placement tool may rotate it. Games author scenes against engine north
+ * (heading `0` degrees, increasing clockwise) instead of transplanting per-game yaw offsets and magic
+ * scales; the catalog entry ({@link "scene/assetCatalog".ModelAssetRef}) is the upstream owner of the
+ * correction. Public APIs speak degrees; the only radians here are the private Three.js Y-rotation this
+ * module converts to, matching `world/placementController`'s `quarterTurnsToRotationY` sign so a
+ * quarter turn still equals 90 degrees clockwise. Pure and serializable — no three.js, no allocation of
+ * shared state — so preview, placement, and runtime spawning share one interpretation.
+ */
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+const FULL_TURN = 360;
+/**
+ * Wrap `degrees` into `[0, 360)` — the canonical heading range every policy and conversion here works
+ * in. Non-finite input collapses to `0` so bad metadata never leaks a `NaN` heading downstream.
+ * @capability asset-heading normalize a placement heading into the engine's degree convention
+ */
+export function normalizeDegrees(degrees) {
+    if (!Number.isFinite(degrees))
+        return 0;
+    const wrapped = degrees % FULL_TURN;
+    return wrapped < 0 ? wrapped + FULL_TURN : wrapped;
+}
+function wrapRadians(radians) {
+    let r = radians % (2 * Math.PI);
+    if (r <= -Math.PI)
+        r += 2 * Math.PI;
+    if (r > Math.PI)
+        r -= 2 * Math.PI;
+    return r + 0; // normalize -0 to 0
+}
+/**
+ * Convert a compass heading (degrees, `0` = engine north, increasing clockwise) into the Three.js
+ * Y-rotation (radians, wrapped to `(-PI, PI]`) a renderer applies. Sign matches
+ * `world/placementController.quarterTurnsToRotationY`, so heading `90` equals one clockwise quarter
+ * turn. This is the one place degrees cross into the private radian space Three.js requires.
+ * @capability asset-heading turn a north-relative degree heading into a Three.js Y-rotation
+ */
+export function headingToRotationY(headingDegrees) {
+    return wrapRadians(-normalizeDegrees(headingDegrees) * DEG2RAD);
+}
+/**
+ * Inverse of {@link headingToRotationY}: recover the `[0, 360)` compass heading from a Three.js
+ * Y-rotation. Lets a gizmo or inspector present radians as the degrees authors edit.
+ * @capability asset-heading read a Three.js Y-rotation back as a north-relative degree heading
+ */
+export function rotationYToHeading(rotationY) {
+    return normalizeDegrees(-rotationY * RAD2DEG);
+}
+/** Bridge the legacy 0–3 quarter-turn placement model onto degrees (each turn is 90 degrees clockwise). @internal */
+export function quarterTurnsToHeading(quarterTurns) {
+    return normalizeDegrees(Math.round(quarterTurns) * 90);
+}
+/**
+ * Quantize `degrees` to the nearest multiple of `increment` (both in the `[0, 360)` convention). A
+ * non-positive increment is treated as free rotation and only normalizes. The math behind a
+ * `snap`-mode {@link PlacementRotationPolicy}.
+ * @capability placement-rotation snap a heading to a fixed degree increment
+ */
+export function snapHeading(degrees, increment) {
+    if (!(increment > 0))
+        return normalizeDegrees(degrees);
+    return normalizeDegrees(Math.round(normalizeDegrees(degrees) / increment) * increment);
+}
+/**
+ * Resolve a raw drag/scroll heading through a {@link PlacementRotationPolicy} into the heading a
+ * placement should actually commit: `locked` ignores the input for its fixed heading, `snap` quantizes,
+ * `free` (or an absent policy) normalizes. Deterministic — the single interpreter preview, editor
+ * placement, and runtime spawning share instead of each re-implementing the modes.
+ * @capability placement-rotation apply a rotation policy to a candidate placement heading
+ */
+export function applyRotationPolicy(degrees, policy) {
+    if (policy === undefined || policy.mode === "free")
+        return normalizeDegrees(degrees);
+    if (policy.mode === "locked")
+        return normalizeDegrees(policy.degrees ?? 0);
+    return snapHeading(degrees, policy.snapDegrees);
+}
+/**
+ * The Three.js Y-rotation that makes a model whose front is authored at `forwardDegrees` visually point
+ * `headingDegrees` (engine north = `0`). This is the catalog-owned replacement for per-game corrective
+ * yaw: a model authored facing south (`forwardDegrees: 180`) placed toward north resolves to `Math.PI`.
+ * @capability asset-facing resolve a placement heading into a Three.js Y-rotation using canonical forward
+ */
+export function resolveFacingRotationY(headingDegrees, space) {
+    return headingToRotationY(headingDegrees - (space?.forwardDegrees ?? 0));
+}
+/** The effective, guarded unit scale for an asset — a finite positive `unitScale`, else `1`. @internal */
+export function assetUnitScale(space) {
+    const s = space?.unitScale;
+    return typeof s === "number" && Number.isFinite(s) && s > 0 ? s : 1;
+}
+/**
+ * Convert a source-space length to engine meters through the asset's {@link AssetSpace.unitScale} — the
+ * data-owned replacement for per-game scale constants (a native ~4-unit kit tile down to a 1-unit grid).
+ * @capability asset-units convert a source-space length to engine meters via catalog unit scale
+ */
+export function toEngineUnits(sourceValue, space) {
+    return sourceValue * assetUnitScale(space);
+}
+/**
+ * The pivot's offset from the footprint center, in engine meters, implied by {@link AssetSpace.anchor}
+ * and {@link AssetSpace.footprint}. `center` yields `[0, 0]`; `corner` yields the min corner; a
+ * normalized `{ x, z }` scales by the footprint. Subtract it to seat a footprint centered on a point.
+ * @capability asset-anchor resolve a model's pivot offset from its footprint center
+ */
+export function resolveAnchorOffset(space) {
+    const w = space?.footprint?.w ?? 0;
+    const d = space?.footprint?.d ?? 0;
+    const anchor = space?.anchor ?? "center";
+    let fx = 0;
+    let fz = 0;
+    if (anchor === "corner") {
+        fx = -0.5;
+        fz = -0.5;
+    }
+    else if (typeof anchor === "object") {
+        fx = clamp(anchor.x, -0.5, 0.5);
+        fz = clamp(anchor.z, -0.5, 0.5);
+    }
+    return [fx * w, fz * d];
+}
+/**
+ * The axis-aligned footprint extent after rotating a rectangular {@link Footprint} by `headingDegrees`
+ * — footprint-aware placement: a 90-degree turn swaps width/depth, and arbitrary headings grow the
+ * bounding box so overlap and snap checks see the space the rotated asset truly occupies.
+ * @capability asset-footprint rotate a rectangular footprint into its axis-aligned extent
+ */
+export function rotatedFootprint(footprint, headingDegrees) {
+    const rad = normalizeDegrees(headingDegrees) * DEG2RAD;
+    const cos = Math.abs(Math.cos(rad));
+    const sin = Math.abs(Math.sin(rad));
+    return {
+        w: footprint.w * cos + footprint.d * sin,
+        d: footprint.w * sin + footprint.d * cos,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function finitePositive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function validateRotationPolicy(raw) {
+    if (!isRecord(raw))
+        return [{ field: "mode", message: "expected an object" }];
+    if (raw.mode === "free")
+        return [];
+    if (raw.mode === "locked") {
+        return raw.degrees !== undefined && (typeof raw.degrees !== "number" || !Number.isFinite(raw.degrees))
+            ? [{ field: "degrees", message: "expected a finite number" }]
+            : [];
+    }
+    if (raw.mode === "snap") {
+        return finitePositive(raw.snapDegrees) ? [] : [{ field: "snapDegrees", message: "expected a positive number" }];
+    }
+    return [{ field: "mode", message: "expected 'locked', 'snap', or 'free'" }];
+}
+/**
+ * Report contradictory or malformed asset-space metadata so catalog generation can reject it before it
+ * reaches a tool: non-finite headings, non-positive scales/sizes, inverted bounds, unknown anchors, and
+ * ill-formed rotation policies (a `snap` with a non-positive increment, an unknown `mode`). An empty
+ * array means valid. Validation lives here so tools consume resolved metadata instead of reinterpreting.
+ * @capability asset-space validate catalog asset-space metadata during index generation
+ */
+export function validateAssetSpace(raw) {
+    const issues = [];
+    if (!isRecord(raw)) {
+        issues.push({ field: "", message: "expected an object" });
+        return issues;
+    }
+    if (raw.forwardDegrees !== undefined && (typeof raw.forwardDegrees !== "number" || !Number.isFinite(raw.forwardDegrees))) {
+        issues.push({ field: "forwardDegrees", message: "expected a finite number" });
+    }
+    if (raw.unitScale !== undefined && !finitePositive(raw.unitScale)) {
+        issues.push({ field: "unitScale", message: "expected a positive number" });
+    }
+    if (raw.gridSize !== undefined && !finitePositive(raw.gridSize)) {
+        issues.push({ field: "gridSize", message: "expected a positive number" });
+    }
+    if (raw.footprint !== undefined) {
+        const fp = raw.footprint;
+        if (!isRecord(fp) || !finitePositive(fp.w) || !finitePositive(fp.d)) {
+            issues.push({ field: "footprint", message: "expected { w > 0, d > 0 }" });
+        }
+    }
+    if (raw.anchor !== undefined) {
+        const a = raw.anchor;
+        const named = a === "center" || a === "corner";
+        const explicit = isRecord(a) && typeof a.x === "number" && typeof a.z === "number";
+        if (!named && !explicit)
+            issues.push({ field: "anchor", message: "expected 'center', 'corner', or { x, z }" });
+    }
+    if (raw.bounds !== undefined) {
+        const b = raw.bounds;
+        if (!isRecord(b) || typeof b.minX !== "number" || typeof b.maxX !== "number" || typeof b.minZ !== "number" || typeof b.maxZ !== "number") {
+            issues.push({ field: "bounds", message: "expected an Aabb" });
+        }
+        else if (b.maxX < b.minX || b.maxZ < b.minZ) {
+            issues.push({ field: "bounds", message: "max must be >= min" });
+        }
+    }
+    if (raw.rotation !== undefined) {
+        issues.push(...validateRotationPolicy(raw.rotation).map((m) => ({ field: `rotation.${m.field}`, message: m.message })));
+    }
+    return issues;
+}
+/**
+ * Parse an untrusted rotation policy (from a scene document or catalog JSON) into a valid
+ * {@link PlacementRotationPolicy}, defaulting to `free` when absent or malformed. The lenient companion
+ * to {@link validateAssetSpace} for the read path.
+ * @capability placement-rotation parse a serialized rotation policy, defaulting to free
+ */
+export function parseRotationPolicy(raw) {
+    if (isRecord(raw)) {
+        if (raw.mode === "locked") {
+            return typeof raw.degrees === "number" && Number.isFinite(raw.degrees)
+                ? { mode: "locked", degrees: normalizeDegrees(raw.degrees) }
+                : { mode: "locked" };
+        }
+        if (raw.mode === "snap" && finitePositive(raw.snapDegrees))
+            return { mode: "snap", snapDegrees: raw.snapDegrees };
+    }
+    return { mode: "free" };
+}
+/**
+ * Parse untrusted JSON into an {@link AssetSpace}, dropping malformed fields, or `undefined` when
+ * nothing valid remains — the round-trippable read path for serialized catalog/scene metadata.
+ * @capability asset-space parse serialized asset-space metadata into a validated shape
+ */
+export function parseAssetSpace(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const out = {};
+    if (typeof raw.forwardDegrees === "number" && Number.isFinite(raw.forwardDegrees))
+        out.forwardDegrees = normalizeDegrees(raw.forwardDegrees);
+    if (finitePositive(raw.unitScale))
+        out.unitScale = raw.unitScale;
+    if (finitePositive(raw.gridSize))
+        out.gridSize = raw.gridSize;
+    if (isRecord(raw.footprint) && finitePositive(raw.footprint.w) && finitePositive(raw.footprint.d)) {
+        out.footprint = { w: raw.footprint.w, d: raw.footprint.d };
+    }
+    if (raw.anchor === "center" || raw.anchor === "corner")
+        out.anchor = raw.anchor;
+    else if (isRecord(raw.anchor) && typeof raw.anchor.x === "number" && typeof raw.anchor.z === "number") {
+        out.anchor = { x: raw.anchor.x, z: raw.anchor.z };
+    }
+    if (isRecord(raw.bounds) && typeof raw.bounds.minX === "number" && typeof raw.bounds.maxX === "number" && typeof raw.bounds.minZ === "number" && typeof raw.bounds.maxZ === "number") {
+        out.bounds = { minX: raw.bounds.minX, maxX: raw.bounds.maxX, minZ: raw.bounds.minZ, maxZ: raw.bounds.maxZ };
+    }
+    if (isRecord(raw.rotation))
+        out.rotation = parseRotationPolicy(raw.rotation);
+    return Object.keys(out).length === 0 ? undefined : out;
+}