@zylem/game-lib 0.8.9 → 0.9.1

package/dist/cinematics.d.ts

@@ -0,0 +1,279 @@
+import { k as CutsceneEasing, V as Vec3Def, h as CutsceneScene, n as CameraShot, g as CutsceneDefinition, s as DollyPath, i as CutsceneCamera, o as CameraTrack, x as SceneTransition, y as SceneTransitionType, v as EventItem, w as AudioItem } from './cutscene-definition-C479fkei.js';
+export { A as AudioItemSchema, q as AudioTrack, l as CameraKeyframe, c as CameraKeyframeSchema, m as CameraPoseDef, d as CameraShotSchema, j as CutsceneCameraKind, b as CutsceneCameraSchema, C as CutsceneDefinitionSchema, u as CutsceneEvent, e as CutsceneEventSchema, a as CutsceneSceneSchema, r as CutsceneTrack, f as CutsceneTrackSchema, D as DollyPathSchema, E as EventItemSchema, p as EventTrack, S as SceneTransitionSchema, t as ShotBlend } from './cutscene-definition-C479fkei.js';
+import { f as CameraBehavior, d as CameraContext, C as CameraPose, l as ZylemCamera } from './zylem-camera-CYDtrVgi.js';
+import { Z as ZylemTransitionShader } from './stage-transition-CmGpV4tc.js';
+import { Z as ZylemStage, q as Stage } from './stage-CAPlk_cN.js';
+import { g as SongDefinition } from './song-definition-rEKksP0B.js';
+import { CutsceneStatusPayload, CutsceneViewPayload, CutsceneLoadPayload, CameraPosePayload } from '@zylem/bridge';
+import '@sinclair/typebox';
+import 'three';
+import './entity-BIf_a4dl.js';
+import './simulation-body-zQw-emOr.js';
+import '@zylem/behaviors/core';
+import 'three/webgpu';
+import './base-node-idopiSw5.js';
+import './base-node-life-cycle-BK9xebT9.js';
+import './entity-type-map-CrsrKT8c.js';
+import './entity-XqvuWgPm.js';
+import './vector-D3eDzvcA.js';
+import './material-CxxAyJYp.js';
+import './collision-builder-BckxkdmA.js';
+import './events.js';
+import 'mitt';
+import './selection-bounds-BKmSo9aG.js';
+import '@zylem/behaviors/particle-emitter';
+import 'three/addons/lines/webgpu/Line2.js';
+import './game-interfaces-vF5sRi1n.js';
+
+/**
+ * Pure evaluation of a cutscene at a point in time: which scene and shot are
+ * active, where each camera is, and the blended pose the picture should
+ * show. Nothing here touches Three.js cameras or the stage, so the same code
+ * drives the runtime player, the editor's scrubbing, and the unit specs.
+ */
+declare function easeValue(easing: CutsceneEasing, t: number): number;
+interface EvaluatedPose {
+    position: Vec3Def;
+    lookAt: Vec3Def;
+    fov: number;
+}
+declare function lerpVec3(a: Vec3Def, b: Vec3Def, t: number): Vec3Def;
+declare function lerpPose(a: EvaluatedPose, b: EvaluatedPose, t: number): EvaluatedPose;
+/** The scene containing `time` (last one wins on shared boundaries; the final scene past the end). */
+declare function sceneAt(scenes: readonly CutsceneScene[], time: number): CutsceneScene | undefined;
+/** The shot covering `time` on one track, if any (last one wins on overlaps). */
+declare function shotAt(shots: readonly CameraShot[], time: number): CameraShot | undefined;
+/**
+ * The active shot across every camera track. Tracks are prioritised in
+ * order, so a shot on the first camera track overrides one on the second.
+ */
+declare function activeShot(definition: CutsceneDefinition, time: number): CameraShot | undefined;
+/** The shot that ended most recently before `shot` began, on any camera track. */
+declare function previousShot(definition: CutsceneDefinition, shot: CameraShot): CameraShot | undefined;
+/** Point along a dolly path at `u` in 0…1 (arc-length parameterised). */
+declare function dollyPointAt(path: DollyPath, u: number): Vec3Def;
+/** Evenly spaced samples of a dolly path, for drawing it. */
+declare function sampleDollyPath(path: DollyPath, segments?: number): Vec3Def[];
+/** Positions of named entities the cameras may reference, by name. */
+type TargetLookup = (name: string) => Vec3Def | undefined;
+/**
+ * Where a camera is at `time` while `shot` is active: base pose, then dolly
+ * progress or follow target, then keyframes on top.
+ */
+declare function evaluateCameraPose(camera: CutsceneCamera, definition: Pick<CutsceneDefinition, 'dollies'>, shot: Pick<CameraShot, 'start' | 'end'>, time: number, lookup?: TargetLookup): EvaluatedPose;
+interface CutsceneFrame {
+    scene: CutsceneScene | undefined;
+    shot: CameraShot | undefined;
+    camera: CutsceneCamera | undefined;
+    pose: EvaluatedPose | undefined;
+    /** 0…1 while blending in from the previous shot, else 1. */
+    blend: number;
+}
+/**
+ * Everything the picture needs at `time`: the active scene and shot, and the
+ * camera pose after blending from the previous shot when the shot asks for
+ * it. Without an active shot the pose is `undefined` and the gameplay camera
+ * keeps control.
+ */
+declare function evaluateCutscene(definition: CutsceneDefinition, time: number, lookup?: TargetLookup): CutsceneFrame;
+/** Items on every event/audio track with `time` in `(from, to]`, in time order. */
+declare function itemsBetween<T extends {
+    time: number;
+}>(items: readonly T[], from: number, to: number): T[];
+/** Camera tracks in priority order. */
+declare function cameraTracks(definition: CutsceneDefinition): CameraTrack[];
+/** Total length: the declared duration, or the furthest scene end if longer. */
+declare function cutsceneLength(definition: Pick<CutsceneDefinition, 'duration' | 'scenes'>): number;
+
+/** Pipeline key the cutscene player registers its behavior under. */
+declare const CUTSCENE_BEHAVIOR_KEY = "cutscene";
+/**
+ * Camera behavior that hands the pipeline a fixed pose each frame while a
+ * cutscene is playing. It runs after the game's own behaviors (high
+ * priority) so shots override follow/look-at logic, and it disables itself
+ * when the player has no pose (no active shot) so gameplay framing resumes.
+ *
+ * `damping` applies optional per-frame smoothing for follow cameras; the
+ * player passes 0 for authored moves so keyframes land exactly.
+ */
+declare class CutsceneCameraBehavior implements CameraBehavior {
+    priority: number;
+    enabled: boolean;
+    private target;
+    private smoothed;
+    private damping;
+    /** Sets the pose to show; `null` releases the camera back to gameplay. */
+    setPose(pose: EvaluatedPose | null, damping?: number): void;
+    /** Snap smoothing state so the next frame lands exactly on the pose (seeks, cuts). */
+    snap(): void;
+    onDetach(): void;
+    update(ctx: CameraContext, pose: CameraPose): CameraPose;
+}
+
+type CutscenePlayerState = 'idle' | 'playing' | 'paused' | 'finished';
+/**
+ * What the player needs from the running game. `createStageCutsceneHost`
+ * builds one from a live stage; tests and the editor can hand in stubs.
+ */
+interface CutsceneHost {
+    /** The camera the cutscene drives; resolved each frame so stage swaps are safe. */
+    camera: () => ZylemCamera | null;
+    /** World position of a named entity, for follow cameras and dolly look-ats. */
+    entityPosition?: (name: string) => Vec3Def | undefined;
+    playAnimation?: (entity: string, key: string) => void;
+    /** Stage event dispatch (`emit` events). */
+    dispatch?: (name: string, payload: Record<string, unknown>) => void;
+    setVariable?: (name: string, value: unknown) => void;
+    playSong?: (ref: string, options: {
+        loop: boolean;
+        volume: number;
+    }) => void;
+    stopSong?: (ref?: string) => void;
+    playSfx?: (url: string, options: {
+        volume: number;
+        loop: boolean;
+    }) => void;
+    /**
+     * Runs a picture transition into the new scene: snapshot the current frame
+     * and blend it into the frames that follow. Omit to hard-cut everywhere.
+     */
+    beginTransition?: (transition: SceneTransition, shader: ZylemTransitionShader | undefined) => void;
+}
+interface CutscenePlayerOptions {
+    host: CutsceneHost;
+    /**
+     * `auto` (default) advances on `requestAnimationFrame`; `manual` leaves it
+     * to the caller's `update(dt)` — e.g. a stage `update` hook, so the
+     * cutscene pauses with the game.
+     */
+    tick?: 'auto' | 'manual';
+    /** Maps a transition type to a blend shader (e.g. `createStageTransition({ pattern }).shader`). */
+    transitionShader?: (type: SceneTransitionType) => ZylemTransitionShader | undefined;
+    /** Fire events/audio crossed by a `seek`. Off by default: scrubbing should not trigger gameplay. */
+    fireEventsOnSeek?: boolean;
+    timeScale?: number;
+}
+interface CutscenePlayerEvents {
+    time: (time: number) => void;
+    state: (state: CutscenePlayerState) => void;
+    scene: (scene: CutsceneScene | undefined) => void;
+    shot: (shot: CameraShot | undefined) => void;
+    event: (item: EventItem) => void;
+    audio: (item: AudioItem) => void;
+    complete: () => void;
+    skip: () => void;
+}
+interface CutscenePlayer {
+    readonly definition: CutsceneDefinition;
+    readonly state: CutscenePlayerState;
+    /** Seconds. */
+    readonly time: number;
+    readonly length: number;
+    /** The pose the picture shows right now, if a shot is active. */
+    readonly pose: EvaluatedPose | undefined;
+    play(from?: number): void;
+    pause(): void;
+    /** Stops, rewinds, and returns the camera to gameplay. */
+    stop(): void;
+    seek(time: number): void;
+    /** Jumps to the end (when `skippable`) and completes. */
+    skip(): boolean;
+    /** Advances by `dt` seconds; only needed with `tick: 'manual'`. */
+    update(dt: number): void;
+    /** Swaps the definition in place, keeping time and state (live editing). */
+    setDefinition(definition: CutsceneDefinition): void;
+    on<K extends keyof CutscenePlayerEvents>(event: K, handler: CutscenePlayerEvents[K]): () => void;
+    dispose(): void;
+}
+/**
+ * Plays a cutscene against a live stage: drives the camera through a
+ * pipeline behavior, fires event/audio items as the playhead crosses them,
+ * and runs scene transitions through the renderer.
+ *
+ * ```ts
+ * const player = createCutscenePlayer(INTRO_CUTSCENE, { host: createStageCutsceneHost(stage) });
+ * player.on('complete', () => player.dispose());
+ * player.play();
+ * ```
+ */
+declare function createCutscenePlayer(initial: CutsceneDefinition, options: CutscenePlayerOptions): CutscenePlayer;
+
+interface StageCutsceneHostOptions {
+    /**
+     * Looks a song reference (slug or URL from a `playSong` event / audio
+     * item) up to a definition the audio module can play. Without it song
+     * items are ignored.
+     */
+    resolveSong?: (ref: string) => SongDefinition | Promise<SongDefinition | undefined> | undefined;
+    /** Maps a transition type to a blend shader; defaults to a crossfade for every type. */
+    transitionShader?: (type: SceneTransitionType) => ZylemTransitionShader | undefined;
+    /** Called for `emit` events in addition to the stage dispatch. */
+    onEvent?: (name: string, payload: Record<string, unknown>) => void;
+}
+/**
+ * Registers the blend shaders every stage-bound cutscene uses for its scene
+ * transitions, typically once at startup:
+ *
+ * ```ts
+ * import { createStageTransition } from '@zylem/shaders';
+ * setCutsceneTransitionShaders((type) => createStageTransition({ pattern: type }).shader);
+ * ```
+ *
+ * Without this, every non-`cut` transition is a plain crossfade.
+ */
+declare function setCutsceneTransitionShaders(resolver: ((type: SceneTransitionType) => ZylemTransitionShader | undefined) | null): void;
+/**
+ * A `CutsceneHost` bound to a live stage: drives the stage camera, resolves
+ * entities by name, dispatches stage events, writes stage variables, plays
+ * songs through `@zylem/game-lib/audio` (loaded on demand) and one-shots
+ * through Howler, and runs scene transitions on the stage renderer.
+ */
+/** What a stage-bound cutscene plays on: the public `Stage` wrapper or the internal stage. */
+type CutsceneStageLike = ZylemStage | Stage;
+declare function createStageCutsceneHost(stageLike: CutsceneStageLike, options?: StageCutsceneHostOptions): CutsceneHost;
+
+/**
+ * Editor preview of a cutscene inside the running game: answers the bridge's
+ * `cutscene:*` commands with a player bound to the current stage and reports
+ * progress back. Owned by `ZylemGame`; Director mode drives it.
+ */
+declare class CutscenePreviewController {
+    private readonly getStage;
+    private readonly publish;
+    private readonly hostOptions;
+    private readonly publishView?;
+    private player;
+    private lastStatus;
+    /** A load that arrived before the stage existed; replayed by `stageReady()`. */
+    private pending;
+    private readonly viewInverse;
+    private readonly viewProjection;
+    private lastView;
+    constructor(getStage: () => ZylemStage | null, publish: (status: CutsceneStatusPayload) => void, hostOptions?: StageCutsceneHostOptions, publishView?: ((view: CutsceneViewPayload) => void) | undefined);
+    get active(): boolean;
+    /**
+     * The game reports itself running before its first stage finishes loading,
+     * so an editor that loads a cutscene straight away would find no stage.
+     * The game calls this once a stage is up; a held load runs then.
+     */
+    stageReady(): void;
+    load(payload: CutsceneLoadPayload): void;
+    play(from?: number): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    /** Drops the player because its stage is going away; a held load survives for the next stage. */
+    releaseStage(): void;
+    /**
+     * Once per rendered frame while a cutscene is loaded: publishes the
+     * camera's projection and the canvas box when either changed, so the
+     * editor's overlays track the view without polling.
+     */
+    frame(): void;
+    unload(): void;
+    /** The live camera as position + look-at, for "capture from viewport". */
+    cameraPose(): Omit<CameraPosePayload, 'requestId'> | null;
+    private report;
+}
+
+export { AudioItem, CUTSCENE_BEHAVIOR_KEY, CameraShot, CameraTrack, CutsceneCamera, CutsceneCameraBehavior, CutsceneDefinition, CutsceneEasing, type CutsceneFrame, type CutsceneHost, type CutscenePlayer, type CutscenePlayerEvents, type CutscenePlayerOptions, type CutscenePlayerState, CutscenePreviewController, CutsceneScene, type CutsceneStageLike, DollyPath, type EvaluatedPose, EventItem, SceneTransition, SceneTransitionType, type StageCutsceneHostOptions, type TargetLookup, Vec3Def, activeShot, cameraTracks, createCutscenePlayer, createStageCutsceneHost, cutsceneLength, dollyPointAt, easeValue, evaluateCameraPose, evaluateCutscene, itemsBetween, lerpPose, lerpVec3, previousShot, sampleDollyPath, sceneAt, setCutsceneTransitionShaders, shotAt };

package/dist/cinematics.js

@@ -0,0 +1 @@
+import"./chunk-VMXSE3EC.js";import{a as u,b as v,c as w,d as x,e as y,f as z,g as A,h as B,i as C,j as D,k as E}from"./chunk-YNX3Q3CL.js";import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t}from"./chunk-2XMG3NJS.js";import"./chunk-7GYFZKK7.js";import"./chunk-QGIYILYI.js";import"./chunk-WOT6VMZA.js";export{C as AudioItemSchema,a as CUTSCENE_BEHAVIOR_KEY,w as CameraKeyframeSchema,z as CameraShotSchema,b as CutsceneCameraBehavior,x as CutsceneCameraSchema,E as CutsceneDefinitionSchema,A as CutsceneEventSchema,t as CutscenePreviewController,v as CutsceneSceneSchema,D as CutsceneTrackSchema,y as DollyPathSchema,B as EventItemSchema,u as SceneTransitionSchema,h as activeShot,o as cameraTracks,q as createCutscenePlayer,s as createStageCutsceneHost,p as cutsceneLength,j as dollyPointAt,c as easeValue,l as evaluateCameraPose,m as evaluateCutscene,n as itemsBetween,e as lerpPose,d as lerpVec3,i as previousShot,k as sampleDollyPath,f as sceneAt,r as setCutsceneTransitionShaders,g as shotAt};

package/dist/core.d.ts

@@ -1,29 +1,32 @@
-import { B as Stage, E as StageStateInterface, C as CameraWrapper } from './game-DyKbOeck.js';
-export { A as AspectRatio, q as AspectRatioValue, k as CameraManager, j as CameraOptions, D as DeviceProfile, p as FirstPersonOptions, l as FirstPersonPerspective, o as Fixed2DOptions, F as Fixed2DPerspective, G as Game, b as GameConfigLike, d as GameDeviceConfig, a as GameLoadingEvent, P as PerspectiveOptions, y as RenderBundleManager, z as RenderStrategyManager, R as ResolutionInput, e as ResolveGameConfigRuntime, v as RetroPreset, w as RetroPresetKey, x as RetroResolution, S as StageConfigLike, h as StageOptions, n as ThirdPersonOptions, T as ThirdPersonPerspective, i as createCamera, c as createGame, m as createPerspective, f as createStage, g as gameConfig, r as getDisplayAspect, t as getPresetResolution, u as parseResolution, s as stageConfig } from './game-DyKbOeck.js';
+import { S as StageStateInterface } from './game-D8KTP3fD.js';
+export { A as AspectRatio, f as AspectRatioValue, D as DeviceProfile, G as Game, b as GameConfigLike, d as GameDeviceConfig, a as GameLoadingEvent, R as ResolutionInput, e as ResolveGameConfigRuntime, j as RetroPreset, k as RetroPresetKey, l as RetroResolution, c as createGame, g as gameConfig, h as getDisplayAspect, i as getPresetResolution, p as parseResolution } from './game-D8KTP3fD.js';
 export { G as GameInputConfig, a as GameInputPlayerConfig, K as KeyboardMapping, M as MouseConfig, b as MouseMapping, V as VirtualTouchButtonConfig, d as VirtualTouchButtonSlot, c as VirtualTouchButtonsConfig, e as VirtualTouchConfig, f as VirtualTouchJoystickConfig, g as VirtualTouchJoysticksConfig, h as VirtualTouchPosition, i as VirtualTouchStyle, Z as ZylemGameConfig } from './game-interfaces-vF5sRi1n.js';
+import { q as Stage, C as CameraWrapper } from './stage-CAPlk_cN.js';
+export { e as CameraManager, d as CameraOptions, l as FirstPersonOptions, f as FirstPersonPerspective, k as Fixed2DOptions, F as Fixed2DPerspective, n as IsometricOptions, I as IsometricPerspective, P as PerspectiveOptions, R as RenderBundleManager, p as RenderStrategyManager, m as SecondPersonOptions, g as SecondPersonPerspective, S as StageConfigLike, a as StageOptions, j as ThirdPersonOptions, T as ThirdPersonPerspective, o as TopDownOptions, h as TopDownPerspective, b as createCamera, i as createPerspective, c as createStage, s as stageConfig } from './stage-CAPlk_cN.js';
 import { Vector2 } from 'three';
 import { G as GameEntity, a as GameEntityOptions } from './entity-XqvuWgPm.js';
 import { S as StageBlueprint } from './blueprints-TbGY-h53.js';
 import { a as SetupContext, k as LoadedContext, U as UpdateContext, D as DestroyContext, l as CleanupContext } from './base-node-life-cycle-BK9xebT9.js';
 export { L as LoadingEvent, S as StageNavigationOptions } from './base-node-life-cycle-BK9xebT9.js';
 export { S as StageTransitionConfig, a as StageTransitionEasing, Z as ZylemTransitionShader, c as crossfadeTransitionShader } from './stage-transition-CmGpV4tc.js';
-import { f as CameraBehavior } from './zylem-camera-DZTpPOiD.js';
-export { g as CameraAction, d as CameraContext, e as CameraPerspective, j as CameraPipeline, h as CameraPipelineState, C as CameraPose, P as PerspectiveType, a as Perspectives, c as PoseDelta, T as TransformLike, V as Viewport, b as ZylemRenderer, i as isWebGPUSupported } from './zylem-camera-DZTpPOiD.js';
+import { f as CameraBehavior } from './zylem-camera-CYDtrVgi.js';
+export { g as CameraAction, d as CameraContext, e as CameraPerspective, k as CameraPipeline, h as CameraPipelineState, C as CameraPose, j as CameraProjection, P as PerspectiveType, a as Perspectives, c as PoseDelta, T as TransformLike, V as Viewport, b as ZylemRenderer, i as isWebGPUSupported } from './zylem-camera-CYDtrVgi.js';
 import { e as Vec3Input, c as Vec3 } from './vector-D3eDzvcA.js';
 export { f as VEC2_ONE, g as VEC2_ZERO, h as VEC3_ONE, i as VEC3_ZERO, V as Vec2, a as Vec2Components, b as Vec2Input, d as Vec3Components, n as normalizeVec2, j as normalizeVec3, t as toThreeVector2, k as toThreeVector3 } from './vector-D3eDzvcA.js';
 import { S as StageEntity } from './entity-BIf_a4dl.js';
 import { B as BaseNode, N as NodeInterface } from './base-node-idopiSw5.js';
-import './entity-type-map-D6BeAdvg.js';
+import './default-controls-CAKJ5zlo.js';
+import './events.js';
+import 'mitt';
+import '@zylem/behaviors/core';
+import './entity-type-map-CrsrKT8c.js';
 import './material-CxxAyJYp.js';
 import 'three/webgpu';
-import '@zylem/behaviors/core';
+import './selection-bounds-BKmSo9aG.js';
 import '@zylem/behaviors/particle-emitter';
 import 'three/addons/lines/webgpu/Line2.js';
 import './simulation-body-zQw-emOr.js';
 import '@zylem/bridge';
-import './events.js';
-import 'mitt';
-import './default-controls-CAKJ5zlo.js';
 import './collision-builder-BckxkdmA.js';
 import '@sinclair/typebox';
 
@@ -135,6 +138,117 @@ interface FollowTargetOptions {
  */
 declare function createFollowTarget(options?: FollowTargetOptions): CameraBehavior;
 
+/** How one axis of the follow focus tracks the target. */
+type PlatformAxisMode = 'delay' | 'settle' | 'off';
+interface PlatformAxisModes {
+    x?: PlatformAxisMode;
+    y?: PlatformAxisMode;
+    z?: PlatformAxisMode;
+}
+/**
+ * Options for the Super Mario World style follow.
+ *
+ * `delay` lerps toward the target and can wait inside a deadzone.
+ * `settle` holds still while the axis is moving (a jump, a lane change) and
+ * eases to the new rest once the axis goes quiet — landing on a platform.
+ * `off` leaves that axis of the incoming pose alone.
+ */
+interface PlatformFollowOptions {
+    /** Key in CameraContext.targets to follow. Default 'primary'. */
+    targetKey?: string;
+    /**
+     * Per-axis mode. Default: x and z delay, y settles. Vertical jumps do not
+     * drag the camera; landing does. The same settle mode works on a horizontal axis.
+     */
+    axes?: PlatformAxisModes;
+    /**
+     * Interpolation factor for `delay` axes, in 0..1 per 60Hz frame.
+     * 1 = instant. Scaled by dt. Default 0.1.
+     */
+    lerpFactor?: number;
+    /**
+     * Deadzone in world units for `delay` axes. The focus holds until the
+     * target (plus lookahead) leaves this window. Default 0.
+     */
+    window?: number;
+    /** Speed, in units/second, at or below which a `settle` axis counts as resting. Default 0.75. */
+    settleSpeed?: number;
+    /** Seconds a `settle` axis must stay slow before the focus accepts the new rest. Default 0.15. */
+    settleTime?: number;
+    /** Interpolation factor used once a `settle` axis has a new rest. Default 0.08. */
+    settleLerp?: number;
+    /**
+     * World units of lookahead along the last travel direction.
+     * Applied on `delay` axes only. Default 0.
+     */
+    lookahead?: number;
+}
+/**
+ * Follow a target with per-axis delay or platform settling.
+ *
+ * Shifts `position` and `lookAt` by the same delta, so the perspective's
+ * offset stays intact and the framed point becomes the filtered focus.
+ *
+ * "On a platform" is inferred from the axis going quiet. Games do not have
+ * to supply a grounded flag.
+ */
+declare function createPlatformFollow(options?: PlatformFollowOptions): CameraBehavior;
+
+/**
+ * Pointer for edge scrolling.
+ * `x`/`y` are 0..1 from the top-left, unless `centered` is set, in which case
+ * they are −1..1 with −1 at the left and top (the shape of `inputs.p1.pointer.centerX/Y`).
+ */
+interface StrategyPointer {
+    x: number;
+    y: number;
+    centered?: boolean;
+}
+/** What {@link StrategyPanOptions.sampleInput} returns each frame. */
+interface StrategyPanInput {
+    pointer?: StrategyPointer;
+    /** Stick or arrow intent, −1..1. +x is screen right, +y is screen up. */
+    pan?: {
+        x: number;
+        y: number;
+    };
+}
+interface StrategyPanOptions {
+    /**
+     * Read pointer and pan intent. Kept as a closure so the behavior does not
+     * import InputManager. Typical source: `inputs.p1.pointer` and directions.
+     */
+    sampleInput?: () => StrategyPanInput;
+    /** Fraction of the viewport that counts as an edge. Default 0.08. */
+    edgeMargin?: number;
+    /** World units per second at a flush edge. Default 12. */
+    edgeSpeed?: number;
+    /** World units per second at full stick deflection. Default 16. */
+    panSpeed?: number;
+    /** Target key to ease toward. Null follows nothing. */
+    followKey?: string | null;
+    /** Interpolation factor while following, per 60Hz frame. Default 0.12. */
+    followLerp?: number;
+    /**
+     * A manual pan or edge scroll drops follow until {@link StrategyPanBehavior.setFollowKey}.
+     * Default true.
+     */
+    breakFollowOnPan?: boolean;
+}
+interface StrategyPanBehavior extends CameraBehavior {
+    /** Follow `key`, or pass null to pan freely. Clears a manual-pan suspension. */
+    setFollowKey(key: string | null): void;
+}
+/**
+ * StarCraft-style pan on the XZ plane.
+ *
+ * The perspective (top-down or isometric) owns the angle. This behavior only
+ * slides the framed point: edge scroll, arrow or stick pan, and an optional
+ * follow target. Screen up maps to world −Z, which matches a top-down camera
+ * whose up vector is −Z.
+ */
+declare function createStrategyPan(options?: StrategyPanOptions): StrategyPanBehavior;
+
 /**
  * Options for setCameraFeed.
  */
@@ -224,4 +338,4 @@ declare function isManagedRenderEntity(entity: {
  */
 type Vect3 = Vec3;
 
-export { CameraBehavior, type CameraFeedOptions, CameraWrapper, type FollowTargetOptions, type RenderCategory, STAGE_STATE_CHANGE, SetupContext, StageBlueprint, StageEntity, StageManager, type StageStateChangeEvent, UpdateContext, Vec3, Vec3Input, type Vect3, createFollowTarget, dispatchStageState, entitySpawner, initStageStateDispatcher, isManagedRenderEntity, resolveRenderCategory, setCameraFeed, setStageFrameProfilerEnabled, stageState, usesManagedRenderPath, vessel };
+export { CameraBehavior, type CameraFeedOptions, CameraWrapper, type FollowTargetOptions, type PlatformAxisMode, type PlatformAxisModes, type PlatformFollowOptions, type RenderCategory, STAGE_STATE_CHANGE, SetupContext, StageBlueprint, StageEntity, StageManager, type StageStateChangeEvent, type StrategyPanBehavior, type StrategyPanInput, type StrategyPanOptions, type StrategyPointer, UpdateContext, Vec3, Vec3Input, type Vect3, createFollowTarget, createPlatformFollow, createStrategyPan, dispatchStageState, entitySpawner, initStageStateDispatcher, isManagedRenderEntity, resolveRenderCategory, setCameraFeed, setStageFrameProfilerEnabled, stageState, usesManagedRenderPath, vessel };

package/dist/core.js

@@ -1 +1 @@
-import{a as b,b as c,c as d,d as e,e as f,f as H,g as I,h as J,i as K,j as L,k as M,l as N,m as O,n as P,o as Q}from"./chunk-AXJTUVGC.js";import{a,c as p,d as q,e as r,f as s,g as t,h as u,i as v,k as w,l as x,m as y,n as z,o as A,p as B,q as C,r as D,s as E,t as F,v as G}from"./chunk-BWOZF5YK.js";import{a as o}from"./chunk-7GYFZKK7.js";import"./chunk-Q2YDBMVY.js";import"./chunk-BCFFS3FP.js";import"./chunk-EYDC2PMO.js";import"./chunk-2HSR5XDQ.js";import"./chunk-G3TBBZUI.js";import"./chunk-CBUQBP2U.js";import"./chunk-EVMLNMGU.js";import"./chunk-WBQ5TNRZ.js";import"./chunk-7JSZEEAE.js";import"./chunk-YQS7CGXE.js";import"./chunk-X7T7QRYP.js";import"./chunk-KP6DLLJO.js";import"./chunk-6FGXC4T6.js";import"./chunk-AIQ6IVT5.js";import"./chunk-QXVH6POE.js";import"./chunk-EVYHPR3J.js";import"./chunk-VUJXR5K5.js";import"./chunk-D2PATZCC.js";import"./chunk-4QLJUQSJ.js";import{a as g,b as h,c as i,d as j,g as k,h as l,i as m,j as n}from"./chunk-7WRQ2UAN.js";import"./chunk-BH53MBAZ.js";import"./chunk-XRP4JJXL.js";import"./chunk-PCFF4LLO.js";import"./chunk-UG22Z42P.js";import"./chunk-WOT6VMZA.js";export{b as AspectRatio,B as CameraManager,w as CameraPipeline,C as CameraWrapper,z as FirstPersonPerspective,y as Fixed2DPerspective,J as Game,v as Perspectives,s as RenderBundleManager,t as RenderStrategyManager,M as STAGE_STATE_CHANGE,I as StageManager,x as ThirdPersonPerspective,h as VEC2_ONE,g as VEC2_ZERO,j as VEC3_ONE,i as VEC3_ZERO,D as createCamera,P as createFollowTarget,K as createGame,A as createPerspective,G as createStage,o as crossfadeTransitionShader,O as dispatchStageState,L as entitySpawner,f as gameConfig,c as getDisplayAspect,d as getPresetResolution,N as initStageStateDispatcher,r as isManagedRenderEntity,a as isWebGPUSupported,k as normalizeVec2,l as normalizeVec3,e as parseResolution,p as resolveRenderCategory,Q as setCameraFeed,u as setStageFrameProfilerEnabled,E as stageConfig,H as stageState,m as toThreeVector2,n as toThreeVector3,q as usesManagedRenderPath,F as vessel};
+import{a as b,b as c,c as d,d as e,e as f,f as K,g as L,h as M,i as N,j as O,k as P,l as Q,m as R,n as S,o as T,p as U,q as V}from"./chunk-SHDHPDOV.js";import{a,c as p,d as q,e as r,f as s,g as t,h as u,i as v,k as w,l as x,m as y,n as z,o as A,p as B,q as C,r as D,s as E,t as F,u as G,v as H,w as I,y as J}from"./chunk-SWDNK4GG.js";import"./chunk-PCFF4LLO.js";import"./chunk-Q2YDBMVY.js";import"./chunk-BCFFS3FP.js";import"./chunk-VSFULLND.js";import"./chunk-2HSR5XDQ.js";import"./chunk-7CBJKE42.js";import"./chunk-BQRMYLYD.js";import"./chunk-GPCSX3M6.js";import"./chunk-WBQ5TNRZ.js";import"./chunk-LI43BZQN.js";import"./chunk-YQS7CGXE.js";import"./chunk-STVEILJJ.js";import"./chunk-KP6DLLJO.js";import"./chunk-6FGXC4T6.js";import"./chunk-AIQ6IVT5.js";import"./chunk-QXVH6POE.js";import"./chunk-UUOPT2N4.js";import"./chunk-EVYHPR3J.js";import"./chunk-VUJXR5K5.js";import"./chunk-2XMG3NJS.js";import{a as o}from"./chunk-7GYFZKK7.js";import"./chunk-QGIYILYI.js";import"./chunk-D2PATZCC.js";import"./chunk-4QLJUQSJ.js";import{a as g,b as h,c as i,d as j,g as k,h as l,i as m,j as n}from"./chunk-7WRQ2UAN.js";import"./chunk-BH53MBAZ.js";import"./chunk-XRP4JJXL.js";import"./chunk-UG22Z42P.js";import"./chunk-WOT6VMZA.js";export{b as AspectRatio,E as CameraManager,w as CameraPipeline,F as CameraWrapper,z as FirstPersonPerspective,y as Fixed2DPerspective,M as Game,A as IsometricPerspective,v as Perspectives,s as RenderBundleManager,t as RenderStrategyManager,P as STAGE_STATE_CHANGE,C as SecondPersonPerspective,L as StageManager,x as ThirdPersonPerspective,B as TopDownPerspective,h as VEC2_ONE,g as VEC2_ZERO,j as VEC3_ONE,i as VEC3_ZERO,G as createCamera,S as createFollowTarget,N as createGame,D as createPerspective,T as createPlatformFollow,J as createStage,U as createStrategyPan,o as crossfadeTransitionShader,R as dispatchStageState,O as entitySpawner,f as gameConfig,c as getDisplayAspect,d as getPresetResolution,Q as initStageStateDispatcher,r as isManagedRenderEntity,a as isWebGPUSupported,k as normalizeVec2,l as normalizeVec3,e as parseResolution,p as resolveRenderCategory,V as setCameraFeed,u as setStageFrameProfilerEnabled,H as stageConfig,K as stageState,m as toThreeVector2,n as toThreeVector3,q as usesManagedRenderPath,I as vessel};