@jgengine/core 0.10.0 → 0.12.0

package/dist/world/pathTerrain.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Path-driven terrain modifiers: one authored centerline reshapes a heightfield across a corridor —
+ * flatten a roadbed, grade a constant-slope ramp, carve a river/trench, and hold retaining walls where
+ * the corridor cuts or fills into the surrounding ground. Genre-agnostic: roads, rails, rivers,
+ * trenches, runways, and accessibility ramps are all the same profile with different numbers, so no game
+ * hand-rolls its own flatten-mask generator. Pure XZ math over a polyline — deterministic, bounded
+ * (O(points) per sample), and serializable; it composes onto any height sampler and pairs with
+ * `resolveTerrainField` so the same authored path drives both the rendered mesh and player collision.
+ * @capability path-terrain flatten / grade / carve a heightfield from an authored path with retaining profiles
+ * @consumer packages/core/src/world/terrain.ts (resolveTerrainField), Games/the-robots roads
+ */
+import type { Vec2 } from "./geometry.js";
+/**
+ * Where a path corridor drives its centerline height:
+ * - `sample` — follow the base terrain under the centerline, so the corridor drapes level across its
+ *   width while still tracking the hills the path crosses (the natural policy for a road or trail).
+ * - `fixed` — hold one constant height for the whole corridor (a level causeway, runway, or dam crest).
+ * - `grade` — interpolate linearly from `start` to `end` height along the path's arc length, a
+ *   constant-slope ramp between two anchors (a switchback, a graded rail bed, an accessibility ramp).
+ */
+export type PathHeightPolicy = {
+    readonly kind: "sample";
+} | {
+    readonly kind: "fixed";
+    readonly height: number;
+} | {
+    readonly kind: "grade";
+    readonly start: number;
+    readonly end: number;
+};
+/**
+ * Retaining behavior for a path corridor's shoulders. A wall rises only where the corridor already cuts or
+ * fills into the surrounding ground by at least `threshold` — gentle stretches stay open — so a road
+ * through a canyon gets held banks while the same profile on flat ground does not. The wall fades in
+ * smoothly across `taper` above the threshold so it never steps on or off between adjacent samples.
+ */
+export interface PathRetaining {
+    /** Crest height raised above the corridor edge on both shoulders (canyon walls, road berms, levee banks). */
+    readonly wallHeight: number;
+    /** Minimum cut/fill (world units) between corridor and surrounding ground before a wall rises. Default 0 (wall the whole path). */
+    readonly threshold?: number;
+    /** Cut/fill band above `threshold` over which the wall fades from none to full height. Default equal to `threshold`. */
+    readonly taper?: number;
+}
+/**
+ * A serializable path-driven terrain modifier. The `points` centerline reshapes the heightfield across a
+ * corridor of `width`, feathering back to the surrounding ground across `shoulder`. `height` sets the
+ * centerline target (sample / fixed / grade); `depth` carves a channel below it (deepest at the
+ * centerline, easing to zero at the core edge — rivers and trenches); `retaining` raises walls where the
+ * cut/fill exceeds a threshold; `maxCut`/`maxFill` cap how far the ground may move from its base height.
+ * All fields are plain data (numbers, string enums, point arrays) so a profile round-trips through the
+ * scene document and evaluates identically at author time and runtime.
+ */
+export interface TerrainPathProfile {
+    /** Centerline vertices in world XZ; needs at least two points. Repeat the first point as the last for a closed loop. */
+    readonly points: readonly Vec2[];
+    /** Full corridor width; the reshaped core extends `width / 2` either side of the centerline. */
+    readonly width: number;
+    /** Blend-ring width outside the core where the corridor height smoothsteps back to the surrounding ground. Default `width * 0.5`. */
+    readonly shoulder?: number;
+    /** Centerline target-height policy. Default `{ kind: "sample" }` (drape level across the base terrain). */
+    readonly height?: PathHeightPolicy;
+    /** Carve depth below the target height, deepest at the centerline and easing to zero at the core edge (0 = flat corridor). Default 0. */
+    readonly depth?: number;
+    /** Never cut the ground more than this far below its base height. Omit for unlimited cut. */
+    readonly maxCut?: number;
+    /** Never fill the ground more than this far above its base height. Omit for unlimited fill. */
+    readonly maxFill?: number;
+    /** Raise retaining walls along the shoulders where the corridor cuts/fills into the surrounding ground. */
+    readonly retaining?: PathRetaining;
+}
+/**
+ * Wraps a height sampler so each authored `TerrainPathProfile` reshapes it. Profiles apply in list order
+ * (later profiles compose over earlier ones, so an intersection's last profile wins its core); each reads
+ * the running height as its surrounding ground and the original `base` for `sample` centerline heights.
+ * The returned sampler is pure and deterministic. Degenerate profiles (fewer than two points, non-positive
+ * width or length) are skipped; with no usable profile the original `base` is returned unchanged.
+ * @capability path-terrain compose flatten/grade/carve/retaining path profiles onto a height sampler
+ */
+export declare function withPathProfiles(base: (x: number, z: number) => number, profiles: readonly TerrainPathProfile[]): (x: number, z: number) => number;

package/dist/world/pathTerrain.js

@@ -0,0 +1,142 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function smoothstep01(t) {
+    const clamped = clamp01(t);
+    return clamped * clamped * (3 - 2 * clamped);
+}
+function buildCorridor(points) {
+    const cumulative = [0];
+    for (let i = 1; i < points.length; i += 1) {
+        const a = points[i - 1];
+        const b = points[i];
+        cumulative.push(cumulative[i - 1] + Math.hypot(b[0] - a[0], b[1] - a[1]));
+    }
+    return { points, cumulative, total: cumulative[cumulative.length - 1] ?? 0 };
+}
+/**
+ * Closest point on the corridor to `(x, z)`: unsigned lateral distance and arc-length position. Self-
+ * contained (each segment projects independently and the minimum lateral wins) so a vertex always reports
+ * a near-zero lateral, regardless of which side of the line the neighbours fall.
+ */
+function nearestOnCorridor(corridor, x, z) {
+    let bestLateral = Number.POSITIVE_INFINITY;
+    let bestAlong = 0;
+    let bestPoint = corridor.points[0] ?? [x, z];
+    for (let i = 1; i < corridor.points.length; i += 1) {
+        const a = corridor.points[i - 1];
+        const b = corridor.points[i];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const segLenSq = abx * abx + abz * abz;
+        const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / segLenSq));
+        const px = a[0] + abx * t;
+        const pz = a[1] + abz * t;
+        const lateral = Math.hypot(x - px, z - pz);
+        if (lateral < bestLateral) {
+            bestLateral = lateral;
+            bestAlong = corridor.cumulative[i - 1] + t * Math.sqrt(segLenSq);
+            bestPoint = [px, pz];
+        }
+    }
+    return { lateral: bestLateral, along: bestAlong, point: bestPoint };
+}
+function resolveProfile(profile) {
+    if (profile.points.length < 2 || profile.width <= 0)
+        return null;
+    const corridor = buildCorridor(profile.points.map((point) => [point[0], point[1]]));
+    if (corridor.total <= 0)
+        return null;
+    const shoulder = Math.max(0, profile.shoulder ?? profile.width * 0.5);
+    return {
+        corridor,
+        half: profile.width / 2,
+        shoulder,
+        reach: profile.width / 2 + shoulder,
+        height: profile.height ?? { kind: "sample" },
+        depth: Math.max(0, profile.depth ?? 0),
+        ...(profile.maxCut === undefined ? {} : { maxCut: Math.max(0, profile.maxCut) }),
+        ...(profile.maxFill === undefined ? {} : { maxFill: Math.max(0, profile.maxFill) }),
+        wallHeight: Math.max(0, profile.retaining?.wallHeight ?? 0),
+        threshold: Math.max(0, profile.retaining?.threshold ?? 0),
+        taper: Math.max(0, profile.retaining?.taper ?? profile.retaining?.threshold ?? 0),
+    };
+}
+/** Wall strength 0..1: full above `threshold + taper`, none below `threshold`, smooth between. */
+function wallStrength(profile, cutFill) {
+    if (profile.wallHeight <= 0)
+        return 0;
+    if (cutFill < profile.threshold)
+        return 0;
+    if (profile.taper <= 0)
+        return 1;
+    return smoothstep01((cutFill - profile.threshold) / profile.taper);
+}
+function clampCutFill(height, base, maxCut, maxFill) {
+    let out = height;
+    if (maxFill !== undefined && out > base + maxFill)
+        out = base + maxFill;
+    if (maxCut !== undefined && out < base - maxCut)
+        out = base - maxCut;
+    return out;
+}
+function centerlineTarget(profile, along, point, base) {
+    const policy = profile.height;
+    if (policy.kind === "fixed")
+        return policy.height;
+    if (policy.kind === "grade") {
+        const fraction = profile.corridor.total <= 0 ? 0 : clamp01(along / profile.corridor.total);
+        return policy.start + (policy.end - policy.start) * fraction;
+    }
+    return base(point[0], point[1]);
+}
+function applyProfileAt(profile, x, z, surrounding, base) {
+    const hit = nearestOnCorridor(profile.corridor, x, z);
+    const lateral = hit.lateral;
+    if (lateral > profile.reach)
+        return surrounding;
+    const target = clampCutFill(centerlineTarget(profile, hit.along, hit.point, base), surrounding, profile.maxCut, profile.maxFill);
+    // Inside the core: carve a channel below the target, deepest at the centerline, level at the edge.
+    if (lateral <= profile.half) {
+        const edgeT = profile.half <= 0 ? 0 : lateral / profile.half;
+        const carved = target - profile.depth * (1 - edgeT * edgeT);
+        return clampCutFill(carved, surrounding, profile.maxCut, profile.maxFill);
+    }
+    // Shoulder: feather the corridor edge (target) back to the surrounding ground, or hold a retaining wall.
+    const shoulderT = clamp01((lateral - profile.half) / profile.shoulder);
+    const feathered = lerp(target, surrounding, smoothstep01(shoulderT));
+    const strength = wallStrength(profile, Math.abs(target - surrounding));
+    if (strength <= 0)
+        return feathered;
+    const crest = target + profile.wallHeight;
+    const walled = shoulderT <= 0.5 ? lerp(target, crest, smoothstep01(shoulderT / 0.5)) : lerp(crest, surrounding, smoothstep01((shoulderT - 0.5) / 0.5));
+    return lerp(feathered, walled, strength);
+}
+/**
+ * Wraps a height sampler so each authored `TerrainPathProfile` reshapes it. Profiles apply in list order
+ * (later profiles compose over earlier ones, so an intersection's last profile wins its core); each reads
+ * the running height as its surrounding ground and the original `base` for `sample` centerline heights.
+ * The returned sampler is pure and deterministic. Degenerate profiles (fewer than two points, non-positive
+ * width or length) are skipped; with no usable profile the original `base` is returned unchanged.
+ * @capability path-terrain compose flatten/grade/carve/retaining path profiles onto a height sampler
+ */
+export function withPathProfiles(base, profiles) {
+    const resolved = [];
+    for (const profile of profiles) {
+        const prepared = resolveProfile(profile);
+        if (prepared !== null)
+            resolved.push(prepared);
+    }
+    if (resolved.length === 0)
+        return base;
+    return (x, z) => {
+        let height = base(x, z);
+        for (const profile of resolved) {
+            height = applyProfileAt(profile, x, z, height, base);
+        }
+        return height;
+    };
+}

package/dist/world/place.d.ts

@@ -0,0 +1,166 @@
+import type { PhysicsConfig } from "../game/defineGame.js";
+/**
+ * The place model: a world is the place you play in — substrate (ground) plus laws (physics,
+ * surface) — never a dressed diorama. Sky look, foliage scatter, props, and sculpt are content:
+ * they are authored in the editor (or by a content preset that writes into the scene document)
+ * and consumed through the authored-scene seams, not declared on the world.
+ *
+ * Hard rules the API enforces:
+ * - No `seed` anywhere in a world definition. Determinism comes from the runtime: the engine
+ *   derives generator/scatter seeds from the world `id` plus the save/run seed (see
+ *   {@link seedForPlace}), so the same place replays identically without the author owning RNG.
+ * - No sky, vegetation, or theme fields. A world with no authored sky renders the engine
+ *   default sky; "void"/"space" is content, not a world knob.
+ * - No genre or franchise presets. `generator` carries algorithm parameters only.
+ */
+/**
+ * Matter/feel laws of a place's ground that systems, physics, and audio read — restitution for a
+ * metal chamber the pieces ping off, stickiness for a slime pit, a soft felt mat. The same rule
+ * systems play on any surface; swapping the surface (plus content audio) changes the feel without
+ * forking the rules. This is place law, not a theme kit: visual/audio dressing stays in content.
+ */
+export interface SurfaceLaws {
+    /** Named matter of the ground ("metal", "slime", "felt", …) — a label systems and audio cues key off. */
+    matter?: string;
+    /** Sliding friction scalar, 0 (ice) … 1+ (grippy). Interpreted by movement/physics systems. */
+    friction?: number;
+    /** Bounce energy retention, 0 (dead stop) … 1 (perfect bounce). Interpreted by physics/board systems. */
+    restitution?: number;
+    /** Free-form serializable place-law traits game systems read (e.g. `{ stuckTurns: 1 }` for slime). */
+    traits?: Readonly<Record<string, number | string | boolean>>;
+}
+/** Serializable algorithm parameters for a procedural ground generator. Never a genre kit. */
+export interface GroundGenerator {
+    /** Algorithm identifier the game's generation system resolves (e.g. "fbm", "caves", "layers"). */
+    algorithm: string;
+    /**
+     * Algorithm tuning only — amplitudes, frequencies, thresholds, palettes of ids. Never a `seed`
+     * (the engine injects one from world id + save/run) and never a genre/franchise preset name.
+     */
+    params?: Readonly<Record<string, number | string | boolean>>;
+}
+/**
+ * Size of a `flat` ground: extents in world units. `Infinity` on an axis means unbounded — an
+ * endless plain needs no bounds number invented for it. `y` optionally bounds vertical play space.
+ */
+export interface FlatGroundSize {
+    x: number;
+    /** Optional vertical bound of the play volume; omit for open sky. */
+    y?: number;
+    z: number;
+    radius?: never;
+}
+/** Size of a `round` ground: the planet/sphere radius in world units. Nothing else. */
+export interface RoundGroundSize {
+    radius: number;
+    x?: never;
+    y?: never;
+    z?: never;
+}
+/** Size of a `voxel` ground: the generator's domain per axis; axes may be `Infinity` for streaming volumes. */
+export interface VoxelGroundSize {
+    x: number;
+    y: number;
+    z: number;
+    radius?: never;
+}
+/** Size of a `board` ground: a 2D surface you look at, in cells or layout units. */
+export interface BoardGroundSize {
+    x: number;
+    y: number;
+    z?: never;
+    radius?: never;
+}
+/** A 3D walkable plane/slab. `Infinity` axes are unbounded; no separate "infinite" mode exists. */
+export interface FlatGround {
+    mode: "flat";
+    size: FlatGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/** A planet/sphere you play on the outside of. Sized by `radius` only. */
+export interface RoundGround {
+    mode: "round";
+    size: RoundGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/** A procedural volume of blocks. `size` is the generator domain; `generator` is algorithm params only. */
+export interface VoxelGround {
+    mode: "voxel";
+    size: VoxelGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/**
+ * A 2D surface you look at — grid games, solitaire, tabletop. Physics is often zero-gravity or
+ * omitted; the game owns the face it draws on the board.
+ */
+export interface BoardGround {
+    /** `"stage"` is accepted as an alias and normalized to `"board"`. */
+    mode: "board" | "stage";
+    size: BoardGroundSize;
+    surface?: SurfaceLaws;
+}
+/** The substrate of a place, discriminated by `mode` — TS rejects a `radius` on `flat` and `x`/`z` on `round`. */
+export type GroundConfig = FlatGround | RoundGround | VoxelGround | BoardGround;
+/** Canonical ground modes after normalization (`stage` → `board`). */
+export type GroundMode = "flat" | "round" | "voxel" | "board";
+/** {@link BoardGround} with the `stage` alias resolved away. */
+export type ResolvedBoardGround = Omit<BoardGround, "mode"> & {
+    mode: "board";
+};
+/** A place's ground after `world()` normalization. */
+export type ResolvedGround = FlatGround | RoundGround | VoxelGround | ResolvedBoardGround;
+/** Input to {@link world}: place identity, substrate, and the laws of this place. */
+export interface PlaceConfig {
+    /** Place identity — names the world for saves, seeds, and world switching. */
+    id: string;
+    /** The substrate: what you stand on / look at, discriminated by `mode`. */
+    ground: GroundConfig;
+    /**
+     * Laws of THIS place (gravity, jump). Each world carries its own physics, so a game with several
+     * places (a station and a moon) gives each different laws; `defineGameDefinition` resolves the
+     * active world's physics over the game-level default. The engine owns simulation.
+     */
+    physics?: PhysicsConfig;
+}
+/** A declared place — the `world()` result carried on `GameDefinition.world`. */
+export interface PlaceWorldFeature {
+    kind: "place";
+    id: string;
+    ground: ResolvedGround;
+    physics?: PhysicsConfig;
+}
+/**
+ * Declares the place a game is played in: substrate (`ground`) + laws (`physics`, `ground.surface`).
+ * The thin default start — `flat` with `Infinity` axes and default physics, `board` for 2D — is a
+ * complete world; dressing it (sky, foliage, props, sculpt) is editor-authored scene content.
+ * Multiple worlds per game are first-class: declare one `world()` per place, each with its own id,
+ * ground, and physics. Games that are not a spatial place (pure UI/rules) omit `world` entirely.
+ *
+ * @capability world-place declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+ */
+export declare function world(config: PlaceConfig): PlaceWorldFeature;
+/**
+ * The engine-side seed derivation for a place: a stable string from the world `id` plus the
+ * save/run seed. Generators and scatter receive this — never a `seed` field in the world
+ * definition — so a save replays its world deterministically and a fresh run can vary by
+ * `runSeed` alone.
+ *
+ * @capability world-seed derive a deterministic generator/scatter seed from world id + save/run seed
+ */
+export declare function seedForPlace(worldId: string, runSeed?: string): string;
+/**
+ * Resolves the physics laws in effect for the active world: a place world's own `physics` wins
+ * field-by-field over the game-level default. Non-place worlds (and games with no world) keep the
+ * game-level config unchanged.
+ */
+export declare function resolveWorldPhysics(worldFeature: {
+    kind: string;
+    physics?: PhysicsConfig;
+} | undefined, base: PhysicsConfig | undefined): PhysicsConfig | undefined;
+/** Type guard for the place-model world feature. */
+export declare function isPlaceWorld(worldFeature: {
+    kind: string;
+} | undefined): worldFeature is PlaceWorldFeature;

package/dist/world/place.js

@@ -0,0 +1,96 @@
+const BANNED_WORLD_KEYS = ["sky", "vegetation", "terrain", "environment", "weather", "seed"];
+function assertNoDressing(config) {
+    const record = config;
+    for (const key of BANNED_WORLD_KEYS) {
+        if (record[key] !== undefined) {
+            throw new Error(key === "seed"
+                ? "world: seed does not belong in a world definition — the engine derives seeds from the world id and the save/run seed (seedForPlace)."
+                : `world: "${key}" does not belong in a world definition — a world is substrate + laws. Author sky, foliage, and dressing in the editor (or a content preset that writes scene data).`);
+        }
+    }
+}
+function assertAxis(mode, axis, value, allowInfinite) {
+    const ok = value > 0 && (allowInfinite ? true : Number.isFinite(value));
+    if (!ok) {
+        throw new Error(`world: ground.size.${axis} for mode "${mode}" must be a positive${allowInfinite ? "" : " finite"} number, got ${value}`);
+    }
+}
+function resolveGround(ground) {
+    if (ground["seed"] !== undefined) {
+        throw new Error("world: seed does not belong on ground — the engine injects seeds into generators (seedForPlace).");
+    }
+    if ("generator" in ground && ground.generator?.params !== undefined && "seed" in ground.generator.params) {
+        throw new Error("world: generator.params.seed is not allowed — the engine injects the seed from world id + save/run (seedForPlace).");
+    }
+    switch (ground.mode) {
+        case "flat": {
+            assertAxis("flat", "x", ground.size.x, true);
+            assertAxis("flat", "z", ground.size.z, true);
+            if (ground.size.y !== undefined)
+                assertAxis("flat", "y", ground.size.y, true);
+            return ground;
+        }
+        case "round": {
+            assertAxis("round", "radius", ground.size.radius, false);
+            return ground;
+        }
+        case "voxel": {
+            assertAxis("voxel", "x", ground.size.x, true);
+            assertAxis("voxel", "y", ground.size.y, true);
+            assertAxis("voxel", "z", ground.size.z, true);
+            return ground;
+        }
+        case "board":
+        case "stage": {
+            assertAxis("board", "x", ground.size.x, false);
+            assertAxis("board", "y", ground.size.y, false);
+            return ground.mode === "board" ? ground : { ...ground, mode: "board" };
+        }
+    }
+}
+/**
+ * Declares the place a game is played in: substrate (`ground`) + laws (`physics`, `ground.surface`).
+ * The thin default start — `flat` with `Infinity` axes and default physics, `board` for 2D — is a
+ * complete world; dressing it (sky, foliage, props, sculpt) is editor-authored scene content.
+ * Multiple worlds per game are first-class: declare one `world()` per place, each with its own id,
+ * ground, and physics. Games that are not a spatial place (pure UI/rules) omit `world` entirely.
+ *
+ * @capability world-place declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+ */
+export function world(config) {
+    if (config.id.trim().length === 0) {
+        throw new Error("world: id must be non-empty — it names the place for saves, seeds, and world switching");
+    }
+    assertNoDressing(config);
+    return {
+        kind: "place",
+        id: config.id,
+        ground: resolveGround(config.ground),
+        ...(config.physics === undefined ? {} : { physics: config.physics }),
+    };
+}
+/**
+ * The engine-side seed derivation for a place: a stable string from the world `id` plus the
+ * save/run seed. Generators and scatter receive this — never a `seed` field in the world
+ * definition — so a save replays its world deterministically and a fresh run can vary by
+ * `runSeed` alone.
+ *
+ * @capability world-seed derive a deterministic generator/scatter seed from world id + save/run seed
+ */
+export function seedForPlace(worldId, runSeed = "") {
+    return runSeed.length === 0 ? worldId : `${worldId}:${runSeed}`;
+}
+/**
+ * Resolves the physics laws in effect for the active world: a place world's own `physics` wins
+ * field-by-field over the game-level default. Non-place worlds (and games with no world) keep the
+ * game-level config unchanged.
+ */
+export function resolveWorldPhysics(worldFeature, base) {
+    if (worldFeature === undefined || worldFeature.kind !== "place" || worldFeature.physics === undefined)
+        return base;
+    return base === undefined ? worldFeature.physics : { ...base, ...worldFeature.physics };
+}
+/** Type guard for the place-model world feature. */
+export function isPlaceWorld(worldFeature) {
+    return worldFeature?.kind === "place";
+}

package/dist/world/placeAsset.d.ts

@@ -0,0 +1,81 @@
+import { type AssetSpace } from "../scene/assetSpace.js";
+import type { PlacementCommit } from "./placementController.js";
+import type { AddStructureInput, StructureVec3 } from "./placedStructureStore.js";
+/** World-space point shared by structure stores and editor markers. */
+export type PlaceAssetVec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Shared place-asset verb: one resolved payload for editor `place_asset` and in-game
+ * build-mode commits. Convert with {@link toStructureInput} / {@link toEditorMarker}.
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export interface PlaceAssetResult {
+    id: string;
+    assetId: string;
+    kind: string;
+    label: string;
+    position: PlaceAssetVec3;
+    rotationY: number;
+    color: string;
+    meta: Readonly<Record<string, unknown>>;
+}
+/** Inputs to {@link resolvePlaceAsset}: asset id, pose, and optional catalog/known fields. */
+export interface ResolvePlaceAssetInput {
+    assetId: string;
+    position: PlaceAssetVec3 | StructureVec3;
+    kind?: string;
+    label?: string;
+    rotationY?: number;
+    /**
+     * Placement heading in degrees (engine north = `0`, clockwise). When set it takes precedence over
+     * `rotationY`: the resolved `rotationY` runs through `space.rotation` (the asset's rotation policy)
+     * and `space.forwardDegrees` (canonical facing), so the catalog owns the correction instead of games.
+     */
+    headingDegrees?: number;
+    /** Asset-space metadata driving the heading resolution when `headingDegrees` is set. */
+    space?: AssetSpace;
+    id?: string;
+    color?: string;
+    meta?: Readonly<Record<string, unknown>>;
+    url?: string;
+    knownKind?: string;
+    knownLabel?: string;
+    knownUrl?: string;
+}
+/** Optional catalog/label overrides for {@link placeAssetFromCommit}. */
+export interface PlaceAssetFromCommitOptions {
+    kind?: string;
+    label?: string;
+    id?: string;
+    color?: string;
+    meta?: Readonly<Record<string, unknown>>;
+    url?: string;
+    knownKind?: string;
+    knownLabel?: string;
+    knownUrl?: string;
+}
+/**
+ * Resolve a place-asset intent into a shared payload (editor + games, one verb).
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export declare function resolvePlaceAsset(input: ResolvePlaceAssetInput): PlaceAssetResult;
+/**
+ * Bridge a {@link PlacementCommit} into the shared place-asset verb.
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export declare function placeAssetFromCommit(commit: PlacementCommit, assetId: string, options?: PlaceAssetFromCommitOptions): PlaceAssetResult;
+/** Game-state form: feed {@link createPlacedStructureStore}.add. */
+export declare function toStructureInput(result: PlaceAssetResult): AddStructureInput;
+/** Scene-document form: feed editor `addMarker` / `place_asset` path. */
+export declare function toEditorMarker(result: PlaceAssetResult): {
+    id: string;
+    kind: string;
+    position: PlaceAssetVec3;
+    rotationY: number;
+    label: string;
+    color: string;
+    meta: Record<string, unknown>;
+};

package/dist/world/placeAsset.js

@@ -0,0 +1,79 @@
+import { applyRotationPolicy, resolveFacingRotationY } from "../scene/assetSpace.js";
+function normalizePosition(position) {
+    if (typeof position.x === "number") {
+        const p = position;
+        return { x: p.x, y: p.y, z: p.z };
+    }
+    const t = position;
+    return { x: t[0], y: t[1], z: t[2] };
+}
+let placementSequence = 0;
+function placementId(assetId, explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    placementSequence += 1;
+    return `placed_${assetId}_${Date.now().toString(36)}_${placementSequence.toString(36)}`;
+}
+/**
+ * Resolve a place-asset intent into a shared payload (editor + games, one verb).
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export function resolvePlaceAsset(input) {
+    const position = normalizePosition(input.position);
+    const assetId = input.assetId;
+    const kind = input.kind ?? input.knownKind ?? "prop";
+    const label = input.label ?? input.knownLabel ?? assetId;
+    const url = input.url ?? input.knownUrl;
+    const meta = {
+        assetId,
+        ...(url === undefined ? {} : { url }),
+        ...(input.meta ?? {}),
+    };
+    const rotationY = input.headingDegrees === undefined
+        ? (input.rotationY ?? 0)
+        : resolveFacingRotationY(applyRotationPolicy(input.headingDegrees, input.space?.rotation), input.space);
+    return {
+        id: placementId(assetId, input.id),
+        assetId,
+        kind,
+        label,
+        position,
+        rotationY,
+        color: input.color ?? "#e2e8f0",
+        meta,
+    };
+}
+/**
+ * Bridge a {@link PlacementCommit} into the shared place-asset verb.
+ * @capability place-asset resolve a placement commit into a shared asset placement payload
+ */
+export function placeAssetFromCommit(commit, assetId, options = {}) {
+    return resolvePlaceAsset({
+        assetId,
+        position: [commit.center[0], commit.y, commit.center[1]],
+        rotationY: commit.rotationY,
+        ...options,
+    });
+}
+/** Game-state form: feed {@link createPlacedStructureStore}.add. */
+export function toStructureInput(result) {
+    return {
+        id: result.id,
+        catalogId: result.assetId,
+        position: [result.position.x, result.position.y, result.position.z],
+        rotationY: result.rotationY,
+        data: { ...result.meta, kind: result.kind, label: result.label, color: result.color },
+    };
+}
+/** Scene-document form: feed editor `addMarker` / `place_asset` path. */
+export function toEditorMarker(result) {
+    return {
+        id: result.id,
+        kind: result.kind,
+        position: result.position,
+        rotationY: result.rotationY,
+        label: result.label,
+        color: result.color,
+        meta: { ...result.meta },
+    };
+}

package/dist/world/placement.d.ts

@@ -26,5 +26,9 @@ export type PlacementResult = {
     obstacle: PlacementObstacle;
     index: number;
 };
+/**
+ * Footprint validity: bounds + obstacle overlap after optional grid snap.
+ * @capability placement-math grid/surface footprint validity for build mode
+ */
 export declare function validatePlacement(request: PlacementRequest, rules?: PlacementRules): PlacementResult;
 export declare function footprintObstacle(request: PlacementRequest, id?: string): PlacementObstacle;

package/dist/world/placement.js

@@ -1,4 +1,8 @@
 import { aabbContains, aabbOverlap, footprintAabb, snapToGrid, } from "./geometry.js";
+/**
+ * Footprint validity: bounds + obstacle overlap after optional grid snap.
+ * @capability placement-math grid/surface footprint validity for build mode
+ */
 export function validatePlacement(request, rules = {}) {
     const center = rules.snap === undefined ? request.center : snapToGrid(request.center, rules.snap);
     const aabb = footprintAabb(center, request.footprint, request.quarterTurns ?? 0);