@nice2dev/game-engine 1.3.12 → 1.3.14

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

@@ -1,620 +0,0 @@
-/**
- * NiceQuest - Comprehensive Quest/Mission System
- *
- * Professional quest system for RPGs and adventure games.
- * Supports complex objectives, branching, tracking, rewards, and discovery.
- *
- * Features:
- * - Multi-objective quests with dependencies
- * - Branching quest lines
- * - Quest chains and prerequisites
- * - Auto-tracking and discovery
- * - Dynamic objectives
- * - Rewards system (items, XP, reputation)
- * - Quest journal with categories
- * - Time-limited quests
- * - Repeatable/daily quests
- * - Hidden/secret quests
- * - Quest markers/waypoints
- *
- * @packageDocumentation
- */
-import { EventEmitter } from 'eventemitter3';
-/** Unique identifier for quests */
-export type QuestId = string;
-/** Unique identifier for objectives */
-export type ObjectiveId = string;
-/** Unique identifier for quest chains */
-export type ChainId = string;
-/** Unique identifier for NPCs */
-export type NpcId = string;
-/** Unique identifier for quest markers */
-export type MarkerId = string;
-/** Quest states */
-export type QuestState = 'unknown' | 'available' | 'active' | 'completed' | 'failed' | 'abandoned' | 'locked';
-/** Objective states */
-export type ObjectiveState = 'hidden' | 'active' | 'completed' | 'failed' | 'optional';
-/** Objective types */
-export type ObjectiveType = 'collect' | 'kill' | 'talk' | 'explore' | 'escort' | 'defend' | 'deliver' | 'interact' | 'craft' | 'use' | 'survive' | 'win' | 'custom';
-/** Quest difficulty */
-export type QuestDifficulty = 'trivial' | 'easy' | 'normal' | 'hard' | 'legendary';
-/** Quest category */
-export type QuestCategory = 'main' | 'side' | 'daily' | 'weekly' | 'world' | 'guild' | 'dungeon' | 'pvp' | 'achievement';
-/** 2D position */
-export interface Vec2 {
-    x: number;
-    y: number;
-}
-/** 3D position */
-export interface Vec3 {
-    x: number;
-    y: number;
-    z: number;
-}
-/** Reward types */
-export interface Reward {
-    type: 'item' | 'currency' | 'experience' | 'reputation' | 'unlock' | 'custom';
-    id?: string;
-    amount?: number;
-    data?: Record<string, unknown>;
-}
-/** Condition for quest availability */
-export interface QuestCondition {
-    type: 'level' | 'quest' | 'item' | 'reputation' | 'time' | 'flag' | 'custom';
-    operator?: '==' | '!=' | '>' | '<' | '>=' | '<=';
-    target?: string;
-    value?: number | string | boolean;
-    customCheck?: () => boolean;
-}
-/** Quest marker for map/compass */
-export interface QuestMarker {
-    id: MarkerId;
-    questId: QuestId;
-    objectiveId?: ObjectiveId;
-    position: Vec3;
-    type: 'quest' | 'objective' | 'turn-in' | 'poi';
-    icon?: string;
-    label?: string;
-    visible: boolean;
-    tracked: boolean;
-}
-/** Objective definition */
-export interface ObjectiveDefinition {
-    id: ObjectiveId;
-    type: ObjectiveType;
-    description: string;
-    shortDescription?: string;
-    target?: string;
-    targetId?: string;
-    requiredCount: number;
-    currentCount?: number;
-    isOptional?: boolean;
-    isHidden?: boolean;
-    revealConditions?: QuestCondition[];
-    failConditions?: QuestCondition[];
-    location?: Vec3;
-    radius?: number;
-    timeLimit?: number;
-    markers?: QuestMarker[];
-    dependencies?: ObjectiveId[];
-    onComplete?: () => void;
-    onFail?: () => void;
-    metadata?: Record<string, unknown>;
-}
-/** Objective instance */
-export interface ObjectiveInstance {
-    definition: ObjectiveDefinition;
-    state: ObjectiveState;
-    currentCount: number;
-    startTime?: number;
-    completionTime?: number;
-    failTime?: number;
-}
-/** Quest stage (for branching) */
-export interface QuestStage {
-    id: string;
-    name: string;
-    description?: string;
-    objectives: ObjectiveId[];
-    nextStages?: Array<{
-        stageId: string;
-        conditions?: QuestCondition[];
-    }>;
-    onEnter?: () => void;
-    onExit?: () => void;
-}
-/** Quest definition */
-export interface QuestDefinition {
-    id: QuestId;
-    name: string;
-    description: string;
-    shortDescription?: string;
-    category: QuestCategory;
-    difficulty?: QuestDifficulty;
-    levelRequirement?: number;
-    levelRecommended?: number;
-    prerequisites?: QuestCondition[];
-    objectives: ObjectiveDefinition[];
-    stages?: QuestStage[];
-    startStage?: string;
-    rewards: Reward[];
-    bonusRewards?: Array<{
-        conditions: QuestCondition[];
-        rewards: Reward[];
-    }>;
-    questGiver?: NpcId;
-    turnInNpc?: NpcId;
-    isRepeatable?: boolean;
-    repeatCooldown?: number;
-    isHidden?: boolean;
-    autoAccept?: boolean;
-    autoComplete?: boolean;
-    timeLimit?: number;
-    failOnAbandon?: boolean;
-    canAbandon?: boolean;
-    chainId?: ChainId;
-    chainOrder?: number;
-    tags?: string[];
-    icon?: string;
-    markers?: QuestMarker[];
-    onStart?: () => void;
-    onComplete?: () => void;
-    onFail?: () => void;
-    onAbandon?: () => void;
-    metadata?: Record<string, unknown>;
-}
-/** Quest instance (active/completed quest) */
-export interface QuestInstance {
-    definition: QuestDefinition;
-    state: QuestState;
-    objectives: Map<ObjectiveId, ObjectiveInstance>;
-    currentStage?: string;
-    startTime?: number;
-    completionTime?: number;
-    failTime?: number;
-    abandonTime?: number;
-    completionCount: number;
-    lastCompletionTime?: number;
-    isTracked: boolean;
-    metadata: Map<string, unknown>;
-}
-/** Quest chain definition */
-export interface QuestChain {
-    id: ChainId;
-    name: string;
-    description?: string;
-    quests: QuestId[];
-    isLinear: boolean;
-    rewards?: Reward[];
-    onComplete?: () => void;
-    metadata?: Record<string, unknown>;
-}
-/** Quest chain progress */
-export interface ChainProgress {
-    chain: QuestChain;
-    currentQuestIndex: number;
-    completedQuests: QuestId[];
-    isComplete: boolean;
-}
-/** Quest journal entry */
-export interface JournalEntry {
-    timestamp: number;
-    questId: QuestId;
-    type: 'started' | 'objective' | 'stage' | 'completed' | 'failed' | 'abandoned';
-    objectiveId?: ObjectiveId;
-    stageId?: string;
-    message?: string;
-}
-/** Quest event types */
-export type QuestEventType = 'quest:discovered' | 'quest:available' | 'quest:started' | 'quest:completed' | 'quest:failed' | 'quest:abandoned' | 'quest:tracked' | 'quest:untracked' | 'objective:started' | 'objective:progress' | 'objective:completed' | 'objective:failed' | 'objective:revealed' | 'stage:entered' | 'stage:exited' | 'chain:started' | 'chain:progress' | 'chain:completed' | 'reward:granted' | 'marker:added' | 'marker:removed' | 'marker:updated' | 'error';
-/** Quest event */
-export interface QuestEvent {
-    type: QuestEventType;
-    questId?: QuestId;
-    objectiveId?: ObjectiveId;
-    chainId?: ChainId;
-    stageId?: string;
-    markerId?: MarkerId;
-    quest?: QuestInstance;
-    objective?: ObjectiveInstance;
-    chain?: ChainProgress;
-    marker?: QuestMarker;
-    reward?: Reward;
-    progress?: {
-        current: number;
-        required: number;
-    };
-    error?: Error;
-    timestamp: number;
-}
-/** Event callback */
-export type QuestEventCallback = (event: QuestEvent) => void;
-/** Quest system configuration */
-export interface QuestConfig {
-    /** Maximum active quests */
-    maxActiveQuests: number;
-    /** Maximum tracked quests */
-    maxTrackedQuests: number;
-    /** Enable quest journal */
-    enableJournal: boolean;
-    /** Maximum journal entries */
-    maxJournalEntries: number;
-    /** Auto-track new quests */
-    autoTrackNewQuests: boolean;
-    /** Show objective notifications */
-    showObjectiveNotifications: boolean;
-    /** Check conditions interval (ms) */
-    conditionCheckInterval: number;
-    /** Debug mode */
-    debug: boolean;
-}
-export declare const DEFAULT_QUEST_CONFIG: QuestConfig;
-export declare class NiceQuest extends EventEmitter<Record<QuestEventType, [QuestEvent]>> {
-    private config;
-    private questDefinitions;
-    private questInstances;
-    private questChains;
-    private chainProgress;
-    private markers;
-    private journal;
-    private playerLevel;
-    private playerFlags;
-    private playerReputation;
-    private conditionCheckTimer?;
-    private markerCounter;
-    constructor(config?: Partial<QuestConfig>);
-    /**
-     * Register a quest definition
-     */
-    registerQuest(quest: QuestDefinition): void;
-    /**
-     * Register multiple quests
-     */
-    registerQuests(quests: QuestDefinition[]): void;
-    /**
-     * Register a quest chain
-     */
-    registerChain(chain: QuestChain): void;
-    /**
-     * Get quest definition
-     */
-    getQuestDefinition(id: QuestId): QuestDefinition | undefined;
-    /**
-     * Get quest instance
-     */
-    getQuest(id: QuestId): QuestInstance | undefined;
-    /**
-     * Get quest chain
-     */
-    getChain(id: ChainId): QuestChain | undefined;
-    /**
-     * Get chain progress
-     */
-    getChainProgress(id: ChainId): ChainProgress | undefined;
-    /**
-     * Start a quest
-     */
-    startQuest(questId: QuestId): boolean;
-    /**
-     * Complete a quest
-     */
-    completeQuest(questId: QuestId, grantRewards?: boolean): boolean;
-    /**
-     * Fail a quest
-     */
-    failQuest(questId: QuestId): boolean;
-    /**
-     * Abandon a quest
-     */
-    abandonQuest(questId: QuestId): boolean;
-    /**
-     * Reset a quest (for repeatable)
-     */
-    private resetQuest;
-    /**
-     * Update objective progress
-     */
-    updateObjective(questId: QuestId, objectiveId: ObjectiveId, progress: number, absolute?: boolean): boolean;
-    /**
-     * Update objective by type
-     */
-    updateObjectiveByType(objectiveType: ObjectiveType, targetId: string, progress?: number): void;
-    /**
-     * Complete an objective
-     */
-    completeObjective(questId: QuestId, objectiveId: ObjectiveId): boolean;
-    /**
-     * Fail an objective
-     */
-    failObjective(questId: QuestId, objectiveId: ObjectiveId): boolean;
-    /**
-     * Reveal a hidden objective
-     */
-    revealObjective(questId: QuestId, objectiveId: ObjectiveId): boolean;
-    /**
-     * Check and advance stages
-     */
-    private checkStageProgress;
-    /**
-     * Enter a new stage
-     */
-    private enterStage;
-    /**
-     * Track a quest
-     */
-    trackQuest(questId: QuestId): boolean;
-    /**
-     * Untrack a quest
-     */
-    untrackQuest(questId: QuestId): boolean;
-    /**
-     * Add quest markers
-     */
-    private addQuestMarkers;
-    /**
-     * Add a marker
-     */
-    addMarker(marker: QuestMarker): void;
-    /**
-     * Remove quest markers
-     */
-    private removeQuestMarkers;
-    /**
-     * Remove objective markers
-     */
-    private removeObjectiveMarkers;
-    /**
-     * Get all markers
-     */
-    getMarkers(): QuestMarker[];
-    /**
-     * Get visible markers
-     */
-    getVisibleMarkers(): QuestMarker[];
-    /**
-     * Update chain progress
-     */
-    private updateChainProgress;
-    /**
-     * Grant rewards
-     */
-    private grantRewards;
-    /**
-     * Get active quests
-     */
-    getActiveQuests(): QuestInstance[];
-    /**
-     * Get available quests
-     */
-    getAvailableQuests(): QuestInstance[];
-    /**
-     * Get completed quests
-     */
-    getCompletedQuests(): QuestInstance[];
-    /**
-     * Get failed quests
-     */
-    getFailedQuests(): QuestInstance[];
-    /**
-     * Get tracked quests
-     */
-    getTrackedQuests(): QuestInstance[];
-    /**
-     * Get quests by category
-     */
-    getQuestsByCategory(category: QuestCategory): QuestInstance[];
-    /**
-     * Get quests by NPC
-     */
-    getQuestsByNpc(npcId: NpcId): QuestInstance[];
-    /**
-     * Get quests available from NPC
-     */
-    getAvailableQuestsFromNpc(npcId: NpcId): QuestInstance[];
-    /**
-     * Get quests ready to turn in to NPC
-     */
-    getCompletableQuestsForNpc(npcId: NpcId): QuestInstance[];
-    /**
-     * Check a condition
-     */
-    checkCondition(condition: QuestCondition): boolean;
-    /**
-     * Compare values
-     */
-    private compareValue;
-    /**
-     * Check quest availability
-     */
-    private checkQuestAvailability;
-    /**
-     * Start condition checking loop
-     */
-    private startConditionChecking;
-    /**
-     * Check all conditions
-     */
-    private checkAllConditions;
-    /**
-     * Set player level
-     */
-    setPlayerLevel(level: number): void;
-    /**
-     * Set player flag
-     */
-    setFlag(name: string, value: boolean): void;
-    /**
-     * Set player reputation
-     */
-    setReputation(faction: string, value: number): void;
-    /**
-     * Add reputation
-     */
-    addReputation(faction: string, amount: number): void;
-    /**
-     * Add journal entry
-     */
-    private addJournalEntry;
-    /**
-     * Get journal entries
-     */
-    getJournal(): JournalEntry[];
-    /**
-     * Get journal for quest
-     */
-    getQuestJournal(questId: QuestId): JournalEntry[];
-    /**
-     * Clear journal
-     */
-    clearJournal(): void;
-    /**
-     * Create quest instance
-     */
-    private createQuestInstance;
-    /**
-     * Emit error event
-     */
-    private emitError;
-    /**
-     * Get statistics
-     */
-    getStats(): {
-        totalQuests: number;
-        activeQuests: number;
-        completedQuests: number;
-        failedQuests: number;
-        availableQuests: number;
-        trackedQuests: number;
-        totalChains: number;
-        completedChains: number;
-        journalEntries: number;
-        markerCount: number;
-    };
-    /**
-     * Export state for saving
-     */
-    exportState(): {
-        quests: Array<{
-            id: QuestId;
-            state: QuestState;
-            objectives: Array<{
-                id: ObjectiveId;
-                state: ObjectiveState;
-                currentCount: number;
-            }>;
-            currentStage?: string;
-            startTime?: number;
-            completionTime?: number;
-            completionCount: number;
-            isTracked: boolean;
-        }>;
-        chains: Array<{
-            id: ChainId;
-            currentQuestIndex: number;
-            completedQuests: QuestId[];
-            isComplete: boolean;
-        }>;
-        playerLevel: number;
-        flags: Record<string, boolean>;
-        reputation: Record<string, number>;
-        journal: JournalEntry[];
-    };
-    /**
-     * Import state
-     */
-    importState(data: ReturnType<typeof this.exportState>): void;
-    /**
-     * Destroy the quest system
-     */
-    destroy(): void;
-}
-/**
- * Create a quest system
- */
-export declare function createQuestSystem(config?: Partial<QuestConfig>): NiceQuest;
-/**
- * Fluent builder for creating quests
- */
-export declare class QuestBuilder {
-    private quest;
-    constructor(id: QuestId, name: string, category?: QuestCategory);
-    description(desc: string): this;
-    shortDescription(desc: string): this;
-    difficulty(d: QuestDifficulty): this;
-    levelRequirement(level: number): this;
-    levelRecommended(level: number): this;
-    prerequisite(condition: QuestCondition): this;
-    requiresQuest(questId: QuestId, state?: QuestState): this;
-    requiresLevel(level: number): this;
-    questGiver(npcId: NpcId): this;
-    turnIn(npcId: NpcId): this;
-    objective(id: ObjectiveId, type: ObjectiveType, description: string, requiredCount?: number): ObjectiveBuilder;
-    collectObjective(id: ObjectiveId, itemId: string, description: string, count?: number): this;
-    killObjective(id: ObjectiveId, enemyId: string, description: string, count?: number): this;
-    talkObjective(id: ObjectiveId, npcId: NpcId, description: string): this;
-    exploreObjective(id: ObjectiveId, description: string, location: Vec3, radius?: number): this;
-    reward(type: Reward['type'], id?: string, amount?: number): this;
-    rewardItem(itemId: string, amount?: number): this;
-    rewardCurrency(currencyId: string, amount: number): this;
-    rewardExperience(amount: number): this;
-    rewardReputation(factionId: string, amount: number): this;
-    repeatable(cooldown?: number): this;
-    timeLimit(ms: number): this;
-    hidden(): this;
-    autoAccept(): this;
-    autoComplete(): this;
-    cannotAbandon(): this;
-    failOnAbandon(): this;
-    chain(chainId: ChainId, order: number): this;
-    tags(...tags: string[]): this;
-    icon(icon: string): this;
-    onStart(callback: () => void): this;
-    onComplete(callback: () => void): this;
-    onFail(callback: () => void): this;
-    onAbandon(callback: () => void): this;
-    build(): QuestDefinition;
-}
-/**
- * Objective builder
- */
-export declare class ObjectiveBuilder {
-    private parent;
-    private objective;
-    constructor(parent: QuestBuilder, objective: ObjectiveDefinition);
-    target(targetId: string): this;
-    location(loc: Vec3, radius?: number): this;
-    optional(): this;
-    hidden(): this;
-    timeLimit(ms: number): this;
-    dependsOn(...objectiveIds: ObjectiveId[]): this;
-    revealWhen(condition: QuestCondition): this;
-    failWhen(condition: QuestCondition): this;
-    onComplete(callback: () => void): this;
-    onFail(callback: () => void): this;
-    marker(position: Vec3, type?: QuestMarker['type'], label?: string): this;
-    done(): QuestBuilder;
-}
-/**
- * Create a quest builder
- */
-export declare function quest(id: QuestId, name: string, category?: QuestCategory): QuestBuilder;
-/**
- * Create a quest chain
- */
-export declare function questChain(id: ChainId, name: string, quests: QuestId[], isLinear?: boolean): QuestChain;
-/**
- * Create a level condition
- */
-export declare function levelCondition(level: number, operator?: QuestCondition['operator']): QuestCondition;
-/**
- * Create a quest condition
- */
-export declare function questCondition(questId: QuestId, state?: QuestState): QuestCondition;
-/**
- * Create a flag condition
- */
-export declare function flagCondition(flagName: string, value?: boolean): QuestCondition;
-/**
- * Create a reputation condition
- */
-export declare function reputationCondition(faction: string, value: number, operator?: QuestCondition['operator']): QuestCondition;