@jgengine/core 0.11.0 → 0.12.0

package/dist/stats/spawnLevelStats.js

@@ -0,0 +1,140 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function normalizeLevel(level) {
+    const floored = Math.floor(level);
+    return floored < 1 ? 1 : floored;
+}
+/**
+ * Scatter `count` points one at a time across `statIds`, choosing each target uniformly from the
+ * injected rng. Mutates `into` in place; bounded by `count`. The rng draws the sole source of
+ * randomness, so an identical rng sequence reproduces an identical distribution.
+ */
+function distributePoints(statIds, count, rng, into) {
+    const n = statIds.length;
+    if (n === 0 || count <= 0)
+        return;
+    for (let i = 0; i < count; i++) {
+        let index = Math.floor(rng() * n);
+        if (index >= n)
+            index = n - 1;
+        if (index < 0)
+            index = 0;
+        const stat = statIds[index];
+        into[stat] = (into[stat] ?? 0) + 1;
+    }
+}
+function zeroedPoints(statIds) {
+    const points = {};
+    for (const stat of statIds)
+        points[stat] = 0;
+    return points;
+}
+/**
+ * Roll a fresh wild creature at `level`: distribute `(level - 1)` points randomly across the
+ * species' stats using the injected rng and return a serializable {@link CreatureStatInstance}.
+ * Deterministic — the same rng sequence yields the same point spread. Levels below 1 clamp to 1
+ * (no points). Use `seededRng` from `../random/rng` for a persisted, reproducible stream.
+ *
+ * @capability spawn-level-roll distribute a wild creature's spawn level into random per-stat points
+ */
+export function rollSpawnInstance(speciesId, species, level, rng) {
+    const statIds = Object.keys(species);
+    const points = zeroedPoints(statIds);
+    const normalized = normalizeLevel(level);
+    distributePoints(statIds, normalized - 1, rng, points);
+    return { speciesId, level: normalized, points, domesticLevels: 0 };
+}
+/**
+ * Resolve an instance's live stat values from its distributed points:
+ * `value = base * (1 + points * growth)` per stat. Stats with zero points return their base.
+ *
+ * @capability spawn-stat-values resolve a creature's per-stat values from its distributed points
+ */
+export function resolveSpawnStats(species, instance) {
+    const out = {};
+    for (const stat of Object.keys(species)) {
+        const def = species[stat];
+        const pts = instance.points[stat] ?? 0;
+        out[stat] = def.base * (1 + pts * def.growth);
+    }
+    return out;
+}
+/**
+ * Bonus levels granted by a capture at the given effectiveness:
+ * `floor(level * clamp01(effectiveness) / 2)`. A perfect (1.0) capture grants half the wild
+ * level; a botched (0) capture grants none. Effectiveness outside `[0,1]` clamps.
+ *
+ * @capability capture-bonus-levels convert wild level and capture effectiveness into bonus levels
+ */
+export function captureBonusLevels(level, effectiveness) {
+    return Math.floor((normalizeLevel(level) * clamp01(effectiveness)) / 2);
+}
+/**
+ * Apply a capture at the given effectiveness: compute bonus levels via {@link captureBonusLevels},
+ * distribute those extra points randomly with the injected rng, and return the post-capture
+ * instance (level raised to the tamed total) alongside the granted bonus levels and tamed level.
+ * The input instance is not mutated.
+ *
+ * @capability capture-effectiveness-tame apply capture effectiveness to grant and distribute bonus levels
+ */
+export function applyCaptureEffectiveness(species, instance, effectiveness, rng) {
+    const bonusLevels = captureBonusLevels(instance.level, effectiveness);
+    const statIds = Object.keys(species);
+    const points = { ...instance.points };
+    distributePoints(statIds, bonusLevels, rng, points);
+    const tamedLevel = instance.level + bonusLevels;
+    return {
+        bonusLevels,
+        tamedLevel,
+        instance: { ...instance, level: tamedLevel, points },
+    };
+}
+/**
+ * Spend one earned post-capture level into `stat`, adding a single growth increment (one point)
+ * and raising both `level` and `domesticLevels`. When `maxDomesticLevels` is set and already
+ * reached, the spend is refused (`spent: false`) and the instance is returned untouched. Pure:
+ * returns a new instance rather than mutating the input.
+ *
+ * @capability domestic-level-spend spend an earned post-capture level into a chosen stat under a cap
+ */
+export function spendDomesticLevel(instance, stat, options) {
+    const cap = options?.maxDomesticLevels;
+    if (cap !== undefined && instance.domesticLevels >= cap) {
+        return { instance, spent: false };
+    }
+    const points = { ...instance.points };
+    points[stat] = (points[stat] ?? 0) + 1;
+    return {
+        instance: {
+            ...instance,
+            points,
+            level: instance.level + 1,
+            domesticLevels: instance.domesticLevels + 1,
+        },
+        spent: true,
+    };
+}
+/**
+ * Deep-copy an instance into a detached, serializable record — the transport/save counterpart of
+ * {@link restoreSpawnInstance}. Copies the points map so later edits don't leak into the snapshot.
+ *
+ * @capability spawn-instance-snapshot deep-copy a creature stat instance into a serializable record
+ */
+export function snapshotSpawnInstance(instance) {
+    return {
+        speciesId: instance.speciesId,
+        level: instance.level,
+        domesticLevels: instance.domesticLevels,
+        points: { ...instance.points },
+    };
+}
+/**
+ * Rehydrate a creature stat instance from decoded data (e.g. `JSON.parse` output), returning a
+ * fresh deep copy the caller owns. Inverse of {@link snapshotSpawnInstance}.
+ *
+ * @capability spawn-instance-restore rehydrate a creature stat instance from decoded snapshot data
+ */
+export function restoreSpawnInstance(data) {
+    return snapshotSpawnInstance(data);
+}

package/dist/stats/statPool.d.ts

@@ -0,0 +1,70 @@
+/** Serializable state for any bounded named resource. The caller defines what the resource means. */
+export interface StatPool {
+    current: number;
+    max: number;
+    min: number;
+}
+/** Input used to create a normalized pool. `current` defaults to `max`; `min` defaults to zero. */
+export interface StatPoolInput {
+    current?: number;
+    max: number;
+    min?: number;
+}
+/** Partial update applied without mutating the previous pool. */
+export interface StatPoolPatch {
+    current?: number;
+    max?: number;
+    min?: number;
+}
+/**
+ * Structural bridge to caller-owned resource state. Implement it over an ECS,
+ * Redux/Zustand store, plain object, database-backed model, or JGengine's native
+ * entity stats without moving ownership into the SDK.
+ */
+export interface StatPoolAccess<TOwnerId extends string = string, TStatId extends string = string> {
+    get(ownerId: TOwnerId, statId: TStatId): StatPool | null;
+    set(ownerId: TOwnerId, statId: TStatId, next: StatPool): unknown;
+}
+/** Inspectable result of a bounded pool change. */
+export interface StatPoolChange {
+    previous: StatPool;
+    pool: StatPool;
+    /** Actual applied amount after clamping. */
+    applied: number;
+    hitMin: boolean;
+    hitMax: boolean;
+}
+/** Outcome of changing a pool through {@link StatPoolAccess}. */
+export type StatPoolAccessResult = ({
+    status: "ok";
+} & StatPoolChange) | {
+    status: "rejected";
+    reason: string;
+};
+/**
+ * Normalize caller data into a complete plain-data pool.
+ *
+ * @capability stat-pool create a serializable current/min/max pool for any caller-named resource
+ */
+export declare function createStatPool(input: StatPoolInput): StatPool;
+/**
+ * Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
+ *
+ * @capability stat-pool-patch immutably retune a bounded resource's current value or bounds
+ */
+export declare function patchStatPool(pool: StatPool, patch: StatPoolPatch): StatPool;
+/**
+ * Pure bounded delta transition with the exact applied amount and boundary flags.
+ *
+ * @capability stat-pool-change immutably increase or decrease any named bounded resource with clamp evidence
+ */
+export declare function changeStatPool(pool: StatPool, amount: number): StatPoolChange;
+/**
+ * Read, transition, and write a caller-owned pool through the structural
+ * adapter. Positive amounts increase the resource; negative amounts decrease
+ * it. The adapter receives a complete replacement value, never a hidden
+ * mutation.
+ *
+ * @capability portable-stat-pool apply deterministic bounded resource changes through a caller-owned stat adapter
+ */
+export declare function applyStatPoolDelta<TOwnerId extends string, TStatId extends string>(access: StatPoolAccess<TOwnerId, TStatId>, ownerId: TOwnerId, statId: TStatId, amount: number): StatPoolAccessResult;

package/dist/stats/statPool.js

@@ -0,0 +1,59 @@
+import { clamp } from "../math/scalar.js";
+/**
+ * Normalize caller data into a complete plain-data pool.
+ *
+ * @capability stat-pool create a serializable current/min/max pool for any caller-named resource
+ */
+export function createStatPool(input) {
+    const min = input.min ?? 0;
+    return {
+        current: clamp(input.current ?? input.max, min, input.max),
+        max: input.max,
+        min,
+    };
+}
+/**
+ * Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
+ *
+ * @capability stat-pool-patch immutably retune a bounded resource's current value or bounds
+ */
+export function patchStatPool(pool, patch) {
+    const max = patch.max ?? pool.max;
+    const min = patch.min ?? pool.min;
+    return {
+        current: clamp(patch.current ?? pool.current, min, max),
+        max,
+        min,
+    };
+}
+/**
+ * Pure bounded delta transition with the exact applied amount and boundary flags.
+ *
+ * @capability stat-pool-change immutably increase or decrease any named bounded resource with clamp evidence
+ */
+export function changeStatPool(pool, amount) {
+    const next = patchStatPool(pool, { current: pool.current + amount });
+    return {
+        previous: pool,
+        pool: next,
+        applied: next.current - pool.current,
+        hitMin: next.current === next.min,
+        hitMax: next.current === next.max,
+    };
+}
+/**
+ * Read, transition, and write a caller-owned pool through the structural
+ * adapter. Positive amounts increase the resource; negative amounts decrease
+ * it. The adapter receives a complete replacement value, never a hidden
+ * mutation.
+ *
+ * @capability portable-stat-pool apply deterministic bounded resource changes through a caller-owned stat adapter
+ */
+export function applyStatPoolDelta(access, ownerId, statId, amount) {
+    const pool = access.get(ownerId, statId);
+    if (pool === null)
+        return { status: "rejected", reason: `unknown stat "${statId}"` };
+    const change = changeStatPool(pool, amount);
+    access.set(ownerId, statId, change.pool);
+    return { status: "ok", ...change };
+}

package/dist/store/changeSignal.d.ts

@@ -1,7 +1,10 @@
+/** @internal */
 export interface ChangeSignal {
     subscribe(listener: () => void): () => void;
     notify(): void;
     version(): number;
 }
+/** @internal */
 export declare function createChangeSignal(): ChangeSignal;
+/** @internal */
 export declare function notifyAfter<T extends object, K extends keyof T>(target: T, methods: readonly K[], notify: () => void): T;

package/dist/store/changeSignal.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createChangeSignal() {
     const listeners = new Set();
     let version = 0;
@@ -18,6 +19,7 @@ export function createChangeSignal() {
         },
     };
 }
+/** @internal */
 export function notifyAfter(target, methods, notify) {
     const wrapped = { ...target };
     for (const method of methods) {

package/dist/store/observableKeyedStore.d.ts

@@ -1,3 +1,4 @@
+/** @internal */
 export interface ObservableKeyedStore<T> {
     set(key: string, value: T): void;
     delete(key: string): void;
@@ -16,4 +17,5 @@ export interface ObservableKeyedStore<T> {
     /** Replace all entries with `data` (clears keys absent from it), emitting once. */
     hydrate(data: readonly (readonly [string, T])[]): void;
 }
+/** @internal */
 export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;

package/dist/store/observableKeyedStore.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createObservableKeyedStore(areEqual) {
     const store = new Map();
     const listeners = new Set();

package/dist/survival/decayMeter.js

@@ -1,6 +1,4 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
+import { clamp } from "../math/scalar.js";
 function meterMin(def) {
     return def.min ?? 0;
 }

package/dist/survival/regionHealth.js

@@ -1,6 +1,4 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
+import { clamp } from "../math/scalar.js";
 /**
  * Per-region/limb health tracked separately, so each body part takes and heals damage on its own.
  *

package/dist/ui/hudLayout.d.ts

@@ -86,5 +86,10 @@ export declare function rectFromPlacement(placement: HudPlacement, size: HudSize
 export declare function registerActiveHudLayout(store: HudLayoutStore): () => void;
 /** @internal */
 export declare function listActiveHudLayouts(): HudLayoutStore[];
+/**
+ * @internal Notified whenever a `HudCanvas` mounts or unmounts (the active-layout set changes).
+ * Lets the editor's HUD-layout surface enable editing on layouts that mount after it opens.
+ */
+export declare function subscribeActiveHudLayouts(listener: () => void): () => void;
 /** @internal */
 export declare function createHudLayout(options?: HudLayoutOptions): HudLayoutStore;

package/dist/ui/hudLayout.js

@@ -116,17 +116,33 @@ function parseSerialized(raw) {
     return out;
 }
 const activeHudLayouts = new Set();
+const activeHudLayoutListeners = new Set();
 /** @internal Agent bridge seam — HudCanvas registers its store while mounted so headless drivers can reach canvas mode. */
 export function registerActiveHudLayout(store) {
     activeHudLayouts.add(store);
+    for (const listener of [...activeHudLayoutListeners])
+        listener();
     return () => {
-        activeHudLayouts.delete(store);
+        if (!activeHudLayouts.delete(store))
+            return;
+        for (const listener of [...activeHudLayoutListeners])
+            listener();
     };
 }
 /** @internal */
 export function listActiveHudLayouts() {
     return [...activeHudLayouts];
 }
+/**
+ * @internal Notified whenever a `HudCanvas` mounts or unmounts (the active-layout set changes).
+ * Lets the editor's HUD-layout surface enable editing on layouts that mount after it opens.
+ */
+export function subscribeActiveHudLayouts(listener) {
+    activeHudLayoutListeners.add(listener);
+    return () => {
+        activeHudLayoutListeners.delete(listener);
+    };
+}
 function panelToUi(panel) {
     const layout = {
         anchor: panel.placement.anchor,

package/dist/world/authoredEntities.d.ts

@@ -0,0 +1,29 @@
+import { ENTITY_MARKER_KINDS, type AuthoredObjectMarkerLike } from "./authoredObjects.js";
+/** Marker kinds {@link authoredEntitySpawns} treats as spawnable entities by default. Re-exported from `authoredObjects` as the single source of truth (the same kinds `resolveAuthoredObjects` skips). */
+export { ENTITY_MARKER_KINDS };
+/** The minimal marker shape entity spawns read; any `EditorMarker` satisfies it. */
+export type AuthoredEntityMarkerLike = AuthoredObjectMarkerLike;
+/** The minimal document shape {@link authoredEntitySpawns} walks; any `EditorDocument` satisfies it. */
+export interface AuthoredEntityDocumentLike {
+    markers: readonly AuthoredEntityMarkerLike[];
+}
+/** One resolved entity to spawn from the authored scene — its marker id, catalog id, and pose. */
+export interface AuthoredEntitySpawn {
+    /** The marker's id — a stable spawn id, so re-spawning the same marker is idempotent. */
+    markerId: string;
+    /** The entity catalog id to spawn (join key into `content.entityById`). */
+    catalogId: string;
+    /** World-space spawn position as a spawn-ready `[x, y, z]` tuple. */
+    position: [number, number, number];
+    /** Facing (yaw radians), 0 when the marker has none. */
+    rotationY: number;
+}
+/**
+ * Every authored entity marker (`mob`/`boss` by default) that carries a `catalogId`, as a spawn plan
+ * the runtime feeds to `ctx.scene.entity.spawn(catalogId, { id, position })`. Reads the same document
+ * the editor authors, so placing a mob and setting its catalog id in the editor is all it takes to
+ * spawn it — no coordinates or spawn tables copied into game code. Markers without a catalog id are
+ * skipped (they are placement-only, e.g. a boss arena marker a game handles specially).
+ * @capability authored-entities spawn authored mob/boss markers from the editor document at runtime
+ */
+export declare function authoredEntitySpawns(document: AuthoredEntityDocumentLike, kinds?: readonly string[]): AuthoredEntitySpawn[];

package/dist/world/authoredEntities.js

@@ -0,0 +1,29 @@
+import { ENTITY_MARKER_KINDS, markerCatalogId } from "./authoredObjects.js";
+/** Marker kinds {@link authoredEntitySpawns} treats as spawnable entities by default. Re-exported from `authoredObjects` as the single source of truth (the same kinds `resolveAuthoredObjects` skips). */
+export { ENTITY_MARKER_KINDS };
+/**
+ * Every authored entity marker (`mob`/`boss` by default) that carries a `catalogId`, as a spawn plan
+ * the runtime feeds to `ctx.scene.entity.spawn(catalogId, { id, position })`. Reads the same document
+ * the editor authors, so placing a mob and setting its catalog id in the editor is all it takes to
+ * spawn it — no coordinates or spawn tables copied into game code. Markers without a catalog id are
+ * skipped (they are placement-only, e.g. a boss arena marker a game handles specially).
+ * @capability authored-entities spawn authored mob/boss markers from the editor document at runtime
+ */
+export function authoredEntitySpawns(document, kinds = ENTITY_MARKER_KINDS) {
+    const wanted = new Set(kinds);
+    const spawns = [];
+    for (const marker of document.markers) {
+        if (!wanted.has(marker.kind))
+            continue;
+        const catalogId = markerCatalogId(marker);
+        if (catalogId === null)
+            continue;
+        spawns.push({
+            markerId: marker.id,
+            catalogId,
+            position: [marker.position.x, marker.position.y, marker.position.z],
+            rotationY: marker.rotationY ?? 0,
+        });
+    }
+    return spawns;
+}

package/dist/world/authoredObjects.d.ts

@@ -42,12 +42,26 @@ export interface PlaceAuthoredObjectsOptions {
  * @capability authored-objects place catalog mesh props from an editor document
  */
 export declare function markerCatalogId(marker: AuthoredObjectMarkerLike): string | null;
+/**
+ * Marker kinds that are spawnable entities (materialized by `authoredEntitySpawns`), not static
+ * catalog props. {@link resolveAuthoredObjects} skips them by default so a placed `mob`/`boss` is
+ * spawned once as an entity and never also placed as a static mesh.
+ * @capability authored-objects marker kinds resolved as entity spawns, not static props
+ */
+export declare const ENTITY_MARKER_KINDS: readonly string[];
+/** Options for {@link resolveAuthoredObjects}. */
+export interface ResolveAuthoredObjectsOptions {
+    /** Marker kinds to skip (they are handled elsewhere). Default {@link ENTITY_MARKER_KINDS}. */
+    excludeKinds?: readonly string[];
+}
 /**
  * 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.
+ * Entity-spawn kinds (`mob`/`boss`) are skipped by default — they carry a `catalogId` for their
+ * entity definition, but are spawned via `authoredEntitySpawns`, not placed as static meshes.
  * @capability authored-objects place catalog mesh props from an editor document
  */
-export declare function resolveAuthoredObjects(document: AuthoredObjectsDocumentLike): AuthoredObject[];
+export declare function resolveAuthoredObjects(document: AuthoredObjectsDocumentLike, options?: ResolveAuthoredObjectsOptions): AuthoredObject[];
 /**
  * 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).

package/dist/world/authoredObjects.js

@@ -22,14 +22,26 @@ function markerVerticalOffset(marker) {
         metaNumber(marker.meta, "yOffset");
     return fromMeta ?? 0;
 }
+/**
+ * Marker kinds that are spawnable entities (materialized by `authoredEntitySpawns`), not static
+ * catalog props. {@link resolveAuthoredObjects} skips them by default so a placed `mob`/`boss` is
+ * spawned once as an entity and never also placed as a static mesh.
+ * @capability authored-objects marker kinds resolved as entity spawns, not static props
+ */
+export const ENTITY_MARKER_KINDS = ["mob", "boss"];
 /**
  * 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.
+ * Entity-spawn kinds (`mob`/`boss`) are skipped by default — they carry a `catalogId` for their
+ * entity definition, but are spawned via `authoredEntitySpawns`, not placed as static meshes.
  * @capability authored-objects place catalog mesh props from an editor document
  */
-export function resolveAuthoredObjects(document) {
+export function resolveAuthoredObjects(document, options = {}) {
+    const excluded = new Set(options.excludeKinds ?? ENTITY_MARKER_KINDS);
     const out = [];
     for (const marker of document.markers) {
+        if (excluded.has(marker.kind))
+            continue;
         const catalogId = markerCatalogId(marker);
         if (catalogId === null)
             continue;

package/dist/world/authoredSpawn.d.ts

@@ -0,0 +1,39 @@
+import type { SceneMarkerLike } from "./sceneShapes.js";
+/** Minimal marker shape spawn queries read; any `EditorMarker` satisfies it. */
+export interface AuthoredSpawnMarkerLike extends SceneMarkerLike {
+    rotationY?: number;
+}
+/** Minimal document shape spawn queries walk; any `EditorDocument` satisfies it. */
+export interface AuthoredSpawnDocumentLike {
+    markers: readonly AuthoredSpawnMarkerLike[];
+}
+/** Marker kind {@link authoredSpawnPosition} resolves by default. */
+export declare const PLAYER_SPAWN_KIND = "player_spawn";
+/**
+ * Every marker of `kind`, in document order — the generic query behind gameplay that references
+ * authored markers by kind instead of copying coordinates into code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export declare function markersOfKind<TMarker extends AuthoredSpawnMarkerLike>(document: {
+    markers: readonly TMarker[];
+}, kind: string): TMarker[];
+/** Options for {@link authoredSpawnPosition}: pick a specific marker id or a non-default kind. */
+export interface AuthoredSpawnOptions {
+    /** Marker kind to resolve. Default {@link PLAYER_SPAWN_KIND}. */
+    kind?: string;
+    /** Exact marker id; when set, kind only filters among markers with this id's kind. */
+    id?: string;
+}
+/**
+ * Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the
+ * document has none. Reads the first `player_spawn` marker by default, so dragging the marker in
+ * the editor moves where players spawn — no coordinates copied into game code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export declare function authoredSpawnPosition(document: AuthoredSpawnDocumentLike, options?: AuthoredSpawnOptions): [number, number, number] | null;
+/**
+ * Facing (yaw radians) of the authored spawn marker, or 0 when the document has none — pair with
+ * {@link authoredSpawnPosition} to spawn players where and how the editor placed them.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export declare function authoredSpawnRotation(document: AuthoredSpawnDocumentLike, options?: AuthoredSpawnOptions): number;

package/dist/world/authoredSpawn.js

@@ -0,0 +1,37 @@
+/** Marker kind {@link authoredSpawnPosition} resolves by default. */
+export const PLAYER_SPAWN_KIND = "player_spawn";
+/**
+ * Every marker of `kind`, in document order — the generic query behind gameplay that references
+ * authored markers by kind instead of copying coordinates into code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export function markersOfKind(document, kind) {
+    return document.markers.filter((marker) => marker.kind === kind);
+}
+/**
+ * Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the
+ * document has none. Reads the first `player_spawn` marker by default, so dragging the marker in
+ * the editor moves where players spawn — no coordinates copied into game code.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export function authoredSpawnPosition(document, options = {}) {
+    const kind = options.kind ?? PLAYER_SPAWN_KIND;
+    const marker = options.id === undefined
+        ? document.markers.find((entry) => entry.kind === kind)
+        : document.markers.find((entry) => entry.id === options.id && entry.kind === kind);
+    if (marker === undefined)
+        return null;
+    return [marker.position.x, marker.position.y, marker.position.z];
+}
+/**
+ * Facing (yaw radians) of the authored spawn marker, or 0 when the document has none — pair with
+ * {@link authoredSpawnPosition} to spawn players where and how the editor placed them.
+ * @capability authored-spawn read spawn points and markers from the editor document
+ */
+export function authoredSpawnRotation(document, options = {}) {
+    const kind = options.kind ?? PLAYER_SPAWN_KIND;
+    const marker = options.id === undefined
+        ? document.markers.find((entry) => entry.kind === kind)
+        : document.markers.find((entry) => entry.id === options.id && entry.kind === kind);
+    return marker?.rotationY ?? 0;
+}