@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.2

package/dist/runtime/client/services/cinematic.d.ts

@@ -0,0 +1,288 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { IClientPlatformBridge } from '../adapter/platform-bridge';
+import { IClientRuntimeBridge } from '../adapter/runtime-bridge';
+import { type CameraEffectDefinition, type CameraEffectReference, CameraEffectsRegistry } from './camera-effects.registry';
+import { type CameraRotation, Camera } from './camera';
+import { SceneBuilder, type SceneBuildable } from './cinematic-builder';
+/**
+ * Supported easing names for timeline interpolation.
+ */
+export type CinematicEase = 'linear' | 'inSine' | 'outSine' | 'inOutSine' | 'inCubic' | 'outCubic' | 'inOutCubic';
+/**
+ * Position source resolved at runtime.
+ */
+export type PositionInput = {
+    type: 'coords';
+    x: number;
+    y: number;
+    z: number;
+} | {
+    type: 'entity';
+    entity: number;
+    offset?: Vector3;
+} | {
+    type: 'entityBone';
+    entity: number;
+    bone: number;
+    offset?: Vector3;
+} | {
+    type: 'anchor';
+    name: string;
+    offset?: Vector3;
+} | {
+    type: 'resolver';
+    resolve: () => Vector3 | Promise<Vector3>;
+};
+/**
+ * Camera node input used by shot from/to/path definitions.
+ */
+export type CameraNodeInput = PositionInput & {
+    rotation?: CameraRotation;
+    fov?: number;
+};
+/**
+ * Look-at target source resolved at runtime.
+ */
+export type LookAtInput = PositionInput;
+/**
+ * A single cinematic timeline shot.
+ */
+export interface CinematicShot {
+    /** Optional stable shot id for runtime edits. */
+    id?: string;
+    /** Shot duration. Required for camera movement shots. */
+    durationMs?: number;
+    /** Wait step duration without camera transform changes. */
+    waitMs?: number;
+    /** Start camera node used when path is omitted. */
+    from?: CameraNodeInput;
+    /** End camera node used when path is omitted. */
+    to?: CameraNodeInput;
+    /** Multi-point path that may mix different position source types. */
+    path?: CameraNodeInput[];
+    /** Optional look target or look target path. */
+    lookAt?: LookAtInput | LookAtInput[];
+    /** Interpolation easing. Defaults to linear. */
+    ease?: CinematicEase;
+    /** Effects applied only during this shot. */
+    effects?: CameraEffectReference[];
+}
+/**
+ * Full cinematic timeline definition.
+ */
+export interface CinematicDefinition {
+    /** Optional timeline id used for logs/debugging. */
+    id?: string;
+    /** Whether player can skip with skipControlId. */
+    skippable?: boolean;
+    /** Freeze player while running. */
+    freezePlayer?: boolean;
+    /** Set player invincible while running. */
+    invinciblePlayer?: boolean;
+    /** Hide HUD while running. */
+    hideHud?: boolean;
+    /** Hide radar while running. */
+    hideRadar?: boolean;
+    /** Global effects active across all shots. */
+    effects?: CameraEffectReference[];
+    /** Effect presets to expand into global effects. */
+    effectPresets?: string[];
+    /** Reusable named anchors for this timeline. */
+    anchors?: Record<string, Vector3>;
+    /** Ordered timeline shots. */
+    shots: CinematicShot[];
+}
+/**
+ * Runtime options for playback.
+ */
+export interface CinematicStartOptions {
+    /** Control id used to skip when skippable is true. */
+    skipControlId?: number;
+    /** Camera name used for CreateCam. */
+    cameraName?: string;
+}
+/**
+ * Final status of a cinematic timeline.
+ */
+export type CinematicResultStatus = 'completed' | 'cancelled' | 'interrupted';
+/**
+ * Completion payload returned by play() and handle.result.
+ */
+export interface CinematicResult {
+    status: CinematicResultStatus;
+    definitionId?: string;
+}
+/**
+ * Structured validation error thrown when a cinematic definition is invalid.
+ */
+export declare class CinematicValidationError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/**
+ * Payload for shot lifecycle events.
+ */
+export interface CinematicShotEventPayload {
+    shotIndex: number;
+    totalShots: number;
+    shotId?: string;
+    kind: 'wait' | 'motion';
+    plannedDurationMs: number;
+}
+/**
+ * Payload for effect activation events.
+ */
+export interface CinematicEffectEventPayload {
+    effectId: string;
+    shotIndex: number;
+    shotId?: string;
+}
+/**
+ * Event payload mapping for strongly typed subscriptions.
+ */
+export interface CinematicEventPayloadMap {
+    shotStart: CinematicShotEventPayload;
+    shotEnd: CinematicShotEventPayload;
+    effectApplied: CinematicEffectEventPayload;
+    paused: undefined;
+    resumed: undefined;
+    completed: CinematicResult;
+    cancelled: CinematicResult;
+    interrupted: CinematicResult;
+}
+/**
+ * Runtime events emitted by cinematic handles.
+ */
+export type CinematicEventName = 'shotStart' | 'shotEnd' | 'effectApplied' | 'paused' | 'resumed' | 'completed' | 'cancelled' | 'interrupted';
+type CinematicEventHandler<TPayload> = (payload: TPayload) => void;
+interface CinematicRuntimeState {
+    definition: CinematicDefinition;
+    options: Required<CinematicStartOptions>;
+    camHandle: number;
+    cancelled: boolean;
+    paused: boolean;
+    pauseStartedAt: number | null;
+    interruptStatus: CinematicResultStatus | null;
+}
+/**
+ * Mutable control handle for a running cinematic.
+ */
+export declare class CinematicHandle {
+    private runtime;
+    /** Promise resolved when the cinematic finishes. */
+    readonly result: Promise<CinematicResult>;
+    private listeners;
+    constructor(runtime: CinematicRuntimeState, 
+    /** Promise resolved when the cinematic finishes. */
+    result: Promise<CinematicResult>);
+    /**
+     * Pauses timeline progression.
+     */
+    pause(): void;
+    /**
+     * Resumes timeline progression.
+     */
+    resume(): void;
+    /**
+     * Cancels timeline execution.
+     */
+    cancel(): void;
+    /**
+     * Requests skip as a cancellation with completed cleanup.
+     */
+    skip(): void;
+    /**
+     * Applies an in-place patch to the live definition object.
+     */
+    edit(mutator: (definition: CinematicDefinition) => void): void;
+    /**
+     * Inserts a shot at a specific index.
+     */
+    insertShot(index: number, shot: CinematicShot): void;
+    /**
+     * Replaces a shot by id or no-ops when not found.
+     */
+    replaceShot(shotId: string, shot: CinematicShot): void;
+    /**
+     * Replaces global effects for the running definition.
+     */
+    setEffects(effects: CameraEffectReference[]): void;
+    /**
+     * Adds a global effect to the running definition.
+     */
+    addEffect(effect: CameraEffectReference): void;
+    /**
+     * Removes all global effects with a matching id.
+     */
+    removeEffect(effectId: string): void;
+    /**
+     * Subscribes to runtime handle events.
+     */
+    on<TEventName extends CinematicEventName>(eventName: TEventName, handler: CinematicEventHandler<CinematicEventPayloadMap[TEventName]>): () => void;
+    /**
+     * Emits an event to handle subscribers.
+     */
+    emit<TEventName extends CinematicEventName>(eventName: TEventName, payload: CinematicEventPayloadMap[TEventName]): void;
+}
+/**
+ * High-level cinematic timeline API built on top of Camera.
+ */
+export declare class Cinematic {
+    private readonly camera;
+    private readonly platform;
+    private readonly runtimeBridge;
+    /**
+     * Exposes the registry so consumers can add custom effects and presets.
+     */
+    readonly effects: CameraEffectsRegistry;
+    private activeRuntime;
+    constructor(camera: Camera, effectsRegistry: CameraEffectsRegistry, platform: IClientPlatformBridge, runtimeBridge: IClientRuntimeBridge);
+    /**
+     * Creates a fluent cinematic scene builder bound to this service.
+     */
+    scene(id?: string): SceneBuilder;
+    /**
+     * Starts a cinematic and returns a mutable runtime handle immediately.
+     */
+    start(scene: SceneBuildable, options?: CinematicStartOptions): CinematicHandle;
+    /**
+     * Starts and awaits a cinematic timeline until completion.
+     */
+    play(scene: SceneBuildable, options?: CinematicStartOptions): Promise<CinematicResult>;
+    /**
+     * Returns true when a cinematic timeline is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Cancels the active cinematic if one exists.
+     */
+    cancel(): void;
+    /**
+     * Registers a custom effect.
+     */
+    registerEffect<TParams = Record<string, unknown>>(effect: CameraEffectDefinition<TParams>): void;
+    private run;
+    private applyRuntimeFlags;
+    private cleanupRuntime;
+    private resolveGlobalEffects;
+    private buildRuntimeEffects;
+    private runShot;
+    private waitStep;
+    private updateEffects;
+    private finalizeEffects;
+    private createEffectContext;
+    private resolveShotNodes;
+    private resolveCameraNode;
+    private resolveLookAtTarget;
+    private resolvePosition;
+    private validateDefinition;
+    private validateEffects;
+    private validatePositionNode;
+    private sampleNode;
+    private samplePosition;
+    private interpolateRotation;
+    private interpolateFov;
+    private lerp;
+    private applyEase;
+}
+export {};