@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/runtime/client/services/camera-effects.registry.d.ts

@@ -0,0 +1,94 @@
+import { Camera } from './camera';
+/**
+ * Reason reported when an effect instance is finalized.
+ */
+export type EffectTeardownReason = 'completed' | 'cancelled' | 'interrupted';
+/**
+ * Shared context delivered to effect handlers.
+ */
+export interface CameraEffectContext {
+    /** Low-level camera API instance used by the cinematic runtime. */
+    camera: Camera;
+    /** Active camera handle for the running cinematic. */
+    camHandle: number;
+    /** Absolute elapsed time in milliseconds within the current shot. */
+    elapsedMs: number;
+    /** Normalized [0..1] progress inside the active effect window. */
+    normalized: number;
+    /** Delta time since previous frame in milliseconds. */
+    deltaMs: number;
+    /** Draws a subtitle line on screen for one frame. */
+    drawSubtitle(text: string): void;
+    /** Draws cinematic bars for one frame. */
+    drawLetterbox(top: number, bottom: number, alpha?: number): void;
+}
+/**
+ * A reusable effect implementation.
+ */
+export interface CameraEffectDefinition<TParams = Record<string, unknown>> {
+    /** Unique effect id. */
+    id: string;
+    /** Optional default params merged with user params. */
+    defaults?: Partial<TParams>;
+    /** Called when the effect enters its active window. */
+    setup?: (ctx: CameraEffectContext, params: TParams) => void | Promise<void>;
+    /** Called every frame while active. */
+    update?: (ctx: CameraEffectContext, params: TParams) => void | Promise<void>;
+    /** Called when the effect leaves its active window. */
+    teardown?: (ctx: CameraEffectContext, params: TParams, reason: EffectTeardownReason) => void | Promise<void>;
+}
+/**
+ * Effect reference used inside a cinematic definition.
+ */
+export interface CameraEffectReference<TParams = Record<string, unknown>> {
+    /** Effect id to load from registry. */
+    id: string;
+    /** Optional runtime params merged over effect defaults. */
+    params?: Partial<TParams>;
+    /** Optional local start timestamp in milliseconds. */
+    fromMs?: number;
+    /** Optional local end timestamp in milliseconds. */
+    toMs?: number;
+}
+/**
+ * Named collection of effects that can be reused in multiple cinematics.
+ */
+export interface CameraEffectPreset {
+    id: string;
+    effects: CameraEffectReference[];
+}
+/**
+ * Registry for built-in and custom cinematic camera effects.
+ */
+export declare class CameraEffectsRegistry {
+    private effects;
+    private presets;
+    /**
+     * Registers a single effect definition.
+     */
+    register<TParams = Record<string, unknown>>(definition: CameraEffectDefinition<TParams>): void;
+    /**
+     * Registers a reusable effect preset.
+     */
+    definePreset(preset: CameraEffectPreset): void;
+    /**
+     * Returns an effect by id.
+     */
+    get(effectId: string): CameraEffectDefinition | undefined;
+    /**
+     * Returns a cloned effect list from a preset id.
+     */
+    usePreset(presetId: string): CameraEffectReference[];
+    /**
+     * Returns true when an effect id exists in the registry.
+     */
+    has(effectId: string): boolean;
+    /**
+     * Returns true when a preset id exists in the registry.
+     */
+    hasPreset(presetId: string): boolean;
+    /**
+     * Registers the framework default effect set.
+     */
+    registerBuiltins(): void;
+}

package/dist/runtime/client/services/camera-effects.registry.js

@@ -0,0 +1,145 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from 'tsyringe';
+/**
+ * Registry for built-in and custom cinematic camera effects.
+ */
+let CameraEffectsRegistry = class CameraEffectsRegistry {
+    effects = new Map();
+    presets = new Map();
+    /**
+     * Registers a single effect definition.
+     */
+    register(definition) {
+        this.effects.set(definition.id, definition);
+    }
+    /**
+     * Registers a reusable effect preset.
+     */
+    definePreset(preset) {
+        this.presets.set(preset.id, preset);
+    }
+    /**
+     * Returns an effect by id.
+     */
+    get(effectId) {
+        return this.effects.get(effectId);
+    }
+    /**
+     * Returns a cloned effect list from a preset id.
+     */
+    usePreset(presetId) {
+        const preset = this.presets.get(presetId);
+        if (!preset)
+            return [];
+        return preset.effects.map((effect) => ({ ...effect }));
+    }
+    /**
+     * Returns true when an effect id exists in the registry.
+     */
+    has(effectId) {
+        return this.effects.has(effectId);
+    }
+    /**
+     * Returns true when a preset id exists in the registry.
+     */
+    hasPreset(presetId) {
+        return this.presets.has(presetId);
+    }
+    /**
+     * Registers the framework default effect set.
+     */
+    registerBuiltins() {
+        this.register({
+            id: 'fadeIn',
+            defaults: { ms: 500 },
+            setup: (_ctx, params) => {
+                const ms = Number(params.ms ?? 500);
+                DoScreenFadeIn(ms);
+            },
+        });
+        this.register({
+            id: 'fadeOut',
+            defaults: { ms: 500 },
+            setup: (_ctx, params) => {
+                const ms = Number(params.ms ?? 500);
+                DoScreenFadeOut(ms);
+            },
+        });
+        this.register({
+            id: 'camShake',
+            defaults: { type: 'HAND_SHAKE', amplitude: 0.35 },
+            setup: (ctx, params) => {
+                const p = params;
+                const type = String(p.type ?? 'HAND_SHAKE');
+                const amplitude = Number(p.amplitude ?? 0.35);
+                ctx.camera.shake(ctx.camHandle, { type, amplitude });
+            },
+            teardown: (ctx) => {
+                ctx.camera.stopShaking(ctx.camHandle, true);
+            },
+        });
+        this.register({
+            id: 'timecycle',
+            defaults: { name: 'default', strength: 1 },
+            setup: (_ctx, params) => {
+                const p = params;
+                const name = String(p.name ?? 'default');
+                const strength = Number(p.strength ?? 1);
+                SetTimecycleModifier(name);
+                SetTimecycleModifierStrength(strength);
+            },
+            teardown: () => {
+                ClearTimecycleModifier();
+            },
+        });
+        this.register({
+            id: 'letterbox',
+            defaults: { top: 0.1, bottom: 0.1, alpha: 230 },
+            update: (ctx, params) => {
+                const p = params;
+                ctx.drawLetterbox(Number(p.top ?? 0.1), Number(p.bottom ?? 0.1), Number(p.alpha ?? 230));
+            },
+        });
+        this.register({
+            id: 'subtitle',
+            defaults: { text: '', durationMs: 1000 },
+            update: (ctx, params) => {
+                const p = params;
+                if (!p.text)
+                    return;
+                ctx.drawSubtitle(String(p.text));
+            },
+        });
+        this.definePreset({
+            id: 'dramatic_intro',
+            effects: [
+                { id: 'fadeIn', params: { ms: 700 }, fromMs: 0, toMs: 700 },
+                { id: 'letterbox', params: { top: 0.12, bottom: 0.12, alpha: 240 } },
+                { id: 'timecycle', params: { name: 'MP_corona_switch', strength: 0.45 } },
+            ],
+        });
+        this.definePreset({
+            id: 'action_chase',
+            effects: [
+                { id: 'camShake', params: { type: 'HAND_SHAKE', amplitude: 0.5 } },
+                { id: 'letterbox', params: { top: 0.08, bottom: 0.08, alpha: 220 } },
+            ],
+        });
+        this.definePreset({
+            id: 'dialog_scene',
+            effects: [
+                { id: 'letterbox', params: { top: 0.1, bottom: 0.1, alpha: 225 } },
+                { id: 'timecycle', params: { name: 'cinema', strength: 0.2 } },
+            ],
+        });
+    }
+};
+CameraEffectsRegistry = __decorate([
+    injectable()
+], CameraEffectsRegistry);
+export { CameraEffectsRegistry };

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

@@ -0,0 +1,129 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+/**
+ * Camera rotation represented in degrees.
+ */
+export interface CameraRotation {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Full camera transform in world space.
+ */
+export interface CameraTransform {
+    position: Vector3;
+    rotation?: CameraRotation;
+    fov?: number;
+}
+/**
+ * Configuration used when creating and activating a scripted camera.
+ */
+export interface CameraCreateOptions {
+    /** Native camera name, defaults to DEFAULT_SCRIPTED_CAMERA. */
+    camName?: string;
+    /** Whether the created camera should become active immediately. */
+    active?: boolean;
+    /** Optional initial transform. */
+    transform?: CameraTransform;
+}
+/**
+ * Render options used when enabling/disabling scripted camera rendering.
+ */
+export interface CameraRenderOptions {
+    /** Smooth transition in or out. */
+    ease?: boolean;
+    /** Transition duration in milliseconds. */
+    easeTimeMs?: number;
+}
+/**
+ * Shake configuration for scripted camera effects.
+ */
+export interface CameraShakeOptions {
+    /** Native shake type name, e.g. HAND_SHAKE. */
+    type: string;
+    /** Shake amplitude. */
+    amplitude: number;
+}
+/**
+ * Injectable camera API that wraps FiveM scripted camera natives.
+ *
+ * @remarks
+ * This class intentionally exposes low-level camera primitives so higher-level
+ * systems can build cinematic workflows on top of it.
+ */
+export declare class Camera {
+    private activeCam;
+    private rendering;
+    /**
+     * Creates a scripted camera and optionally initializes its transform.
+     */
+    create(options?: CameraCreateOptions): number;
+    /**
+     * Returns the currently tracked active camera handle.
+     */
+    getActiveCam(): number | null;
+    /**
+     * Sets camera active state and tracks active handle.
+     */
+    setActive(cam: number, active: boolean): void;
+    /**
+     * Enables or disables scripted camera rendering.
+     */
+    render(enable: boolean, options?: CameraRenderOptions): void;
+    /**
+     * Returns whether scripted camera rendering is currently enabled.
+     */
+    isRendering(): boolean;
+    /**
+     * Destroys a single camera.
+     */
+    destroy(cam: number, destroyActiveCam?: boolean): void;
+    /**
+     * Destroys all scripted cameras managed by the game runtime.
+     */
+    destroyAll(destroyActiveCam?: boolean): void;
+    /**
+     * Sets camera world position.
+     */
+    setPosition(cam: number, position: Vector3): void;
+    /**
+     * Sets camera world rotation.
+     */
+    setRotation(cam: number, rotation: CameraRotation, rotationOrder?: number): void;
+    /**
+     * Sets camera field of view.
+     */
+    setFov(cam: number, fov: number): void;
+    /**
+     * Applies a full transform to a camera in a single call path.
+     */
+    setTransform(cam: number, transform: CameraTransform): void;
+    /**
+     * Points a camera at world coordinates.
+     */
+    pointAtCoords(cam: number, position: Vector3): void;
+    /**
+     * Points a camera at an entity with an optional offset.
+     */
+    pointAtEntity(cam: number, entity: number, offset?: Vector3): void;
+    /**
+     * Removes point-at target from the camera.
+     */
+    stopPointing(cam: number): void;
+    /**
+     * Interpolates from one camera to another using native interpolation.
+     */
+    interpolate(fromCam: number, toCam: number, durationMs: number, easeLocation?: boolean, easeRotation?: boolean): void;
+    /**
+     * Starts a camera shake effect.
+     */
+    shake(cam: number, options: CameraShakeOptions): void;
+    /**
+     * Stops camera shake for a camera.
+     */
+    stopShaking(cam: number, stopImmediately?: boolean): void;
+    /**
+     * Fully resets camera rendering and internal camera tracking.
+     */
+    reset(options?: CameraRenderOptions): void;
+}

package/dist/runtime/client/services/camera.js

@@ -0,0 +1,158 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from 'tsyringe';
+/**
+ * Injectable camera API that wraps FiveM scripted camera natives.
+ *
+ * @remarks
+ * This class intentionally exposes low-level camera primitives so higher-level
+ * systems can build cinematic workflows on top of it.
+ */
+let Camera = class Camera {
+    activeCam = null;
+    rendering = false;
+    /**
+     * Creates a scripted camera and optionally initializes its transform.
+     */
+    create(options = {}) {
+        const cam = CreateCam(options.camName ?? 'DEFAULT_SCRIPTED_CAMERA', options.active ?? false);
+        if (options.transform) {
+            this.setTransform(cam, options.transform);
+        }
+        if (options.active) {
+            this.activeCam = cam;
+        }
+        return cam;
+    }
+    /**
+     * Returns the currently tracked active camera handle.
+     */
+    getActiveCam() {
+        return this.activeCam;
+    }
+    /**
+     * Sets camera active state and tracks active handle.
+     */
+    setActive(cam, active) {
+        SetCamActive(cam, active);
+        if (active) {
+            this.activeCam = cam;
+        }
+        else if (this.activeCam === cam) {
+            this.activeCam = null;
+        }
+    }
+    /**
+     * Enables or disables scripted camera rendering.
+     */
+    render(enable, options = {}) {
+        RenderScriptCams(enable, options.ease ?? false, options.easeTimeMs ?? 0, true, true);
+        this.rendering = enable;
+    }
+    /**
+     * Returns whether scripted camera rendering is currently enabled.
+     */
+    isRendering() {
+        return this.rendering;
+    }
+    /**
+     * Destroys a single camera.
+     */
+    destroy(cam, destroyActiveCam = false) {
+        DestroyCam(cam, destroyActiveCam);
+        if (this.activeCam === cam) {
+            this.activeCam = null;
+        }
+    }
+    /**
+     * Destroys all scripted cameras managed by the game runtime.
+     */
+    destroyAll(destroyActiveCam = false) {
+        DestroyAllCams(destroyActiveCam);
+        this.activeCam = null;
+    }
+    /**
+     * Sets camera world position.
+     */
+    setPosition(cam, position) {
+        SetCamCoord(cam, position.x, position.y, position.z);
+    }
+    /**
+     * Sets camera world rotation.
+     */
+    setRotation(cam, rotation, rotationOrder = 2) {
+        SetCamRot(cam, rotation.x, rotation.y, rotation.z, rotationOrder);
+    }
+    /**
+     * Sets camera field of view.
+     */
+    setFov(cam, fov) {
+        SetCamFov(cam, fov);
+    }
+    /**
+     * Applies a full transform to a camera in a single call path.
+     */
+    setTransform(cam, transform) {
+        this.setPosition(cam, transform.position);
+        if (transform.rotation) {
+            this.setRotation(cam, transform.rotation);
+        }
+        if (typeof transform.fov === 'number') {
+            this.setFov(cam, transform.fov);
+        }
+    }
+    /**
+     * Points a camera at world coordinates.
+     */
+    pointAtCoords(cam, position) {
+        PointCamAtCoord(cam, position.x, position.y, position.z);
+    }
+    /**
+     * Points a camera at an entity with an optional offset.
+     */
+    pointAtEntity(cam, entity, offset = { x: 0, y: 0, z: 0 }) {
+        PointCamAtEntity(cam, entity, offset.x, offset.y, offset.z, true);
+    }
+    /**
+     * Removes point-at target from the camera.
+     */
+    stopPointing(cam) {
+        StopCamPointing(cam);
+    }
+    /**
+     * Interpolates from one camera to another using native interpolation.
+     */
+    interpolate(fromCam, toCam, durationMs, easeLocation = true, easeRotation = true) {
+        SetCamActiveWithInterp(toCam, fromCam, durationMs, easeLocation ? 1 : 0, easeRotation ? 1 : 0);
+        this.activeCam = toCam;
+    }
+    /**
+     * Starts a camera shake effect.
+     */
+    shake(cam, options) {
+        ShakeCam(cam, options.type, options.amplitude);
+    }
+    /**
+     * Stops camera shake for a camera.
+     */
+    stopShaking(cam, stopImmediately = true) {
+        StopCamShaking(cam, stopImmediately);
+    }
+    /**
+     * Fully resets camera rendering and internal camera tracking.
+     */
+    reset(options = {}) {
+        if (this.rendering) {
+            this.render(false, options);
+        }
+        this.destroyAll(false);
+    }
+};
+Camera = __decorate([
+    injectable()
+], Camera);
+export { Camera };

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

@@ -0,0 +1,107 @@
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { type CameraEffectReference } from './camera-effects.registry';
+import { type CameraRotation } from './camera';
+import { type CameraNodeInput, type CinematicDefinition, type CinematicEase, type CinematicEventName, type CinematicEventPayloadMap, type CinematicHandle, type CinematicShot, type CinematicStartOptions, type LookAtInput, type PositionInput } from './cinematic';
+type EffectLike = CameraEffectReference | EffectBuilder;
+type NodeLike = CameraNodeInput | NodeBuilder;
+type LookAtLike = LookAtInput | NodeBuilder;
+type SceneStartFn = (scene: SceneBuildable, options?: CinematicStartOptions) => CinematicHandle;
+export interface SceneDefaults {
+    ease?: CinematicEase;
+    rotation?: CameraRotation;
+    fov?: number;
+    lookAt?: LookAtLike | LookAtLike[];
+    effects?: EffectLike[];
+}
+export interface SceneFlags {
+    skippable?: boolean;
+    freezePlayer?: boolean;
+    invinciblePlayer?: boolean;
+    hideHud?: boolean;
+    hideRadar?: boolean;
+}
+export interface SceneBuildable {
+    build(): CinematicDefinition;
+}
+interface SceneBuilderOptions {
+    id?: string;
+    start?: SceneStartFn;
+}
+export declare class EffectBuilder {
+    private readonly value;
+    constructor(value: CameraEffectReference);
+    window(fromMs: number, toMs: number): EffectBuilder;
+    from(fromMs: number): EffectBuilder;
+    to(toMs: number): EffectBuilder;
+    build(): CameraEffectReference;
+}
+export declare const Fx: {
+    effect(id: string, params?: Record<string, unknown>): EffectBuilder;
+    fadeIn(ms?: number): EffectBuilder;
+    fadeOut(ms?: number): EffectBuilder;
+    camShake(type?: string, amplitude?: number): EffectBuilder;
+    timecycle(name?: string, strength?: number): EffectBuilder;
+    letterbox(top?: number, bottom?: number, alpha?: number): EffectBuilder;
+    subtitle(text: string, durationMs?: number): EffectBuilder;
+};
+export declare class NodeBuilder {
+    private readonly value;
+    private rotationValue;
+    private fovValue;
+    constructor(value: PositionInput);
+    offset(x: number, y: number, z: number): NodeBuilder;
+    rot(x: number, y: number, z: number): NodeBuilder;
+    fov(value: number): NodeBuilder;
+    build(): CameraNodeInput;
+    toPosition(): PositionInput;
+}
+export declare const Pos: {
+    coords(x: number, y: number, z: number): NodeBuilder;
+    entity(entity: number, offset?: Vector3): NodeBuilder;
+    entityBone(entity: number, bone: number, offset?: Vector3): NodeBuilder;
+    anchor(name: string, offset?: Vector3): NodeBuilder;
+    resolver(resolve: () => Vector3 | Promise<Vector3>): NodeBuilder;
+};
+export declare class ShotBuilder {
+    private readonly id?;
+    private shot;
+    constructor(id?: string | undefined);
+    duration(durationMs: number): ShotBuilder;
+    ease(ease: CinematicEase): ShotBuilder;
+    from(node: NodeLike): ShotBuilder;
+    to(node: NodeLike): ShotBuilder;
+    path(...nodes: NodeLike[]): ShotBuilder;
+    lookAt(target: LookAtLike, ...targets: LookAtLike[]): ShotBuilder;
+    effect(effect: EffectLike): ShotBuilder;
+    effects(...effects: EffectLike[]): ShotBuilder;
+    build(defaults?: SceneDefaults): CinematicShot;
+}
+export declare class SceneBuilder implements SceneBuildable {
+    private definition;
+    private defaultsValue;
+    private startFn?;
+    private listeners;
+    constructor(options?: SceneBuilderOptions);
+    id(id: string): SceneBuilder;
+    flags(flags: SceneFlags): SceneBuilder;
+    skippable(value?: boolean): SceneBuilder;
+    freezePlayer(value?: boolean): SceneBuilder;
+    invinciblePlayer(value?: boolean): SceneBuilder;
+    hideHud(value?: boolean): SceneBuilder;
+    hideRadar(value?: boolean): SceneBuilder;
+    defaults(defaults: SceneDefaults): SceneBuilder;
+    anchor(name: string, position: Vector3): SceneBuilder;
+    anchors(anchors: Record<string, Vector3>): SceneBuilder;
+    effect(effect: EffectLike): SceneBuilder;
+    effects(...effects: EffectLike[]): SceneBuilder;
+    preset(id: string): SceneBuilder;
+    presets(...ids: string[]): SceneBuilder;
+    shot(id: string, configure: (shot: ShotBuilder) => ShotBuilder | undefined): SceneBuilder;
+    shot(configure: (shot: ShotBuilder) => ShotBuilder | undefined): SceneBuilder;
+    wait(id: string, waitMs: number): SceneBuilder;
+    wait(waitMs: number): SceneBuilder;
+    on<TEventName extends CinematicEventName>(eventName: TEventName, handler: (payload: CinematicEventPayloadMap[TEventName]) => void): SceneBuilder;
+    build(): CinematicDefinition;
+    start(options?: CinematicStartOptions): CinematicHandle;
+}
+export {};