@jgengine/core 0.5.0 → 0.7.0

package/dist/scene/form.d.ts

@@ -0,0 +1,40 @@
+import type { EntityMovement, SceneEntity } from "./entityStore.js";
+export interface FormDef {
+    id: string;
+    movement?: EntityMovement;
+    abilities?: readonly string[];
+    model?: string;
+}
+export interface FormChangedEvent {
+    instanceId: string;
+    formId: string | null;
+}
+export interface FormEntities {
+    get(id: string): SceneEntity | null;
+    update(id: string, patch: {
+        movement?: EntityMovement;
+        name?: string;
+    }): boolean;
+}
+export interface FormTime {
+    after(seconds: number, callback: () => void): () => void;
+}
+export interface FormEvents {
+    emit(name: "form.changed", payload: FormChangedEvent): void;
+}
+export interface FormsDeps {
+    entities: FormEntities;
+    time: FormTime;
+    events?: FormEvents;
+}
+export interface Forms {
+    register(defs: readonly FormDef[]): void;
+    get(formId: string): FormDef | null;
+    abilities(instanceId: string): readonly string[] | null;
+    active(instanceId: string): string | null;
+    shapeshift(instanceId: string, formId: string, durationSeconds?: number): {
+        reason: string;
+    } | null;
+    revert(instanceId: string): void;
+}
+export declare function createForms(deps: FormsDeps): Forms;

package/dist/scene/form.js

@@ -0,0 +1,56 @@
+export function createForms(deps) {
+    const defs = new Map();
+    const runtime = new Map();
+    function emitChange(instanceId, formId) {
+        deps.events?.emit("form.changed", { instanceId, formId });
+    }
+    function revertInternal(instanceId) {
+        const state = runtime.get(instanceId);
+        if (state === undefined)
+            return;
+        state.cancelTimer?.();
+        runtime.delete(instanceId);
+        deps.entities.update(instanceId, { movement: state.baseline.movement, name: state.baseline.name });
+        emitChange(instanceId, null);
+    }
+    return {
+        register(list) {
+            for (const def of list)
+                defs.set(def.id, def);
+        },
+        get(formId) {
+            return defs.get(formId) ?? null;
+        },
+        abilities(instanceId) {
+            const state = runtime.get(instanceId);
+            if (state === undefined)
+                return null;
+            return defs.get(state.formId)?.abilities ?? null;
+        },
+        active(instanceId) {
+            return runtime.get(instanceId)?.formId ?? null;
+        },
+        shapeshift(instanceId, formId, durationSeconds) {
+            const def = defs.get(formId);
+            if (def === undefined)
+                return { reason: `unknown form "${formId}"` };
+            const entity = deps.entities.get(instanceId);
+            if (entity === null)
+                return { reason: `entity "${instanceId}" is not spawned` };
+            const existing = runtime.get(instanceId);
+            existing?.cancelTimer?.();
+            const baseline = existing?.baseline ?? { movement: entity.movement, name: entity.name };
+            deps.entities.update(instanceId, {
+                movement: def.movement ?? baseline.movement,
+                name: def.model ?? baseline.name,
+            });
+            const cancelTimer = durationSeconds === undefined ? null : deps.time.after(durationSeconds, () => revertInternal(instanceId));
+            runtime.set(instanceId, { baseline, formId, cancelTimer });
+            emitChange(instanceId, formId);
+            return null;
+        },
+        revert(instanceId) {
+            revertInternal(instanceId);
+        },
+    };
+}

package/dist/scene/mount.d.ts

@@ -0,0 +1,62 @@
+export type MountKind = "ground" | "boat" | "flying" | "swimming";
+export interface MountKit {
+    kind: MountKind;
+    moveSpeed?: number;
+    turnSpeed?: number;
+}
+export interface MountSeat {
+    id: string;
+    offset: readonly [number, number, number];
+    control?: boolean;
+}
+export interface RideableConfig {
+    id: string;
+    kit: MountKit;
+    seats?: readonly MountSeat[];
+}
+export interface SeatRef {
+    mountId: string;
+    seatId: string;
+}
+export interface Occupant {
+    riderId: string;
+    seatId: string;
+}
+export type MountResult = {
+    ok: true;
+    seat: MountSeat;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Mount / rideable control-transfer (issue #83). Registers rideables (each with one or more seats — a
+ * control seat drives, the rest ride) and tracks who is on what. It owns no camera or physics: game code
+ * reads `cameraTarget(riderId)` to point the follow camera at the mount, and `driveTarget(riderId)` to
+ * route that rider's {@link import("../physics/vehicleBody.js").AxisInput}-driven input at the mount's
+ * movement kit — the same seam a horse, a truck, or a shared multi-seat ship all plug into.
+ */
+export declare class MountController {
+    private readonly mounts;
+    private readonly seatOfRider;
+    register(config: RideableConfig): void;
+    isRegistered(mountId: string): boolean;
+    kitOf(mountId: string): MountKit | null;
+    seatsOf(mountId: string): readonly MountSeat[];
+    private firstFreeSeat;
+    mount(riderId: string, mountId: string, seatId?: string): MountResult;
+    dismount(riderId: string): string | null;
+    seatOf(riderId: string): SeatRef | null;
+    isSeated(riderId: string): boolean;
+    seatOffset(riderId: string): readonly [number, number, number] | null;
+    occupants(mountId: string): readonly Occupant[];
+    driver(mountId: string): string | null;
+    /** Entity the follow camera should track for this rider: the mount when seated, else the rider. */
+    cameraTarget(riderId: string): string;
+    /**
+     * Entity this rider's input drives: the mount when in a control seat, `null` for a passenger seat
+     * (they ride but do not steer), and the rider themselves when not mounted at all.
+     */
+    driveTarget(riderId: string): string | null;
+}
+export declare function createMountController(): MountController;

package/dist/scene/mount.js

@@ -0,0 +1,107 @@
+const DEFAULT_SEAT = { id: "driver", offset: [0, 0, 0], control: true };
+/**
+ * Mount / rideable control-transfer (issue #83). Registers rideables (each with one or more seats — a
+ * control seat drives, the rest ride) and tracks who is on what. It owns no camera or physics: game code
+ * reads `cameraTarget(riderId)` to point the follow camera at the mount, and `driveTarget(riderId)` to
+ * route that rider's {@link import("../physics/vehicleBody.js").AxisInput}-driven input at the mount's
+ * movement kit — the same seam a horse, a truck, or a shared multi-seat ship all plug into.
+ */
+export class MountController {
+    mounts = new Map();
+    seatOfRider = new Map();
+    register(config) {
+        const seats = config.seats !== undefined && config.seats.length > 0 ? config.seats : [DEFAULT_SEAT];
+        this.mounts.set(config.id, { config, seats, bySeat: new Map() });
+    }
+    isRegistered(mountId) {
+        return this.mounts.has(mountId);
+    }
+    kitOf(mountId) {
+        return this.mounts.get(mountId)?.config.kit ?? null;
+    }
+    seatsOf(mountId) {
+        return this.mounts.get(mountId)?.seats ?? [];
+    }
+    firstFreeSeat(reg) {
+        const control = reg.seats.find((s) => s.control === true && !reg.bySeat.has(s.id));
+        if (control !== undefined)
+            return control;
+        return reg.seats.find((s) => !reg.bySeat.has(s.id)) ?? null;
+    }
+    mount(riderId, mountId, seatId) {
+        const reg = this.mounts.get(mountId);
+        if (reg === undefined)
+            return { ok: false, reason: "unknown_mount" };
+        const seat = seatId !== undefined ? reg.seats.find((s) => s.id === seatId) : this.firstFreeSeat(reg);
+        if (seat === undefined)
+            return { ok: false, reason: "unknown_seat" };
+        if (seat === null)
+            return { ok: false, reason: "mount_full" };
+        if (reg.bySeat.has(seat.id))
+            return { ok: false, reason: "seat_taken" };
+        this.dismount(riderId);
+        reg.bySeat.set(seat.id, riderId);
+        this.seatOfRider.set(riderId, { mountId, seatId: seat.id });
+        return { ok: true, seat };
+    }
+    dismount(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        if (ref === undefined)
+            return null;
+        this.mounts.get(ref.mountId)?.bySeat.delete(ref.seatId);
+        this.seatOfRider.delete(riderId);
+        return ref.mountId;
+    }
+    seatOf(riderId) {
+        return this.seatOfRider.get(riderId) ?? null;
+    }
+    isSeated(riderId) {
+        return this.seatOfRider.has(riderId);
+    }
+    seatOffset(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        if (ref === undefined)
+            return null;
+        return this.mounts.get(ref.mountId)?.seats.find((s) => s.id === ref.seatId)?.offset ?? null;
+    }
+    occupants(mountId) {
+        const reg = this.mounts.get(mountId);
+        if (reg === undefined)
+            return [];
+        return reg.seats
+            .filter((s) => reg.bySeat.has(s.id))
+            .map((s) => ({ riderId: reg.bySeat.get(s.id), seatId: s.id }));
+    }
+    driver(mountId) {
+        const reg = this.mounts.get(mountId);
+        if (reg === undefined)
+            return null;
+        for (const seat of reg.seats) {
+            if (seat.control === true) {
+                const rider = reg.bySeat.get(seat.id);
+                if (rider !== undefined)
+                    return rider;
+            }
+        }
+        return null;
+    }
+    /** Entity the follow camera should track for this rider: the mount when seated, else the rider. */
+    cameraTarget(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        return ref === undefined ? riderId : ref.mountId;
+    }
+    /**
+     * Entity this rider's input drives: the mount when in a control seat, `null` for a passenger seat
+     * (they ride but do not steer), and the rider themselves when not mounted at all.
+     */
+    driveTarget(riderId) {
+        const ref = this.seatOfRider.get(riderId);
+        if (ref === undefined)
+            return riderId;
+        const seat = this.mounts.get(ref.mountId)?.seats.find((s) => s.id === ref.seatId);
+        return seat?.control === true ? ref.mountId : null;
+    }
+}
+export function createMountController() {
+    return new MountController();
+}

package/dist/scene/possession.d.ts

@@ -0,0 +1,30 @@
+import type { SceneEntity } from "./entityStore.js";
+export interface PossessionSwappedEvent {
+    userId: string;
+    entityId: string;
+    previousEntityId: string;
+}
+export interface PossessionEntities {
+    get(id: string): SceneEntity | null;
+    update(id: string, patch: {
+        role?: SceneEntity["role"];
+    }): boolean;
+}
+export interface PossessionEvents {
+    emit(name: "possession.swapped", payload: PossessionSwappedEvent): void;
+}
+export interface PossessionDeps {
+    entities: PossessionEntities;
+    events?: PossessionEvents;
+}
+export interface Possession {
+    own(userId: string, entityId: string): void;
+    disown(userId: string, entityId: string): void;
+    owns(userId: string, entityId: string): boolean;
+    listOwned(userId: string): readonly string[];
+    active(userId: string): string;
+    possess(userId: string, entityId: string): {
+        reason: string;
+    } | null;
+}
+export declare function createPossession(deps: PossessionDeps): Possession;

package/dist/scene/possession.js

@@ -0,0 +1,51 @@
+export function createPossession(deps) {
+    const owned = new Map();
+    const activeByUser = new Map();
+    function ownedSet(userId) {
+        let set = owned.get(userId);
+        if (set === undefined) {
+            set = new Set([userId]);
+            owned.set(userId, set);
+        }
+        return set;
+    }
+    return {
+        own(userId, entityId) {
+            ownedSet(userId).add(entityId);
+        },
+        disown(userId, entityId) {
+            if (entityId === userId)
+                return;
+            ownedSet(userId).delete(entityId);
+            if (activeByUser.get(userId) === entityId)
+                activeByUser.delete(userId);
+        },
+        owns(userId, entityId) {
+            return ownedSet(userId).has(entityId);
+        },
+        listOwned(userId) {
+            return Array.from(ownedSet(userId));
+        },
+        active(userId) {
+            return activeByUser.get(userId) ?? userId;
+        },
+        possess(userId, entityId) {
+            if (!ownedSet(userId).has(entityId)) {
+                return { reason: `entity "${entityId}" is not owned by "${userId}"` };
+            }
+            if (deps.entities.get(entityId) === null) {
+                return { reason: `entity "${entityId}" is not spawned` };
+            }
+            const previousEntityId = activeByUser.get(userId) ?? userId;
+            if (previousEntityId === entityId)
+                return null;
+            activeByUser.set(userId, entityId);
+            if (deps.entities.get(previousEntityId) !== null) {
+                deps.entities.update(previousEntityId, { role: "npc" });
+            }
+            deps.entities.update(entityId, { role: "player" });
+            deps.events?.emit("possession.swapped", { userId, entityId, previousEntityId });
+            return null;
+        },
+    };
+}

package/dist/scene/roster.d.ts

@@ -0,0 +1,25 @@
+export interface RosterEntry {
+    id: string;
+    catalogId: string;
+    capturedAt: number;
+    equipped: boolean;
+}
+export interface RosterCaptureOptions {
+    id?: string;
+    capturedAt?: number;
+}
+export interface Roster {
+    capture(userId: string, catalogId: string, options?: RosterCaptureOptions): RosterEntry;
+    release(userId: string, entryId: string): boolean;
+    has(userId: string, entryId: string): boolean;
+    get(userId: string, entryId: string): RosterEntry | null;
+    list(userId: string): readonly RosterEntry[];
+    equippedList(userId: string): readonly RosterEntry[];
+    setEquipped(userId: string, entryId: string, equipped: boolean): RosterEntry | null;
+    snapshot(userId: string): readonly RosterEntry[];
+    hydrate(userId: string, entries: readonly RosterEntry[]): void;
+}
+export interface RosterDeps {
+    now?: () => number;
+}
+export declare function createRoster(deps?: RosterDeps): Roster;

package/dist/scene/roster.js

@@ -0,0 +1,57 @@
+export function createRoster(deps = {}) {
+    const now = deps.now ?? Date.now;
+    const rosters = new Map();
+    let counter = 0;
+    function requireEntries(userId) {
+        let entries = rosters.get(userId);
+        if (entries === undefined) {
+            entries = new Map();
+            rosters.set(userId, entries);
+        }
+        return entries;
+    }
+    return {
+        capture(userId, catalogId, options = {}) {
+            counter += 1;
+            const id = options.id ?? `roster_${counter}`;
+            const entry = {
+                id,
+                catalogId,
+                capturedAt: options.capturedAt ?? now(),
+                equipped: false,
+            };
+            requireEntries(userId).set(id, entry);
+            return entry;
+        },
+        release(userId, entryId) {
+            return rosters.get(userId)?.delete(entryId) ?? false;
+        },
+        has(userId, entryId) {
+            return rosters.get(userId)?.has(entryId) ?? false;
+        },
+        get(userId, entryId) {
+            return rosters.get(userId)?.get(entryId) ?? null;
+        },
+        list(userId) {
+            return Array.from(rosters.get(userId)?.values() ?? []);
+        },
+        equippedList(userId) {
+            return Array.from(rosters.get(userId)?.values() ?? []).filter((entry) => entry.equipped);
+        },
+        setEquipped(userId, entryId, equipped) {
+            const entries = rosters.get(userId);
+            const entry = entries?.get(entryId);
+            if (entries === undefined || entry === undefined)
+                return null;
+            const next = { ...entry, equipped };
+            entries.set(entryId, next);
+            return next;
+        },
+        snapshot(userId) {
+            return Array.from(rosters.get(userId)?.values() ?? []);
+        },
+        hydrate(userId, entries) {
+            rosters.set(userId, new Map(entries.map((entry) => [entry.id, entry])));
+        },
+    };
+}

package/dist/scene/selection.d.ts

@@ -0,0 +1,30 @@
+export interface ScreenRect {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface ScreenPoint {
+    id: string;
+    x: number;
+    y: number;
+}
+/** Normalize two drag corners (in any order) into a rectangle. */
+export declare function screenRect(ax: number, ay: number, bx: number, by: number): ScreenRect;
+export declare function rectContainsPoint(rect: ScreenRect, x: number, y: number): boolean;
+/** Ids of the projected candidates whose screen point falls inside the marquee. */
+export declare function selectWithinRect(candidates: readonly ScreenPoint[], rect: ScreenRect): string[];
+/** True when the drag is large enough to be a marquee rather than a click. */
+export declare function isMarquee(rect: ScreenRect, thresholdPx?: number): boolean;
+export interface SelectionSet {
+    add(id: string): void;
+    remove(id: string): void;
+    toggle(id: string): void;
+    has(id: string): boolean;
+    replace(ids: Iterable<string>): void;
+    clear(): void;
+    list(): string[];
+    size(): number;
+}
+/** An ordered, deduplicated set of selected instance ids for RTS unit-command routing. */
+export declare function createSelectionSet(initial?: Iterable<string>): SelectionSet;

package/dist/scene/selection.js

@@ -0,0 +1,38 @@
+/** Normalize two drag corners (in any order) into a rectangle. */
+export function screenRect(ax, ay, bx, by) {
+    return {
+        minX: Math.min(ax, bx),
+        minY: Math.min(ay, by),
+        maxX: Math.max(ax, bx),
+        maxY: Math.max(ay, by),
+    };
+}
+export function rectContainsPoint(rect, x, y) {
+    return x >= rect.minX && x <= rect.maxX && y >= rect.minY && y <= rect.maxY;
+}
+/** Ids of the projected candidates whose screen point falls inside the marquee. */
+export function selectWithinRect(candidates, rect) {
+    return candidates.filter((candidate) => rectContainsPoint(rect, candidate.x, candidate.y)).map((c) => c.id);
+}
+/** True when the drag is large enough to be a marquee rather than a click. */
+export function isMarquee(rect, thresholdPx = 4) {
+    return rect.maxX - rect.minX >= thresholdPx || rect.maxY - rect.minY >= thresholdPx;
+}
+/** An ordered, deduplicated set of selected instance ids for RTS unit-command routing. */
+export function createSelectionSet(initial) {
+    const ids = new Set(initial);
+    return {
+        add: (id) => void ids.add(id),
+        remove: (id) => void ids.delete(id),
+        toggle: (id) => (ids.has(id) ? ids.delete(id) : ids.add(id)),
+        has: (id) => ids.has(id),
+        replace(next) {
+            ids.clear();
+            for (const id of next)
+                ids.add(id);
+        },
+        clear: () => ids.clear(),
+        list: () => Array.from(ids),
+        size: () => ids.size,
+    };
+}

package/dist/scene/stationClaim.d.ts

@@ -0,0 +1,43 @@
+import { MountController, type MountKit } from "./mount.js";
+export interface Station {
+    id: string;
+    facet: string;
+    offset: readonly [number, number, number];
+    control?: boolean;
+}
+export interface SharedVehicleConfig {
+    id: string;
+    kit: MountKit;
+    stations: readonly Station[];
+}
+export type ClaimResult = {
+    ok: true;
+    station: Station;
+} | {
+    ok: false;
+    reason: "unknown_vehicle" | "unknown_facet" | "station_taken" | "vehicle_full";
+};
+export declare class StationClaim {
+    private readonly controller;
+    private readonly vehicles;
+    constructor(controller?: MountController);
+    register(config: SharedVehicleConfig): void;
+    private resolveStation;
+    claim(playerId: string, vehicleId: string, facetOrStationId: string): ClaimResult;
+    release(playerId: string): string | null;
+    facetOf(playerId: string): string | null;
+    stationOf(playerId: string): Station | null;
+    controllerOf(vehicleId: string, facet: string): string | null;
+    crew(vehicleId: string): {
+        playerId: string;
+        stationId: string;
+        facet: string;
+    }[];
+    stationsOf(vehicleId: string): readonly Station[];
+    openFacets(vehicleId: string): string[];
+    driver(vehicleId: string): string | null;
+    cameraTarget(playerId: string): string;
+    driveTarget(playerId: string): string | null;
+    get mounts(): MountController;
+}
+export declare function createStationClaim(controller?: MountController): StationClaim;

package/dist/scene/stationClaim.js

@@ -0,0 +1,109 @@
+import { createMountController, MountController } from "./mount.js";
+export class StationClaim {
+    controller;
+    vehicles = new Map();
+    constructor(controller) {
+        this.controller = controller ?? createMountController();
+    }
+    register(config) {
+        const byStationId = new Map();
+        const facetToStation = new Map();
+        for (const station of config.stations) {
+            byStationId.set(station.id, station);
+            if (!facetToStation.has(station.facet))
+                facetToStation.set(station.facet, station.id);
+        }
+        this.vehicles.set(config.id, { config, byStationId, facetToStation });
+        this.controller.register({
+            id: config.id,
+            kit: config.kit,
+            seats: config.stations.map((station) => ({
+                id: station.id,
+                offset: station.offset,
+                control: station.control,
+            })),
+        });
+    }
+    resolveStation(vehicle, facetOrStationId) {
+        const direct = vehicle.byStationId.get(facetOrStationId);
+        if (direct !== undefined)
+            return direct;
+        const stationId = vehicle.facetToStation.get(facetOrStationId);
+        if (stationId === undefined)
+            return null;
+        return vehicle.byStationId.get(stationId) ?? null;
+    }
+    claim(playerId, vehicleId, facetOrStationId) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return { ok: false, reason: "unknown_vehicle" };
+        const station = this.resolveStation(vehicle, facetOrStationId);
+        if (station === null)
+            return { ok: false, reason: "unknown_facet" };
+        const result = this.controller.mount(playerId, vehicleId, station.id);
+        if (!result.ok) {
+            return { ok: false, reason: result.reason === "seat_taken" ? "station_taken" : "vehicle_full" };
+        }
+        return { ok: true, station };
+    }
+    release(playerId) {
+        return this.controller.dismount(playerId);
+    }
+    facetOf(playerId) {
+        const ref = this.controller.seatOf(playerId);
+        if (ref === null)
+            return null;
+        return this.vehicles.get(ref.mountId)?.byStationId.get(ref.seatId)?.facet ?? null;
+    }
+    stationOf(playerId) {
+        const ref = this.controller.seatOf(playerId);
+        if (ref === null)
+            return null;
+        return this.vehicles.get(ref.mountId)?.byStationId.get(ref.seatId) ?? null;
+    }
+    controllerOf(vehicleId, facet) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return null;
+        for (const occupant of this.controller.occupants(vehicleId)) {
+            if (vehicle.byStationId.get(occupant.seatId)?.facet === facet)
+                return occupant.riderId;
+        }
+        return null;
+    }
+    crew(vehicleId) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return [];
+        return this.controller.occupants(vehicleId).map((occupant) => ({
+            playerId: occupant.riderId,
+            stationId: occupant.seatId,
+            facet: vehicle.byStationId.get(occupant.seatId)?.facet ?? "",
+        }));
+    }
+    stationsOf(vehicleId) {
+        return this.vehicles.get(vehicleId)?.config.stations ?? [];
+    }
+    openFacets(vehicleId) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return [];
+        const taken = new Set(this.controller.occupants(vehicleId).map((o) => o.seatId));
+        return vehicle.config.stations.filter((s) => !taken.has(s.id)).map((s) => s.facet);
+    }
+    driver(vehicleId) {
+        return this.controller.driver(vehicleId);
+    }
+    cameraTarget(playerId) {
+        return this.controller.cameraTarget(playerId);
+    }
+    driveTarget(playerId) {
+        return this.controller.driveTarget(playerId);
+    }
+    get mounts() {
+        return this.controller;
+    }
+}
+export function createStationClaim(controller) {
+    return new StationClaim(controller);
+}