@nice2dev/game-engine 1.1.5 → 1.1.7

package/dist/types/editor/DialogueSystem.d.ts

@@ -0,0 +1,251 @@
+/**
+ * @file DialogueSystem.ts
+ * @description Branching Dialogue System with localization support
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Dialogue nodes and connections
+ * - Branching conversations
+ * - Conditions for dialogue options
+ * - Variables and state tracking
+ * - Localization support (multiple languages)
+ * - Character/speaker definitions
+ * - Emotions/expressions
+ * - Voice line references
+ * - Custom commands/events
+ * - Import/Export (JSON, Ink, Yarn)
+ * - Dialogue preview/testing
+ */
+export type DialogueNodeType = 'start' | 'dialogue' | 'choice' | 'condition' | 'action' | 'random' | 'hub' | 'end';
+export type ConditionOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startsWith' | 'endsWith';
+export type LogicalOperator = 'and' | 'or' | 'not';
+export interface DialogueCondition {
+    type: 'variable' | 'flag' | 'item' | 'quest' | 'custom';
+    variable: string;
+    operator: ConditionOperator;
+    value: string | number | boolean;
+    negate?: boolean;
+}
+export interface ConditionGroup {
+    logic: LogicalOperator;
+    conditions: (DialogueCondition | ConditionGroup)[];
+}
+export interface DialogueAction {
+    type: 'setVariable' | 'setFlag' | 'addItem' | 'removeItem' | 'startQuest' | 'completeQuest' | 'playSound' | 'playAnimation' | 'custom';
+    target: string;
+    value?: string | number | boolean;
+    params?: Record<string, unknown>;
+}
+export interface DialogueChoice {
+    id: string;
+    text: LocalizedText;
+    targetNodeId: string;
+    condition?: ConditionGroup;
+    actions?: DialogueAction[];
+    isDefault?: boolean;
+    isHidden?: boolean;
+    once?: boolean;
+    priority?: number;
+    shortcut?: string;
+}
+export interface LocalizedText {
+    key: string;
+    default: string;
+    translations: Map<string, string>;
+}
+export interface Speaker {
+    id: string;
+    name: LocalizedText;
+    displayName?: LocalizedText;
+    portrait?: string;
+    color?: string;
+    voiceId?: string;
+    tags?: string[];
+}
+export interface Emotion {
+    id: string;
+    name: string;
+    portrait?: string;
+    animation?: string;
+    voiceModifier?: number;
+}
+export interface DialogueLine {
+    speakerId: string;
+    text: LocalizedText;
+    emotion?: string;
+    voiceLine?: string;
+    duration?: number;
+    animation?: string;
+    effects?: string[];
+}
+export interface DialogueNode {
+    id: string;
+    type: DialogueNodeType;
+    name: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    lines?: DialogueLine[];
+    choices?: DialogueChoice[];
+    nextNodeId?: string;
+    condition?: ConditionGroup;
+    randomWeights?: number[];
+    entryActions?: DialogueAction[];
+    exitActions?: DialogueAction[];
+    tags?: string[];
+    notes?: string;
+    color?: string;
+}
+export interface DialogueTree {
+    id: string;
+    name: string;
+    description: string;
+    version: number;
+    nodes: Map<string, DialogueNode>;
+    startNodeId: string;
+    speakers: Map<string, Speaker>;
+    variables: Map<string, DialogueVariable>;
+    flags: Set<string>;
+    defaultLanguage: string;
+    supportedLanguages: string[];
+    tags: string[];
+    createdAt: number;
+    modifiedAt: number;
+}
+export interface DialogueVariable {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    defaultValue: string | number | boolean;
+    description?: string;
+    minValue?: number;
+    maxValue?: number;
+    options?: string[];
+}
+export interface DialogueState {
+    treeId: string;
+    currentNodeId: string;
+    currentLineIndex: number;
+    variables: Map<string, string | number | boolean>;
+    flags: Set<string>;
+    visitedNodes: Set<string>;
+    selectedChoices: Set<string>;
+    history: DialogueHistoryEntry[];
+}
+export interface DialogueHistoryEntry {
+    nodeId: string;
+    lineIndex?: number;
+    choiceId?: string;
+    timestamp: number;
+}
+export interface DialogueRenderData {
+    speaker?: Speaker;
+    emotion?: Emotion;
+    text: string;
+    choices?: {
+        id: string;
+        text: string;
+        available: boolean;
+        shortcut?: string;
+    }[];
+    isEnd: boolean;
+    autoAdvance?: number;
+}
+export declare class DialogueManager {
+    private trees;
+    private speakers;
+    private emotions;
+    private currentState;
+    private currentLanguage;
+    private onDialogueStart?;
+    private onDialogueEnd?;
+    private onNodeEnter?;
+    private onLineDisplay?;
+    private onChoicesDisplay?;
+    private onAction?;
+    private customConditionEvaluator?;
+    createTree(name: string, defaultLanguage?: string): DialogueTree;
+    getTree(id: string): DialogueTree | undefined;
+    deleteTree(id: string): boolean;
+    addNode(treeId: string, node: Partial<DialogueNode>): DialogueNode | null;
+    updateNode(treeId: string, nodeId: string, updates: Partial<DialogueNode>): boolean;
+    deleteNode(treeId: string, nodeId: string): boolean;
+    connectNodes(treeId: string, fromNodeId: string, toNodeId: string, choiceId?: string): boolean;
+    addLine(treeId: string, nodeId: string, line: Partial<DialogueLine>): DialogueLine | null;
+    addChoice(treeId: string, nodeId: string, choice: Partial<DialogueChoice>): DialogueChoice | null;
+    addSpeaker(treeId: string, speaker: Partial<Speaker>): Speaker | null;
+    getSpeaker(id: string): Speaker | undefined;
+    addEmotion(emotion: Emotion): void;
+    getEmotion(id: string): Emotion | undefined;
+    addVariable(treeId: string, variable: DialogueVariable): boolean;
+    setFlag(treeId: string, flag: string, value?: boolean): void;
+    createLocalizedText(defaultText: string, language: string): LocalizedText;
+    setTranslation(text: LocalizedText, language: string, translation: string): void;
+    getText(text: LocalizedText, language?: string): string;
+    setLanguage(language: string): void;
+    addLanguageSupport(treeId: string, language: string): boolean;
+    startDialogue(treeId: string): boolean;
+    endDialogue(): void;
+    private processCurrentNode;
+    private displayDialogueLine;
+    private displayChoices;
+    private getAvailableChoices;
+    advanceLine(): void;
+    selectChoice(choiceId: string): void;
+    private advanceToNextNode;
+    private gotoNode;
+    private evaluateConditionNode;
+    private executeNodeActions;
+    private selectRandomPath;
+    private evaluateConditions;
+    private evaluateCondition;
+    private executeAction;
+    getVariable(name: string): string | number | boolean | undefined;
+    setVariable(name: string, value: string | number | boolean): void;
+    hasFlag(name: string): boolean;
+    isNodeVisited(nodeId: string): boolean;
+    getCurrentState(): DialogueState | null;
+    setOnDialogueStart(callback: (tree: DialogueTree) => void): void;
+    setOnDialogueEnd(callback: (tree: DialogueTree) => void): void;
+    setOnNodeEnter(callback: (node: DialogueNode) => void): void;
+    setOnLineDisplay(callback: (data: DialogueRenderData) => void): void;
+    setOnChoicesDisplay(callback: (choices: DialogueRenderData['choices']) => void): void;
+    setOnAction(callback: (action: DialogueAction) => void): void;
+    setCustomConditionEvaluator(evaluator: (condition: DialogueCondition) => boolean): void;
+    exportToJson(treeId: string): string | null;
+    importFromJson(json: string): DialogueTree | null;
+    exportStringsForLocalization(treeId: string): Map<string, string>;
+    importTranslations(treeId: string, language: string, translations: Map<string, string>): boolean;
+    getGraphData(treeId: string): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    } | null;
+}
+export interface GraphNode {
+    id: string;
+    type: DialogueNodeType;
+    name: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    color?: string;
+    hasLines: boolean;
+    hasChoices: boolean;
+    hasCondition: boolean;
+}
+export interface GraphEdge {
+    id: string;
+    from: string;
+    to: string;
+    type: 'default' | 'choice' | 'condition';
+    label?: string;
+    hasCondition?: boolean;
+}
+export declare function createDialogueManager(): DialogueManager;
+export declare function createDialogueNode(type: DialogueNodeType, name: string, position: {
+    x: number;
+    y: number;
+}): Partial<DialogueNode>;
+export declare function createConditionGroup(logic: LogicalOperator, conditions: (DialogueCondition | ConditionGroup)[]): ConditionGroup;
+export declare function createCondition(type: DialogueCondition['type'], variable: string, operator: ConditionOperator, value: string | number | boolean): DialogueCondition;

package/dist/types/editor/LeaderboardSystem.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @file LeaderboardSystem.ts
+ * @description Leaderboard Integration system with online scoreboards
+ * PRO-1.4: Professional Editor Features
+ *
+ * Features:
+ * - Multiple leaderboard types
+ * - Time-based scoping (daily, weekly, monthly, all-time)
+ * - Friend/global filtering
+ * - Score submission and validation
+ * - Rank calculation
+ * - Pagination support
+ * - Anti-cheat integration
+ * - Platform-specific adapters
+ * - Offline queuing
+ * - Real-time updates
+ */
+export type LeaderboardType = 'score' | 'time' | 'distance' | 'kills' | 'wins' | 'rating' | 'custom';
+export type LeaderboardScope = 'global' | 'friends' | 'country' | 'region' | 'guild' | 'custom';
+export type LeaderboardPeriod = 'all_time' | 'yearly' | 'monthly' | 'weekly' | 'daily' | 'hourly' | 'custom';
+export type SortOrder = 'ascending' | 'descending';
+export type VerificationStatus = 'pending' | 'verified' | 'rejected' | 'suspicious';
+export interface LeaderboardDefinition {
+    id: string;
+    name: string;
+    description: string;
+    type: LeaderboardType;
+    sortOrder: SortOrder;
+    scoreFormat: string;
+    decimalPlaces: number;
+    minScore?: number;
+    maxScore?: number;
+    maxEntriesPerPlayer: number;
+    allowTies: boolean;
+    requireVerification: boolean;
+    period: LeaderboardPeriod;
+    customPeriodDays?: number;
+    resetTime?: string;
+    requiredMetadata?: string[];
+    maxScoreIncrease?: number;
+    minPlayTime?: number;
+    checksumRequired: boolean;
+    icon?: string;
+    color?: string;
+    tags: string[];
+    isPublic: boolean;
+    platformLeaderboardId?: string;
+    platform?: string;
+    createdAt: number;
+    modifiedAt: number;
+}
+export interface LeaderboardEntry {
+    id: string;
+    leaderboardId: string;
+    playerId: string;
+    playerName: string;
+    playerAvatar?: string;
+    playerCountry?: string;
+    score: number;
+    formattedScore: string;
+    rank: number;
+    previousRank?: number;
+    metadata?: Record<string, unknown>;
+    replayId?: string;
+    screenshotUrl?: string;
+    verificationStatus: VerificationStatus;
+    verifiedAt?: number;
+    verifiedBy?: string;
+    submittedAt: number;
+    achievedAt: number;
+    playTime?: number;
+    checksum?: string;
+    clientVersion?: string;
+    platform?: string;
+}
+export interface LeaderboardPage {
+    leaderboardId: string;
+    entries: LeaderboardEntry[];
+    totalEntries: number;
+    pageNumber: number;
+    pageSize: number;
+    totalPages: number;
+    scope: LeaderboardScope;
+    period: LeaderboardPeriod;
+    updatedAt: number;
+}
+export interface PlayerRank {
+    leaderboardId: string;
+    playerId: string;
+    rank: number;
+    totalPlayers: number;
+    percentile: number;
+    score: number;
+    entry?: LeaderboardEntry;
+}
+export interface ScoreSubmission {
+    leaderboardId: string;
+    playerId: string;
+    playerName: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+    replayData?: unknown;
+    screenshot?: Blob | string;
+    playTime?: number;
+    checksum?: string;
+    clientVersion?: string;
+}
+export interface SubmissionResult {
+    success: boolean;
+    entry?: LeaderboardEntry;
+    newRank?: number;
+    previousRank?: number;
+    isNewHighScore: boolean;
+    isNewRecord: boolean;
+    error?: string;
+}
+export interface ILeaderboardPlatformAdapter {
+    platformName: string;
+    submitScore(submission: ScoreSubmission): Promise<SubmissionResult>;
+    getLeaderboard(leaderboardId: string, scope: LeaderboardScope, page: number, pageSize: number): Promise<LeaderboardPage>;
+    getPlayerRank(leaderboardId: string, playerId: string): Promise<PlayerRank | null>;
+    getFriendsLeaderboard(leaderboardId: string, playerId: string): Promise<LeaderboardEntry[]>;
+}
+export declare class LocalLeaderboardAdapter implements ILeaderboardPlatformAdapter {
+    readonly platformName = "local";
+    private entries;
+    submitScore(submission: ScoreSubmission): Promise<SubmissionResult>;
+    getLeaderboard(leaderboardId: string, _scope: LeaderboardScope, page: number, pageSize: number): Promise<LeaderboardPage>;
+    getPlayerRank(leaderboardId: string, playerId: string): Promise<PlayerRank | null>;
+    getFriendsLeaderboard(_leaderboardId: string, _playerId: string): Promise<LeaderboardEntry[]>;
+    private getEntries;
+    clearLeaderboard(leaderboardId: string): void;
+    clearAll(): void;
+}
+export declare class LeaderboardManager {
+    private definitions;
+    private adapter;
+    private cache;
+    private cacheTimeout;
+    private offlineQueue;
+    private isOnline;
+    private playerId?;
+    private playerName?;
+    private friendIds;
+    private onScoreSubmitted?;
+    private onLeaderboardUpdated?;
+    private onNewHighScore?;
+    private onNewRecord?;
+    private onRankChanged?;
+    private onError?;
+    constructor(adapter?: ILeaderboardPlatformAdapter);
+    createLeaderboard(name: string, type: LeaderboardType): LeaderboardDefinition;
+    getLeaderboard(id: string): LeaderboardDefinition | undefined;
+    updateLeaderboard(id: string, updates: Partial<LeaderboardDefinition>): boolean;
+    deleteLeaderboard(id: string): boolean;
+    getAllLeaderboards(): LeaderboardDefinition[];
+    setCurrentPlayer(playerId: string, playerName: string): void;
+    setFriends(friendIds: string[]): void;
+    submitScore(leaderboardId: string, score: number, metadata?: Record<string, unknown>, options?: {
+        replayData?: unknown;
+        screenshot?: Blob | string;
+        playTime?: number;
+    }): Promise<SubmissionResult>;
+    private validateScore;
+    private generateChecksum;
+    private getClientVersion;
+    getEntries(leaderboardId: string, scope?: LeaderboardScope, page?: number, pageSize?: number, forceRefresh?: boolean): Promise<LeaderboardPage | null>;
+    getTopEntries(leaderboardId: string, count?: number): Promise<LeaderboardEntry[]>;
+    getPlayerRank(leaderboardId: string, playerId?: string): Promise<PlayerRank | null>;
+    getFriendsEntries(leaderboardId: string): Promise<LeaderboardEntry[]>;
+    getEntriesAroundPlayer(leaderboardId: string, playerId?: string, entriesAbove?: number, entriesBelow?: number): Promise<LeaderboardEntry[]>;
+    invalidateCache(leaderboardId?: string): void;
+    setCacheTimeout(ms: number): void;
+    setOnlineStatus(online: boolean): void;
+    private processOfflineQueue;
+    getOfflineQueueSize(): number;
+    setAdapter(adapter: ILeaderboardPlatformAdapter): void;
+    getAdapter(): ILeaderboardPlatformAdapter;
+    setOnScoreSubmitted(callback: (result: SubmissionResult) => void): void;
+    setOnLeaderboardUpdated(callback: (page: LeaderboardPage) => void): void;
+    setOnNewHighScore(callback: (entry: LeaderboardEntry, leaderboard: LeaderboardDefinition) => void): void;
+    setOnNewRecord(callback: (entry: LeaderboardEntry, leaderboard: LeaderboardDefinition) => void): void;
+    setOnRankChanged(callback: (leaderboardId: string, oldRank: number, newRank: number) => void): void;
+    setOnError(callback: (error: string) => void): void;
+    formatScore(leaderboardId: string, score: number): string;
+    getLeaderboardsByType(type: LeaderboardType): LeaderboardDefinition[];
+    getLeaderboardsByTag(tag: string): LeaderboardDefinition[];
+    getPublicLeaderboards(): LeaderboardDefinition[];
+    subscribeToLeaderboard(_leaderboardId: string, _callback: (page: LeaderboardPage) => void): () => void;
+    exportDefinitions(): string;
+    importDefinitions(json: string): boolean;
+}
+export declare function createLeaderboardManager(adapter?: ILeaderboardPlatformAdapter): LeaderboardManager;
+export declare function createLocalAdapter(): LocalLeaderboardAdapter;

package/dist/types/editor/NiceAnimationTimeline.d.ts

@@ -0,0 +1,114 @@
+import React from 'react';
+export interface KeyframeValue {
+    number?: number;
+    vector2?: {
+        x: number;
+        y: number;
+    };
+    vector3?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    quaternion?: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    color?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    boolean?: boolean;
+    string?: string;
+}
+export interface Keyframe {
+    id: string;
+    time: number;
+    value: KeyframeValue;
+    easing: EasingType;
+    tangentIn?: {
+        x: number;
+        y: number;
+    };
+    tangentOut?: {
+        x: number;
+        y: number;
+    };
+}
+export type EasingType = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'bezier' | 'step' | 'bounce' | 'elastic';
+export interface AnimationTrack {
+    id: string;
+    name: string;
+    targetId: string;
+    property: string;
+    propertyType: 'number' | 'vector2' | 'vector3' | 'quaternion' | 'color' | 'boolean' | 'string';
+    keyframes: Keyframe[];
+    muted: boolean;
+    locked: boolean;
+    color: string;
+}
+export interface AnimationLayer {
+    id: string;
+    name: string;
+    weight: number;
+    blendMode: 'override' | 'additive' | 'multiply';
+    tracks: AnimationTrack[];
+    expanded: boolean;
+}
+export interface AnimationClipData {
+    id: string;
+    name: string;
+    duration: number;
+    frameRate: number;
+    loop: boolean;
+    layers: AnimationLayer[];
+    events: AnimationEvent[];
+}
+export interface AnimationEvent {
+    id: string;
+    time: number;
+    name: string;
+    parameters: Record<string, unknown>;
+}
+export interface AnimationTimelineTheme {
+    background: string;
+    trackBackground: string;
+    trackBackgroundAlt: string;
+    headerBackground: string;
+    rulerBackground: string;
+    rulerText: string;
+    keyframeDefault: string;
+    keyframeSelected: string;
+    keyframeHovered: string;
+    playhead: string;
+    gridLine: string;
+    gridLineMajor: string;
+    curveColor: string;
+    eventColor: string;
+    textPrimary: string;
+    textSecondary: string;
+    selectionBox: string;
+}
+export interface NiceAnimationTimelineProps {
+    clip?: AnimationClipData;
+    theme?: Partial<AnimationTimelineTheme>;
+    readOnly?: boolean;
+    onClipChange?: (clip: AnimationClipData) => void;
+    onTimeChange?: (time: number) => void;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export interface NiceAnimationTimelineRef {
+    getClip: () => AnimationClipData;
+    setTime: (time: number) => void;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+    addKeyframe: (trackId: string, time: number, value: KeyframeValue) => void;
+}
+export declare const NiceAnimationTimeline: React.ForwardRefExoticComponent<NiceAnimationTimelineProps & React.RefAttributes<NiceAnimationTimelineRef>>;
+export default NiceAnimationTimeline;

package/dist/types/editor/NiceGameEditor.d.ts

@@ -1,6 +1,7 @@
+import { type NiceComponentTutorial } from '@nice2dev/ui';
 import React from 'react';
-import type { GameProject, EntityId } from '../core/types';
 import { EventBus } from '../core/EventBus';
+import type { GameProject, EntityId } from '../core/types';
 import { World, type ComponentMap } from '../ecs/World';
 import { SceneManager } from '../scene/SceneManager';
 export interface UndoEntry {
@@ -121,6 +122,8 @@ export interface NiceGameEditorProps {
     onSave?: (project: GameProject) => void;
     className?: string;
     style?: React.CSSProperties;
+    /** Optional "?" guided tour. Off by default; `true` uses the built-in tour. */
+    tutorial?: NiceComponentTutorial;
 }
 export declare const NiceGameEditor: React.FC<NiceGameEditorProps>;
 export {};