playlist-data-engine 1.1.0

package/dist/core/types/Enemy.d.ts

@@ -0,0 +1,447 @@
+/**
+ * Enemy Generation Type Definitions
+ *
+ * Defines types and interfaces for the enemy generation system.
+ * Enemies are generated as CharacterSheet instances with enemy-specific
+ * traits and abilities, supporting multiple rarity tiers and audio-influenced generation.
+ */
+import type { AudioProfile } from './AudioProfile.js';
+import type { AbilityScores, Attack } from './Character.js';
+import type { DamageType } from './Combat.js';
+import type { PlaylistTrack } from './Playlist.js';
+/**
+ * Enemy categories for classification and filtering
+ */
+export type EnemyCategory = 'humanoid' | 'beast' | 'undead' | 'dragon' | 'fiend' | 'construct' | 'elemental' | 'monstrosity';
+/**
+ * Rarity tiers that determine enemy power scaling
+ *
+ * Each rarity increases stats, scales signature ability dice, and adds extra abilities
+ */
+export type EnemyRarity = 'common' | 'uncommon' | 'elite' | 'boss';
+/**
+ * Combat archetypes that define enemy role in battle
+ */
+export type EnemyArchetype = 'brute' | 'archer' | 'support';
+/**
+ * Enemy mix modes for encounter generation
+ */
+export type EnemyMixMode = 'uniform' | 'custom' | 'category' | 'random';
+/**
+ * Difficulty settings for party-based encounters
+ *
+ * Maps to D&D 5e encounter difficulty thresholds
+ */
+export type EncounterDifficulty = 'easy' | 'medium' | 'hard' | 'deadly';
+/**
+ * Signature ability - The unique ability shared across all rarities of an enemy type
+ *
+ * The damageDie scales by rarity: d6 (common) -> d8 (uncommon) -> d10 (elite) -> d12 (boss)
+ */
+export interface SignatureAbility {
+    /** Unique identifier for this ability */
+    id: string;
+    /** Display name shown to players */
+    name: string;
+    /** Detailed description of what the ability does */
+    description: string;
+    /** Base damage die (scales by rarity: d6 -> d8 -> d10 -> d12) */
+    damageDie: string;
+    /** Type of damage dealt */
+    damageType: DamageType;
+    /** Attack type (melee, ranged, spell) */
+    attackType: 'melee' | 'ranged' | 'spell';
+    /** Range in feet (for ranged attacks) */
+    range?: number;
+    /** Any special properties (e.g., 'versatile', 'finesse') */
+    properties?: string[];
+}
+/**
+ * Audio preference weights for template selection
+ *
+ * Determines which templates are more likely to be selected
+ * based on audio profile characteristics
+ */
+export interface AudioPreference {
+    /** Weight for bass-heavy audio (0.0 - 1.0) */
+    bass: number;
+    /** Weight for mid-range audio (0.0 - 1.0) */
+    mid: number;
+    /** Weight for treble-heavy audio (0.0 - 1.0) */
+    treble: number;
+}
+/**
+ * Enemy template - Base definition for an enemy type
+ *
+ * Templates define the foundation of an enemy that is then scaled
+ * by rarity tier and modified by audio profile
+ */
+export interface EnemyTemplate {
+    /** Unique identifier (e.g., 'orc', 'goblin-archer', 'giant-spider') */
+    id: string;
+    /** Display name (used as enemy name when generated) */
+    name: string;
+    /** Category for classification and filtering */
+    category: EnemyCategory;
+    /** Combat role archetype */
+    archetype: EnemyArchetype;
+    /** Signature ability shared across all rarities */
+    signatureAbility: SignatureAbility;
+    /** Base ability scores before rarity scaling */
+    baseStats: AbilityScores;
+    /** Base hit points before rarity scaling */
+    baseHP: number;
+    /** Base armor class before DEX modifier */
+    baseAC: number;
+    /** Base speed in feet */
+    baseSpeed: number;
+    /** Audio preference weights for template selection */
+    audioPreference: AudioPreference;
+    /** Damage resistances/immunities for Elite+ rarity scaling */
+    resistances?: {
+        /** Damage types resisted (half damage) */
+        resistances?: DamageType[];
+        /** Damage types immune (zero damage) */
+        immunities?: DamageType[];
+    };
+    /** Optional icon URL for small UI display */
+    icon?: string;
+    /** Optional image URL for larger display */
+    image?: string;
+}
+/**
+ * Rarity configuration - Scaling factors per rarity tier
+ *
+ * Defines how enemies scale across rarity tiers
+ */
+export interface RarityConfig {
+    /** Multiplier applied to base ability scores */
+    statMultiplier: number;
+    /** Multiplier applied to HP on top of stat scaling (separate for dramatic HP differences) */
+    hpMultiplier: number;
+    /** Die size for signature ability (6 = d6, 8 = d8, etc.) */
+    signatureDieSize: number;
+    /** Number of extra abilities from FeatureQuery pool */
+    extraAbilityCount: number;
+    /** Whether this rarity gains resistances from template */
+    hasResistances: boolean;
+}
+/**
+ * Options for generating a single enemy
+ *
+ * All generation is deterministic based on the provided seed
+ *
+ * ## CR vs Rarity Distinction
+ *
+ * **CR (Challenge Rating)** and **Rarity** are two INDEPENDENT axes:
+ *
+ * | Property | Determines | Examples |
+ * |----------|------------|----------|
+ * | **CR** | Power level (stats, HP, level, proficiency) | Weak beast vs. ancient dragon |
+ * | **Rarity** | Complexity (abilities, resistances, legendary actions) | Simple guard vs. complex spellcaster |
+ *
+ * **Any CR can combine with any rarity:**
+ * - CR 0.25 + Boss = Goblin chieftain (weak but complex)
+ * - CR 20 + Common = Ancient beast (powerful but simple)
+ *
+ * **CR is the primary power-scaling parameter.** Always provide `cr` for predictable enemy power.
+ * If omitted, CR is derived from rarity (deprecated behavior for backward compatibility).
+ */
+export interface EnemyGenerationOptions {
+    /** Required - Seed for deterministic generation */
+    seed: string;
+    /**
+     * Challenge Rating for power scaling.
+     *
+     * **RECOMMENDED** - Always provide CR for predictable power scaling.
+     * Determines level, HP, and base stats. Fractional CRs (0.25, 0.5) create sub-level enemies
+     * with reduced stats (75%/85% respectively).
+     *
+     * If omitted, falls back to rarity-based CR (deprecated for backward compatibility).
+     *
+     * @example
+     * ```typescript
+     * // Generate a CR 5 elite enemy
+     * EnemyGenerator.generate({ seed: 'test', cr: 5, rarity: 'elite' });
+     *
+     * // Generate a weak but complex boss (CR 0.25 + boss)
+     * EnemyGenerator.generate({ seed: 'test', cr: 0.25, rarity: 'boss' });
+     * ```
+     */
+    cr?: number;
+    /**
+     * Optional level override. If provided, overrides CR-based level calculation.
+     * Default: derived from CR via CRLevelConverter (CR ≈ level in D&D 5e)
+     */
+    level?: number;
+    /** Optional - Force specific template by ID */
+    templateId?: string;
+    /**
+     * Rarity tier for complexity scaling.
+     * Affects ability count, resistances, and legendary actions - NOT power level.
+     * @default 'common'
+     */
+    rarity?: EnemyRarity;
+    /** Optional - Difficulty multiplier (default: 1.0) */
+    difficultyMultiplier?: number;
+    /** Optional - Audio profile for stat influence */
+    audioProfile?: AudioProfile;
+    /** Optional - Track data (required if audioProfile provided) */
+    track?: PlaylistTrack;
+    /**
+     * Optional - Override effective levels for HP, attack, and defense independently
+     *
+     * Allows each stat axis to scale at a different effective level than the CR-derived level.
+     * When not set, all stats use the CR-derived level (identical to current generation).
+     *
+     * @see StatLevelOverrides
+     * @example
+     * ```typescript
+     * // Glass cannon: high attack, low HP and defense
+     * EnemyGenerator.generate({
+     *   seed: 'glass-cannon',
+     *   cr: 5,
+     *   rarity: 'elite',
+     *   statLevels: { attackLevel: 15, hpLevel: 1, defenseLevel: 1 }
+     * });
+     * ```
+     */
+    statLevels?: StatLevelOverrides;
+    /** Optional - Enemy category for template selection */
+    category?: EnemyCategory;
+    /** Optional - Combat archetype for template selection */
+    archetype?: EnemyArchetype;
+}
+/**
+ * Options for generating an encounter (group of enemies)
+ *
+ * Supports two generation modes:
+ * 1. Party-based: Analyze party strength for balanced encounter
+ * 2. CR-based: Generate enemies matching target CR directly
+ *
+ * CR vs Rarity Distinction:
+ * - **CR (Challenge Rating)**: Determines power level (stats, HP, level, proficiency)
+ * - **Rarity**: Determines complexity (abilities, resistances, legendary actions)
+ *
+ * By default, rarity is **independent of CR**. Set `scaleRarityWithCR: true` to enable
+ * automatic rarity scaling based on CR tier (opt-in feature).
+ */
+export interface EncounterGenerationOptions {
+    /** Required - Seed for deterministic generation */
+    seed: string;
+    /** Required - Number of enemies to generate */
+    count: number;
+    /** Optional - Difficulty for party-based encounters (default: 'medium') */
+    difficulty?: EncounterDifficulty;
+    /** Optional - Target CR for CR-based generation (no party needed) */
+    targetCR?: number;
+    /**
+     * Optional - Base rarity for all enemies (default: 'common')
+     *
+     * Rarity is independent of CR by default. Use `scaleRarityWithCR: true` to enable
+     * automatic rarity scaling based on CR tier.
+     */
+    baseRarity?: EnemyRarity;
+    /**
+     * Optional - Enable automatic rarity scaling based on CR (default: false)
+     *
+     * When enabled, rarities scale gradually with CR:
+     * - CR 0-2: all common
+     * - CR 3-5: one uncommon upgrade per party
+     * - CR 6-10: two uncommon upgrades
+     * - CR 11-15: three uncommon upgrades
+     * - CR 16-20: one elite + uncommon upgrades
+     * - CR 21-30: two elite + uncommon upgrades
+     * - CR 31+: all elite
+     *
+     * When disabled (default), uses explicit `baseRarity` for all enemies.
+     */
+    scaleRarityWithCR?: boolean;
+    /** Optional - Fine-tune difficulty multiplier (default: 1.0) */
+    difficultyMultiplier?: number;
+    /** Optional - Filter by category */
+    category?: EnemyCategory;
+    /** Optional - Filter by archetype */
+    archetype?: EnemyArchetype;
+    /** Optional - Force specific template for all enemies */
+    templateId?: string;
+    /** Optional - Enemy mix mode (default: 'uniform') */
+    enemyMix?: EnemyMixMode;
+    /** Optional - Template IDs for 'custom' mix mode */
+    templates?: string[];
+    /** Optional - Audio profile for template selection and stat influence */
+    audioProfile?: AudioProfile;
+    /** Optional - Track data (required if audioProfile provided) */
+    track?: PlaylistTrack;
+    /** Optional - Enable leader promotion for groups > 3 (default: true) */
+    enableLeaderPromotion?: boolean;
+    /** Optional - Allow mixing enemy categories in 'random' mode (default: false) */
+    allowMixedCategories?: boolean;
+    /** Optional - Include lair actions for boss enemies (default: false) */
+    lairFeatures?: boolean;
+    /** Optional - Force minimum rarity for all enemies */
+    minRarity?: EnemyRarity;
+    /** Optional - Cap maximum rarity for all enemies */
+    maxRarity?: EnemyRarity;
+    /** Optional - Override effective levels for HP, attack, and defense independently */
+    statLevels?: StatLevelOverrides;
+}
+/**
+ * Generated enemy metadata
+ *
+ * Tracks information about how an enemy was generated
+ */
+export interface EnemyMetadata {
+    /** Template ID used for generation */
+    templateId: string;
+    /** Rarity tier of this enemy */
+    rarity: EnemyRarity;
+    /** Seed used for generation */
+    seed: string;
+    /** Whether leader promotion was applied */
+    isLeader?: boolean;
+    /** Audio profile used (if any) */
+    audioProfile?: AudioProfile;
+}
+/**
+ * Feature type for enemy abilities
+ *
+ * Reuses ClassFeature structure but simplified for enemy use
+ * Enemies don't have classes, so features are standalone abilities
+ */
+export interface EnemyFeature {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description of ability */
+    description: string;
+    /** Type: passive, active, resource, trigger */
+    type: 'passive' | 'active' | 'resource' | 'trigger';
+    /** Attack data if this is an attack ability */
+    attack?: Attack;
+    /** Tags for filtering (e.g., ['melee', 'damage', 'control']) */
+    tags?: string[];
+    /** Rarity level this feature appears at */
+    minRarity?: EnemyRarity;
+}
+/**
+ * Type guard to check if a value is a valid EnemyCategory
+ */
+export declare function isValidEnemyCategory(value: unknown): value is EnemyCategory;
+/**
+ * Type guard to check if a value is a valid EnemyRarity
+ */
+export declare function isValidEnemyRarity(value: unknown): value is EnemyRarity;
+/**
+ * Type guard to check if a value is a valid EnemyArchetype
+ */
+export declare function isValidEnemyArchetype(value: unknown): value is EnemyArchetype;
+/**
+ * Stat Level Overrides — Allow HP, attack, and defense to scale independently
+ *
+ * Normally all enemy stats scale together as a unit determined by CR + rarity.
+ * StatLevelOverrides allows each axis to be independently set to a different
+ * effective level, enabling creative encounter designs:
+ * - **Tank**: high HP level, normal attack, high defense
+ * - **Glass cannon**: low HP, high attack, low defense
+ * - **Brute**: high HP, high attack, low defense
+ * - **Standard**: all at CR level (default, no overrides needed)
+ *
+ * When all three levels match CR, output is identical to current generation
+ * (backward compatible). The AI and simulator don't need to know about this —
+ * they read the final CharacterSheet stats. This is purely a generation-layer
+ * feature.
+ */
+export interface StatLevelOverrides {
+    /** Override HP to this effective level (default: CR-derived level) */
+    hpLevel?: number;
+    /** Override attack scaling to this effective level (damage die + modifier + attack bonus) */
+    attackLevel?: number;
+    /** Override defense scaling to this effective level (AC) */
+    defenseLevel?: number;
+}
+/**
+ * Equipment template for enemy generation
+ *
+ * Defines equipment options for enemies based on archetype and rarity.
+ * Used by EquipmentGenerator to select appropriate weapons/armor for enemies.
+ */
+export interface EquipmentTemplate {
+    /** Unique identifier for this equipment template */
+    id: string;
+    /** Display name of the equipment */
+    name: string;
+    /** Equipment type: weapon, armor, or shield */
+    type: 'weapon' | 'armor' | 'shield';
+    /** Archetypes that can use this equipment */
+    archetypes: EnemyArchetype[];
+    /** Rarity tiers that can spawn this equipment */
+    rarities: EnemyRarity[];
+    /** Damage dice (for weapons) */
+    damage?: string;
+    /** AC bonus (for armor/shields) */
+    acBonus?: number;
+    /** Weapon properties (e.g., ['reach', 'two-handed']) */
+    properties?: string[];
+}
+/**
+ * Equipment configuration for generated enemies
+ *
+ * Contains the equipment assigned to an enemy during generation.
+ */
+export interface EquipmentConfig {
+    /** Primary weapon (if any) */
+    weapon?: EquipmentTemplate;
+    /** Armor (if any) */
+    armor?: EquipmentTemplate;
+    /** Shield (if any) */
+    shield?: EquipmentTemplate;
+}
+/**
+ * Type guard to check if a value is a valid EncounterDifficulty
+ */
+export declare function isValidEncounterDifficulty(value: unknown): value is EncounterDifficulty;
+/**
+ * Legendary action for boss enemies
+ *
+ * Legendary actions are special abilities that boss enemies can use at the end
+ * of another creature's turn, spending legendary action points.
+ */
+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 boss-tier enemies
+ *
+ * Contains all legendary-specific data for a boss enemy,
+ * including legendary resistances per day and available legendary actions.
+ */
+export interface LegendaryConfig {
+    /** Number of legendary resistances per day */
+    resistances: number;
+    /** Legendary actions available to this boss */
+    actions: LegendaryAction[];
+    /** Optional lair action hint for encounter design */
+    lairActionHint?: string;
+}
+export type { LegendaryAction as LegendaryActionFromGenerator, LegendaryConfig as LegendaryConfigFromGenerator } from '../generation/LegendaryGenerator.js';
+export type { InnateSpell, SpellcastingConfig } from '../generation/SpellcastingGenerator.js';
+//# sourceMappingURL=Enemy.d.ts.map

package/dist/core/types/Enemy.d.ts.map

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

package/dist/core/types/Environmental.d.ts

@@ -0,0 +1,213 @@
+export type SensorType = 'geolocation' | 'motion' | 'weather';
+/**
+ * Performance metrics for API calls
+ */
+export interface PerformanceMetrics {
+    /** Number of successful API calls */
+    successCount: number;
+    /** Number of failed API calls */
+    errorCount: number;
+    /** Total time spent on successful API calls (milliseconds) */
+    totalTime: number;
+    /** Time of the fastest API call (milliseconds) */
+    minTime: number;
+    /** Time of the slowest API call (milliseconds) */
+    maxTime: number;
+    /** Timestamp of the last API call */
+    lastCallTimestamp: number | null;
+}
+/**
+ * Detailed performance statistics derived from metrics
+ */
+export interface PerformanceStatistics {
+    /** Average API call time in milliseconds */
+    average: number;
+    /** Minimum API call time in milliseconds */
+    min: number;
+    /** Maximum API call time in milliseconds */
+    max: number;
+    /** Total number of API calls */
+    totalCalls: number;
+    /** Success rate as percentage (0-100) */
+    successRate: number;
+}
+export interface SensorPermission {
+    type: SensorType;
+    granted: boolean;
+    timestamp: number;
+}
+/**
+ * Health status of a sensor
+ */
+export type SensorHealthStatus = 'healthy' | 'degraded' | 'failed' | 'unknown';
+/**
+ * Status information for a single sensor
+ */
+export interface SensorStatus {
+    type: SensorType;
+    health: SensorHealthStatus;
+    lastSuccessTimestamp: number | null;
+    lastFailureTimestamp: number | null;
+    consecutiveFailures: number;
+    totalFailures: number;
+    lastError: string | null;
+    isRetrying: boolean;
+}
+/**
+ * Log entry for a sensor failure event
+ */
+export interface SensorFailureLog {
+    sensorType: SensorType;
+    timestamp: number;
+    error: string;
+    retryAttempt: number;
+    willRetry: boolean;
+}
+/**
+ * Configuration for sensor retry behavior
+ */
+export interface SensorRetryConfig {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+}
+/**
+ * Notification callback for sensor recovery events
+ */
+export interface SensorRecoveryNotification {
+    sensorType: SensorType;
+    previousStatus: SensorHealthStatus;
+    newStatus: SensorHealthStatus;
+    timestamp: number;
+    message: string;
+}
+export interface GeolocationData {
+    latitude: number;
+    longitude: number;
+    altitude: number | null;
+    accuracy: number;
+    heading: number | null;
+    speed: number | null;
+    timestamp: number;
+}
+export interface MotionData {
+    acceleration: {
+        x: number | null;
+        y: number | null;
+        z: number | null;
+    };
+    accelerationIncludingGravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationRate: {
+        alpha: number | null;
+        beta: number | null;
+        gamma: number | null;
+    };
+    interval: number;
+    timestamp: number;
+}
+export interface WeatherData {
+    temperature: number;
+    humidity: number;
+    pressure: number;
+    weatherType: string;
+    windSpeed: number;
+    windDirection: number;
+    isNight: boolean;
+    moonPhase: number;
+    timestamp: number;
+}
+export interface ForecastData {
+    temperature: number;
+    humidity: number;
+    pressure: number;
+    weatherType: string;
+    windSpeed: number;
+    windDirection: number;
+    timestamp: number;
+    forecastTime: Date;
+    probabilityOfPrecipitation: number;
+}
+/**
+ * Day stage categories based on sun position
+ */
+export type DayStage = 'night' | 'dawn' | 'day' | 'dusk';
+/**
+ * Twilight type definitions (based on sun angle below horizon)
+ * - civil: Sun 6° below horizon (brightest stars visible)
+ * - nautical: Sun 12° below horizon (horizon visible at sea)
+ * - astronomical: Sun 18° below horizon (full darkness)
+ */
+export type TwilightType = 'astronomical' | 'nautical' | 'civil';
+/**
+ * Solar information including sunrise, sunset, and day stage.
+ * Works without API key using astronomical calculations.
+ */
+export interface SolarInfo {
+    /** Current time */
+    currentTime: Date;
+    /** Current day stage */
+    stage: DayStage;
+    /** Sunrise time (when sun first appears above horizon) */
+    sunrise: Date;
+    /** Sunset time (when sun last appears above horizon) */
+    sunset: Date;
+    /** Solar noon (when sun is at highest point) */
+    solarNoon: Date;
+    /** Civil dawn time (sun 6° below horizon, approaching sunrise) */
+    civilDawn?: Date;
+    /** Civil dusk time (sun 6° below horizon, after sunset) */
+    civilDusk?: Date;
+    /** Current sun altitude in degrees (negative = below horizon) */
+    sunAltitude: number;
+    /** Current sun azimuth in degrees (0-360, North = 0) */
+    sunAzimuth: number;
+    /** Day length in hours */
+    dayLengthHours: number;
+    /** Whether data came from API (true) or calculated astronomically (false) */
+    fromApi: boolean;
+    /** Timestamp when this data was generated */
+    timestamp: number;
+}
+export type BiomeType = 'urban' | 'forest' | 'desert' | 'mountain' | 'valley' | 'water' | 'tundra' | 'plains' | 'jungle' | 'swamp' | 'taiga' | 'savanna';
+export interface EnvironmentalContext {
+    geolocation?: GeolocationData;
+    motion?: MotionData;
+    weather?: WeatherData;
+    biome?: BiomeType;
+    timestamp: number;
+    environmental_xp_modifier?: number;
+}
+/**
+ * A single source of XP bonus
+ */
+export interface XPBonusSource {
+    /** Unique identifier for this bonus type */
+    id: string;
+    /** Human-readable label for display */
+    label: string;
+    /** Emoji icon for UI display */
+    icon: string;
+    /** The bonus multiplier value (e.g., 0.25 for +25%) */
+    bonus: number;
+    /** Whether this bonus is currently active */
+    active: boolean;
+}
+/**
+ * Detailed breakdown of the XP modifier calculation
+ */
+export interface XpModifierBreakdown {
+    /** Final computed modifier (1.0 - 3.0) */
+    total: number;
+    /** Base value, always 1.0 */
+    baseValue: number;
+    /** All possible bonus sources with their active state */
+    sources: XPBonusSource[];
+    /** Only the currently active bonuses (convenience) */
+    activeBonuses: XPBonusSource[];
+}
+//# sourceMappingURL=Environmental.d.ts.map

package/dist/core/types/Environmental.d.ts.map

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