@jgengine/core 0.7.0 → 0.8.0

package/dist/game/playableGame.d.ts

@@ -1,7 +1,9 @@
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
+import type { TouchControlsConfig } from "../input/touchScheme.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
-import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
+import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
+import type { SkyEnvironmentConfig } from "../world/features.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
 import type { LootFilterRule } from "./lootFilter.js";
 import type { RarityStyle } from "./worldItem.js";
@@ -25,6 +27,8 @@ export interface PointerConfig {
     grabWorldItems?: boolean;
     /** Press the bound `ping` action → `worldHit()` → run this command with `{ point, entity, object, normal }` (contextual ping, #94). */
     pingCommand?: string;
+    /** Right-click runs this command with `{ point, entity, object, aim }` when neither `orderCommand` nor `contextMenu` claims the click (#164.4). */
+    secondaryCommand?: string;
 }
 export interface CameraFollowState {
     entityId: string;
@@ -65,13 +69,31 @@ export interface FirstPersonCameraConfig {
  * - `lockOn` — yaw bound to the player→target vector; move axis becomes strafe.
  * - `chase` — speed-reactive vehicle chase (speed→FOV, spring arm, shake) + cockpit/hood/rear views.
  * - `observer` — detached spectator/photo cam bound to any entity or fixed point; never reads player input.
+ * - `turntable` — slow auto-orbit of a fixed point: a rotating display stand for a scene. The friendly, flat spelling of `observer`'s point-orbit mode; providing `camera.turntable` selects it without an explicit `rig`.
+ * - `sideScroll` — fixed lateral follow (2.5D platformer/beat-'em-up side view); reads no player input.
+ * - `inspection` — model-viewer rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input.
+ * - `none` — no camera rig is mounted; use for HUD-only presentations or a game that manages its own camera.
  */
-export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer";
+export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
+/** Fixed lateral 2.5D follow (side-on platformer cam): the camera sits perpendicular to the travel axis, tracks the followed entity, and never reads player look input. */
+export interface SideScrollCameraConfig {
+    /** World axis the action travels along; the camera watches from the perpendicular side. Default "x". */
+    axis?: "x" | "z";
+    /** Camera distance from the followed entity along the perpendicular axis. Default 10. */
+    distance?: number;
+    /** Camera height above the followed entity. Default 3. */
+    height?: number;
+    /** Height of the look point above the entity. Default 1. */
+    lookHeight?: number;
+    /** Per-second smoothing factor for the follow (0 hard-locks). Default 8. */
+    followSmoothing?: number;
+    fov?: number;
+}
 /** Fixed top-down / isometric rig (#23) — height/pitch/yaw + decoupled follow. */
 export interface TopDownCameraConfig {
     /** Camera height above the follow point. Default 18. */
     height?: number;
-    /** Look-down angle in radians (0 = straight down, PI/2 = level). Default ~1.02 (~58°, ARPG iso). */
+    /** Elevation of the camera above the ground plane in radians (PI/2 = straight down, near 0 = grazing; values below 0.05 clamp to 0.05). Default ~1.02 (~58°, ARPG iso). */
     pitch?: number;
     /** Fixed azimuth in radians; ~PI/4 reads as isometric, 0 as straight top-down. Default PI/4. */
     yaw?: number;
@@ -113,6 +135,8 @@ export interface RtsCameraConfig extends TopDownCameraConfig {
         x?: number;
         z?: number;
     };
+    /** Read WASD/arrow pan, edge-scroll, Q/E rotate, and wheel zoom. `false` sits static at the start/bounds position — a backdrop camera, no input at all. Default true. */
+    pan?: boolean;
 }
 /** Over-the-shoulder combat rig (#25) — offset, ADS, shoulder swap, decoupled reticle. */
 export interface ShoulderCameraConfig {
@@ -225,6 +249,70 @@ export interface ObserverCameraConfig {
     startAngle?: number;
     fov?: number;
 }
+/**
+ * Turntable / showcase rig — slowly auto-orbits a fixed world point (no player
+ * input), the way a museum turntable rotates an object on display. A flat,
+ * self-describing spelling of `observer`'s point-orbit mode: `target` names the
+ * point directly instead of `bind: { kind: "point", position }`. Set
+ * `camera.turntable` and the rig is inferred — you don't also write `rig`.
+ */
+export interface TurntableCameraConfig {
+    /** World point the camera circles. Default the world origin. */
+    target?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Orbit radius from the target. Default 8. */
+    distance?: number;
+    /** Camera height above the target. Default 3. */
+    height?: number;
+    /** Height of the look point above the target. Default 1.2. */
+    lookHeight?: number;
+    /** Radians/second of rotation; 0 holds a fixed angle. Default 0.2. */
+    orbitSpeed?: number;
+    /** Starting angle in radians. Default 0. */
+    startAngle?: number;
+    fov?: number;
+}
+/**
+ * How scroll-zoom re-anchors the view for the inspection rig (#207.7):
+ * - `target` — dolly toward the orbit target (classic OrbitControls behavior).
+ * - `cursor` — dolly toward the point under the pointer.
+ * - `center` — dolly toward the viewport center; equivalent to `target` for an
+ *   OrbitControls-driven rig, since the camera always faces `target` and that
+ *   point already projects to the exact center of the viewport.
+ */
+export type InspectionZoomAnchor = "target" | "cursor" | "center";
+/** Model-viewer / inspection rig (#207.7) — orbit + pan + anchored zoom around a fixed point, never reads player input. */
+export interface InspectionCameraConfig {
+    /** Where scroll-zoom re-anchors the view. Default "target". */
+    anchor?: InspectionZoomAnchor;
+    /** Orbit target (the point orbited/panned around). Default origin. */
+    target?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Camera distance from `target` used to seed the initial camera position when `initialPosition` is unset. Default 6. */
+    initialDistance?: number;
+    /** Explicit starting camera world position; overrides `initialDistance` when set. */
+    initialPosition?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    minDistance?: number;
+    maxDistance?: number;
+    /** Vertical orbit clamp (radians). Unset allows a full pole-to-pole orbit, unlike the tighter default on the classic orbit rig. */
+    minPolarAngle?: number;
+    maxPolarAngle?: number;
+    /** Middle-mouse/right-drag pan. Default true for this rig. */
+    pan?: boolean;
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+    dampingFactor?: number;
+}
 /** One stop on a scripted camera path (#29). */
 export interface CameraKeyframe {
     position: {
@@ -262,9 +350,20 @@ export interface CameraShakeConfig {
     /** Noise frequency (Hz) of the shake oscillation. Default 24. */
     frequency?: number;
 }
+export declare const CAMERA_FRUSTUM_DEFAULTS: {
+    readonly fov: 55;
+    readonly near: 0.1;
+    readonly far: 300;
+};
 export interface GameCameraConfig {
     /** Selects the rig. Overrides `perspective`; leave unset to fall back to `perspective`. */
     rig?: CameraRigKind;
+    /** Render frustum overrides applied to the canvas camera. `far` defaults to 300 — raise it for worlds whose content spans more than a few hundred units, or distant scenery silently clips. */
+    frustum?: {
+        fov?: number;
+        near?: number;
+        far?: number;
+    };
     /** "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. Shorthand for `rig: "orbit" | "first"`. */
     perspective?: "third" | "first";
     /** First-person tuning; only read when the rig resolves to "first". */
@@ -281,6 +380,12 @@ export interface GameCameraConfig {
     chase?: ChaseCameraConfig;
     /** Detached spectator/photo cam tuning (#120); read when `rig: "observer"`. */
     observer?: ObserverCameraConfig;
+    /** Turntable / showcase tuning; setting this selects the `turntable` rig on its own. */
+    turntable?: TurntableCameraConfig;
+    /** Fixed side-on follow tuning; read when `rig: "sideScroll"`. */
+    sideScroll?: SideScrollCameraConfig;
+    /** Model-viewer / inspection tuning (#207.7); read when `rig: "inspection"`. */
+    inspection?: InspectionCameraConfig;
     /** Camera-shake / trauma channel defaults (#28); read by every rig. */
     shake?: CameraShakeConfig;
     /** Scripted keyframe path (#29); when set, plays over the active rig. */
@@ -331,6 +436,47 @@ export interface WorldItemRenderConfig {
     pickupRadius?: number;
     /** Beam height above the item's ground position. Default 2.5. */
     beamHeight?: number;
+    /** Walk-over collection: the shell grants the nearest dropped item within this radius of the local player each frame (Minecraft-style pickup). `true` uses `pickupRadius`. Omitted/false leaves pickup to `pointer.grabWorldItems` clicks. */
+    autoPickup?: boolean | {
+        radius?: number;
+    };
+}
+/**
+ * Player-vs-world collision for the first-person controller. Without this the
+ * shell keeps the player on flat ground at y=0. With `voxel: true` the shell
+ * resolves the player as a box against placed scene objects (each treated as a
+ * solid unit cell), so they stand on blocks, fall into holes, and are stopped by
+ * walls — the controller a block-building/mining game needs.
+ */
+export interface VoxelCollisionConfig {
+    voxel: true;
+    /** Half the player box width on each horizontal axis. Default 0.3. */
+    halfWidth?: number;
+    /** Player box height from the feet. Default 1.8. */
+    height?: number;
+    /** Tallest ledge walked up without jumping. Default 0.6. */
+    stepHeight?: number;
+}
+/** Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses. */
+export interface ModelAnimationConfig {
+    /** Clip name to play; defaults to the GLB's first clip. */
+    clip?: string;
+    /** Loop the clip. Default true. */
+    loop?: boolean;
+    /** Playback rate multiplier. Default 1. */
+    timeScale?: number;
+    /** Hold the rig on a fixed frame instead of advancing it each tick. */
+    paused?: boolean;
+    /** Seek the clip to this time in seconds; combine with `paused: true` to hold a specific pose ("pose library" usage). */
+    time?: number;
+}
+/** Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph. */
+export interface ModelMaterialOverride {
+    color?: string;
+    metalness?: number;
+    roughness?: number;
+    emissive?: string;
+    emissiveIntensity?: number;
 }
 export interface ModelConfig {
     url: string;
@@ -340,35 +486,109 @@ export interface ModelConfig {
     anchor?: "center" | "origin";
     /** Measured footprint/center/minY; supplied automatically when the model resolves through an `@jgengine/assets` catalog. Required for `anchor: "center"` to take effect. */
     dims?: ModelDims;
+    /** Per-entity PBR tint/finish override (#151.3); cloned onto each `MeshStandardMaterial` in the model so shared GLTF caches stay untouched. */
+    material?: ModelMaterialOverride;
+    /** Plays a GLTF animation clip on the model when the source has any (skinned or not); omit to render the rig's bind pose. */
+    animation?: ModelAnimationConfig;
+}
+export interface ObjectStyle {
+    color?: string;
+    opacity?: number;
+    hidden?: boolean;
+}
+export interface AmbientLightingConfig {
+    color?: string;
+    intensity?: number;
+}
+export interface DirectionalLightingConfig {
+    color?: string;
+    intensity?: number;
+    position: readonly [number, number, number];
+    castShadow?: boolean;
+}
+export interface HemisphereLightingConfig {
+    skyColor?: string;
+    groundColor?: string;
+    intensity?: number;
+}
+/** Declarative lighting replacing the shell's hardcoded ambient/directional default (#207.5); mounts regardless of world kind, only when supplied. */
+export interface LightingConfig {
+    ambient?: AmbientLightingConfig;
+    directional?: readonly DirectionalLightingConfig[];
+    hemisphere?: HemisphereLightingConfig;
+}
+export interface BackdropFogConfig {
+    color?: string;
+    near?: number;
+    far?: number;
+    /** Exponential (`FogExp2`) falloff instead of linear near/far; when set, `near`/`far` are ignored. */
+    density?: number;
+}
+/** Generic sky/background/fog for ANY world kind, including a custom `environment` component (#207.6). */
+export interface BackdropConfig {
+    background?: string;
+    sky?: SkyEnvironmentConfig;
+    fog?: BackdropFogConfig;
+}
+/** Movement-control levers for the shell-driven local player walk controller. */
+export interface PlayerMovementConfig {
+    /** "free" (default) moves camera-relative across the plane; "axis" locks travel to one world axis; "grid" snaps each committed position to cell centers. */
+    mode?: "free" | "axis" | "grid";
+    /** World axis for mode "axis". Default "x". */
+    axis?: "x" | "z";
+    /** Cell size for mode "grid". Default 1. */
+    cellSize?: number;
+    /** Collide the walking player against placed scene objects (unit-box AABBs) even without `collision.voxel`. Default false. */
+    collideObjects?: boolean;
+    /** Intercepts each frame's resolved position before the pose commits (and before onTick): return a replacement [x,y,z] to constrain or redirect the step, or nothing to accept it. */
+    beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;
+}
+/** One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`. */
+export interface MovementCommitFrame {
+    entityId: string;
+    current: readonly [number, number, number];
+    next: readonly [number, number, number];
+    dt: number;
 }
-export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never> {
+export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never> {
     game: GameDefinition;
     content: GameContextContent;
     loop: Required<GameLoop<GameContext>>;
     GameUI: TUi;
+    /** Which shell mount to use. Default `"3d"` (canvas, camera rig, pointer, world rendering). `"hud"` mounts no 3D canvas, camera rig, or pointer — the game is `GameUI` plus the command/input loop, for board/card/menu games. */
+    presentation?: "3d" | "hud";
     /** Optional canvas-layer VFX component (e.g. traveling projectiles). */
     WorldOverlay?: TWorldOverlay;
-    /** Replaces the default demo backdrop (ground + grid + rocks) with the game's own scene — ground, sky, structures. Camera, input, HUD, entity rendering, and the loop stay shell-provided; supply your world without forking the shell. */
+    /** Replaces the default demo backdrop (ground + grid + rocks) with the game's own scene — ground, sky, structures. Camera, input, HUD, entity rendering, and the loop stay shell-provided; supply your world without forking the shell. When unset and `game.world` is an `environment()` descriptor, the shell auto-renders that world here — no manual wiring needed. */
     environment?: TWorldOverlay;
     /** Per-entity visual override: return your own mesh for an entity and the shell still positions it and drives selection/targeting. Return null/undefined to fall back to model → sprite → primitive. */
     renderEntity?: TRenderEntity;
+    /** Per-object visual override: return your own mesh for a placed scene object and the shell still positions it and drives picking. Return null/undefined to fall back to objectModels → styled box. */
+    renderObject?: TRenderObject;
     /** Billboard sprites keyed by entity kind name; unmatched entities get primitive markers. */
     entitySprites?: Record<string, EntitySpriteConfig>;
     /** GLB models keyed by entity kind name; a string resolves as an asset-catalog key via game.assets, a ModelConfig renders directly. Takes priority over sprites, then primitives. */
     entityModels?: Record<string, string | ModelConfig>;
     /** GLB models keyed by object catalog id; a string resolves via game.assets, a ModelConfig renders directly. Replaces the colored box when present. */
     objectModels?: Record<string, string | ModelConfig>;
+    /** Styling for the default colored-box object render, keyed by catalog id: color override, opacity (< 1 sets transparent), hidden (skips the mesh but keeps the positioning group + picking). */
+    objectStyles?: Record<string, ObjectStyle>;
     /** Optional scroll-selected hotbar index for primary ability (mouse0). */
     hotbarSelection?: () => number;
     /** Positioned proximity prompts for the interact key + HUD; single source shared with useActivePrompt. */
     prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
     /** Camera tuning (perspective, orbit, first-person) for the dev game player shell. */
     camera?: GameCameraConfig;
+    /** Cast/receive shadows across the scene (R3F Canvas shadow pass). Default true. */
+    shadows?: boolean;
     /** Pointer-driven input: click-to-move, box-select, right-click verbs, cursor aim (#22/#30/#31). */
     pointer?: PointerConfig;
-    /** Opt in to world-space health bars floating over non-local entities that carry the stat. */
+    /** Touch controls on coarse-pointer devices. Unset derives a scheme from `input` (virtual joystick for movement actions, on-screen buttons for the rest); a config refines it with gestures and curated buttons; `false` opts out. */
+    touch?: TouchControlsConfig | false;
+    /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles. */
     worldHealthBars?: boolean | {
         statId?: string;
+        roles?: readonly CatalogEntityRole[];
     };
     /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. */
     audio?: {
@@ -381,4 +601,15 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     objectSounds?: Record<string, string>;
     /** Rarity render binding + loot filter for dropped-item ground presentation (#32/#33). */
     worldItem?: WorldItemRenderConfig;
+    /** Player-vs-world collision for the first-person controller (block/voxel worlds). Off by default (flat ground). */
+    collision?: VoxelCollisionConfig;
+    /** Movement-control levers (axis/grid constraints, object collision, pre-commit hook) for the shell-driven walk controller. */
+    movement?: PlayerMovementConfig;
+    /** Declarative ambient/directional/hemisphere lighting (#207.5); replaces the shell's hardcoded default lights when present, regardless of world kind. */
+    lighting?: LightingConfig;
+    /** Generic background/sky/fog (#207.6), applied for any world kind including a custom `environment` component. */
+    backdrop?: BackdropConfig;
+    /** F2 debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
+    devtools?: boolean;
 }
+export declare function worldHealthBarAllowsRole(roles: readonly CatalogEntityRole[] | undefined, role: CatalogEntityRole | undefined): boolean;

package/dist/game/playableGame.js

@@ -1 +1,6 @@
-export {};
+export const CAMERA_FRUSTUM_DEFAULTS = { fov: 55, near: 0.1, far: 300 };
+export function worldHealthBarAllowsRole(roles, role) {
+    if (roles === undefined)
+        return true;
+    return role !== undefined && roles.includes(role);
+}

package/dist/game/progression.d.ts

@@ -40,6 +40,7 @@ export interface LevelingConfig {
     startLevel?: number;
     xpStat?: string;
     levelStat?: string;
+    thresholdMode?: "perLevel" | "cumulative";
 }
 export interface LevelingStatAccess {
     get(userId: string, statId: string): {

package/dist/game/progression.js

@@ -60,8 +60,13 @@ export function leveling(config) {
     const startLevel = config.startLevel ?? 1;
     const xpStat = config.xpStat ?? "xp";
     const levelStat = config.levelStat ?? "level";
-    const xpForLevel = (level) => evalCurve(config.xpForLevel, level);
-    const resolve = (level, xp) => {
+    const thresholdMode = config.thresholdMode ?? "perLevel";
+    const xpForLevel = (level) => {
+        if (thresholdMode === "cumulative" && level <= startLevel)
+            return 0;
+        return evalCurve(config.xpForLevel, level);
+    };
+    const resolvePerLevel = (level, xp) => {
         let currentLevel = level;
         let currentXp = xp;
         let levelsGained = 0;
@@ -79,6 +84,22 @@ export function leveling(config) {
             levelsGained,
         };
     };
+    const resolveCumulative = (level, xp) => {
+        let currentLevel = level;
+        let levelsGained = 0;
+        while (currentLevel < maxLevel && xp >= xpForLevel(currentLevel + 1)) {
+            currentLevel += 1;
+            levelsGained += 1;
+        }
+        const capped = currentLevel >= maxLevel;
+        return {
+            level: currentLevel,
+            xp: capped ? xpForLevel(maxLevel) : xp,
+            xpMax: capped ? xpForLevel(maxLevel) : xpForLevel(currentLevel + 1),
+            levelsGained,
+        };
+    };
+    const resolve = (level, xp) => thresholdMode === "cumulative" ? resolveCumulative(level, xp) : resolvePerLevel(level, xp);
     const grantXp = (access, userId, amount, onLevelUp) => {
         const xp = access.get(userId, xpStat);
         const level = access.get(userId, levelStat);

package/dist/game/race.d.ts

@@ -69,6 +69,7 @@ export interface RaceStateConfig {
  * volumes. It emits `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished`, keeps
  * cumulative split times for PB deltas, resolves a pluggable win condition (first-past-post, round-cut,
  * derby last-standing), and `resetToCheckpoint` hands back a respawn pose at the racer's last checkpoint.
+ * `removeRacer` drops a racer mid-race and `reset` returns the whole instance to its pre-race state for reuse.
  */
 export declare class RaceState {
     private readonly track;
@@ -79,6 +80,10 @@ export declare class RaceState {
     private finalRanking;
     constructor(config: RaceStateConfig);
     addRacer(racerId: string, startTime?: number): void;
+    /** Removes a racer's progress/standing and renumbers the remaining field's positions; a no-op for an unknown id. */
+    removeRacer(racerId: string): void;
+    /** Clears all racer progress and finish state back to construction time; `track` and `win` are untouched, so the same instance can run another race. */
+    reset(): void;
     eliminate(racerId: string): void;
     get finished(): boolean;
     get ranking(): readonly string[];

package/dist/game/race.js

@@ -50,6 +50,7 @@ function distanceToNext(point, cp) {
  * volumes. It emits `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished`, keeps
  * cumulative split times for PB deltas, resolves a pluggable win condition (first-past-post, round-cut,
  * derby last-standing), and `resetToCheckpoint` hands back a respawn pose at the racer's last checkpoint.
+ * `removeRacer` drops a racer mid-race and `reset` returns the whole instance to its pre-race state for reuse.
  */
 export class RaceState {
     track;
@@ -80,6 +81,25 @@ export class RaceState {
         });
         this.order.push(racerId);
     }
+    /** Removes a racer's progress/standing and renumbers the remaining field's positions; a no-op for an unknown id. */
+    removeRacer(racerId) {
+        if (!this.racers.delete(racerId))
+            return;
+        const idx = this.order.indexOf(racerId);
+        if (idx >= 0)
+            this.order.splice(idx, 1);
+        const remaining = this.order.map((id) => this.racers.get(id)).sort((a, b) => this.compare(a, b, null));
+        remaining.forEach((r, i) => {
+            r.position = i + 1;
+        });
+    }
+    /** Clears all racer progress and finish state back to construction time; `track` and `win` are untouched, so the same instance can run another race. */
+    reset() {
+        this.racers.clear();
+        this.order.length = 0;
+        this.raceFinished = false;
+        this.finalRanking = [];
+    }
     eliminate(racerId) {
         const r = this.racers.get(racerId);
         if (r !== undefined)

package/dist/game/social.d.ts

@@ -23,6 +23,7 @@ export interface SocialDeps {
     presence?: (userId: string) => PresenceInfo;
     now?: () => number;
     emotes?: EmotesDeps;
+    worldInviteTtlMs?: number;
 }
 export interface FriendEntry {
     userId: string;
@@ -32,6 +33,10 @@ export interface FriendsSnapshot {
     friends: string[];
     blocked: string[];
 }
+export interface FriendRequestEntry {
+    requestId: string;
+    fromUserId: string;
+}
 export interface Friends {
     canRequest(fromUserId: string, toUserId: string): {
         reason: string;
@@ -44,9 +49,11 @@ export interface Friends {
     accept(userId: string, requestId: string): {
         reason: string;
     } | null;
+    decline(userId: string, requestId: string): void;
     remove(userId: string, friendUserId: string): void;
     block(userId: string, targetUserId: string): void;
     list(userId: string): FriendEntry[];
+    requestsFor(userId: string): FriendRequestEntry[];
     snapshot(userId: string): FriendsSnapshot;
     hydrate(userId: string, data: FriendsSnapshot): void;
 }
@@ -59,6 +66,11 @@ export interface PartyConfig {
     maxMembers: number;
     inviteTtlMs?: number;
 }
+export interface PartyInviteEntry {
+    inviteId: string;
+    fromUserId: string;
+    createdAt: number;
+}
 export interface Party {
     register(config: PartyConfig): void;
     canInvite(fromUserId: string, toUserId: string): {
@@ -72,6 +84,7 @@ export interface Party {
     accept(userId: string, inviteId: string): {
         reason: string;
     } | null;
+    decline(userId: string, inviteId: string): void;
     kick(leaderUserId: string, memberUserId: string): {
         reason: string;
     } | null;
@@ -81,6 +94,7 @@ export interface Party {
     } | null;
     list(userId: string): PartyMemberEntry[];
     membersOf(userId: string): string[];
+    invitesFor(userId: string): PartyInviteEntry[];
 }
 export declare const DEFAULT_EMOTE_RADIUS = 20;
 export interface EmoteBroadcastResult {
@@ -94,6 +108,33 @@ export interface Emotes {
         reason: string;
     };
 }
+export interface WorldInviteTarget {
+    serverId: string;
+    joinCode?: string;
+}
+export interface WorldInvite extends WorldInviteTarget {
+    id: string;
+    fromUserId: string;
+    toUserId: string;
+    createdAt: number;
+}
+export interface WorldInvites {
+    canInvite(fromUserId: string, toUserId: string): {
+        reason: string;
+    } | null;
+    invite(fromUserId: string, toUserId: string, target: WorldInviteTarget): {
+        inviteId: string;
+    } | {
+        reason: string;
+    };
+    accept(userId: string, inviteId: string): {
+        target: WorldInviteTarget;
+    } | {
+        reason: string;
+    };
+    decline(userId: string, inviteId: string): void;
+    listFor(userId: string): WorldInvite[];
+}
 export interface Social {
     friends: Friends;
     party: Party;
@@ -101,5 +142,6 @@ export interface Social {
         get(userId: string): PresenceInfo;
     };
     emotes: Emotes;
+    worldInvites: WorldInvites;
 }
 export declare function createSocial(deps: SocialDeps): Social;