@jgengine/core 0.8.0 → 0.10.0

package/dist/render/postProcessing.d.ts

@@ -0,0 +1,56 @@
+/** Renderer tone-mapping curve applied by the post chain's output stage. */
+export type ToneMappingMode = "aces" | "agx" | "reinhard" | "cineon" | "linear" | "none";
+/** UnrealBloom stage — soft HDR glow around bright pixels (sun, glints, emissive). */
+export interface BloomConfig {
+    /** Glow intensity. Default 0.32. */
+    strength?: number;
+    /** Glow spread radius, 0..1. Default 0.55. */
+    radius?: number;
+    /** Luminance above which a pixel blooms, 0..1. Default 0.85. */
+    threshold?: number;
+}
+/** Ground-truth ambient occlusion stage — darkens contact creases and cavities for depth. */
+export interface AoConfig {
+    /** Sample radius in world units. Default 1.8. */
+    radius?: number;
+    /** Occlusion strength multiplier. Default 2.4. */
+    intensity?: number;
+    /** Distance over which occlusion fades out, world units. Default 3.6. */
+    distanceFalloff?: number;
+    /** Blend the AO onto the beauty at this fraction, 0..1. Default 1. */
+    blend?: number;
+}
+/** Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping. */
+export interface GradeConfig {
+    /** Additive shadow tint (RGB, ~0..0.1). Default cool [0.012, 0.010, 0.018]. */
+    lift?: readonly [number, number, number];
+    /** Multiplicative highlight tint (RGB, ~1). Default warm [1.05, 1.02, 0.98]. */
+    gain?: readonly [number, number, number];
+    /** Output gamma. Default 0.96. */
+    gamma?: number;
+    /** Saturation multiplier around luma. Default 1.12. */
+    saturation?: number;
+    /** Vignette darkening strength at the corners, 0..1. Default 0.2. */
+    vignette?: number;
+    /** Animated film-grain amplitude. Default 0.012. */
+    grain?: number;
+}
+/**
+ * Declarative post-processing chain (RenderPass → AO → Bloom → tone-map output →
+ * Grade). Present on a game means the shell mounts an `EffectComposer` and owns
+ * the render; absent means the renderer draws directly (unchanged). Each stage is
+ * a config object, `false` to skip, or omitted for its default. Pure data — no
+ * three.js types leak into core.
+ */
+export interface PostProcessingConfig {
+    /** Master switch; a config object with `enabled: false` mounts nothing. Default true. */
+    enabled?: boolean;
+    /** Tone-mapping curve the output stage applies. Default "aces". */
+    toneMapping?: ToneMappingMode;
+    /** Exposure multiplier applied before tone mapping. Default 1. */
+    exposure?: number;
+    bloom?: BloomConfig | false;
+    /** Ambient occlusion. Heavier than the other stages — omit or `false` on low-end targets. Default off (omitted). */
+    ao?: AoConfig | false;
+    grade?: GradeConfig | false;
+}

package/dist/render/postProcessing.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/adapter.d.ts

@@ -1,52 +1,71 @@
 export type MultiplayerTopology = "shared" | "lobbies" | "private";
+/**
+ * Where the world simulation is authoritative. `"client"` (default) keeps the historical model — each client runs
+ * its own `onTick` and syncs only presence/feeds/chat. `"server"` opts into host-authoritative replication: the
+ * host runs the loop, and the shell mirrors the server's world into the local `ctx` instead of simulating locally.
+ */
+export type MultiplayerAuthority = "server" | "client";
 export type MultiplayerAdapterConfig = {
     kind: "convex";
     topology?: MultiplayerTopology;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "ws";
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "socketio";
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "p2p";
     topology?: MultiplayerTopology;
     room?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "lan";
     topology?: MultiplayerTopology;
     port?: number;
     path?: string;
+    authority?: MultiplayerAuthority;
 } | {
     kind: "offline";
 };
 export declare function convex(config?: {
     topology?: MultiplayerTopology;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function ws(config?: {
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function fly(config: {
     app: string;
     topology?: MultiplayerTopology;
     path?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function socketIo(config?: {
     topology?: MultiplayerTopology;
     url?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function p2p(config?: {
     topology?: MultiplayerTopology;
     room?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
 export declare function lan(config?: {
     topology?: MultiplayerTopology;
     port?: number;
     path?: string;
+    authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
+/** True when the adapter opts into host-authoritative world replication (`authority: "server"`). */
+export declare function isServerAuthoritative(multiplayer: unknown): boolean;
 export declare function offline(): MultiplayerAdapterConfig;
 export declare function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null;
 export declare function multiplayerAdapterKind(multiplayer: unknown): string | null;

package/dist/runtime/adapter.js

@@ -1,24 +1,30 @@
 export function convex(config) {
-    return { kind: "convex", topology: config?.topology ?? "shared" };
+    return { kind: "convex", topology: config?.topology ?? "shared", authority: config?.authority };
 }
 export function ws(config) {
-    return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url };
+    return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
 export function fly(config) {
     return {
         kind: "ws",
         topology: config.topology ?? "shared",
         url: `wss://${config.app}.fly.dev${config.path ?? "/ws"}`,
+        authority: config.authority,
     };
 }
 export function socketIo(config) {
-    return { kind: "socketio", topology: config?.topology ?? "shared", url: config?.url };
+    return { kind: "socketio", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
 export function p2p(config) {
-    return { kind: "p2p", topology: config?.topology ?? "private", room: config?.room };
+    return { kind: "p2p", topology: config?.topology ?? "private", room: config?.room, authority: config?.authority };
 }
 export function lan(config) {
-    return { kind: "lan", topology: config?.topology ?? "shared", port: config?.port, path: config?.path };
+    return { kind: "lan", topology: config?.topology ?? "shared", port: config?.port, path: config?.path, authority: config?.authority };
+}
+/** True when the adapter opts into host-authoritative world replication (`authority: "server"`). */
+export function isServerAuthoritative(multiplayer) {
+    const adapter = adapterOf(multiplayer);
+    return adapter !== null && "authority" in adapter && adapter.authority === "server";
 }
 export function offline() {
     return { kind: "offline" };

package/dist/runtime/cameraDirector.d.ts

@@ -1,10 +1,15 @@
-import type { CinematicCameraConfig } from "../game/playableGame.js";
+import type { ChaseCameraConfig, CinematicCameraConfig } from "../game/playableGame.js";
+/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11). */
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank">>;
 export interface CameraDirector {
     follow(entityId: string | null): void;
     /** `undefined` means no runtime override — the shell falls back to the static `playable.camera.followEntityId`. `null` means explicitly follow nothing. */
     followedEntityId(): string | null | undefined;
     setCinematic(config: CinematicCameraConfig | null): void;
     cinematic(): CinematicCameraConfig | null;
+    /** Overlay a runtime patch on the chase rig's config — a boss-intro pull-back, drift zoom-out; `null` restores the static config. */
+    setChaseTuning(tuning: ChaseCameraTuning | null): void;
+    chaseTuning(): ChaseCameraTuning | null;
     subscribe(listener: () => void): () => void;
 }
 export declare function createCameraDirector(): CameraDirector;

package/dist/runtime/cameraDirector.js

@@ -2,6 +2,7 @@ export function createCameraDirector() {
     const listeners = new Set();
     let followEntity = undefined;
     let cinematicConfig = null;
+    let chaseTuningPatch = null;
     function notify() {
         for (const listener of listeners)
             listener();
@@ -17,6 +18,11 @@ export function createCameraDirector() {
             notify();
         },
         cinematic: () => cinematicConfig,
+        setChaseTuning(tuning) {
+            chaseTuningPatch = tuning;
+            notify();
+        },
+        chaseTuning: () => chaseTuningPatch,
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);

package/dist/runtime/commandRunner.d.ts

@@ -2,8 +2,8 @@ export type CommandValidationError = {
     reason: string;
 };
 export type CommandDef<TInput = unknown> = {
-    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput) => CommandValidationError | null;
-    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput) => import("./snapshot.js").GameRuntimeSnapshot;
+    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => CommandValidationError | null;
+    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => import("./snapshot.js").GameRuntimeSnapshot;
 };
 export type RunCommandResult = {
     ok: true;

package/dist/runtime/commandRunner.js

@@ -3,11 +3,11 @@ export function runCommand(snapshot, commands, commandName, input, actorUserId)
     if (!command) {
         return { ok: false, reason: `Unknown command: ${commandName}` };
     }
-    const validationError = command.validate(snapshot, input);
+    const validationError = command.validate(snapshot, input, actorUserId);
     if (validationError) {
         return { ok: false, reason: validationError.reason };
     }
-    const next = command.apply(snapshot, input);
+    const next = command.apply(snapshot, input, actorUserId);
     return {
         ok: true,
         snapshot: {

package/dist/runtime/gameContext.d.ts

@@ -28,18 +28,23 @@ import { type PoseAllowedStates, type PoseState } from "../movement/poseState.js
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
 import { type PaintLayer } from "../scene/paintLayer.js";
 import { type EntityStatsApi, type StatCatalog } from "../scene/entityStats.js";
-import type { EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
+import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import { type Forms } from "../scene/form.js";
+import { type EntityColliderSet } from "../scene/colliders.js";
 import { type ObjectRaycastHit, type ObjectRaycastInput } from "../scene/objectQuery.js";
 import { type ObjectStore } from "../scene/objectStore.js";
 import { type Roster } from "../scene/roster.js";
+import { type ConnectedPlayers } from "../game/connectedPlayers.js";
 import { type Possession } from "../scene/possession.js";
+import { type SceneRaycastHit, type SceneRaycastInput } from "../scene/sceneRaycast.js";
 import { type SpatialApi } from "../scene/spatial.js";
 import { type CycleTargetOptions } from "../scene/targeting.js";
 import { type Stats } from "../stats/statModifiers.js";
 import { type ObservableKeyedStore } from "../store/observableKeyedStore.js";
+import { type WorldSnapshot } from "./worldSnapshot.js";
 import { type SimClock } from "../time/simClock.js";
 import { type TurnLoop, type TurnLoopConfig } from "../turn/turnLoop.js";
+import { RaceState, type RaceStateConfig } from "../game/race.js";
 import { type CameraDirector } from "./cameraDirector.js";
 import { type InputSnapshot } from "./inputSnapshot.js";
 import { type MotionIntents } from "./motionIntents.js";
@@ -63,6 +68,8 @@ export interface GameContextEntityEntry {
     role?: CatalogEntityRole;
     /** Right-click context-menu verbs for this entity (#31). */
     verbs?: readonly ContextVerb[];
+    /** Purpose-specific colliders (physical body + named damage hitboxes). */
+    colliders?: EntityColliderSet;
 }
 export interface GameContextObjectEntry {
     proximityPrompt?: ProximityPrompt;
@@ -72,6 +79,8 @@ export interface GameContextObjectEntry {
     slotInventory?: InventoryLayout;
     /** Right-click context-menu verbs for this object (#31). */
     verbs?: readonly ContextVerb[];
+    colliders?: EntityColliderSet;
+    halfExtents?: readonly [number, number, number];
 }
 export interface GameContextContent {
     itemById?(itemId: string): GameContextItemEntry | null | undefined;
@@ -86,11 +95,14 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
         isNew: boolean;
     };
     now?: () => number;
+    occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
 }
 export interface SceneObjectContext extends ObjectStore {
     catalog(instanceId: string): GameContextObjectEntry | null;
     raycast(input: ObjectRaycastInput): ObjectRaycastHit | null;
     raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[];
+    setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
+    collidersOf(instanceId: string): EntityColliderSet | null;
 }
 export interface FloatTextInput {
     instanceId?: string;
@@ -129,11 +141,13 @@ export interface SceneEntityContext {
     despawn(instanceId: string): boolean;
     update: EntityStore["update"];
     setPose(instanceId: string, pose: EntityPose): boolean;
+    setPoseConstraint: EntityStore["setPoseConstraint"];
     get(instanceId: string): SceneEntity | null;
     list(): readonly SceneEntity[];
     spawnPoseOf(instanceId: string): SpawnPose | null;
     resetToSpawn(instanceId: string): boolean;
     resetAllToSpawn(filter?: (entity: SceneEntity) => boolean): number;
+    blackboard: EntityBlackboard;
     stats: EntityStatsApi;
     floatText(input: FloatTextInput): void;
     telegraph(input: TelegraphInput): () => void;
@@ -152,6 +166,9 @@ export interface SceneEntityContext {
     hasLineOfSight: SpatialApi["hasLineOfSight"];
     queryArc: SpatialApi["queryArc"];
     moveToward: SpatialApi["moveToward"];
+    invalidateSpatial: SpatialApi["invalidate"];
+    setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
+    collidersOf(instanceId: string): EntityColliderSet | null;
     form: Forms;
     paint: PaintLayer;
 }
@@ -175,6 +192,10 @@ export interface GameContextCommands {
     has(name: string): boolean;
     names(): string[];
     run(name: string, input: unknown): CommandResult<GameContext>;
+    /** Run a command attributed to `actorUserId` — a shared-world host routes each client's command through this so the handler can read {@link actor}. */
+    runAs(actorUserId: string, name: string, input: unknown): CommandResult<GameContext>;
+    /** The user a command is running on behalf of, or `null` outside a {@link runAs} call — commands default to `ctx.player.userId` when this is `null`. */
+    actor(): string | null;
 }
 export interface GameContextFeed extends Omit<GameFeed, "bind"> {
     bind(action: keyof GameEventMap): () => void;
@@ -210,36 +231,69 @@ export interface GameContextTurn {
     /** Lazily creates (on first call, `config` required) or returns the existing notify-wrapped turn loop for `id`. */
     loop(id: string, config?: TurnLoopConfig): TurnLoop;
 }
+export interface GameContextRace {
+    /** Lazily creates (on first call, `config` required) or returns the existing reactive race for `id` — discrete mutations and eventful `update` calls bump `ctx.version()`, so HUDs stop hand-managing `store.set` (#286.2). */
+    state(id: string, config?: RaceStateConfig): RaceState;
+}
+/** Reachable audio seam on `ctx.game`: `play`, `music`, and `resume` route through the `audio.play`/`audio.music`/`audio.resume` events the shell's audio engine listens on, so game code triggers sound without importing the shell. */
+export interface GameAudio {
+    play(sound: string, at?: readonly [number, number, number]): void;
+    /** Crossfade the procedural soundtrack to `theme` (null fades out); `transpose` shifts the incoming theme's key in semitones. */
+    music(theme: string | null, transpose?: number): void;
+    resume(): void;
+}
 export interface GameContext {
     scene: {
         object: SceneObjectContext;
         entity: SceneEntityContext;
         worldItem: SceneWorldItemContext;
+        raycast(input: SceneRaycastInput): SceneRaycastHit | null;
+        raycastAll(input: SceneRaycastInput): readonly SceneRaycastHit[];
     };
     world: GameContextWorld;
     game: {
         commands: GameContextCommands;
         events: GameEvents;
+        audio: GameAudio;
+        /** Play a model's one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an attack swing) — emits `entity.animation` for the shell to pick up. */
+        playEntityAnimation(instanceId: string, event: string): void;
         feed: GameContextFeed;
         loot: GameContextLoot;
         trade: TradeSystem;
         quest: QuestJournal;
-        social: Social;
-        chat: Chat;
+        /** Friends/party/presence/emotes/world-invites — present only when `features.social` is set. */
+        social?: Social;
+        /** Channels + messages — present only when `features.chat` is set (implies `social`). */
+        chat?: Chat;
         unlocks: Unlocks;
         economy: GameContextEconomy;
-        leaderboard: Leaderboard;
-        roster: Roster;
+        /** Competitive score tracking — present only when `features.leaderboard` is set. */
+        leaderboard?: Leaderboard;
+        /** Owned-entity roster — present only when `features.roster` is set. */
+        roster?: Roster;
         /** Game-defined keyed reactive store slot (#163.1); mutations bump `ctx.version()`/notify `ctx.subscribe`. */
         store: ObservableKeyedStore<unknown>;
-        cards: GameContextCards;
-        turn: GameContextTurn;
+        /** Card pile zones — present only when `features.cards` is set. */
+        cards?: GameContextCards;
+        /** Turn/phase loop — present only when `features.turn` is set. */
+        turn?: GameContextTurn;
+        /** Lap/checkpoint race state — present only when `features.race` is set. */
+        race?: GameContextRace;
+        /** Connected-player set for a shared world — present only when `features.players` is set. */
+        players?: ConnectedPlayers;
     };
     player: {
+        /** The acting player's id — the command actor inside `runAs`, the local player everywhere else. */
         userId: string;
         isNew: boolean;
+        /** The acting player's inventory set — the command actor's bags inside `runAs`, the local player's everywhere else. */
         inventory: InventorySet<string>;
+        /** A specific player's inventory set — how a host reads or grants into any connected player's bags. */
+        inventoryFor(userId: string): InventorySet<string>;
+        /** The acting player's stat modifiers — the command actor's inside `runAs`, the local player's everywhere else. */
         stats: Stats<string>;
+        /** A specific player's stat modifiers — how a host reads or buffs any connected player's stats. */
+        statsFor(userId: string): Stats<string>;
         loadout: Loadouts;
         applyLoadout(userId: string, loadoutId: string): {
             reason: string;
@@ -247,8 +301,10 @@ export interface GameContext {
         movement: PoseState;
         possession: Possession;
         cosmetics: Cosmetics;
-        /** Vertical-motion seam into the shell-owned FrameDriver (#162.4); see `MotionIntents`. */
+        /** Motion seam into the movement integrator (#162.4); routes to the command actor's queue (or the local player outside a command), so a command's impulse lands on whoever ran it. See `MotionIntents`. */
         motion: MotionIntents;
+        /** A specific player's motion queue — how the host-side per-player movement integrator drains each connected player's impulses. */
+        motionFor(userId: string): MotionIntents;
     };
     item: {
         use: GameContextItemUse;
@@ -261,5 +317,13 @@ export interface GameContext {
     input: InputSnapshot;
     subscribe(listener: () => void): () => void;
     version(): number;
+    /**
+     * Gather every opted-in live subsystem into one {@link WorldSnapshot} — entities, entity stats, the
+     * keyed store, the action feed, plus leaderboard/chat when those features are on. The full-world
+     * baseline a host sends a joining client; {@link hydrate} is its inverse.
+     */
+    snapshot(): WorldSnapshot;
+    /** Apply a {@link WorldSnapshot} from an authoritative host, hydrating each subsystem key present in it. */
+    hydrate(snapshot: WorldSnapshot): void;
 }
 export declare function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext;