playlist-data-engine 1.1.0

package/dist/core/generation/EquipmentGenerator.d.ts

@@ -0,0 +1,204 @@
+/**
+ * EquipmentGenerator - Manages equipment assignment, inventory, and equipped items
+ *
+ * Supports extensibility through ExtensionManager for custom equipment.
+ * All equipment lookups check both default and custom equipment databases.
+ *
+ * Enhanced to support equipment properties, effects, modifications, and D&D 5e stats.
+ */
+import type { Class, CharacterSheet } from '../types/Character.js';
+import type { CharacterEquipment, EnhancedEquipment, EnhancedInventoryItem, EquipmentProperty, EquipmentModification } from '../types/Equipment.js';
+/**
+ * Basic equipment data interface (for backward compatibility)
+ */
+export interface Equipment {
+    name: string;
+    type: 'weapon' | 'armor' | 'item' | 'box';
+    rarity: 'common' | 'uncommon' | 'rare' | 'very_rare' | 'legendary';
+    weight: number;
+}
+/**
+ * Inventory item with quantity (basic version, for backward compatibility)
+ */
+export interface InventoryItem {
+    name: string;
+    quantity: number;
+    equipped: boolean;
+}
+export declare class EquipmentGenerator {
+    /**
+     * Ensure equipment defaults are initialized
+     * Safe to call multiple times
+     */
+    private static ensureInitialized;
+    /**
+     * Get equipment data from extended database (defaults + custom)
+     *
+     * Public static method for external access.
+     *
+     * @param itemName - Name of the equipment to look up
+     * @returns EnhancedEquipment data or undefined if not found
+     */
+    static getEquipmentDataStatic(itemName: string): EnhancedEquipment | undefined;
+    /**
+     * Get equipment data from extended database (defaults + custom)
+     *
+     * @param itemName - Name of the equipment to look up
+     * @returns EnhancedEquipment data or undefined if not found
+     */
+    private static getEquipmentData;
+    /**
+     * Get starting equipment for a class
+     *
+     * Supports custom classes registered via the 'classStartingEquipment.${ClassName}' category in ExtensionManager.
+     *
+     * @param characterClass - The character's class
+     * @returns Object with weapons, armor, and items arrays
+     */
+    static getStartingEquipment(characterClass: Class): {
+        weapons: string[];
+        armor: string[];
+        items: string[];
+    };
+    /**
+     * Initialize complete equipment for a character
+     *
+     * @param characterClass - The character's class
+     * @returns CharacterEquipment with starting gear in inventory
+     */
+    static initializeEquipment(characterClass: Class): CharacterEquipment;
+    /**
+     * Add an item to inventory
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of item to add
+     * @param quantity - Quantity to add (default: 1)
+     * @returns Updated equipment with new item
+     */
+    static addItem(equipment: CharacterEquipment, itemName: string, quantity?: number): CharacterEquipment;
+    /**
+     * Remove an item from inventory
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of item to remove
+     * @param quantity - Quantity to remove (default: 1)
+     * @returns Updated equipment with item removed
+     */
+    static removeItem(equipment: CharacterEquipment, itemName: string, quantity?: number): CharacterEquipment;
+    /**
+     * Equip an item from inventory
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of item to equip
+     * @param character - Optional character to apply equipment effects to
+     * @returns Updated equipment with item equipped
+     */
+    static equipItem(equipment: CharacterEquipment, itemName: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Unequip an item
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of item to unequip
+     * @param character - Optional character to remove equipment effects from
+     * @returns Updated equipment with item unequipped
+     */
+    static unequipItem(equipment: CharacterEquipment, itemName: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Get inventory as flattened list
+     *
+     * @param equipment - Current equipment state
+     * @returns Array of all inventory items
+     */
+    static getInventoryList(equipment: CharacterEquipment): EnhancedInventoryItem[];
+    /**
+     * Get equipment by type
+     *
+     * Utility method to retrieve a specific equipment category (weapons, armor, or items)
+     * from a CharacterEquipment object.
+     *
+     * @param equipment - Current equipment state
+     * @param type - Equipment category to retrieve
+     * @returns Array of inventory items for the specified type
+     */
+    static getEquipmentByType(equipment: CharacterEquipment, type: 'weapons' | 'armor' | 'items'): EnhancedInventoryItem[];
+    /**
+     * Calculate total weight of all equipment
+     *
+     * @param weapons - Weapon inventory
+     * @param armor - Armor inventory
+     * @param items - Item inventory
+     * @returns Total weight in pounds
+     */
+    private static calculateTotalWeight;
+    /**
+     * Calculate weight of equipped items only
+     *
+     * @param weapons - Weapon inventory
+     * @param armor - Armor inventory
+     * @param items - Item inventory
+     * @returns Total equipped weight in pounds
+     */
+    private static calculateEquippedWeight;
+    /**
+     * Create a deep clone of equipment state
+     *
+     * @param equipment - Equipment to clone
+     * @returns Cloned equipment
+     */
+    private static cloneEquipment;
+    /**
+     * Get the type of ammunition a class uses based on their starting weapons
+     *
+     * @param characterClass - The character's class
+     * @param weapons - Array of weapon names the class starts with
+     * @returns Ammunition type ('Arrow', 'Bolt', etc.) or null if not applicable
+     */
+    private static getAmmunitionType;
+    /**
+     * Get the quantity of ammunition a class starts with
+     *
+     * @param characterClass - The character's class
+     * @returns Number of ammunition items
+     */
+    private static getAmmunitionQuantity;
+    /**
+     * Add a modification to an equipment item (per-instance)
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item to modify
+     * @param modification - The modification to apply
+     * @param instanceId - Optional instance ID (for multi-item tracking)
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with modification applied
+     */
+    static addModification(equipment: CharacterEquipment, itemName: string, modification: EquipmentModification, instanceId?: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Remove a modification from an equipment item
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param modificationId - ID of the modification to remove
+     * @param character - Optional character to reapply effects to
+     * @returns Updated equipment with modification removed
+     */
+    static removeModification(equipment: CharacterEquipment, itemName: string, modificationId: string, character?: CharacterSheet): CharacterEquipment;
+    /**
+     * Get all active effects from an equipment item (base + modifications)
+     *
+     * @param equipment - Current equipment state
+     * @param itemName - Name of the item
+     * @param instanceId - Optional instance ID
+     * @returns Array of all active equipment properties
+     */
+    static getActiveEffects(equipment: CharacterEquipment, itemName: string, instanceId?: string): EquipmentProperty[];
+    /**
+     * Apply combined effects from base equipment and modifications
+     *
+     * @param character - Character to apply effects to
+     * @param baseEquipment - Base equipment data
+     * @param modification - Modification to apply
+     * @param instanceId - Instance ID for tracking
+     */
+    private static applyCombinedEffects;
+}
+//# sourceMappingURL=EquipmentGenerator.d.ts.map

package/dist/core/generation/EquipmentGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EquipmentGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/generation/EquipmentGenerator.ts"],"names":[],"mappings":"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"}

package/dist/core/generation/LegendaryGenerator.d.ts

@@ -0,0 +1,213 @@
+/**
+ * LegendaryGenerator - Generates legendary actions and resistances for boss enemies
+ *
+ * Provides legendary action generation with:
+ * - Deterministic seeded generation
+ * - Archetype-appropriate action selection
+ * - Configurable legendary resistances per CR tier
+ */
+import type { EnemyArchetype, EnemyRarity } from '../types/Enemy.js';
+import { SeededRNG } from '../../utils/random.js';
+/**
+ * Legendary action that a boss can perform
+ *
+ * Legendary actions are special abilities that boss enemies can use at the end
+ * of another creature's turn, spending legendary action points (typically 3 per round).
+ */
+export interface LegendaryAction {
+    /** Unique identifier for this action */
+    id: string;
+    /** Display name shown to players */
+    name: string;
+    /** Detailed description of what the action does */
+    description: string;
+    /** Cost in legendary action points (1, 2, or 3) */
+    cost: number;
+    /** Effect description for combat system */
+    effect: string;
+    /** Damage dice if this action deals damage */
+    damage?: string;
+    /** Damage type for damaging actions */
+    damageType?: string;
+    /** Archetypes this action is appropriate for */
+    archetypes: EnemyArchetype[];
+    /** Tags for filtering and categorization */
+    tags?: string[];
+}
+/**
+ * Legendary configuration for a boss enemy
+ *
+ * Contains all legendary-specific data for a boss-tier enemy.
+ */
+export interface LegendaryConfig {
+    /** Number of legendary resistances per day (usually 3) */
+    resistances: number;
+    /** Array of legendary actions available to this boss */
+    actions: LegendaryAction[];
+    /** Optional lair action hint for encounter design */
+    lairActionHint?: string;
+}
+/**
+ * Legendary action pool organized by archetype
+ *
+ * Each archetype has a pool of legendary actions to choose from.
+ * Boss enemies receive 3 legendary actions selected from their archetype pool,
+ * with at least one movement option guaranteed.
+ */
+export declare const LEGENDARY_ACTIONS: Record<EnemyArchetype, LegendaryAction[]>;
+/**
+ * Legendary resistances per CR tier
+ *
+ * Bosses gain a number of legendary resistances per day (typically 3).
+ * Higher CR bosses may have more legendary resistances.
+ */
+export declare const LEGENDARY_RESISTANCES: Record<number, number>;
+/**
+ * Legendary action count per boss tier
+ *
+ * Defines how many legendary actions a boss receives (always 3 for standard bosses).
+ */
+export declare const LEGENDARY_ACTION_COUNT = 3;
+/**
+ * LegendaryGenerator - Static class for legendary action generation
+ *
+ * Generates legendary actions and resistances for boss-tier enemies.
+ * All generation is deterministic based on the provided seed.
+ *
+ * @example
+ * ```typescript
+ * const legendary = LegendaryGenerator.generate({
+ *   archetype: 'brute',
+ *   cr: 8,
+ *   seed: 'dragon-lair-1'
+ * });
+ * // Returns: { resistances: 3, actions: [...], lairActionHint?: string }
+ * ```
+ */
+export declare class LegendaryGenerator {
+    /**
+     * Generate legendary configuration for a boss enemy
+     *
+     * Selects 3 legendary actions for the boss based on archetype,
+     * with at least one movement option guaranteed.
+     *
+     * @param options - Generation options
+     * @returns Legendary configuration with actions and resistances
+     *
+     * @example
+     * ```typescript
+     * const config = LegendaryGenerator.generate({
+     *   archetype: 'brute',
+     *   cr: 8,
+     *   seed: 'boss-1'
+     * });
+     * console.log(config.actions); // 3 legendary actions
+     * console.log(config.resistances); // 3 per day
+     * ```
+     */
+    static generate(options: {
+        archetype: EnemyArchetype;
+        cr: number;
+        seed: string;
+    }): LegendaryConfig;
+    /**
+     * Generate legendary configuration using an existing SeededRNG instance
+     *
+     * Same as generate() but accepts a pre-existing RNG for internal use.
+     *
+     * @param options - Generation options with RNG instance
+     * @returns Legendary configuration
+     */
+    static generateWithRNG(options: {
+        archetype: EnemyArchetype;
+        cr: number;
+        rng: SeededRNG;
+    }): LegendaryConfig;
+    /**
+     * Select legendary actions from the available pool
+     *
+     * Selects exactly 3 legendary actions with the following rules:
+     * - At least one movement option (tags include 'movement')
+     * - Actions are selected without replacement
+     * - Uses weighted selection favoring variety
+     *
+     * @param availableActions - Pool of actions to select from
+     * @param rng - Seeded RNG for deterministic selection
+     * @returns Array of 3 legendary actions
+     */
+    private static selectLegendaryActions;
+    /**
+     * Get legendary resistances for a given CR
+     *
+     * Returns the number of legendary resistances per day based on CR.
+     * Uses the closest CR tier (rounds up for in-between values).
+     *
+     * @param cr - Challenge rating
+     * @returns Number of legendary resistances per day
+     *
+     * @example
+     * ```typescript
+     * LegendaryGenerator.getResistancesForCR(5); // 3
+     * LegendaryGenerator.getResistancesForCR(12); // 4
+     * LegendaryGenerator.getResistancesForCR(20); // 5
+     * ```
+     */
+    static getResistancesForCR(cr: number): number;
+    /**
+     * Generate a lair action hint for encounter design
+     *
+     * Creates a brief description of what lair actions this boss
+     * might have, for use by game masters when designing encounters.
+     *
+     * @param archetype - Boss archetype for thematic hints
+     * @param rng - Seeded RNG
+     * @returns Lair action hint string
+     */
+    private static generateLairActionHint;
+    /**
+     * Get legendary action by ID
+     *
+     * Searches all action pools for a matching ID.
+     *
+     * @param id - Action ID to find
+     * @returns Legendary action if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const action = LegendaryGenerator.getActionById('teleport');
+     * console.log(action?.name); // 'Teleport'
+     * ```
+     */
+    static getActionById(id: string): LegendaryAction | undefined;
+    /**
+     * Get all legendary actions for an archetype
+     *
+     * Returns archetype-specific actions plus universal actions.
+     *
+     * @param archetype - Enemy archetype
+     * @returns Array of legendary actions
+     *
+     * @example
+     * ```typescript
+     * const actions = LegendaryGenerator.getActionsForArchetype('brute');
+     * // Returns: [...bruteActions, ...universalActions]
+     * ```
+     */
+    static getActionsForArchetype(archetype: EnemyArchetype): LegendaryAction[];
+    /**
+     * Check if a rarity tier should have legendary actions
+     *
+     * Only boss rarity receives legendary actions.
+     *
+     * @param rarity - Enemy rarity tier
+     * @returns True if rarity should have legendary actions
+     *
+     * @example
+     * ```typescript
+     * LegendaryGenerator.shouldHaveLegendary('boss'); // true
+     * LegendaryGenerator.shouldHaveLegendary('elite'); // false
+     * ```
+     */
+    static shouldHaveLegendary(rarity: EnemyRarity): boolean;
+}
+//# sourceMappingURL=LegendaryGenerator.d.ts.map

package/dist/core/generation/LegendaryGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LegendaryGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/generation/LegendaryGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IAEX,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IAEpB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IAEb,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gDAAgD;IAChD,UAAU,EAAE,cAAc,EAAE,CAAC;IAE7B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IAEpB,wDAAwD;IACxD,OAAO,EAAE,eAAe,EAAE,CAAC;IAE3B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,cAAc,EAAE,eAAe,EAAE,CA0MvE,CAAC;AA4BF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2BxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAkB;IAC3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE;QACrB,SAAS,EAAE,cAAc,CAAC;QAC1B,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;KAChB,GAAG,eAAe;IA+BnB;;;;;;;OAOG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE;QAC5B,SAAS,EAAE,cAAc,CAAC;QAC1B,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,EAAE,SAAS,CAAC;KAClB,GAAG,eAAe;IA4BnB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAuCrC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAgB9C;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAiCrC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAW7D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,sBAAsB,CAAC,SAAS,EAAE,cAAc,GAAG,eAAe,EAAE;IAK3E;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;CAG3D"}