@nice2dev/game-engine 1.1.5 → 1.1.6

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

@@ -0,0 +1,629 @@
+/**
+ * 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 };