@jgengine/core 0.10.0 → 0.11.0

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,259 @@
+/**
+ * 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;
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+/**
+ * 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;
+}

package/dist/scene/authoredTriggers.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Authored behavior triggers on editor volumes and markers — a small `on`/`action` meta vocabulary
+ * so "when player enters this volume, spawn wave 2" is scene data, not game code. Games declare
+ * actions (typed via ParamSchema); the editor inspector renders their fields; a pure runtime
+ * watches membership and dispatches to handlers.
+ */
+import type { SceneDocumentLike, SceneMarkerLike, SceneVolumeLike } from "../world/sceneShapes.js";
+import { type ParamSchema, type ParsedParams } from "./sceneKinds.js";
+/** Event edge that can fire an authored trigger. */
+export type TriggerEvent = "enter" | "exit" | "interact";
+/** Document collection a trigger source lives on. */
+export type TriggerSourceKind = "marker" | "volume";
+/** Reserved meta keys for the trigger vocabulary — action params use every other schema field. @internal */
+export declare const TRIGGER_ON_KEY = "on";
+/** @internal */
+export declare const TRIGGER_ACTION_KEY = "action";
+/** @internal */
+export declare const TRIGGER_RADIUS_KEY = "triggerRadius";
+/** @internal */
+export declare const TRIGGER_LIST_KEY = "triggers";
+/** Default proximity radius (m) for marker enter/exit/interact when neither triggerRadius nor radius is set. @internal */
+export declare const DEFAULT_TRIGGER_RADIUS = 2.5;
+/**
+ * A game-declared action the editor can assign to a volume/marker trigger. Schema drives the
+ * inspector params; `targets`/`events` optionally narrow where it appears.
+ */
+export interface TriggerActionDefinition {
+    id: string;
+    /** Human label for the inspector action dropdown. */
+    label: string;
+    /** Param surface for this action — fields land flat on the object's `meta` (alongside `on`/`action`). */
+    schema: ParamSchema;
+    /** Which document collections accept this action. Default both. */
+    targets?: readonly TriggerSourceKind[];
+    /** Which events this action accepts. Default all (`enter`/`exit`/`interact`). */
+    events?: readonly TriggerEvent[];
+}
+/** One resolved trigger binding from a document object. */
+export interface AuthoredTrigger {
+    sourceId: string;
+    sourceKind: TriggerSourceKind;
+    objectKind: string;
+    on: TriggerEvent;
+    action: string;
+    params: ParsedParams;
+    /** Proximity radius for marker sources; unused for volumes (shape owns containment). */
+    radius: number;
+}
+/** Fired when a watched actor trips an authored trigger edge. */
+export interface TriggerDispatchEvent {
+    on: TriggerEvent;
+    action: string;
+    sourceId: string;
+    sourceKind: TriggerSourceKind;
+    objectKind: string;
+    actorId: string;
+    params: ParsedParams;
+}
+/** Handler map keyed by action id — unknown actions are skipped unless `onDispatch` is set. */
+export type TriggerHandlers = Readonly<Record<string, (event: TriggerDispatchEvent) => void>>;
+/**
+ * Declare a game action the editor can assign to volume/marker triggers. Idempotent per `id`
+ * (last registration wins). Call at module load next to catalogs.
+ *
+ * @capability authored-triggers schema'd on/action vocabulary on volumes and markers with runtime dispatch
+ */
+export declare function registerTriggerAction(definition: TriggerActionDefinition): void;
+/** Registered definition for an action id, or undefined when the game never declared it. */
+export declare function getTriggerAction(id: string): TriggerActionDefinition | undefined;
+/** Every registered action, optionally filtered by target collection. */
+export declare function listTriggerActions(target?: TriggerSourceKind): TriggerActionDefinition[];
+/** Clears the action registry — tests only. @internal */
+export declare function clearTriggerActions(): void;
+/** Resolve the proximity radius for a marker trigger from meta. @internal */
+export declare function triggerRadiusOf(meta: Record<string, unknown> | undefined, fallback?: number): number;
+/**
+ * Read every valid `on`/`action` binding off a raw meta bag. Unknown events/actions are dropped;
+ * params are schema-parsed when the action is registered, else empty.
+ * @internal
+ */
+export declare function readTriggerSpecs(meta: Record<string, unknown> | undefined): readonly {
+    on: TriggerEvent;
+    action: string;
+    params: ParsedParams;
+}[];
+/**
+ * Collect every authored trigger on a document's markers and volumes. Pure — no runtime state.
+ * Action params use the live {@link registerTriggerAction} registry when present.
+ *
+ * @capability authored-triggers schema'd on/action vocabulary on volumes and markers with runtime dispatch
+ */
+export declare function collectAuthoredTriggers(document: SceneDocumentLike): AuthoredTrigger[];
+/**
+ * True when `point` is inside an editor volume (sphere / cylinder / box). Cylinder height defaults
+ * to diameter when omitted; sphere ignores y for the common ground-plane case only when the volume
+ * radius covers the full vertical span — here y is tested for sphere and box too.
+ */
+export declare function pointInVolume(volume: SceneVolumeLike, point: {
+    x: number;
+    y: number;
+    z: number;
+}): boolean;
+/** True when `point` is within `radius` of a marker's position (sphere for enter/exit/interact). @internal */
+export declare function pointNearMarker(marker: SceneMarkerLike, point: {
+    x: number;
+    y: number;
+    z: number;
+}, radius: number): boolean;
+/** @internal */
+export interface TriggerActor {
+    id: string;
+    position: readonly [number, number, number] | {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** @internal */
+export interface AuthoredTriggerStepInput {
+    actors: readonly TriggerActor[];
+    /** Actor ids that pressed interact this frame — fires `on: "interact"` sources in range. */
+    interact?: readonly string[];
+}
+/** Runtime handle that watches authored triggers against moving actors each tick. */
+export interface AuthoredTriggerRuntime {
+    /** Advance membership one tick; returns every edge fired and invokes handlers. */
+    step(input: {
+        actors: readonly {
+            id: string;
+            position: readonly [number, number, number] | {
+                x: number;
+                y: number;
+                z: number;
+            };
+        }[];
+        /** Actor ids that pressed interact this frame — fires `on: "interact"` sources in range. */
+        interact?: readonly string[];
+    }): readonly TriggerDispatchEvent[];
+    /** Drop membership so the next step re-fires enters for still-inside actors. */
+    reset(): void;
+    /** Snapshot of the triggers this runtime was built from. */
+    triggers(): readonly AuthoredTrigger[];
+}
+/**
+ * Build a runtime that watches a document's authored triggers against moving actors and dispatches
+ * to per-action handlers (and optional catch-all). Pure membership math; the game supplies actors
+ * each tick from its own player/entity poses.
+ *
+ * @capability authored-triggers schema'd on/action vocabulary on volumes and markers with runtime dispatch
+ */
+export declare function createAuthoredTriggerRuntime(options: {
+    document: SceneDocumentLike;
+    handlers?: TriggerHandlers;
+    /** Invoked for every dispatch after the matching handler (if any). */
+    onDispatch?: (event: TriggerDispatchEvent) => void;
+    /** Override the collected trigger list (tests / hot-reload). Default: {@link collectAuthoredTriggers}. */
+    triggers?: readonly AuthoredTrigger[];
+}): AuthoredTriggerRuntime;
+/**
+ * Build a meta patch that sets a single flat trigger (`on` + `action` + optional param fields) and
+ * clears a multi-trigger list if present. Used by the editor inspector.
+ * @internal
+ */
+export declare function triggerMetaPatch(on: TriggerEvent | "", action: string, params?: Record<string, unknown>): Record<string, unknown>;
+/** Read the single flat trigger (`on`/`action`) from meta for the inspector, ignoring non-empty multi-lists. @internal */
+export declare function readFlatTrigger(meta: Record<string, unknown> | undefined): {
+    on: TriggerEvent | "";
+    action: string;
+};