@its-not-rocket-science/ananke 0.1.0

package/dist/src/quest.d.ts

@@ -0,0 +1,239 @@
+import type { Q } from "./units.js";
+import type { CompetenceDomain } from "./competence/catalogue.js";
+import type { ImpactEvent } from "./sim/events.js";
+/** State of a quest in its lifecycle. */
+export type QuestState = "inactive" | "active" | "completed" | "failed";
+/** State of an individual objective. */
+export type ObjectiveState = "locked" | "available" | "in_progress" | "completed" | "failed";
+/** Types of quest objectives supported. */
+export type QuestObjectiveType = "reach_location" | "defeat_entity" | "collect_item" | "use_competence" | "deliver_item" | "escort_entity" | "dialogue_choice" | "wait_duration";
+/** Location target for objectives. */
+export interface LocationTarget {
+    x: number;
+    y: number;
+    radius_m: number;
+}
+/** Target specification for objectives. */
+export interface QuestTarget {
+    entityId?: number;
+    location?: LocationTarget;
+    itemId?: string;
+    competence?: {
+        domain: CompetenceDomain;
+        minQuality_Q: Q;
+        taskId?: string;
+    };
+    dialogueChoice?: string;
+}
+/** A single objective within a quest. */
+export interface QuestObjective {
+    objectiveId: string;
+    description: string;
+    type: QuestObjectiveType;
+    target?: QuestTarget;
+    count?: number;
+    progress: number;
+    state: ObjectiveState;
+    hidden: boolean;
+    /** Prerequisites: which objectives must be completed before this unlocks. */
+    requires?: string[];
+    /** Time limit in seconds (undefined = no limit). */
+    timeLimit_s?: number;
+    /** Tick when objective became available (for time limits). */
+    activatedAtTick?: number;
+}
+/** A quest with multiple objectives forming a directed graph. */
+export interface Quest {
+    questId: string;
+    title: string;
+    description: string;
+    giverId?: number;
+    objectives: QuestObjective[];
+    state: QuestState;
+    priority: number;
+    /** Faction reputation requirements to receive this quest. */
+    factionRequirements?: Record<string, number>;
+    /** Rewards granted on completion. */
+    rewards?: QuestRewards;
+    /** Tick when quest was accepted. */
+    acceptedAtTick?: number;
+    /** Overall time limit in seconds. */
+    timeLimit_s?: number;
+}
+/** Rewards for quest completion. */
+export interface QuestRewards {
+    /** Reputation change per faction. */
+    reputation?: Record<string, number>;
+    /** Items granted. */
+    items?: {
+        itemId: string;
+        quantity: number;
+    }[];
+    /** Experience points (Phase 21). */
+    xp?: number;
+    /** Currency/economy units (Phase 25). */
+    currency?: number;
+}
+/** Event fired when a quest or objective state changes. */
+export interface QuestUpdateEvent {
+    questId: string;
+    objectiveId?: string;
+    oldState: QuestState | ObjectiveState;
+    newState: QuestState | ObjectiveState;
+    trigger: QuestTrigger;
+    tick: number;
+}
+/** What triggered the quest update. */
+export type QuestTrigger = {
+    type: "accepted";
+    entityId: number;
+} | {
+    type: "location_reached";
+    position: {
+        x: number;
+        y: number;
+    };
+} | {
+    type: "entity_defeated";
+    entityId: number;
+    defeatedBy: number;
+} | {
+    type: "item_collected";
+    itemId: string;
+    quantity: number;
+} | {
+    type: "competence_used";
+    domain: CompetenceDomain;
+    quality_Q: Q;
+    taskId?: string;
+} | {
+    type: "item_delivered";
+    itemId: string;
+    toEntityId: number;
+} | {
+    type: "escort_survived";
+    entityId: number;
+    destinationReached: boolean;
+} | {
+    type: "dialogue_chosen";
+    choiceId: string;
+} | {
+    type: "time_elapsed";
+    seconds: number;
+} | {
+    type: "timeout";
+} | {
+    type: "manual";
+    reason: string;
+};
+/** Per-entity quest log. */
+export interface QuestLog {
+    entityId: number;
+    active: Map<string, Quest>;
+    completed: Map<string, Quest>;
+    failed: Map<string, Quest>;
+}
+/** Global quest registry for the world. */
+export interface QuestRegistry {
+    /** Template quests available to be assigned. */
+    templates: Map<string, Quest>;
+    /** Per-entity quest logs. */
+    logs: Map<number, QuestLog>;
+    /** History of all quest updates (for chronicle/chronology). */
+    history: QuestUpdateEvent[];
+}
+/** Create a new empty quest registry. */
+export declare function createQuestRegistry(): QuestRegistry;
+/** Get or create a quest log for an entity. */
+export declare function getQuestLog(registry: QuestRegistry, entityId: number): QuestLog;
+/** Register a quest template in the registry. */
+export declare function registerQuestTemplate(registry: QuestRegistry, quest: Quest): void;
+/**
+ * Offer a quest to an entity.
+ * Returns false if entity already has this quest (in any state).
+ */
+export declare function offerQuest(registry: QuestRegistry, entityId: number, questTemplateId: string, tick: number): {
+    accepted: false;
+    reason: string;
+} | {
+    accepted: true;
+    quest: Quest;
+};
+/** Abandon an active quest (moves to failed). */
+export declare function abandonQuest(registry: QuestRegistry, entityId: number, questId: string, tick: number): boolean;
+/**
+ * Check if an objective is complete based on its type and progress.
+ */
+export declare function checkObjectiveComplete(objective: QuestObjective): boolean;
+/**
+ * Unlock objectives whose prerequisites are met.
+ */
+export declare function unlockObjectives(quest: Quest, tick: number): QuestObjective[];
+/**
+ * Check if quest is complete (all non-hidden objectives completed).
+ */
+export declare function checkQuestComplete(quest: Quest): boolean;
+/**
+ * Check if any objective has failed.
+ */
+/**
+ * Check if any objective has failed.
+ */
+export declare function checkQuestFailed(quest: Quest): boolean;
+/** Result of processing a quest event. */
+export interface QuestEventResult {
+    updated: boolean;
+    questId?: string;
+    objectiveId?: string;
+    oldState?: ObjectiveState | QuestState;
+    newState?: ObjectiveState | QuestState;
+    questComplete?: boolean;
+    questFailed?: boolean;
+}
+/**
+ * Handle location reached event.
+ */
+export declare function handleLocationReached(quest: Quest, entityId: number, position: {
+    x: number;
+    y: number;
+    z?: number;
+}, tick: number): QuestEventResult;
+/**
+ * Handle entity defeated event (from combat).
+ */
+export declare function handleEntityDefeated(quest: Quest, impact: ImpactEvent, tick: number): QuestEventResult;
+/**
+ * Handle competence use event (from Phase 40).
+ */
+export declare function handleCompetenceUsed(quest: Quest, domain: CompetenceDomain, quality_Q: Q, taskId: string | undefined, tick: number): QuestEventResult;
+/**
+ * Handle item collection.
+ */
+export declare function handleItemCollected(quest: Quest, itemId: string, quantity: number, tick: number): QuestEventResult;
+/**
+ * Handle dialogue choice selection (Phase 23 integration).
+ */
+export declare function handleDialogueChoice(quest: Quest, choiceId: string, tick: number): QuestEventResult;
+/**
+ * Check time limits and update wait_duration objectives.
+ * Call this periodically (e.g., once per second or per tick).
+ */
+export declare function processTimeBasedObjectives(quest: Quest, currentTick: number, tickHz: number): QuestEventResult[];
+/** Get all active quests for an entity. */
+export declare function getActiveQuests(registry: QuestRegistry, entityId: number): Quest[];
+/** Get quest by ID from any category. */
+export declare function getQuest(log: QuestLog, questId: string): {
+    quest: Quest;
+    category: "active" | "completed" | "failed";
+} | undefined;
+/** Get progress summary for a quest. */
+export declare function getQuestProgress(quest: Quest): {
+    total: number;
+    completed: number;
+    failed: number;
+    percentage: number;
+};
+/** Serialize quest registry to JSON-friendly format. */
+export declare function serializeQuestRegistry(registry: QuestRegistry): unknown;
+/** Deserialize quest registry. */
+export declare function deserializeQuestRegistry(data: unknown): QuestRegistry;