@nice2dev/game-engine 1.1.5 → 1.1.7

package/dist/types/systems/NiceCutscene.d.ts

@@ -0,0 +1,437 @@
+/**
+ * NiceCutscene - Cinematic Cutscene System
+ *
+ * Comprehensive system for creating and playing in-game cutscenes,
+ * cinematics, and scripted sequences.
+ *
+ * Features:
+ * - Timeline-based sequencing
+ * - Camera control
+ * - Character animation
+ * - Dialogue integration
+ * - Audio/music sync
+ * - Visual effects
+ * - Transitions/fades
+ * - Skip functionality
+ * - Pause/resume
+ * - Branching cutscenes
+ * - Keyframe animation
+ * - Event triggers
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+/** Unique cutscene ID */
+export type CutsceneId = string;
+/** Unique track ID */
+export type TrackId = string;
+/** Unique clip ID */
+export type ClipId = string;
+/** Cutscene state */
+export type CutsceneState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'finished' | 'skipped';
+/** Track type */
+export type TrackType = 'camera' | 'animation' | 'dialogue' | 'audio' | 'music' | 'effect' | 'event' | 'property' | 'transition' | 'subtitle' | 'custom';
+/** Easing type */
+export type EasingType = 'linear' | 'ease_in' | 'ease_out' | 'ease_in_out' | 'bounce' | 'elastic' | 'back' | 'cubic' | 'quad' | 'quart' | 'quint' | 'sine' | 'expo' | 'circ';
+/** Transition type */
+export type TransitionType = 'cut' | 'fade' | 'dissolve' | 'wipe_left' | 'wipe_right' | 'wipe_up' | 'wipe_down' | 'zoom_in' | 'zoom_out' | 'blur' | 'custom';
+/** 3D Vector */
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Quaternion rotation */
+export interface Quaternion {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/** Transform */
+export interface Transform {
+    position: Vector3;
+    rotation: Vector3 | Quaternion;
+    scale?: Vector3;
+}
+/** Keyframe */
+export interface Keyframe<T = unknown> {
+    time: number;
+    value: T;
+    easing?: EasingType;
+    tangentIn?: T;
+    tangentOut?: T;
+}
+/** Animation clip */
+export interface AnimationClip {
+    id: ClipId;
+    trackId: TrackId;
+    startTime: number;
+    duration: number;
+    name?: string;
+    targetId?: string;
+    keyframes?: Keyframe[];
+    data?: Record<string, unknown>;
+    loop?: boolean;
+    blendIn?: number;
+    blendOut?: number;
+}
+/** Camera clip */
+export interface CameraClip extends AnimationClip {
+    positionKeyframes: Keyframe<Vector3>[];
+    rotationKeyframes: Keyframe<Vector3>[];
+    fovKeyframes?: Keyframe<number>[];
+    lookAtTarget?: string;
+    shake?: CameraShake;
+}
+/** Camera shake settings */
+export interface CameraShake {
+    intensity: number;
+    frequency: number;
+    duration: number;
+    fadeIn?: number;
+    fadeOut?: number;
+}
+/** Dialogue clip */
+export interface DialogueClip extends AnimationClip {
+    speakerId: string;
+    speakerName: string;
+    text: string;
+    audioFile?: string;
+    portrait?: string;
+    emotion?: string;
+    animationTrigger?: string;
+    voiceStart?: number;
+    voiceEnd?: number;
+}
+/** Audio clip */
+export interface AudioClip extends AnimationClip {
+    audioFile: string;
+    volume?: number;
+    pitch?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    spatial?: boolean;
+    position?: Vector3;
+}
+/** Effect clip */
+export interface EffectClip extends AnimationClip {
+    effectType: string;
+    effectParams?: Record<string, unknown>;
+    position?: Vector3;
+    attachTo?: string;
+    autoDestroy?: boolean;
+}
+/** Event clip */
+export interface EventClip extends AnimationClip {
+    eventName: string;
+    eventData?: Record<string, unknown>;
+}
+/** Property clip */
+export interface PropertyClip extends AnimationClip {
+    property: string;
+    keyframes: Keyframe<number | string | boolean | Vector3>[];
+}
+/** Transition clip */
+export interface TransitionClip extends AnimationClip {
+    transitionType: TransitionType;
+    color?: string;
+    customShader?: string;
+}
+/** Subtitle clip */
+export interface SubtitleClip extends AnimationClip {
+    text: string;
+    speaker?: string;
+    position?: 'top' | 'center' | 'bottom';
+    style?: SubtitleStyle;
+}
+/** Subtitle style */
+export interface SubtitleStyle {
+    fontSize?: number;
+    fontFamily?: string;
+    color?: string;
+    backgroundColor?: string;
+    padding?: number;
+    maxWidth?: number;
+}
+/** Track definition */
+export interface CutsceneTrack {
+    id: TrackId;
+    name: string;
+    type: TrackType;
+    clips: AnimationClip[];
+    muted: boolean;
+    locked: boolean;
+    targetId?: string;
+    color?: string;
+}
+/** Cutscene definition */
+export interface CutsceneDefinition {
+    id: CutsceneId;
+    name: string;
+    description?: string;
+    duration: number;
+    tracks: CutsceneTrack[];
+    skippable: boolean;
+    skipKeyOrButton?: string;
+    preloadAssets?: string[];
+    startCondition?: CutsceneCondition;
+    endCondition?: CutsceneCondition;
+    branches?: CutsceneBranch[];
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Branch condition */
+export interface CutsceneCondition {
+    type: 'time' | 'event' | 'variable' | 'input' | 'custom';
+    value?: unknown;
+    comparator?: 'equals' | 'greater' | 'less' | 'contains';
+    checkValue?: unknown;
+}
+/** Cutscene branch */
+export interface CutsceneBranch {
+    id: string;
+    condition: CutsceneCondition;
+    targetCutsceneId: CutsceneId;
+    targetTime?: number;
+}
+/** Playback state */
+export interface PlaybackState {
+    cutsceneId: CutsceneId;
+    state: CutsceneState;
+    currentTime: number;
+    duration: number;
+    playbackRate: number;
+    loop: boolean;
+    activeClips: ClipId[];
+    completedClips: ClipId[];
+}
+/** Cutscene player options */
+export interface PlayOptions {
+    startTime?: number;
+    playbackRate?: number;
+    loop?: boolean;
+    onComplete?: () => void;
+    onSkip?: () => void;
+    skipToTime?: number;
+}
+/** Cutscene statistics */
+export interface CutsceneStatistics {
+    totalWatched: number;
+    totalSkipped: number;
+    totalPlayTime: number;
+    watchedCutscenes: Set<CutsceneId>;
+    skippedCutscenes: Set<CutsceneId>;
+}
+/** Cutscene event types */
+export type CutsceneEventType = 'cutscene_started' | 'cutscene_paused' | 'cutscene_resumed' | 'cutscene_stopped' | 'cutscene_skipped' | 'cutscene_finished' | 'cutscene_loaded' | 'clip_started' | 'clip_ended' | 'dialogue_started' | 'dialogue_ended' | 'event_triggered' | 'branch_taken' | 'time_updated';
+/** Cutscene event data */
+export interface CutsceneEvent {
+    type: CutsceneEventType;
+    timestamp: number;
+    cutsceneId?: CutsceneId;
+    clipId?: ClipId;
+    data?: unknown;
+}
+/** Cutscene event callback */
+export type CutsceneEventCallback = (event: CutsceneEvent) => void;
+/** Cutscene system configuration */
+export interface CutsceneConfig {
+    defaultPlaybackRate: number;
+    skipFadeDuration: number;
+    preloadAhead: number;
+    maxConcurrentAudio: number;
+    subtitleDefaults: SubtitleStyle;
+    transitionDuration: number;
+    allowPause: boolean;
+    allowSkip: boolean;
+    skipKey: string;
+    pauseKey: string;
+}
+/** Default configuration */
+export declare const DEFAULT_CUTSCENE_CONFIG: CutsceneConfig;
+/**
+ * Cinematic cutscene system
+ */
+export declare class NiceCutscene extends EventEmitter {
+    private config;
+    private cutscenes;
+    private playbackState?;
+    private animationFrame?;
+    private lastFrameTime;
+    private activeClipStates;
+    private statistics;
+    private loadedAssets;
+    private audioSources;
+    private isSkipping;
+    constructor(config?: Partial<CutsceneConfig>);
+    /**
+     * Emit cutscene event
+     */
+    private emitEvent;
+    /**
+     * Setup keyboard listeners
+     */
+    private setupKeyboardListeners;
+    /**
+     * Register cutscene
+     */
+    registerCutscene(definition: CutsceneDefinition): void;
+    /**
+     * Unregister cutscene
+     */
+    unregisterCutscene(cutsceneId: CutsceneId): boolean;
+    /**
+     * Get cutscene
+     */
+    getCutscene(cutsceneId: CutsceneId): CutsceneDefinition | undefined;
+    /**
+     * Get all cutscenes
+     */
+    getAllCutscenes(): CutsceneDefinition[];
+    /**
+     * Play cutscene
+     */
+    play(cutsceneId: CutsceneId, options?: PlayOptions): Promise<boolean>;
+    /**
+     * Pause cutscene
+     */
+    pause(): void;
+    /**
+     * Resume cutscene
+     */
+    resume(): void;
+    /**
+     * Stop cutscene
+     */
+    stop(): void;
+    /**
+     * Skip cutscene
+     */
+    skip(): void;
+    /**
+     * Seek to time
+     */
+    seek(time: number): void;
+    /**
+     * Set playback rate
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Start playback loop
+     */
+    private startPlaybackLoop;
+    /**
+     * Stop playback loop
+     */
+    private stopPlaybackLoop;
+    /**
+     * Update playback
+     */
+    private updatePlayback;
+    /**
+     * Process clip
+     */
+    private processClip;
+    /**
+     * Handle clip start
+     */
+    private handleClipStart;
+    /**
+     * Handle clip end
+     */
+    private handleClipEnd;
+    /**
+     * Update clip
+     */
+    private updateClip;
+    /**
+     * Update camera clip
+     */
+    private updateCameraClip;
+    /**
+     * Update property clip
+     */
+    private updatePropertyClip;
+    /**
+     * Interpolate keyframes
+     */
+    private interpolateKeyframes;
+    /**
+     * Interpolate value
+     */
+    private interpolateValue;
+    /**
+     * Type guard for Vector3
+     */
+    private isVector3;
+    /**
+     * Calculate camera shake
+     */
+    private calculateShake;
+    /**
+     * Check branches
+     */
+    private checkBranches;
+    /**
+     * Evaluate condition
+     */
+    private evaluateCondition;
+    /**
+     * Finish cutscene
+     */
+    private finishCutscene;
+    /**
+     * Stop clip audio
+     */
+    private stopClipAudio;
+    /**
+     * Stop all audio
+     */
+    private stopAllAudio;
+    /**
+     * Preload assets
+     */
+    private preloadAssets;
+    /**
+     * Preload audio
+     */
+    private preloadAudio;
+    /**
+     * Preload image
+     */
+    private preloadImage;
+    /**
+     * Find clip by ID
+     */
+    private findClipById;
+    /**
+     * Get playback state
+     */
+    getPlaybackState(): PlaybackState | undefined;
+    /**
+     * Is playing
+     */
+    isPlaying(): boolean;
+    /**
+     * Get current time
+     */
+    getCurrentTime(): number;
+    /**
+     * Get statistics
+     */
+    getStatistics(): CutsceneStatistics;
+    /**
+     * Has watched cutscene
+     */
+    hasWatched(cutsceneId: CutsceneId): boolean;
+    /**
+     * Destroy cutscene system
+     */
+    destroy(): void;
+}
+/**
+ * Create cutscene system instance
+ */
+export declare function createCutsceneSystem(config?: Partial<CutsceneConfig>): NiceCutscene;
+export default NiceCutscene;

package/dist/types/systems/NiceDaily.d.ts

@@ -0,0 +1,133 @@
+export type RewardId = string;
+export type CalendarId = string;
+export type RewardType = 'item' | 'currency' | 'experience' | 'premium_currency' | 'buff' | 'gacha_ticket' | 'custom';
+export interface DailyReward {
+    id: RewardId;
+    day: number;
+    type: RewardType;
+    itemId?: string;
+    currency?: string;
+    amount: number;
+    isBonus?: boolean;
+    bonusMultiplier?: number;
+    name: string;
+    description?: string;
+    icon?: string;
+    rarity?: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
+}
+export interface RewardCalendar {
+    id: CalendarId;
+    name: string;
+    description: string;
+    startDate: number;
+    endDate?: number;
+    cycleDays: number;
+    resetOnComplete: boolean;
+    rewards: DailyReward[];
+    milestoneRewards: MilestoneReward[];
+    vipBonusMultipliers: Record<number, number>;
+    levelRequired?: number;
+    prerequisiteCalendarId?: CalendarId;
+}
+export interface MilestoneReward {
+    id: RewardId;
+    totalDaysRequired: number;
+    type: RewardType;
+    itemId?: string;
+    currency?: string;
+    amount: number;
+    name: string;
+    description?: string;
+    icon?: string;
+}
+export interface DailyProgress {
+    playerId: string;
+    calendarId: CalendarId;
+    currentDay: number;
+    consecutiveDays: number;
+    totalDaysClaimed: number;
+    lastClaimDate: string;
+    cycleStartDate: number;
+    firstClaimDate: number;
+    claimedDays: number[];
+    claimedMilestones: string[];
+    missedDays: number;
+    catchUpTokens: number;
+}
+export interface ClaimResult {
+    success: boolean;
+    rewards: Array<{
+        type: RewardType;
+        itemId?: string;
+        currency?: string;
+        amount: number;
+        bonusAmount?: number;
+    }>;
+    newConsecutiveDays: number;
+    totalDaysClaimed: number;
+    unlockedMilestones: MilestoneReward[];
+    nextReward?: DailyReward;
+}
+export type DailyEventType = 'daily-claimed' | 'milestone-unlocked' | 'streak-lost' | 'streak-milestone' | 'cycle-completed' | 'cycle-reset' | 'catch-up-used' | 'vip-bonus-applied';
+export interface DailyEvent {
+    type: DailyEventType;
+    timestamp: number;
+    playerId: string;
+    calendarId?: CalendarId;
+    data?: unknown;
+}
+export type DailyEventCallback = (event: DailyEvent) => void;
+export interface DailyConfig {
+    resetHour: number;
+    resetTimezone: string;
+    maxConsecutiveMissed: number;
+    catchUpTokensPerPurchase: number;
+    catchUpTokenCost: number;
+    catchUpCurrency: string;
+    streakMilestones: number[];
+    storageKey: string;
+}
+export declare const DEFAULT_DAILY_CONFIG: DailyConfig;
+export declare class NiceDaily {
+    private config;
+    private calendars;
+    private progress;
+    private playerVIPLevels;
+    private eventListeners;
+    constructor(config?: Partial<DailyConfig>);
+    on(event: DailyEventType, callback: DailyEventCallback): () => void;
+    private emit;
+    registerCalendar(calendar: RewardCalendar): void;
+    setPlayerVIPLevel(playerId: string, level: number): void;
+    canClaim(playerId: string, calendarId: CalendarId): {
+        can: boolean;
+        reason?: string;
+        reward?: DailyReward;
+    };
+    claim(playerId: string, calendarId: CalendarId): ClaimResult;
+    purchaseCatchUpTokens(playerId: string, quantity?: number): boolean;
+    useCatchUp(playerId: string, calendarId: CalendarId): ClaimResult;
+    private findNextUnclaimedDay;
+    private getOrCreateProgress;
+    private getResetDate;
+    private calculateNextDay;
+    private calculateMissedDays;
+    getCalendar(calendarId: CalendarId): RewardCalendar | undefined;
+    getAllCalendars(): RewardCalendar[];
+    getActiveCalendars(): RewardCalendar[];
+    getProgress(playerId: string, calendarId: CalendarId): DailyProgress | undefined;
+    getAllProgress(playerId: string): DailyProgress[];
+    getUpcomingRewards(playerId: string, calendarId: CalendarId, count?: number): DailyReward[];
+    getClaimableCount(playerId: string): number;
+    getStreakInfo(playerId: string, calendarId: CalendarId): {
+        current: number;
+        nextMilestone: number | null;
+        daysUntilMilestone: number;
+    };
+    private save;
+    private load;
+    reset(): void;
+    resetPlayer(playerId: string): void;
+    destroy(): void;
+}
+export declare function createDailySystem(config?: Partial<DailyConfig>): NiceDaily;