@nice2dev/game-engine 1.3.13 → 1.3.14

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

@@ -1,629 +0,0 @@
-/**
- * NiceDialogue - Comprehensive Dialogue System
- *
- * Professional dialogue system for RPGs and narrative games.
- * Supports branching conversations, conditions, effects, voice, and localization.
- *
- * Features:
- * - Branching dialogue trees with conditions
- * - Character/speaker management
- * - Response choices with requirements
- * - Variables and state tracking
- * - Hooks for effects/consequences
- * - Voice acting support
- * - Localization integration
- * - Ink/Yarn-like scripting support
- * - Dialogue history
- * - Skip/auto-advance modes
- *
- * @packageDocumentation
- */
-import { EventEmitter } from 'eventemitter3';
-/** Unique identifier for dialogues */
-export type DialogueId = string;
-/** Unique identifier for nodes */
-export type NodeId = string;
-/** Unique identifier for characters/speakers */
-export type CharacterId = string;
-/** Unique identifier for conversations */
-export type ConversationId = string;
-/** Unique identifier for response options */
-export type ResponseId = string;
-/** Node types in dialogue tree */
-export type NodeType = 'text' | 'choice' | 'branch' | 'jump' | 'set' | 'event' | 'random' | 'sequence' | 'parallel' | 'wait' | 'end';
-/** Comparison operators for conditions */
-export type ComparisonOp = '==' | '!=' | '>' | '<' | '>=' | '<=' | 'contains' | 'startsWith' | 'endsWith';
-/** Logical operators */
-export type LogicalOp = 'and' | 'or' | 'not';
-/** Variable types */
-export type VariableType = 'string' | 'number' | 'boolean' | 'array';
-/** Variable value */
-export type VariableValue = string | number | boolean | VariableValue[];
-/** Condition for branching */
-export interface Condition {
-    type: 'variable' | 'function' | 'compound';
-    variable?: string;
-    operator?: ComparisonOp;
-    value?: VariableValue;
-    functionName?: string;
-    args?: VariableValue[];
-    logicalOp?: LogicalOp;
-    conditions?: Condition[];
-}
-/** Effect/action to execute */
-export interface Effect {
-    type: 'setVariable' | 'addVariable' | 'triggerEvent' | 'callFunction' | 'startQuest' | 'giveItem' | 'playSound' | 'playAnimation';
-    target?: string;
-    value?: VariableValue;
-    eventName?: string;
-    eventData?: Record<string, VariableValue>;
-    functionName?: string;
-    args?: VariableValue[];
-    questId?: string;
-    itemId?: string;
-    amount?: number;
-    soundId?: string;
-    animationId?: string;
-}
-/** Character/speaker definition */
-export interface Character {
-    id: CharacterId;
-    name: string;
-    displayName?: string;
-    portrait?: string;
-    color?: string;
-    voiceId?: string;
-    tags?: string[];
-    metadata?: Record<string, VariableValue>;
-}
-/** Response option for choice nodes */
-export interface DialogueResponse {
-    id: ResponseId;
-    text: string;
-    shortText?: string;
-    targetNode: NodeId;
-    conditions?: Condition[];
-    effects?: Effect[];
-    isDefault?: boolean;
-    isOnce?: boolean;
-    wasSelected?: boolean;
-    priority?: number;
-    hints?: string[];
-    tags?: string[];
-}
-/** Base dialogue node */
-export interface BaseDialogueNode {
-    id: NodeId;
-    type: NodeType;
-    tags?: string[];
-    metadata?: Record<string, VariableValue>;
-}
-/** Text node - displays dialogue */
-export interface TextNode extends BaseDialogueNode {
-    type: 'text';
-    speaker?: CharacterId;
-    text: string;
-    voiceClip?: string;
-    duration?: number;
-    emotion?: string;
-    animation?: string;
-    nextNode?: NodeId;
-    effects?: Effect[];
-    autoAdvance?: boolean;
-    typewriterSpeed?: number;
-}
-/** Choice node - presents options */
-export interface ChoiceNode extends BaseDialogueNode {
-    type: 'choice';
-    speaker?: CharacterId;
-    prompt?: string;
-    responses: DialogueResponse[];
-    timeout?: number;
-    defaultResponse?: ResponseId;
-    shuffleResponses?: boolean;
-}
-/** Branch node - conditional routing */
-export interface BranchNode extends BaseDialogueNode {
-    type: 'branch';
-    branches: Array<{
-        condition: Condition;
-        targetNode: NodeId;
-    }>;
-    defaultNode?: NodeId;
-}
-/** Jump node - go to another node/dialogue */
-export interface JumpNode extends BaseDialogueNode {
-    type: 'jump';
-    targetDialogue?: DialogueId;
-    targetNode: NodeId;
-    returnAfter?: boolean;
-}
-/** Set node - modify variables */
-export interface SetNode extends BaseDialogueNode {
-    type: 'set';
-    effects: Effect[];
-    nextNode?: NodeId;
-}
-/** Event node - trigger game events */
-export interface EventNode extends BaseDialogueNode {
-    type: 'event';
-    eventName: string;
-    eventData?: Record<string, VariableValue>;
-    nextNode?: NodeId;
-    waitForCompletion?: boolean;
-}
-/** Random node - random selection */
-export interface RandomNode extends BaseDialogueNode {
-    type: 'random';
-    options: Array<{
-        weight: number;
-        targetNode: NodeId;
-    }>;
-    noRepeat?: boolean;
-    lastSelected?: NodeId;
-}
-/** Sequence node - play in order */
-export interface SequenceNode extends BaseDialogueNode {
-    type: 'sequence';
-    nodes: NodeId[];
-    currentIndex?: number;
-    nextNode?: NodeId;
-}
-/** Parallel node - concurrent display */
-export interface ParallelNode extends BaseDialogueNode {
-    type: 'parallel';
-    nodes: NodeId[];
-    nextNode?: NodeId;
-}
-/** Wait node - pause for condition */
-export interface WaitNode extends BaseDialogueNode {
-    type: 'wait';
-    duration?: number;
-    condition?: Condition;
-    nextNode?: NodeId;
-}
-/** End node - terminate dialogue */
-export interface EndNode extends BaseDialogueNode {
-    type: 'end';
-    effects?: Effect[];
-}
-/** Union of all node types */
-export type DialogueNode = TextNode | ChoiceNode | BranchNode | JumpNode | SetNode | EventNode | RandomNode | SequenceNode | ParallelNode | WaitNode | EndNode;
-/** Complete dialogue definition */
-export interface Dialogue {
-    id: DialogueId;
-    name: string;
-    description?: string;
-    startNode: NodeId;
-    nodes: Map<NodeId, DialogueNode>;
-    characters?: CharacterId[];
-    tags?: string[];
-    priority?: number;
-    conditions?: Condition[];
-    onStart?: Effect[];
-    onEnd?: Effect[];
-    metadata?: Record<string, VariableValue>;
-}
-/** Active conversation state */
-export interface ConversationState {
-    id: ConversationId;
-    dialogueId: DialogueId;
-    currentNode: NodeId;
-    nodeStack: NodeId[];
-    dialogueStack: DialogueId[];
-    startTime: number;
-    lastUpdateTime: number;
-    isPaused: boolean;
-    isComplete: boolean;
-    variables: Map<string, VariableValue>;
-    visitedNodes: Set<NodeId>;
-    selectedResponses: Map<NodeId, ResponseId>;
-    history: DialogueHistoryEntry[];
-}
-/** History entry */
-export interface DialogueHistoryEntry {
-    timestamp: number;
-    nodeId: NodeId;
-    speaker?: CharacterId;
-    text?: string;
-    selectedResponse?: ResponseId;
-    effects?: Effect[];
-}
-/** Dialogue event types */
-export type DialogueEventType = 'conversation:start' | 'conversation:end' | 'conversation:pause' | 'conversation:resume' | 'node:enter' | 'node:exit' | 'text:display' | 'text:complete' | 'choice:presented' | 'choice:selected' | 'effect:executed' | 'event:triggered' | 'variable:changed' | 'jump:executed' | 'timeout:occurred' | 'error';
-/** Dialogue event */
-export interface DialogueEvent {
-    type: DialogueEventType;
-    conversationId?: ConversationId;
-    dialogueId?: DialogueId;
-    nodeId?: NodeId;
-    speaker?: Character;
-    text?: string;
-    responses?: DialogueResponse[];
-    selectedResponse?: DialogueResponse;
-    effect?: Effect;
-    eventName?: string;
-    eventData?: Record<string, VariableValue>;
-    variable?: string;
-    oldValue?: VariableValue;
-    newValue?: VariableValue;
-    error?: Error;
-    timestamp: number;
-}
-/** Event callback */
-export type DialogueEventCallback = (event: DialogueEvent) => void;
-/** Function registry entry */
-export interface FunctionDefinition {
-    name: string;
-    fn: (...args: VariableValue[]) => VariableValue | boolean | void;
-    description?: string;
-}
-/** Dialogue system configuration */
-export interface DialogueConfig {
-    /** Default typewriter speed (characters per second) */
-    defaultTypewriterSpeed: number;
-    /** Auto-advance delay after text complete (ms) */
-    autoAdvanceDelay: number;
-    /** Enable dialogue history */
-    enableHistory: boolean;
-    /** Maximum history entries */
-    maxHistoryEntries: number;
-    /** Allow skipping text */
-    allowSkip: boolean;
-    /** Allow going back in conversation */
-    allowBack: boolean;
-    /** Default choice timeout (0 = no timeout) */
-    defaultChoiceTimeout: number;
-    /** Localization function */
-    localize?: (key: string, params?: Record<string, string>) => string;
-    /** Voice playback function */
-    playVoice?: (clipId: string) => Promise<void>;
-    /** Debug mode */
-    debug: boolean;
-}
-export declare const DEFAULT_DIALOGUE_CONFIG: DialogueConfig;
-export declare class NiceDialogue extends EventEmitter<Record<DialogueEventType, [DialogueEvent]>> {
-    private config;
-    private dialogues;
-    private characters;
-    private conversations;
-    private globalVariables;
-    private functions;
-    private typewriterTimers;
-    private timeoutTimers;
-    private conversationCounter;
-    constructor(config?: Partial<DialogueConfig>);
-    /**
-     * Register a dialogue
-     */
-    registerDialogue(dialogue: Dialogue): void;
-    /**
-     * Register multiple dialogues
-     */
-    registerDialogues(dialogues: Dialogue[]): void;
-    /**
-     * Unregister a dialogue
-     */
-    unregisterDialogue(id: DialogueId): boolean;
-    /**
-     * Get dialogue by ID
-     */
-    getDialogue(id: DialogueId): Dialogue | undefined;
-    /**
-     * Register a character
-     */
-    registerCharacter(character: Character): void;
-    /**
-     * Register multiple characters
-     */
-    registerCharacters(characters: Character[]): void;
-    /**
-     * Get character by ID
-     */
-    getCharacter(id: CharacterId): Character | undefined;
-    /**
-     * Set global variable
-     */
-    setVariable(name: string, value: VariableValue): void;
-    /**
-     * Get global variable
-     */
-    getVariable(name: string): VariableValue | undefined;
-    /**
-     * Check if variable exists
-     */
-    hasVariable(name: string): boolean;
-    /**
-     * Delete variable
-     */
-    deleteVariable(name: string): boolean;
-    /**
-     * Get all variables
-     */
-    getAllVariables(): Map<string, VariableValue>;
-    /**
-     * Set multiple variables
-     */
-    setVariables(variables: Record<string, VariableValue>): void;
-    /**
-     * Register a custom function
-     */
-    registerFunction(name: string, fn: (...args: VariableValue[]) => VariableValue | boolean | void, description?: string): void;
-    /**
-     * Call a registered function
-     */
-    callFunction(name: string, ...args: VariableValue[]): VariableValue | boolean | void;
-    /**
-     * Register built-in functions
-     */
-    private registerBuiltInFunctions;
-    /**
-     * Start a new conversation
-     */
-    startConversation(dialogueId: DialogueId, initialVariables?: Record<string, VariableValue>): ConversationId | null;
-    /**
-     * End a conversation
-     */
-    endConversation(conversationId: ConversationId): void;
-    /**
-     * Pause a conversation
-     */
-    pauseConversation(conversationId: ConversationId): void;
-    /**
-     * Resume a conversation
-     */
-    resumeConversation(conversationId: ConversationId): void;
-    /**
-     * Get conversation state
-     */
-    getConversation(conversationId: ConversationId): ConversationState | undefined;
-    /**
-     * Check if conversation is active
-     */
-    isConversationActive(conversationId: ConversationId): boolean;
-    /**
-     * Get all active conversations
-     */
-    getActiveConversations(): ConversationState[];
-    /**
-     * Clear conversation timers
-     */
-    private clearConversationTimers;
-    /**
-     * Process current node in conversation
-     */
-    private processNode;
-    /**
-     * Process text node
-     */
-    private processTextNode;
-    /**
-     * Process choice node
-     */
-    private processChoiceNode;
-    /**
-     * Select a response in choice node
-     */
-    selectResponse(conversationId: ConversationId, responseId: ResponseId): void;
-    /**
-     * Process branch node
-     */
-    private processBranchNode;
-    /**
-     * Process jump node
-     */
-    private processJumpNode;
-    /**
-     * Process set node
-     */
-    private processSetNode;
-    /**
-     * Process event node
-     */
-    private processEventNode;
-    /**
-     * Process random node
-     */
-    private processRandomNode;
-    /**
-     * Process sequence node
-     */
-    private processSequenceNode;
-    /**
-     * Process wait node
-     */
-    private processWaitNode;
-    /**
-     * Process end node
-     */
-    private processEndNode;
-    /**
-     * Go to a specific node
-     */
-    private goToNode;
-    /**
-     * Skip current text display
-     */
-    skipText(conversationId: ConversationId): void;
-    /**
-     * Advance to next node (for non-auto text)
-     */
-    advanceConversation(conversationId: ConversationId): void;
-    /**
-     * Evaluate a condition
-     */
-    evaluateCondition(condition: Condition, state?: ConversationState): boolean;
-    /**
-     * Compare two values
-     */
-    private compareValues;
-    /**
-     * Execute an effect
-     */
-    private executeEffect;
-    /**
-     * Interpolate variables in text
-     */
-    private interpolateText;
-    /**
-     * Add entry to conversation history
-     */
-    private addToHistory;
-    /**
-     * Get conversation history
-     */
-    getHistory(conversationId: ConversationId): DialogueHistoryEntry[];
-    /**
-     * Clear conversation history
-     */
-    clearHistory(conversationId: ConversationId): void;
-    /**
-     * Shuffle array (Fisher-Yates)
-     */
-    private shuffleArray;
-    /**
-     * Get dialogue statistics
-     */
-    getStats(): {
-        dialogueCount: number;
-        characterCount: number;
-        activeConversations: number;
-        totalConversations: number;
-        variableCount: number;
-        functionCount: number;
-    };
-    /**
-     * Export state for saving
-     */
-    exportState(): {
-        globalVariables: Record<string, VariableValue>;
-        conversations: Array<{
-            id: ConversationId;
-            dialogueId: DialogueId;
-            currentNode: NodeId;
-            variables: Record<string, VariableValue>;
-            visitedNodes: NodeId[];
-            selectedResponses: Array<[NodeId, ResponseId]>;
-            history: DialogueHistoryEntry[];
-        }>;
-    };
-    /**
-     * Import state
-     */
-    importState(data: ReturnType<typeof this.exportState>): void;
-    /**
-     * Destroy the dialogue system
-     */
-    destroy(): void;
-}
-/**
- * Create a dialogue system
- */
-export declare function createDialogueSystem(config?: Partial<DialogueConfig>): NiceDialogue;
-/**
- * Fluent builder for creating dialogues
- */
-export declare class DialogueBuilder {
-    private dialogue;
-    private currentNodeId;
-    constructor(id: DialogueId, name: string);
-    description(desc: string): this;
-    characters(...ids: CharacterId[]): this;
-    tags(...tags: string[]): this;
-    priority(p: number): this;
-    conditions(...conditions: Condition[]): this;
-    onStart(...effects: Effect[]): this;
-    onEnd(...effects: Effect[]): this;
-    startAt(nodeId: NodeId): this;
-    text(id: NodeId, speaker: CharacterId | undefined, text: string, nextNode?: NodeId): this;
-    choice(id: NodeId, prompt?: string, speaker?: CharacterId): ChoiceBuilder;
-    branch(id: NodeId, defaultNode?: NodeId): BranchBuilder;
-    jump(id: NodeId, targetNode: NodeId, targetDialogue?: DialogueId): this;
-    set(id: NodeId, effects: Effect[], nextNode?: NodeId): this;
-    event(id: NodeId, eventName: string, eventData?: Record<string, VariableValue>, nextNode?: NodeId): this;
-    end(id: NodeId, effects?: Effect[]): this;
-    build(): Dialogue;
-}
-/**
- * Choice node builder
- */
-export declare class ChoiceBuilder {
-    private parent;
-    private node;
-    constructor(parent: DialogueBuilder, node: ChoiceNode);
-    response(id: ResponseId, text: string, targetNode: NodeId): ResponseBuilder;
-    timeout(ms: number, defaultResponse?: ResponseId): this;
-    shuffle(): this;
-    done(): DialogueBuilder;
-}
-/**
- * Response builder
- */
-export declare class ResponseBuilder {
-    private parent;
-    private response;
-    constructor(parent: ChoiceBuilder, response: DialogueResponse);
-    shortText(text: string): this;
-    condition(condition: Condition): this;
-    effect(effect: Effect): this;
-    once(): this;
-    isDefault(): this;
-    priority(p: number): this;
-    done(): ChoiceBuilder;
-}
-/**
- * Branch node builder
- */
-export declare class BranchBuilder {
-    private parent;
-    private node;
-    constructor(parent: DialogueBuilder, node: BranchNode);
-    when(condition: Condition, targetNode: NodeId): this;
-    otherwise(targetNode: NodeId): this;
-    done(): DialogueBuilder;
-}
-/**
- * Create a dialogue builder
- */
-export declare function dialogue(id: DialogueId, name: string): DialogueBuilder;
-/**
- * Create a simple condition
- */
-export declare function condition(variable: string, operator: ComparisonOp, value: VariableValue): Condition;
-/**
- * Create a function condition
- */
-export declare function functionCondition(functionName: string, ...args: VariableValue[]): Condition;
-/**
- * Create an AND compound condition
- */
-export declare function and(...conditions: Condition[]): Condition;
-/**
- * Create an OR compound condition
- */
-export declare function or(...conditions: Condition[]): Condition;
-/**
- * Create a NOT condition
- */
-export declare function not(c: Condition): Condition;
-/**
- * Create a set variable effect
- */
-export declare function setVar(target: string, value: VariableValue): Effect;
-/**
- * Create an add variable effect
- */
-export declare function addVar(target: string, value: number): Effect;
-/**
- * Create a trigger event effect
- */
-export declare function triggerEvent(eventName: string, eventData?: Record<string, VariableValue>): Effect;
-/**
- * Create a give item effect
- */
-export declare function giveItem(itemId: string, amount?: number): Effect;
-/**
- * Create a start quest effect
- */
-export declare function startQuest(questId: string): Effect;
-export { DialogueBuilder as Builder };