@jgengine/shell 0.18.1 → 0.19.0

package/dist/audio/audioEngine.js

@@ -1,11 +1,13 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { dopplerRate } from "@jgengine/core/audio/doppler";
 import { patchDuration } from "@jgengine/core/audio/synth";
 import { createDisposer } from "@jgengine/core/game/defineGame";
-import { clampLoopGain, clampLoopRate } from "./loopParams.js";
+import { clampLoopCutoff, clampLoopGain, clampLoopRate, MIN_LOOP_CUTOFF, MAX_LOOP_CUTOFF } from "./loopParams.js";
 import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 /** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
 const LOOP_PARAM_SMOOTH_TC = 0.02;
+const ZERO_VELOCITY = { x: 0, y: 0, z: 0 };
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
@@ -140,12 +142,17 @@ export function createAudioEngine(config = {}) {
         return pending;
     }
     let listenerPosition = { x: 0, y: 0, z: 0 };
+    let listenerVelocity = { x: 0, y: 0, z: 0 };
+    const nyquist = context.sampleRate / 2;
     const activeSpatialUpdaters = new Set();
     const activeLoops = new Set();
     const NOOP_HANDLE = {
         setPosition: () => undefined,
         setRate: () => undefined,
         setGain: () => undefined,
+        setLowpass: () => undefined,
+        setHighpass: () => undefined,
+        setVelocity: () => undefined,
         stop: () => undefined,
     };
     function playInternal(soundId, position, loop) {
@@ -187,16 +194,34 @@ export function createAudioEngine(config = {}) {
         // Live control state, applied on source creation so updates that race the async buffer load stick.
         let currentRate = 1;
         let currentUserGain = 1;
+        let currentLowpass = MAX_LOOP_CUTOFF;
+        let currentHighpass = MIN_LOOP_CUTOFF;
+        let currentVelocity = { x: 0, y: 0, z: 0 };
+        const dopplerFactor = loop ? sound.doppler ?? 0 : 0;
         let sourceNode = null;
+        let lowpassNode = null;
+        let highpassNode = null;
         let userGainNode = null;
         let falloffGain = null;
         let pannerNode = null;
+        function effectiveRate() {
+            if (dopplerFactor === 0)
+                return currentRate;
+            const shift = dopplerRate([listenerPosition.x, listenerPosition.y, listenerPosition.z], [listenerVelocity.x, listenerVelocity.y, listenerVelocity.z], [currentPosition.x, currentPosition.y, currentPosition.z], [currentVelocity.x, currentVelocity.y, currentVelocity.z], { factor: dopplerFactor });
+            return clampLoopRate(currentRate * shift);
+        }
+        function applyRate() {
+            if (sourceNode !== null)
+                sourceNode.playbackRate.setTargetAtTime(effectiveRate(), context.currentTime, LOOP_PARAM_SMOOTH_TC);
+        }
         function updateFalloff() {
             if (falloffGain !== null && sound.spatial === undefined) {
                 falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             }
             if (pannerNode !== null)
                 setPannerPosition(pannerNode, currentPosition);
+            if (dopplerFactor !== 0)
+                applyRate();
         }
         void bufferPromise.then((buffer) => {
             if (buffer === null)
@@ -204,13 +229,28 @@ export function createAudioEngine(config = {}) {
             const src = context.createBufferSource();
             src.buffer = buffer;
             src.loop = loop || (sound.loop ?? false);
-            src.playbackRate.value = currentRate;
-            // source → per-loop user gain (setGain) → distance falloff → bus
+            src.playbackRate.value = effectiveRate();
+            // source → [lowpass → highpass, loops only] → per-loop user gain (setGain) → distance falloff → bus
             const uGain = context.createGain();
             uGain.gain.value = currentUserGain;
             const fGain = context.createGain();
             fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-            src.connect(uGain);
+            if (loop) {
+                const lp = context.createBiquadFilter();
+                lp.type = "lowpass";
+                lp.frequency.value = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                const hp = context.createBiquadFilter();
+                hp.type = "highpass";
+                hp.frequency.value = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
+                src.connect(lp);
+                lp.connect(hp);
+                hp.connect(uGain);
+                lowpassNode = lp;
+                highpassNode = hp;
+            }
+            else {
+                src.connect(uGain);
+            }
             uGain.connect(fGain);
             if (sound.spatial !== undefined) {
                 const panner = createPanner(context, sound.spatial, currentPosition);
@@ -233,10 +273,14 @@ export function createAudioEngine(config = {}) {
                 catch {
                 }
                 src.disconnect();
+                lowpassNode?.disconnect();
+                highpassNode?.disconnect();
                 uGain.disconnect();
                 fGain.disconnect();
                 pannerNode?.disconnect();
                 sourceNode = null;
+                lowpassNode = null;
+                highpassNode = null;
                 userGainNode = null;
                 falloffGain = null;
             });
@@ -250,8 +294,22 @@ export function createAudioEngine(config = {}) {
             },
             setRate(rate) {
                 currentRate = clampLoopRate(rate);
-                if (sourceNode !== null)
-                    sourceNode.playbackRate.setTargetAtTime(currentRate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+                applyRate();
+            },
+            setLowpass(hz) {
+                currentLowpass = clampLoopCutoff(hz, MAX_LOOP_CUTOFF, nyquist);
+                if (lowpassNode !== null)
+                    lowpassNode.frequency.setTargetAtTime(currentLowpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setHighpass(hz) {
+                currentHighpass = clampLoopCutoff(hz, MIN_LOOP_CUTOFF, nyquist);
+                if (highpassNode !== null)
+                    highpassNode.frequency.setTargetAtTime(currentHighpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setVelocity(velocity) {
+                currentVelocity = velocity;
+                if (dopplerFactor !== 0)
+                    applyRate();
             },
             setGain(gain) {
                 currentUserGain = clampLoopGain(gain);
@@ -272,6 +330,7 @@ export function createAudioEngine(config = {}) {
         setListenerPose(position) {
             const pose = "position" in position ? position : { position, forward: { x: 0, y: 0, z: -1 }, up: { x: 0, y: 1, z: 0 } };
             listenerPosition = pose.position;
+            listenerVelocity = "velocity" in pose && pose.velocity !== undefined ? pose.velocity : ZERO_VELOCITY;
             const listener = context.listener;
             setAudioParam(listener.positionX, pose.position.x);
             setAudioParam(listener.positionY, pose.position.y);

package/dist/audio/audioWire.d.ts

@@ -17,6 +17,9 @@ type AudioLoopSetPayload = {
     rate?: number;
     gain?: number;
     at?: readonly [number, number, number];
+    velocity?: readonly [number, number, number];
+    lowpass?: number;
+    highpass?: number;
 };
 type AudioLoopStopPayload = {
     id: string;

package/dist/audio/audioWire.js

@@ -29,7 +29,7 @@ export function attachAudioEventWire(events, audioEngine) {
         if (handle !== null)
             loops.set(id, { sound, handle });
     });
-    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at }) => {
+    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at, velocity, lowpass, highpass }) => {
         const entry = loops.get(id);
         // Unknown id: a live update may race a stop — silently drop it.
         if (entry === undefined)
@@ -40,6 +40,12 @@ export function attachAudioEventWire(events, audioEngine) {
             entry.handle.setGain(gain);
         if (at !== undefined)
             entry.handle.setPosition({ x: at[0], y: at[1], z: at[2] });
+        if (velocity !== undefined)
+            entry.handle.setVelocity({ x: velocity[0], y: velocity[1], z: velocity[2] });
+        if (lowpass !== undefined)
+            entry.handle.setLowpass(lowpass);
+        if (highpass !== undefined)
+            entry.handle.setHighpass(highpass);
     });
     const offLoopStop = events.on("audio.loopStop", ({ id }) => {
         const entry = loops.get(id);

package/dist/audio/loopParams.d.ts

@@ -18,3 +18,42 @@ export declare function clampLoopRate(rate: number): number;
  * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
  */
 export declare function clampLoopGain(gain: number): number;
+/** Lowest live filter cutoff, Hz. */
+export declare const MIN_LOOP_CUTOFF = 10;
+/** Highest live filter cutoff, Hz; the engine also caps it at the context's Nyquist frequency. */
+export declare const MAX_LOOP_CUTOFF = 22050;
+/**
+ * Clamp a loop filter cutoff into `MIN_LOOP_CUTOFF`–`min(MAX_LOOP_CUTOFF, nyquist)` Hz. Non-finite input
+ * falls back to `fallback` (the open, transparent end of that filter).
+ * @internal — the audio engine applies this; game code sets cutoffs through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopCutoff(hz: number, fallback: number, nyquist?: number): number;
+/** Smoothed listener velocity estimate from per-frame camera positions. @internal */
+export interface ListenerVelocityTrack {
+    last: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** @internal */
+export declare function createListenerVelocityTrack(): ListenerVelocityTrack;
+/**
+ * Advance the listener velocity estimate by one frame: the position delta over `dt`, eased with a
+ * ~50 ms time constant so frame-time jitter does not warble doppler. A cut resets it to zero.
+ * @internal
+ */
+export declare function stepListenerVelocity(track: ListenerVelocityTrack, position: {
+    x: number;
+    y: number;
+    z: number;
+}, dt: number): {
+    x: number;
+    y: number;
+    z: number;
+};

package/dist/audio/loopParams.js

@@ -26,3 +26,46 @@ export function clampLoopGain(gain) {
         return 0;
     return Math.min(1, Math.max(0, gain));
 }
+/** Lowest live filter cutoff, Hz. */
+export const MIN_LOOP_CUTOFF = 10;
+/** Highest live filter cutoff, Hz; the engine also caps it at the context's Nyquist frequency. */
+export const MAX_LOOP_CUTOFF = 22050;
+/**
+ * Clamp a loop filter cutoff into `MIN_LOOP_CUTOFF`–`min(MAX_LOOP_CUTOFF, nyquist)` Hz. Non-finite input
+ * falls back to `fallback` (the open, transparent end of that filter).
+ * @internal — the audio engine applies this; game code sets cutoffs through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopCutoff(hz, fallback, nyquist = MAX_LOOP_CUTOFF) {
+    const max = Math.min(MAX_LOOP_CUTOFF, nyquist);
+    if (!Number.isFinite(hz))
+        return Math.min(max, Math.max(MIN_LOOP_CUTOFF, fallback));
+    return Math.min(max, Math.max(MIN_LOOP_CUTOFF, hz));
+}
+/** @internal */
+export function createListenerVelocityTrack() {
+    return { last: null, velocity: { x: 0, y: 0, z: 0 } };
+}
+/** Camera jumps faster than this (world units/s) are cuts or teleports, not motion, and reset the estimate. */
+const MAX_LISTENER_SPEED = 400;
+/**
+ * Advance the listener velocity estimate by one frame: the position delta over `dt`, eased with a
+ * ~50 ms time constant so frame-time jitter does not warble doppler. A cut resets it to zero.
+ * @internal
+ */
+export function stepListenerVelocity(track, position, dt) {
+    const last = track.last;
+    track.last = { x: position.x, y: position.y, z: position.z };
+    if (last === null || !(dt > 0))
+        return track.velocity;
+    const vx = (position.x - last.x) / dt;
+    const vy = (position.y - last.y) / dt;
+    const vz = (position.z - last.z) / dt;
+    if (Math.hypot(vx, vy, vz) > MAX_LISTENER_SPEED) {
+        track.velocity = { x: 0, y: 0, z: 0 };
+        return track.velocity;
+    }
+    const blend = 1 - Math.exp(-dt / 0.05);
+    const v = track.velocity;
+    track.velocity = { x: v.x + (vx - v.x) * blend, y: v.y + (vy - v.y) * blend, z: v.z + (vz - v.z) * blend };
+    return track.velocity;
+}

package/dist/camera/GameCameraRig.js

@@ -37,7 +37,7 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
         const kind = resolveRigKind(config);
         switch (kind) {
             case "first":
-                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined, viewmodel: viewmodel }));
+                return (_jsx(GameFirstPersonCamera, { yawRef: yawRef, pitchRef: pitchRef, config: config?.firstPerson, followEntityId: followEntityId ?? undefined, viewmodel: viewmodel, weapon: config?.weapon }));
             case "topDown":
                 return _jsx(TopDownRig, { yawRef: yawRef, pitchRef: pitchRef, config: config, followEntityId: followEntityId });
             case "rts":

package/dist/camera/GameFirstPersonCamera.d.ts

@@ -1,6 +1,6 @@
 import { type ComponentType, type MutableRefObject } from "react";
 import * as THREE from "three";
-import type { FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
+import type { CameraWeaponView, FirstPersonCameraConfig } from "@jgengine/core/game/playableGame";
 import type { EntityRenderCues } from "@jgengine/core/combat/renderCues";
 /** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
 export declare function readFirstPersonMuzzle(target: THREE.Vector3): boolean;
@@ -15,5 +15,7 @@ export interface GameFirstPersonCameraProps {
     followEntityId?: string;
     /** Custom viewmodel component replacing the built-in three-mesh gun, rendered inside the same camera-locked, muzzle-tracked anchor. Ignored when `config.viewmodel === false`. */
     viewmodel?: ComponentType<ViewmodelProps>;
+    /** Held-weapon source (`GameCameraConfig.weapon`): poses the viewmodel and adds recoil to the look. */
+    weapon?: (entityId: string) => CameraWeaponView | null;
 }
-export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;
+export declare function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, weapon, }: GameFirstPersonCameraProps): import("react").JSX.Element | null;

package/dist/camera/GameFirstPersonCamera.js

@@ -1,18 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { DEFAULT_EYE_HEIGHT } from "@jgengine/core/combat/shotOrigin";
+import { createWeaponPresentation, viewmodelFovScale, } from "@jgengine/core/combat/weaponPresentation";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useEntityRenderCues } from "../render/useEntityRenderCues.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { GAME_SIM_FRAME_PRIORITY, ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
+import { requestRawPointerLock } from "../input/pointerLock.js";
 const DEFAULT_SENSITIVITY = 0.0025;
 const DEFAULT_MAX_PITCH = 1.45;
 const VIEWMODEL_ORIGIN = new THREE.Vector3(0.34, -0.26, -0.72);
 const MUZZLE_TIP_LOCAL = new THREE.Vector3(0, 0.03, -0.61);
-const MUZZLE_OFFSET = VIEWMODEL_ORIGIN.clone().add(MUZZLE_TIP_LOCAL);
 const muzzleWorld = new THREE.Vector3();
 let muzzleTracked = false;
 /** World position of the first-person weapon muzzle, or false when no viewmodel is mounted. */
@@ -22,7 +23,7 @@ export function readFirstPersonMuzzle(target) {
     target.copy(muzzleWorld);
     return true;
 }
-export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, }) {
+export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId, viewmodel, weapon, }) {
     const eyeHeight = config?.eyeHeight ?? DEFAULT_EYE_HEIGHT;
     const sensitivity = config?.sensitivity ?? DEFAULT_SENSITIVITY;
     const maxPitch = config?.maxPitch ?? DEFAULT_MAX_PITCH;
@@ -34,12 +35,16 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
     const followId = followEntityId ?? userId;
     const seededRef = useRef(false);
     const cuesRef = useEntityRenderCues(followId);
+    const presentation = useMemo(() => createWeaponPresentation(), []);
+    const tuningRef = useRef(undefined);
+    const lastLookRef = useRef(null);
+    const poseRef = useRef(null);
     useEffect(() => {
         const requestLock = () => {
             if (window.matchMedia?.("(pointer: coarse)").matches)
                 return;
             if (document.pointerLockElement !== domElement)
-                void domElement.requestPointerLock?.();
+                requestRawPointerLock(domElement);
         };
         const onMove = (event) => {
             if (document.pointerLockElement !== domElement)
@@ -54,7 +59,7 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
             window.removeEventListener("mousemove", onMove);
         };
     }, [domElement, sensitivity, maxPitch, yawRef, pitchRef]);
-    useFrame(() => {
+    useFrame((_, dt) => {
         const entity = ctx.scene.entity.get(followId);
         if (entity === null)
             return;
@@ -62,22 +67,45 @@ export function GameFirstPersonCamera({ yawRef, pitchRef, config, followEntityId
             seededRef.current = true;
             yawRef.current = entity.rotationY;
         }
-        const cosPitch = Math.cos(pitchRef.current);
+        const view = weapon?.(followId) ?? null;
+        const last = (lastLookRef.current ??= { yaw: yawRef.current, pitch: pitchRef.current });
+        const step = Math.max(1e-4, dt);
+        let pose = null;
+        if (view !== null) {
+            if (view.presentation !== tuningRef.current) {
+                tuningRef.current = view.presentation;
+                presentation.retune(view.presentation ?? {});
+            }
+            pose = presentation.update(dt, {
+                lookYawRate: (yawRef.current - last.yaw) / step,
+                lookPitchRate: (pitchRef.current - last.pitch) / step,
+                speed: cuesRef.current.speed,
+                bobPhase: cuesRef.current.bobPhase,
+                handling: view.handling,
+            });
+        }
+        last.yaw = yawRef.current;
+        last.pitch = pitchRef.current;
+        poseRef.current = pose;
+        const yaw = yawRef.current - (pose?.lookYaw ?? 0);
+        const pitch = Math.max(-maxPitch, Math.min(maxPitch, pitchRef.current + (pose?.lookPitch ?? 0)));
+        const cosPitch = Math.cos(pitch);
         camera.position.set(entity.position[0], entity.position[1] + eyeHeight, entity.position[2]);
-        camera.lookAt(camera.position.x + Math.sin(yawRef.current) * cosPitch, camera.position.y + Math.sin(pitchRef.current), camera.position.z + Math.cos(yawRef.current) * cosPitch);
+        camera.lookAt(camera.position.x + Math.sin(yaw) * cosPitch, camera.position.y + Math.sin(pitch), camera.position.z + Math.cos(yaw) * cosPitch);
         if (camera.isPerspectiveCamera === true) {
             const perspective = camera;
-            if (Math.abs(perspective.fov - playerFov.fov) > 0.001) {
-                perspective.fov = playerFov.fov;
+            const fov = playerFov.fov * (pose?.fovScale ?? 1);
+            if (Math.abs(perspective.fov - fov) > 0.001) {
+                perspective.fov = fov;
                 perspective.updateProjectionMatrix();
             }
         }
     }, ORBIT_CAMERA_FRAME_PRIORITY);
     if (config?.viewmodel === false)
         return null;
-    return _jsx(FirstPersonViewmodel, { camera: camera, viewmodel: viewmodel, cuesRef: cuesRef });
+    return _jsx(FirstPersonViewmodel, { camera: camera, viewmodel: viewmodel, cuesRef: cuesRef, poseRef: poseRef });
 }
-function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, }) {
+function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, poseRef, }) {
     const groupRef = useRef(null);
     useEffect(() => () => {
         muzzleTracked = false;
@@ -86,12 +114,21 @@ function FirstPersonViewmodel({ camera, viewmodel: Viewmodel, cuesRef, }) {
         const group = groupRef.current;
         if (group === null)
             return;
+        const pose = poseRef.current;
+        const perspective = camera;
+        // Scaling camera-space x/y by this projects the viewmodel at its own FOV without a second render pass.
+        const squash = pose?.viewmodelFov == null || perspective.isPerspectiveCamera !== true ? 1 : viewmodelFovScale(perspective.fov, pose.viewmodelFov);
         group.position.copy(camera.position);
         group.quaternion.copy(camera.quaternion);
-        group.translateX(VIEWMODEL_ORIGIN.x);
-        group.translateY(VIEWMODEL_ORIGIN.y);
-        group.translateZ(VIEWMODEL_ORIGIN.z);
-        muzzleWorld.copy(MUZZLE_OFFSET).applyQuaternion(camera.quaternion).add(camera.position);
+        group.translateX((pose?.offset[0] ?? VIEWMODEL_ORIGIN.x) * squash);
+        group.translateY((pose?.offset[1] ?? VIEWMODEL_ORIGIN.y) * squash);
+        group.translateZ(pose?.offset[2] ?? VIEWMODEL_ORIGIN.z);
+        group.rotateX(pose?.pitch ?? 0);
+        group.rotateY(pose?.yaw ?? 0);
+        group.rotateZ(pose?.roll ?? 0);
+        group.scale.set(squash, squash, 1);
+        group.updateMatrixWorld();
+        group.localToWorld(muzzleWorld.copy(MUZZLE_TIP_LOCAL));
         muzzleTracked = true;
     }, GAME_SIM_FRAME_PRIORITY);
     if (Viewmodel !== undefined) {

package/dist/camera/Viewports.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import type { GameCameraConfig } from "@jgengine/core/game/playableGame";
+import { type ViewportDef, type ViewportsConfig } from "@jgengine/core/game/viewports";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import { type LocalPlayerSlot } from "@jgengine/core/runtime/localPlayers";
+/** Camera yaw the split-screen renderer last used for a seat's user, so the walk controller moves that seat camera-relative. @internal */
+export declare function seatCameraYaw(ctx: GameContext, userId: string): number | undefined;
+/**
+ * The viewports for the seats currently joined, re-resolved when a seat joins or leaves.
+ * @internal
+ */
+export declare function useSeatViewports(ctx: GameContext, config: ViewportsConfig | undefined): readonly ViewportDef[];
+/**
+ * Draws one scissored render per viewport. The primary seat keeps the main camera and its rig; every
+ * other seat gets a follow camera (chase or top-down) on its possessed entity. Mounted only while more
+ * than one viewport is drawn, since a render-priority frame callback takes over R3F's own render.
+ * @internal
+ */
+export declare function SplitScreenRenderer({ ctx, viewports, config, mainCamera, }: {
+    ctx: GameContext;
+    viewports: readonly ViewportDef[];
+    config: ViewportsConfig | undefined;
+    mainCamera: GameCameraConfig | undefined;
+}): null;
+/**
+ * One absolutely-positioned HUD root per viewport, laid over the canvas: render each seat's own
+ * health, prompts or score with `children(slot)`. Pass the same `viewports` config the game gave `defineGame`.
+ * @capability split-screen-hud Per-seat HUD roots positioned over each split-screen viewport.
+ */
+export declare function ViewportHuds({ ctx, config, children, }: {
+    ctx: GameContext;
+    config?: ViewportsConfig;
+    children: (slot: LocalPlayerSlot, viewport: ViewportDef) => ReactNode;
+}): import("react").JSX.Element;

package/dist/camera/Viewports.js

@@ -0,0 +1,123 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useMemo, useRef, useSyncExternalStore } from "react";
+import * as THREE from "three";
+import { resolveViewports, viewportPixels, } from "@jgengine/core/game/viewports";
+import { localPlayers } from "@jgengine/core/runtime/localPlayers";
+import { createChaseRigState, resolveChase, resolveTopDown, stepChase, topDownPose } from "./rigMath.js";
+const SEAT_YAW = new WeakMap();
+/** Camera yaw the split-screen renderer last used for a seat's user, so the walk controller moves that seat camera-relative. @internal */
+export function seatCameraYaw(ctx, userId) {
+    return SEAT_YAW.get(ctx)?.get(userId);
+}
+function seatSlotIds(ctx) {
+    return localPlayers(ctx).slots().map((slot) => slot.slotId);
+}
+/**
+ * The viewports for the seats currently joined, re-resolved when a seat joins or leaves.
+ * @internal
+ */
+export function useSeatViewports(ctx, config) {
+    const seats = localPlayers(ctx);
+    const key = useSyncExternalStore(seats.subscribe, () => seatSlotIds(ctx).join("|"), () => seatSlotIds(ctx).join("|"));
+    return useMemo(() => resolveViewports(config, key === "" ? [] : key.split("|")), [config, key]);
+}
+function seatRigKind(camera, main) {
+    return camera?.rig ?? (main?.rig === "topDown" ? "topDown" : "chase");
+}
+/**
+ * Draws one scissored render per viewport. The primary seat keeps the main camera and its rig; every
+ * other seat gets a follow camera (chase or top-down) on its possessed entity. Mounted only while more
+ * than one viewport is drawn, since a render-priority frame callback takes over R3F's own render.
+ * @internal
+ */
+export function SplitScreenRenderer({ ctx, viewports, config, mainCamera, }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    const rigs = useRef(new Map());
+    useFrame((_state, dt) => {
+        const seats = localPlayers(ctx);
+        let yaws = SEAT_YAW.get(ctx);
+        if (yaws === undefined) {
+            yaws = new Map();
+            SEAT_YAW.set(ctx, yaws);
+        }
+        gl.setScissorTest(true);
+        for (const def of viewports) {
+            const slot = seats.slot(def.slot);
+            if (slot === null)
+                continue;
+            const pixels = viewportPixels(def.rect, size.width, size.height);
+            const view = slot.index === 0 ? camera : seatCamera(slot, def.camera ?? config?.camera, dt, yaws);
+            if (view instanceof THREE.PerspectiveCamera) {
+                view.aspect = pixels.width / pixels.height;
+                view.updateProjectionMatrix();
+            }
+            gl.setViewport(pixels.x, pixels.y, pixels.width, pixels.height);
+            gl.setScissor(pixels.x, pixels.y, pixels.width, pixels.height);
+            gl.render(scene, view);
+        }
+        gl.setScissorTest(false);
+        gl.setViewport(0, 0, size.width, size.height);
+        if (camera instanceof THREE.PerspectiveCamera) {
+            camera.aspect = size.width / size.height;
+            camera.updateProjectionMatrix();
+        }
+    }, 1);
+    function seatCamera(slot, cameraConfig, dt, yaws) {
+        let rig = rigs.current.get(slot.slotId);
+        if (rig === undefined) {
+            const created = new THREE.PerspectiveCamera();
+            if (camera instanceof THREE.PerspectiveCamera) {
+                created.near = camera.near;
+                created.far = camera.far;
+            }
+            rig = { camera: created, chase: createChaseRigState() };
+            rigs.current.set(slot.slotId, rig);
+        }
+        const entity = ctx.scene.entity.get(ctx.player.possession.active(slot.userId));
+        const follow = entity === null ? { x: 0, y: 0, z: 0 } : { x: entity.position[0], y: entity.position[1], z: entity.position[2] };
+        let pose;
+        if (seatRigKind(cameraConfig, mainCamera) === "topDown") {
+            const resolved = resolveTopDown(cameraConfig?.topDown ?? mainCamera?.topDown);
+            pose = topDownPose(follow, resolved, rig.camera.fov);
+            yaws.set(slot.userId, resolved.yaw);
+        }
+        else {
+            const velocity = entity?.velocity;
+            const step = stepChase(rig.chase, {
+                follow,
+                yaw: entity?.rotationY ?? 0,
+                bodyPitch: entity?.rotationX ?? 0,
+                velocity: velocity === undefined ? null : { x: velocity[0], y: velocity[1], z: velocity[2] },
+                lookBack: false,
+                fovKick: 0,
+            }, resolveChase(cameraConfig?.chase ?? mainCamera?.chase), dt);
+            pose = step.pose;
+            yaws.set(slot.userId, step.anchorYaw);
+        }
+        rig.camera.position.set(pose.position.x, pose.position.y, pose.position.z);
+        rig.camera.fov = pose.fov;
+        rig.camera.lookAt(pose.lookAt.x, pose.lookAt.y, pose.lookAt.z);
+        return rig.camera;
+    }
+    return null;
+}
+/**
+ * One absolutely-positioned HUD root per viewport, laid over the canvas: render each seat's own
+ * health, prompts or score with `children(slot)`. Pass the same `viewports` config the game gave `defineGame`.
+ * @capability split-screen-hud Per-seat HUD roots positioned over each split-screen viewport.
+ */
+export function ViewportHuds({ ctx, config, children, }) {
+    const viewports = useSeatViewports(ctx, config);
+    const seats = localPlayers(ctx);
+    return (_jsx(_Fragment, { children: viewports.map((viewport) => {
+            const slot = seats.slot(viewport.slot);
+            if (slot === null)
+                return null;
+            const [x, y, width, height] = viewport.rect;
+            return (_jsx("div", { "data-jg-viewport": viewport.slot, className: "pointer-events-none absolute overflow-hidden", style: { left: `${x * 100}%`, top: `${y * 100}%`, width: `${width * 100}%`, height: `${height * 100}%` }, children: children(slot, viewport) }, viewport.slot));
+        }) }));
+}