@nice2dev/game-engine 1.1.5 → 1.1.7

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

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