@jgengine/core 0.19.0 → 0.22.0

package/dist/scene/entityStore.js

@@ -1,4 +1,5 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+import { behaviorDataEqual } from "./behaviors.js";
 /**
  * Narrow `entity.meta` with a type guard — prefer this over `entity.meta as T` so failed shapes return `null`
  * instead of lying to the type checker.
@@ -26,12 +27,29 @@ function toEntityPosition(position) {
         return [position.x, position.y, position.z];
     return position;
 }
-export function createEntityStore() {
-    const store = createObservableKeyedStore();
+export function createEntityStore(options = {}) {
+    const behaviorListeners = new Set();
+    const behaviorChanges = new Set();
+    const store = createObservableKeyedStore(undefined, (id, membershipChanged) => {
+        options.onChange?.(id, membershipChanged);
+        if (id !== undefined && behaviorChanges.delete(id))
+            for (const listener of behaviorListeners)
+                listener(id);
+    });
     const spawnPoses = new Map();
     const constraints = new Map();
     const blackboards = new Map();
     let nextCounter = 1;
+    function writeEntity(entity, previous = store.get(entity.id)?.behaviors) {
+        if (!behaviorDataEqual(previous ?? [], entity.behaviors))
+            behaviorChanges.add(entity.id);
+        store.set(entity.id, entity);
+    }
+    function deleteEntity(id) {
+        if ((store.get(id)?.behaviors.length ?? 0) > 0)
+            behaviorChanges.add(id);
+        store.delete(id);
+    }
     const blackboard = {
         get: (id, key) => blackboards.get(id)?.get(key),
         set(id, key, value) {
@@ -80,7 +98,8 @@ export function createEntityStore() {
             const id = options.id ?? generateId();
             const position = toEntityPosition(options.position);
             const rotationY = options.rotationY ?? 0;
-            store.set(id, {
+            spawnPoses.set(id, { position, rotationY });
+            writeEntity({
                 id,
                 name,
                 position,
@@ -94,12 +113,11 @@ export function createEntityStore() {
                 ...(options.hidden === undefined ? {} : { hidden: options.hidden }),
                 meta: options.meta,
             });
-            spawnPoses.set(id, { position, rotationY });
             return id;
         },
         despawn(id) {
             const existed = store.has(id);
-            store.delete(id);
+            deleteEntity(id);
             spawnPoses.delete(id);
             constraints.delete(id);
             blackboards.delete(id);
@@ -109,6 +127,7 @@ export function createEntityStore() {
             const current = store.get(id);
             if (!current)
                 return false;
+            const previousBehaviors = current.behaviors;
             if (patch.position !== undefined)
                 current.position = toEntityPosition(patch.position);
             if (patch.name !== undefined)
@@ -129,7 +148,10 @@ export function createEntityStore() {
                 current.hidden = patch.hidden;
             if (patch.meta !== undefined)
                 current.meta = patch.meta;
-            store.set(id, current);
+            if (patch.behaviors === undefined)
+                store.set(id, current);
+            else
+                writeEntity(current, previousBehaviors);
             return true;
         },
         setPoseConstraint(id, constraint) {
@@ -173,6 +195,15 @@ export function createEntityStore() {
             store.set(id, current);
             return true;
         },
+        setVelocity(id, velocity) {
+            const current = store.get(id);
+            if (current === undefined || !Array.isArray(velocity) || velocity.length !== 3 ||
+                !velocity.every((component) => typeof component === "number" && Number.isFinite(component)))
+                return false;
+            current.velocity = [velocity[0], velocity[1], velocity[2]];
+            store.set(id, current);
+            return true;
+        },
         get(id) {
             return store.get(id) ?? null;
         },
@@ -184,7 +215,7 @@ export function createEntityStore() {
         },
         clear() {
             for (const entity of store.arraySnapshot()) {
-                store.delete(entity.id);
+                deleteEntity(entity.id);
             }
             constraints.clear();
             blackboards.clear();
@@ -195,6 +226,10 @@ export function createEntityStore() {
         subscribeMembership(listener) {
             return store.subscribeMembership(listener);
         },
+        subscribeBehaviors(listener) {
+            behaviorListeners.add(listener);
+            return () => { behaviorListeners.delete(listener); };
+        },
         snapshot() {
             return store.arraySnapshot();
         },
@@ -202,14 +237,14 @@ export function createEntityStore() {
             const incoming = new Set(entities.map((entity) => entity.id));
             for (const current of store.arraySnapshot()) {
                 if (!incoming.has(current.id)) {
-                    store.delete(current.id);
+                    deleteEntity(current.id);
                     spawnPoses.delete(current.id);
                     constraints.delete(current.id);
                     blackboards.delete(current.id);
                 }
             }
             for (const entity of entities) {
-                store.set(entity.id, {
+                writeEntity({
                     id: entity.id,
                     name: entity.name,
                     position: entity.position,
@@ -220,6 +255,7 @@ export function createEntityStore() {
                     role: entity.role,
                     movement: entity.movement,
                     behaviors: entity.behaviors,
+                    ...(entity.hidden === undefined ? {} : { hidden: entity.hidden }),
                     meta: entity.meta,
                 });
                 if (!spawnPoses.has(entity.id)) {

package/dist/scene/mount.d.ts

@@ -22,6 +22,10 @@ export interface Occupant {
     riderId: string;
     seatId: string;
 }
+/** Occupancy only; register the world's rideables before restoring. */
+export interface MountedRider extends SeatRef {
+    riderId: string;
+}
 export type MountResult = {
     ok: true;
     seat: MountSeat;
@@ -58,5 +62,10 @@ export declare class MountController {
      * (they ride but do not steer), and the rider themselves when not mounted at all.
      */
     driveTarget(riderId: string): string | null;
+    snapshot(): MountedRider[];
+    /** Replace occupancy atomically. Invalid, unknown, or duplicate claims leave it unchanged. */
+    restore(next: readonly MountedRider[]): void;
+    /** Release every rider, preserving authored registrations. */
+    reset(): void;
 }
 export declare function createMountController(): MountController;

package/dist/scene/mount.js

@@ -101,6 +101,41 @@ export class MountController {
         const seat = this.mounts.get(ref.mountId)?.seats.find((s) => s.id === ref.seatId);
         return seat?.control === true ? ref.mountId : null;
     }
+    snapshot() {
+        return [...this.seatOfRider].map(([riderId, ref]) => ({ riderId, ...ref }));
+    }
+    /** Replace occupancy atomically. Invalid, unknown, or duplicate claims leave it unchanged. */
+    restore(next) {
+        const riders = new Set();
+        const claims = new Map();
+        if (!Array.isArray(next))
+            throw new Error("mount occupancy must be an array");
+        for (const row of next) {
+            if (row === null || typeof row !== "object" || typeof row.riderId !== "string" || row.riderId.length === 0 ||
+                typeof row.mountId !== "string" || typeof row.seatId !== "string" || riders.has(row.riderId)) {
+                throw new Error("invalid mount occupant");
+            }
+            const reg = this.mounts.get(row.mountId);
+            const occupied = claims.get(row.mountId) ?? new Set();
+            if (reg === undefined || !reg.seats.some((seat) => seat.id === row.seatId) || occupied.has(row.seatId)) {
+                throw new Error("invalid mount seat claim");
+            }
+            riders.add(row.riderId);
+            occupied.add(row.seatId);
+            claims.set(row.mountId, occupied);
+        }
+        this.reset();
+        for (const { riderId, mountId, seatId } of next) {
+            this.mounts.get(mountId).bySeat.set(seatId, riderId);
+            this.seatOfRider.set(riderId, { mountId, seatId });
+        }
+    }
+    /** Release every rider, preserving authored registrations. */
+    reset() {
+        this.seatOfRider.clear();
+        for (const reg of this.mounts.values())
+            reg.bySeat.clear();
+    }
 }
 export function createMountController() {
     return new MountController();

package/dist/scene/possession.d.ts

@@ -25,6 +25,8 @@ export interface Possession {
     own(userId: string, entityId: string): void;
     disown(userId: string, entityId: string): void;
     owns(userId: string, entityId: string): boolean;
+    /** Unique owner of an explicitly owned pawn, or undefined when absent or shared. Does not create ownership. */
+    ownerOf(entityId: string): string | undefined;
     listOwned(userId: string): readonly string[];
     active(userId: string): string;
     possess(userId: string, entityId: string): {

package/dist/scene/possession.js

@@ -1,28 +1,44 @@
 export function createPossession(deps) {
     const owned = new Map();
     const activeByUser = new Map();
+    const ownersByEntity = new Map();
+    function addOwner(userId, entityId) {
+        const owners = ownersByEntity.get(entityId) ?? new Set();
+        owners.add(userId);
+        ownersByEntity.set(entityId, owners);
+    }
     function ownedSet(userId) {
         let set = owned.get(userId);
         if (set === undefined) {
             set = new Set([userId]);
             owned.set(userId, set);
+            addOwner(userId, userId);
         }
         return set;
     }
     return {
         own(userId, entityId) {
             ownedSet(userId).add(entityId);
+            addOwner(userId, entityId);
         },
         disown(userId, entityId) {
             if (entityId === userId)
                 return;
             ownedSet(userId).delete(entityId);
+            const owners = ownersByEntity.get(entityId);
+            owners?.delete(userId);
+            if (owners?.size === 0)
+                ownersByEntity.delete(entityId);
             if (activeByUser.get(userId) === entityId)
                 activeByUser.delete(userId);
         },
         owns(userId, entityId) {
             return ownedSet(userId).has(entityId);
         },
+        ownerOf(entityId) {
+            const owners = ownersByEntity.get(entityId);
+            return owners?.size === 1 ? owners.values().next().value : undefined;
+        },
         listOwned(userId) {
             return Array.from(ownedSet(userId));
         },
@@ -55,8 +71,12 @@ export function createPossession(deps) {
         },
         hydrateAll(state) {
             owned.clear();
-            for (const [userId, ids] of Object.entries(state.owned))
+            ownersByEntity.clear();
+            for (const [userId, ids] of Object.entries(state.owned)) {
                 owned.set(userId, new Set(ids));
+                for (const entityId of ids)
+                    addOwner(userId, entityId);
+            }
             activeByUser.clear();
             for (const [userId, entityId] of Object.entries(state.active))
                 activeByUser.set(userId, entityId);

package/dist/scene/sceneRaycast.d.ts

@@ -1,6 +1,7 @@
 import type { EntityPosition } from "./entityStore.js";
 import { type ColliderPurpose, type EntityColliderSet } from "./colliders.js";
 import type { SceneObject } from "./objectStore.js";
+import type { WorldSolids } from "../world/worldSolids.js";
 export type SceneRaycastTargetKind = "entity" | "object" | "terrain" | "wall";
 export interface SceneRaycastHit {
     targetKind: SceneRaycastTargetKind;
@@ -18,11 +19,15 @@ export interface SceneRaycastFilter {
     entities?: boolean;
     objects?: boolean;
     terrain?: boolean;
+    /** Wall segments and indexed world solids. */
     walls?: boolean;
 }
 export interface SceneRaycastInput {
+    /** Finite world coordinates. */
     origin: EntityPosition;
+    /** Finite direction and magnitude, normalized by the query. Zero direction returns no hits. */
     direction: EntityPosition;
+    /** Finite, nonnegative segment length in world units. */
     maxDistance: number;
     excludeInstanceIds?: ReadonlySet<string> | readonly string[];
     filter?: SceneRaycastFilter;
@@ -68,6 +73,8 @@ export interface SceneRaycastDeps {
     objects?: SceneObjectQuerySource;
     terrain?: TerrainRaycastSource;
     walls?: readonly WallSegment[];
+    /** Indexed geometry returns physical, non-damage wall hits with instance id `world-solid`. */
+    solids?: Pick<WorldSolids, "inBox" | "inRay">;
 }
 export interface SceneRaycastApi {
     raycast(input: SceneRaycastInput): SceneRaycastHit | null;

package/dist/scene/sceneRaycast.js

@@ -127,6 +127,20 @@ function wallAabb(wall) {
         center: [(ax + bx) / 2, yCenter, (az + bz) / 2],
     };
 }
+function rayHitsWorldSolid(solid, origin, direction, maxDistance) {
+    const cos = Math.cos(solid.rotationY ?? 0);
+    const sin = Math.sin(solid.rotationY ?? 0);
+    const x = origin[0] - solid.center[0];
+    const z = origin[2] - solid.center[2];
+    const [hx, hy, hz] = solid.halfExtents;
+    const hit = intersectAabb([x * cos - z * sin, origin[1] - solid.center[1], x * sin + z * cos], [direction[0] * cos - direction[2] * sin, direction[1], direction[0] * sin + direction[2] * cos], [-hx, -hy, -hz], [hx, hy, hz], maxDistance);
+    if (hit === null)
+        return null;
+    return {
+        distance: hit.distance,
+        normal: [hit.normal[0] * cos + hit.normal[2] * sin, hit.normal[1], -hit.normal[0] * sin + hit.normal[2] * cos],
+    };
+}
 function rayHitsTerrain(origin, direction, maxDistance, terrain) {
     const steps = Math.max(8, Math.ceil(maxDistance * 2));
     const step = maxDistance / steps;
@@ -208,6 +222,11 @@ function candidateObjects(objects, origin, direction, maxDistance) {
     return objects.list();
 }
 function gatherHits(deps, input) {
+    if (!input.origin.every(Number.isFinite) || !input.direction.every(Number.isFinite) || !Number.isFinite(input.maxDistance) || input.maxDistance < 0) {
+        throw new RangeError("Scene rays require finite coordinates, direction and nonnegative distance");
+    }
+    if (!Number.isFinite(Math.hypot(...input.direction)))
+        throw new RangeError("Scene ray direction length must be finite");
     const direction = normalizeDirection(input.direction);
     if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
         return [];
@@ -258,6 +277,42 @@ function gatherHits(deps, input) {
             });
         }
     }
+    if (enabled(input.filter, "walls") && deps.solids !== undefined && !excluded(input.excludeInstanceIds, "world-solid")) {
+        let candidates;
+        if (deps.solids.inRay !== undefined) {
+            candidates = deps.solids.inRay(origin, direction, maxDistance);
+        }
+        else {
+            const end = [
+                origin[0] + direction[0] * maxDistance,
+                origin[1] + direction[1] * maxDistance,
+                origin[2] + direction[2] * maxDistance,
+            ];
+            const min = [Math.min(origin[0], end[0]), Math.min(origin[1], end[1]), Math.min(origin[2], end[2])];
+            const max = [Math.max(origin[0], end[0]), Math.max(origin[1], end[1]), Math.max(origin[2], end[2])];
+            candidates = deps.solids.inBox(min, max);
+        }
+        for (const solid of candidates) {
+            const hit = rayHitsWorldSolid(solid, origin, direction, maxDistance);
+            if (hit === null)
+                continue;
+            hits.push({
+                targetKind: "wall",
+                instanceId: "world-solid",
+                colliderName: "solid",
+                purpose: "physical",
+                damageEligible: false,
+                blocks: true,
+                distance: hit.distance,
+                normal: hit.normal,
+                point: [
+                    origin[0] + direction[0] * hit.distance,
+                    origin[1] + direction[1] * hit.distance,
+                    origin[2] + direction[2] * hit.distance,
+                ],
+            });
+        }
+    }
     if (enabled(input.filter, "terrain") && deps.terrain !== undefined) {
         const terrainHit = rayHitsTerrain(origin, direction, maxDistance, deps.terrain);
         if (terrainHit !== null)

package/dist/scene/spatial.d.ts

@@ -38,11 +38,20 @@ export interface SpatialApiOptions {
     /**
      * Broadphase for `inRadius`/`queryArc`. Defaults to `{ cellSize: 8 }`. Pass `false` to force a
      * linear scan. When enabled, the index rebuilds lazily on first use after `invalidate()` or when
-     * `getVersion()` advances — call `invalidate()` after moves unless a version source is wired.
+     * `getVersion()` advances — call `updateEntity(id)` after each committed move, or `invalidate()`
+     * after an unreported batch, unless a version source is wired.
      */
     grid?: SpatialGridOptions | false;
     /** When this number changes between queries, the grid rebuilds without an explicit `invalidate()`. */
     getVersion?: () => number;
+    /** Opt in only when every candidate add/remove/position change calls `updateEntity(id)` or
+     * `invalidate()`. Avoids scanning all candidate IDs on warm queries. Initially unresolved IDs
+     * still cost one position lookup per query until updated or invalidated. Default false retains
+     * discovery of new candidates without notification. If positions also resolve outside the
+     * candidate set, pass its explicit presence flag to `updateEntity`. Rebuilds are deferred to
+     * the first query.
+     */
+    incremental?: boolean;
     /**
      * Slide a horizontal step against the scene's solid geometry, returning the step actually allowed.
      * Wired by the runtime to the same blocking-collider query the player resolver reads, so a chaser
@@ -61,6 +70,16 @@ export interface SpatialApi {
     queryArc(options: QueryArcOptions): string[];
     moveToward(instanceId: string, target: EntityPosition | string, options: MoveTowardOptions): EntityPosition | null;
     invalidate(): void;
+    /** Notify after committing a candidate's position or membership. Pass `false` to remove an ID
+     * even if its position still resolves, or `true` for a present candidate with a late position.
+     * Omitted presence asserts membership when the position resolves, otherwise removes the entry;
+     * subset candidate sets with a broader position resolver must pass explicit presence.
+     * Preserves candidate order; does not build an invalidated/cold index or enumerate candidates.
+     */
+    updateEntity(instanceId: string, candidatePresent?: boolean): void;
 }
 export declare function distanceBetween(a: EntityPosition, b: EntityPosition): number;
+/** Spatial queries with an optional notified incremental broadphase.
+ * @capability spatial-incremental Update one entity's spatial cell after a committed write without scanning the population
+ */
 export declare function createSpatialApi(options: SpatialApiOptions): SpatialApi;

package/dist/scene/spatial.js

@@ -22,6 +22,10 @@ function packCell(cx, cz) {
     return ((cx + CELL_KEY_OFFSET) << 16) | ((cz + CELL_KEY_OFFSET) & 0xffff);
 }
 const DEFAULT_CELL_SIZE = 8;
+const MEMBERSHIP_REBUILD_THRESHOLD = 256;
+/** Spatial queries with an optional notified incremental broadphase.
+ * @capability spatial-incremental Update one entity's spatial cell after a committed write without scanning the population
+ */
 export function createSpatialApi(options) {
     const { resolvePosition, candidates, occluder, getVersion, resolveStep } = options;
     const gridConfig = options.grid === false ? undefined : (options.grid ?? { cellSize: DEFAULT_CELL_SIZE });
@@ -29,10 +33,14 @@ export function createSpatialApi(options) {
     let gridIndex = null;
     let gridDirty = true;
     let lastVersion;
+    let membershipChanges = 0;
     function resolveTarget(target) {
         return typeof target === "string" ? resolvePosition(target) : target;
     }
     function takeBucket(index) {
+        const recycled = index.freeBuckets.pop();
+        if (recycled !== undefined)
+            return recycled;
         if (index.poolCursor < index.bucketPool.length) {
             const bucket = index.bucketPool[index.poolCursor];
             index.poolCursor += 1;
@@ -52,8 +60,10 @@ export function createSpatialApi(options) {
             gridDirty = true;
             lastVersion = version;
         }
-        if (!gridDirty && gridIndex !== null)
+        if (!gridDirty && gridIndex !== null) {
+            membershipChanges = 0;
             return gridIndex;
+        }
         const previous = gridIndex;
         const cells = previous?.cells ?? new Map();
         cells.clear();
@@ -64,13 +74,27 @@ export function createSpatialApi(options) {
             indexed,
             bucketPool: previous?.bucketPool ?? [],
             poolCursor: 0,
+            locations: previous?.locations ?? new Map(),
+            order: previous?.order ?? new Map(),
+            nextOrder: 0,
+            unresolved: previous?.unresolved ?? new Set(),
+            freeBuckets: [],
         };
+        index.locations.clear();
+        index.order.clear();
+        index.unresolved.clear();
         for (const instanceId of candidates()) {
+            if (index.order.has(instanceId))
+                continue;
+            index.order.set(instanceId, index.nextOrder++);
             const position = resolvePosition(instanceId);
-            if (position === undefined)
+            if (position === undefined) {
+                index.unresolved.add(instanceId);
                 continue;
+            }
             indexed.add(instanceId);
             const key = packCell(cellCoord(position[0], cellSize), cellCoord(position[2], cellSize));
+            index.locations.set(instanceId, key);
             let bucket = cells.get(key);
             if (bucket === undefined) {
                 bucket = takeBucket(index);
@@ -80,8 +104,70 @@ export function createSpatialApi(options) {
         }
         gridIndex = index;
         gridDirty = false;
+        membershipChanges = 0;
         return index;
     }
+    function updateEntity(instanceId, candidatePresent) {
+        const index = gridIndex;
+        if (index === null || gridDirty || cellSize === undefined)
+            return;
+        const position = candidatePresent === false ? undefined : resolvePosition(instanceId);
+        const present = candidatePresent ?? (position !== undefined);
+        const oldKey = index.locations.get(instanceId);
+        const newKey = position === undefined ? undefined
+            : packCell(cellCoord(position[0], cellSize), cellCoord(position[2], cellSize));
+        const had = index.order.has(instanceId);
+        if (had !== present) {
+            membershipChanges += 1;
+            if (membershipChanges > MEMBERSHIP_REBUILD_THRESHOLD) {
+                gridDirty = true;
+                return;
+            }
+        }
+        if (oldKey !== undefined && oldKey !== newKey) {
+            const bucket = index.cells.get(oldKey);
+            bucket.splice(bucket.indexOf(instanceId), 1);
+            if (bucket.length === 0) {
+                index.cells.delete(oldKey);
+                index.freeBuckets.push(bucket);
+            }
+        }
+        index.unresolved.delete(instanceId);
+        if (newKey === undefined) {
+            index.indexed.delete(instanceId);
+            index.locations.delete(instanceId);
+            if (present) {
+                if (!had)
+                    index.order.set(instanceId, index.nextOrder++);
+                index.unresolved.add(instanceId);
+            }
+            else
+                index.order.delete(instanceId);
+            return;
+        }
+        if (!had)
+            index.order.set(instanceId, index.nextOrder++);
+        index.indexed.add(instanceId);
+        index.locations.set(instanceId, newKey);
+        if (oldKey === newKey)
+            return;
+        let bucket = index.cells.get(newKey);
+        if (bucket === undefined) {
+            bucket = takeBucket(index);
+            index.cells.set(newKey, bucket);
+        }
+        const ordinal = index.order.get(instanceId);
+        let low = 0;
+        let high = bucket.length;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            if (index.order.get(bucket[mid]) < ordinal)
+                low = mid + 1;
+            else
+                high = mid;
+        }
+        bucket.splice(low, 0, instanceId);
+    }
     function collectNear(index, centerX, centerZ, radius, out) {
         const size = cellSize;
         const cxMin = cellCoord(centerX - radius, size);
@@ -109,6 +195,11 @@ export function createSpatialApi(options) {
     const nearScratch = [];
     const resultScratch = [];
     function appendUnindexed(index, out) {
+        if (options.incremental === true) {
+            for (const instanceId of index.unresolved)
+                out.push(instanceId);
+            return;
+        }
         for (const instanceId of candidates()) {
             if (index.indexed.has(instanceId))
                 continue;
@@ -130,6 +221,7 @@ export function createSpatialApi(options) {
         return resultScratch.slice();
     }
     return {
+        updateEntity,
         distance(aInstanceId, bInstanceId) {
             const a = resolvePosition(aInstanceId);
             const b = resolvePosition(bInstanceId);

package/dist/scene/vehicleSeat.d.ts

@@ -1,4 +1,7 @@
-import { MountController, type MountSeat, type RideableConfig } from "./mount.js";
+import { MountController, type MountedRider, type MountSeat, type RideableConfig } from "./mount.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { CameraRigKind } from "../game/cameraConfig.js";
+import { type CameraRigConfig, type ChaseCameraTuning } from "../runtime/cameraDirector.js";
 /** World-space `[x, y, z]` for a vehicle's current position. */
 export type VehiclePosition = readonly [number, number, number];
 /** A vehicle's world-space position and heading, used for {@link VehicleSeats.exit}'s dismount placement math. */
@@ -38,7 +41,7 @@ export type ExitVehicleResult = {
     riderMovementPatch: RiderMovementPatch;
 } | {
     ok: false;
-    reason: "not_seated";
+    reason: "not_seated" | "invalid_pose";
 };
 /** Where {@link VehicleSeats.exit} steps the rider out, relative to the vehicle's heading. */
 export interface DismountOffset {
@@ -62,6 +65,11 @@ export declare class VehicleSeats {
     exit(riderId: string, vehiclePose: VehiclePose, offset?: DismountOffset): ExitVehicleResult;
     isSeated(riderId: string): boolean;
     driverOf(vehicleId: string): string | null;
+    /** The seated rider's controlled mount; `null` for passengers and unseated riders. */
+    drivenBy(riderId: string): string | null;
+    snapshot(): MountedRider[];
+    restore(next: readonly MountedRider[]): void;
+    reset(): void;
     get mounts(): MountController;
 }
 /**
@@ -70,3 +78,29 @@ export declare class VehicleSeats {
  * @capability vehicle-seats enter, exit and swap seats in a car or mount (GTA-style boarding) with driver and passenger slots
  */
 export declare function createVehicleSeats(controller?: MountController): VehicleSeats;
+/** Seat selection and optional local camera policy for an explicit rider transition. */
+export interface BoardVehicleOptions extends EnterVehicleOptions {
+    /** Presentation policy; `false` applies only rider/occupancy patches for authoritative remote riders. */
+    camera?: boolean;
+    /** Omit to keep the current rig. `null` restores the configured rig. */
+    rig?: CameraRigKind | null;
+    config?: CameraRigConfig;
+    chase?: ChaseCameraTuning | null;
+}
+/** Exit placement and optional local camera restoration for an explicit rider. */
+export interface LeaveVehicleOptions extends DismountOffset {
+    camera?: boolean;
+    /** Supply a last known vehicle pose when its entity has already been removed. */
+    pose?: VehiclePose;
+}
+/** Apply an existing seat transition to the explicitly named rider. Motor/input policy stays caller-owned.
+ * @capability board-vehicle board a rideable, freeze/hide its rider and apply caller camera policy
+ */
+export declare function boardVehicle(ctx: GameContext, seats: VehicleSeats, riderId: string, vehicleId: string, options?: BoardVehicleOptions): EnterVehicleResult;
+/** Apply dismount placement, restore rider movement/visibility and the configured camera rig.
+ * @capability leave-vehicle leave a rideable beside its current pose and restore on-foot camera/movement
+ */
+export declare function leaveVehicle(ctx: GameContext, seats: VehicleSeats, riderId: string, options?: LeaveVehicleOptions): ExitVehicleResult | {
+    ok: false;
+    reason: "unknown_rider" | "unknown_vehicle";
+};