afnm-types 0.6.11 → 0.6.16

package/dist/GameScreen.d.ts

@@ -1 +1 @@
-export type GameScreen = 'location' | 'recipe' | 'mission' | 'craftingHall' | 'manual' | 'cultivation' | 'map' | 'healer' | 'market' | 'favour' | 'herbField' | 'mine' | 'recipeLibrary' | 'requestBoard' | 'compendium' | 'library' | 'altar' | 'research' | 'pillarGrid' | 'fallenStar';
+export type GameScreen = 'location' | 'recipe' | 'mission' | 'craftingHall' | 'manual' | 'cultivation' | 'map' | 'healer' | 'market' | 'favour' | 'herbField' | 'mine' | 'recipeLibrary' | 'requestBoard' | 'compendium' | 'library' | 'altar' | 'research' | 'pillarGrid' | 'fallenStar' | 'trainingGround';

package/dist/buff.d.ts

@@ -30,6 +30,7 @@ export interface Buff {
     canStack: boolean;
     effectHint?: string;
     tooltip?: string;
+    additionalTooltip?: string;
     flag?: string;
     condition?: TechniqueCondition;
     removeOnConditionFailed?: boolean;

package/dist/character.d.ts

@@ -18,6 +18,11 @@ export interface Character {
     portrait: string;
     image: string;
     imageScale?: number;
+    imageOverride?: {
+        image: string;
+        portrait: string;
+        condition: string;
+    }[];
 }
 export declare const characterRelationships: readonly ["Hostile", "Neutral", "Friendly", "Intimate"];
 export type CharacterRelationship = (typeof characterRelationships)[number];

package/dist/entity.d.ts

@@ -41,6 +41,8 @@ export interface PlayerEntity {
     storedCraftingLoadouts?: StoredCraftingLoadout[];
     craftingQuickAccess?: (string | undefined)[];
     craftingTechniques: KnownCraftingTechnique[];
+    currentEquipmentLoadout?: StoredEquipmentLoadout;
+    storedEquipmentLoadouts?: StoredEquipmentLoadout[];
     destiny: string[];
     monthBuffs?: Buff[];
     injured?: boolean;
@@ -212,4 +214,17 @@ export interface StoredCraftingLoadout {
     autoName?: boolean;
     loadout: string[];
 }
+export interface StoredEquipmentLoadout {
+    name: string;
+    id: string;
+    autoName?: boolean;
+    equipment: {
+        clothing?: ItemDesc;
+        talismans: (ItemDesc | undefined)[];
+        artefacts: (ItemDesc | undefined)[];
+        mount?: ItemDesc;
+        cauldron?: ItemDesc;
+        flame?: ItemDesc;
+    };
+}
 export {};

package/dist/guild.d.ts

@@ -3,6 +3,10 @@ import { OverridableComponent } from '@mui/material/OverridableComponent';
 import { EventStep } from './event';
 import { ShopItem } from './location';
 import { ScreenEffectType } from './ScreenEffectType';
+export interface GuildMission {
+    quest: string;
+    condition: string;
+}
 export interface Guild {
     name: string;
     description: string;
@@ -12,7 +16,7 @@ export interface Guild {
     screenEffect: ScreenEffectType;
     ranks: Record<number, string>;
     rankShop: Record<number, ShopItem[]>;
-    rankQuests: Record<number, string[]>;
+    rankQuests: Record<number, GuildMission[]>;
     reputationToPromote: Record<number, number>;
     promotionQuests: Record<number, {
         title: string;

package/dist/house.d.ts

@@ -14,7 +14,7 @@ export interface House {
     transportSeal: TransportSealItem;
     qiDensity: number;
     fixedRooms: Room[];
-    freeRooms: number;
+    freeRooms: string;
 }
 export interface HouseData {
     densityFormation: ItemDesc | undefined;

package/dist/item.d.ts

@@ -168,6 +168,7 @@ export interface CombatItem extends ItemBase {
     kind: 'consumable';
     effects: TechniqueEffect[];
     tooltip?: string;
+    affinity?: TechniqueElement;
 }
 export interface ConsumablePillItem extends BasePillItem {
     pillKind: 'consumable';

package/dist/mod.d.ts

@@ -15,7 +15,7 @@ import { AuctionStep, CombatStep, CraftingStep, DualCultivationStep, EventStep,
 import { Guild } from './guild';
 import { Crop } from './herbField';
 import { Enchantment, Item, ItemDesc, RecipeItem, UncutStonePool } from './item';
-import { ConditionalLink, ExplorationLink, GameLocation, LocationEnemy, LocationEvent } from './location';
+import { ConditionalLink, ExplorationLink, GameLocation, LocationBuilding, LocationEnemy, LocationEvent, LocationMapEvent, SectMission, CraftingMission } from './location';
 import { Manual } from './manual';
 import { MineChamber } from './mine';
 import { Quest } from './quest';
@@ -33,6 +33,7 @@ import { SoundEffectName } from './audio';
 import { ScreenEffectType } from './ScreenEffectType';
 import { RootState } from './reduxState';
 import { GameButtonFC, GameDialogFC, GameIconButtonFC, MemoBackgroundImageFC } from './components';
+import { PuppetType } from './trainingGround';
 export interface ModMetadata {
     name: string;
     version: string;
@@ -42,30 +43,184 @@ export interface ModMetadata {
     };
 }
 export interface ModReduxAPI {
+    /**
+     * Hook to access the Redux store state. Works like React Redux's useSelector.
+     * @param selector - Function that extracts data from the RootState
+     * @returns The selected data from the store
+     * @example
+     * const playerRealm = useSelector((state) => state.player.realm);
+     * const inventory = useSelector((state) => state.inventory.items);
+     */
     useSelector: <TSelected>(selector: (state: RootState) => TSelected) => TSelected;
+    /**
+     * Hook to access game flags used for tracking quest progress and game state.
+     * @returns Object containing flags map and serialized JSON representation
+     * @example
+     * const { flags, flagsJSON } = useGameFlags();
+     * const questProgress = flags['main_quest_stage'] || 0;
+     */
     useGameFlags: () => {
         flags: Record<string, number>;
         flagsJSON: string;
     };
+    /**
+     * Hook to get a function for playing sound effects.
+     * @returns Function that plays a sound effect by name
+     * @example
+     * const playSfx = usePlaySfx();
+     * playSfx('Select');
+     */
     usePlaySfx: () => (name: SoundEffectName) => void;
+    /**
+     * Hook to register keyboard shortcuts
+     * @param priority - Higher numbers take precedence (0-100 typical)
+     * @param binding - Map of key names to callback functions
+     * @param disableSpaceOverride - If true, spacebar won't be overridden to map to Enter
+     * @example
+     * useKeybinding(10, {
+     *   'Escape': () => closeDialog(),
+     *   'Enter': () => confirmAction(),
+     *   'i': () => openInventory()
+     * });
+     */
     useKeybinding: (priority: number, binding: Record<string, () => void> | undefined, disableSpaceOverride?: boolean) => void;
     actions: {
+        /**
+         * Navigate to a different game screen.
+         * @param screen - Screen identifier (e.g., 'location', 'market', 'auction')
+         * @example
+         * setScreen('my_mod_custom_screen');
+         */
         setScreen: (screen: string) => void;
+        /**
+         * Set or update a game flag value.
+         * @param flag - Flag identifier (e.g., 'quest_started', 'boss_defeated')
+         * @param value - Numeric value to set (typically 0/1 for booleans, or progress counters)
+         * @example
+         * setFlag('tutorial_complete', 1);
+         * setFlag('quest_stage', 3);
+         */
         setFlag: (flag: string, value: number) => void;
+        /**
+         * Store custom mod-specific data in save file.
+         * @param modName - Name of your mod (for namespacing)
+         * @param key - Data key identifier
+         * @param data - Any JSON-serializable data
+         * @example
+         * setModData('myMod', 'customNPC_affinity', { npcId: 'elder_li', value: 75 });
+         */
         setModData: (modName: string, key: string, data: any) => void;
+        /**
+         * Move player to a different location on the world map.
+         * @param location - Location key from the locations data
+         * @example
+         * setLocation('Liang Tiao Village');
+         * setLocation('Shen Henda City');
+         */
         setLocation: (location: string) => void;
+        /**
+         * Update player entity stats and attributes.
+         * @param player - Player entity with properties to update
+         * @example
+         * updatePlayer(newPlayer);
+         */
         updatePlayer: (player: PlayerEntity) => void;
+        /**
+         * Advance the game calendar by specified days.
+         * @param days - Number of days to advance
+         * @example
+         * advanceDays(7); // Skip one week
+         * advanceDays(30); // Skip one month
+         */
         advanceDays: (days: number) => void;
+        /**
+         * Add a quest to the player's quest log.
+         * @param quest - Quest identifier key
+         * @example
+         * addQuest('Burning Bridges');
+         * addQuest('Shadow Cloak');
+         */
         addQuest: (quest: string) => void;
+        /**
+         * Add an item to player inventory.
+         * @param item - Item descriptor with name and optional properties
+         * @example
+         * addItem({ name: 'Spirit Core (III)', count: 10 });
+         * addItem({ name: 'Nine Mountain Hammer', count: 1, quality: 5 });
+         */
         addItem: (item: ItemDesc) => void;
+        /**
+         * Remove items from player inventory.
+         * @param itemName - Name of the item to remove
+         * @param count - Number of items to remove
+         * @example
+         * removeItem('Spirit Core (I)', 5);
+         * removeItem('Healing Pill (III)', 1);
+         */
         removeItem: (itemName: string, count: number) => void;
+        /**
+         * Teach the player a crafting recipe.
+         * @param item - Item name that the recipe produces
+         * @example
+         * learnRecipe('Healing Pill (III) Recipe');
+         */
         learnRecipe: (item: string) => void;
+        /**
+         * Teach the player a combat technique.
+         * @param technique - Technique identifier key
+         * @example
+         * learnTechnique('Gale Blast');
+         * learnTechnique('Advancing Fist');
+         */
         learnTechnique: (technique: string) => void;
+        /**
+         * Teach the player a crafting action/technique.
+         * @param action - Crafting action identifier
+         * @example
+         * learnCraftingAction('Toxic Fusion');
+         * learnCraftingAction('Gentle Repair');
+         */
         learnCraftingAction: (action: string) => void;
+        /**
+         * Modify player's spirit stones.
+         * @param amount - Amount to add (positive) or subtract (negative)
+         * @example
+         * changeMoney(100); // Add 100 spirit stones
+         * changeMoney(-50); // Remove 50 spirit stones
+         */
         changeMoney: (amount: number) => void;
+        /**
+         * Modify player's qi.
+         * @param amount - Amount to add (positive) or subtract (negative)
+         * @example
+         * changeQi(50); // Restore 50 qi
+         * changeQi(-20); // Consume 20 qi
+         */
         changeQi: (amount: number) => void;
+        /**
+         * Modify sect favour.
+         * @param amount - Amount to add (positive) or subtract (negative)
+         * @example
+         * changeFavour(10); // Gain 10 favour
+         * changeFavour(-5); // Lose 5 favour
+         */
         changeFavour: (amount: number) => void;
+        /**
+         * Start a game event.
+         * @param event - Event configuration with steps
+         * @example
+         * startEvent({ location: "Liang Tiao Village", steps: [{ type: 'text', text: 'Welcome!' }] });
+         */
         startEvent: (event: GameEvent) => void;
+        /**
+         * Initiate combat encounter.
+         * @param enemies - Array of enemy entities to fight
+         * @param playerBuffs - Buffs to apply to player at combat start
+         * @param locationBackgroundOverride - Optional custom background for combat
+         * @example
+         * startCombat([ratascar], []);
+         * startCombat([boss], [strengthBuff], { backgroundImage: 'boss_arena.png', screenEffect: 'mist' });
+         */
         startCombat: (enemies: EnemyEntity[], playerBuffs: Buff[], locationBackgroundOverride?: {
             backgroundImage: string;
             screenEffect: ScreenEffectType;
@@ -166,74 +321,600 @@ export interface ModAPI {
         mysticalRegionBlessings: Blessing[];
         harmonyConfigs: Record<RecipeHarmonyType, HarmonyTypeConfig>;
         itemTypeToHarmonyType: Record<ItemKind, RecipeHarmonyType>;
+        puppets: PuppetType[];
     };
     actions: {
+        /**
+         * Add a background option for character creation (birth stage).
+         * @param background - Background configuration with stats and description
+         */
         addBirthBackground: (background: Background) => void;
+        /**
+         * Add a background option for character creation (childhood stage).
+         * @param background - Background configuration for childhood events
+         */
         addChildBackground: (background: Background) => void;
+        /**
+         * Add a background option for character creation (teenage stage).
+         * @param background - Background configuration for teenage experiences
+         */
         addTeenBackground: (background: Background) => void;
+        /**
+         * Register a new item type in the game.
+         * @param item - Complete item definition with stats and properties
+         */
         addItem: (item: Item) => void;
+        /**
+         * Add an item to a shop's inventory.
+         * @param item - Item to add
+         * @param stacks - Number of stacks available
+         * @param location - Location of the shop
+         * @param realm - Required realm to purchase
+         * @param valueModifier - (Optional) Price multiplier (default 1.0)
+         * @param reputation - (Optional) Required reputation tier
+         */
         addItemToShop: (item: Item, stacks: number, location: string, realm: Realm, valueModifier?: number, reputation?: ReputationTier) => void;
+        /**
+         * Add an item to a guild's rank shop.
+         * @param item - Item to add
+         * @param stacks - Number of stacks available
+         * @param guild - Name of the guild
+         * @param rank - Required guild rank to purchase
+         * @param valueModifier - (Optional) Price multiplier (default 1.0)
+         * @param reputation - (Optional) Required reputation tier
+         */
+        addItemToGuild: (item: Item, stacks: number, guild: string, rank: number, valueModifier?: number, reputation?: ReputationTier) => void;
+        /**
+         * Add a crafting recipe to the sect recipe library.
+         * @param item - Recipe item configuration
+         */
         addRecipeToLibrary: (item: RecipeItem) => void;
+        /**
+         * Add an item to auction house pool.
+         * @param item - Item to add
+         * @param chance - Spawn chance (0-1). Default 1 unless you want it to be extra rare
+         * @param condition - Condition expression for availability. Normally should be '1'
+         * @param countOverride - Override stack count
+         * @param countMultiplier - Multiply default count
+         * @example
+         * addItemToAuction(rareRecipe, 1, '1');
+         */
         addItemToAuction: (item: Item, chance: number, condition: string, countOverride?: number, countMultiplier?: number) => void;
+        /**
+         * Add a recipe that can be researched from a base item.
+         * @param baseItem - Item that enables research
+         * @param recipe - Recipe to unlock
+         * @example
+         * addRecipeToResearch(ancientScroll, advancedPillRecipe);
+         */
         addRecipeToResearch: (baseItem: Item, recipe: RecipeItem) => void;
+        /**
+         * Register a new character.
+         * @param character - Complete character definition
+         */
         addCharacter: (character: Character) => void;
+        /**
+         * Add a breakthrough for a realm.
+         * @param realm - Target realm
+         * @param breakthrough - Breakthrough configuration
+         */
         addBreakthrough: (realm: Realm, breakthrough: Breakthrough) => void;
+        /**
+         * Add a recurring calendar event.
+         * @param event - Calendar event configuration
+         * @example
+         * addCalendarEvent({ name: 'Moon Festival', condition: '1', year: 1066, month: 8 });
+         */
         addCalendarEvent: (event: CalendarEvent) => void;
+        /**
+         * Register a new crafting action.
+         * @param action - Crafting action definition
+         */
         addCraftingTechnique: (technique: CraftingTechnique) => void;
+        /**
+         * Add a destiny
+         * @param destiny - Destiny configuration
+         */
         addDestiny: (destiny: Destiny) => void;
+        /**
+         * Add an event that triggers on conditions.
+         * @param event - Triggered event configuration
+         */
         addTriggeredEvent: (event: TriggeredEvent) => void;
+        /**
+         * Add a crop type for herb gardens.
+         * @param realm - Required realm to plant
+         * @param crop - Crop configuration
+         * @example
+         * addCrop('qi_condensation', { item: 'Twisted Vine', yield: 5, growthDays: 30 });
+         */
         addCrop: (realm: Realm, crop: Crop) => void;
+        /**
+         * Register a new world location.
+         * @param location - Complete location definition
+         */
         addLocation: (location: GameLocation) => void;
+        /**
+         * Create a link between two locations.
+         * @param existing - Source location key
+         * @param link - Link configuration
+         * @example
+         * linkLocations('Liang Tiao Village', { location: myLocation, distance: 5, condition: "my_unlock_flag" });
+         */
         linkLocations: (existing: string, link: ConditionalLink | ExplorationLink) => void;
+        /**
+         * Add buildings to an existing location.
+         * @param location - Location key
+         * @param buildings - Buildings to add
+         * @example
+         * addBuildingsToLocation('Liang Tiao Village', [{ kind: 'healer' }]);
+         */
+        addBuildingsToLocation: (location: string, buildings: LocationBuilding[]) => void;
+        /**
+         * Add enemies to an existing location.
+         * @param location - Location key
+         * @param enemies - Enemy configurations
+         */
+        addEnemiesToLocation: (location: string, enemies: LocationEnemy[]) => void;
+        /**
+         * Add events to an existing location.
+         * @param location - Location key
+         * @param events - Event configurations
+         */
+        addEventsToLocation: (location: string, events: LocationEvent[]) => void;
+        /**
+         * Add exploration events to an existing location.
+         * @param location - Location key
+         * @param events - Exploration event configurations
+         */
+        addExplorationEventsToLocation: (location: string, events: LocationEvent[]) => void;
+        /**
+         * Add map events to an existing location.
+         * @param location - Location key
+         * @param mapEvents - Map event configurations
+         */
+        addMapEventsToLocation: (location: string, mapEvents: LocationMapEvent[]) => void;
+        /**
+         * Add sect missions to an existing location.
+         * @param location - Location key
+         * @param missions - Mission configurations
+         * @example
+         * addMissionsToLocation('Sect Hall', [window.modAPI.utils.createCullingMission(...)]);
+         */
+        addMissionsToLocation: (location: string, missions: SectMission[]) => void;
+        /**
+         * Add crafting missions to an existing location.
+         * @param location - Location key
+         * @param missions - Crafting mission configurations
+         * @example
+         * addCraftingMissionsToLocation('Crafting Hall', [window.modAPI.utils.createCraftingMission(...)]);
+         */
+        addCraftingMissionsToLocation: (location: string, missions: CraftingMission[]) => void;
+        /**
+         * Add a manual to the Manual Pagoda.
+         * @param manual - Manual configuration
+         */
         addManual: (manual: Manual) => void;
+        /**
+         * Add a chamber to the spirit stone mine.
+         * @param realm - Required realm
+         * @param progress - Realm progress level
+         * @param chamber - Chamber configuration
+         */
         addMineChamber: (realm: Realm, progress: RealmProgress, chamber: MineChamber) => void;
+        /**
+         * Register a new quest.
+         * @param quest - Complete quest definition
+         */
         addQuest: (quest: Quest) => void;
+        /**
+         * Add a combat technique.
+         * @param technique - Technique configuration
+         */
         addTechnique: (technique: Technique) => void;
+        /**
+         * Register background music tracks.
+         * @param name - Music identifier
+         * @param path - Array of file paths (for variants)
+         * @example
+         * addMusic('boss_theme', ['audio/boss1.ogg', 'audio/boss2.ogg']);
+         */
         addMusic: (name: string, path: string[]) => void;
+        /**
+         * Register a sound effect.
+         * @param name - Sound effect identifier
+         * @param path - File path
+         * @example
+         * addSfx('sword_clash', 'audio/sfx/sword_clash.ogg');
+         */
         addSfx: (name: string, path: string) => void;
+        /**
+         * Add a joinable organisation.
+         * @param guild - Guild configuration
+         */
         addGuild: (guild: Guild) => void;
+        /**
+         * Add a dual cultivation technique.
+         * @param technique - Intimate technique configuration
+         */
         addDualCultivationTechnique: (technique: IntimateTechnique) => void;
+        /**
+         * Register an equipment enchantment.
+         * @param enchantment - Enchantment configuration
+         */
         addEnchantment: (enchantment: Enchantment) => void;
+        /**
+         * Add a fallen star.
+         * @param fallenStar - Fallen star configuration
+         */
         addFallenStar: (fallenStar: FallenStar) => void;
+        /**
+         * Add a room type for player housing.
+         * @param room - Room configuration
+         */
         addRoom: (room: Room) => void;
+        /**
+         * Add a researchable recipe linked to an item.
+         * @param baseItem - Item key that enables research
+         * @param recipe - Recipe to unlock
+         * @example
+         * addResearchableRecipe('ancient_cauldron', advancedPillRecipe);
+         */
         addResearchableRecipe: (baseItem: string, recipe: RecipeItem) => void;
+        /**
+         * Add an uncut stone to stone cutting pool.
+         * @param realm - Required realm
+         * @param uncutStone - Stone item
+         */
         addUncutStone: (realm: Realm, uncutStone: Item) => void;
+        /**
+         * Add a blessing for mystical regions.
+         * @param blessing - Blessing configuration
+         */
         addMysticalRegionBlessing: (blessing: Blessing) => void;
+        /**
+         * Register a new harmony type for crafting.
+         * @param harmonyType - Harmony type identifier
+         * @param config - Harmony configuration
+         */
         addHarmonyType: (harmonyType: RecipeHarmonyType, config: HarmonyTypeConfig) => void;
+        /**
+         * Override item type to harmony type mappings.
+         * @param mapping - Partial mapping of item kinds to harmony types
+         * @example
+         * overrideItemTypeToHarmonyType({ 'pill': 'medicinal', 'artefact': 'elemental' });
+         */
         overrideItemTypeToHarmonyType: (mapping: Partial<Record<ItemKind, RecipeHarmonyType>>) => void;
+        /**
+         * Register a custom game screen.
+         * @param config - Screen configuration
+         */
         addScreen: (config: ModScreenConfig) => void;
+        /**
+         * Register a new puppet type for training ground.
+         * @param puppet - Puppet configuration
+         */
+        addPuppetType: (puppet: PuppetType) => void;
     };
     utils: {
+        /**
+         * Create an alpha variant of an enemy (stronger version).
+         * @param enemy - Base enemy entity
+         * @returns Enhanced enemy with increased stats
+         * @example
+         * const alphaBandit = alpha(bandit);
+         * // Returns bandit with ~1.5x health and damage
+         */
         alpha: (enemy: EnemyEntity) => EnemyEntity;
+        /**
+         * Create an alpha+ variant of an enemy (much stronger).
+         * @param enemy - Base enemy entity
+         * @returns Significantly enhanced enemy
+         * @example
+         * const eliteBoss = alphaPlus(demonLord);
+         * // Returns enemy with ~2x stats and special abilities
+         */
         alphaPlus: (enemy: EnemyEntity) => EnemyEntity;
+        /**
+         * Create realmbreaker variants (group of stronger enemies).
+         * @param enemy - Base enemy template
+         * @returns Array of enhanced enemies
+         * @example
+         * const demonHorde = realmbreaker(demon);
+         * // Returns array of 3-5 demons with varied stats
+         */
         realmbreaker: (enemy: EnemyEntity) => EnemyEntity[];
+        /**
+         * Create a corrupted variant of an enemy.
+         * @param enemy - Base enemy entity
+         * @returns Corrupted enemy with dark powers
+         * @example
+         * const corruptedBeast = corrupted(beast);
+         * // Returns enemy with corruption buffs and abilities
+         */
         corrupted: (enemy: EnemyEntity) => EnemyEntity;
+        /**
+         * Create a combat event from an enemy configuration.
+         * @param enemy - Location enemy definition
+         * @returns Location event that triggers combat
+         */
         createCombatEvent: (enemy: LocationEnemy) => LocationEvent;
+        /**
+         * Create a monster culling quest.
+         * @param monster - Enemy to defeat
+         * @param location - Quest location
+         * @param description - Quest description text
+         * @param favour - Favour reward
+         * @returns Complete quest object
+         */
         createCullingMission: (monster: EnemyEntity, location: string, description: string, favour: number) => Quest;
+        /**
+         * Create an item collection quest.
+         * @param item - Item to collect
+         * @param location - Collection location
+         * @param description - Quest description
+         * @param favour - Favour reward
+         * @returns Complete quest object
+         */
         createCollectionMission: (item: Item, location: string, description: string, favour: number) => Quest;
+        /**
+         * Create a delivery quest with events.
+         * @param items - Items to deliver
+         * @param count - Number of items
+         * @param location - Delivery location
+         * @param description - Quest description
+         * @param preDeliverySteps - Events before delivery
+         * @param postDeliverySteps - Events after delivery
+         * @param favour - Favour reward
+         * @returns Complete quest object
+         */
         createDeliveryMission: (items: Item[], count: number, location: string, description: string, preDeliverySteps: EventStep[], postDeliverySteps: EventStep[], favour: number) => Quest;
+        /**
+         * Create a hunt quest with rewards.
+         * @param monster - Target monster
+         * @param location - Hunt location
+         * @param description - Quest description
+         * @param encounter - Encounter text
+         * @param spiritStones - Money reward
+         * @param reputation - Reputation gain
+         * @param reputationName - Faction name
+         * @param maxReputation - Max reputation tier
+         * @param characterEncounter - Optional NPC encounter
+         * @returns Complete quest object
+         */
         createHuntQuest: (monster: EnemyEntity, location: string, description: string, encounter: string, spiritStones: number, reputation: number, reputationName: string, maxReputation: ReputationTier, characterEncounter?: CharacterRequestEncounter) => Quest;
+        /**
+         * Create a pack hunting quest.
+         * @param monster - Monster type in pack
+         * @param location - Hunt location
+         * @param description - Quest description
+         * @param encounter - Encounter text
+         * @param spiritStones - Money reward
+         * @param reputation - Reputation gain
+         * @param reputationName - Faction name
+         * @param maxReputation - Max tier
+         * @returns Complete quest object
+         */
         createPackQuest: (monster: EnemyEntity, location: string, description: string, encounter: string, spiritStones: number, reputation: number, reputationName: string, maxReputation: ReputationTier) => Quest;
+        /**
+         * Create a delivery quest with full rewards.
+         * @param location - Delivery destination
+         * @param description - Quest description
+         * @param predelivery - Pre-delivery events
+         * @param item - Item to deliver
+         * @param amount - Item count
+         * @param postdelivery - Post-delivery events
+         * @param spiritStones - Money reward
+         * @param reputation - Reputation gain
+         * @param reputationName - Faction name
+         * @param maxReputation - Max tier
+         * @returns Complete quest object
+         */
         createDeliveryQuest: (location: string, description: string, predelivery: EventStep[], item: Item, amount: number, postdelivery: EventStep[], spiritStones: number, reputation: number, reputationName: string, maxReputation: ReputationTier) => Quest;
+        /**
+         * Create a fetch quest between locations.
+         * @param title - Quest title
+         * @param description - Quest description
+         * @param srcLocation - Source location
+         * @param srcHint - Hint for source
+         * @param srcSteps - Source events
+         * @param dstLocation - Destination location
+         * @param dstHint - Hint for destination
+         * @param dstSteps - Destination events
+         * @param spiritStones - Money reward
+         * @param reputation - Reputation gain
+         * @param reputationName - Faction name
+         * @param maxReputation - Max tier
+         * @returns Complete quest object
+         */
         createFetchQuest: (title: string, description: string, srcLocation: string, srcHint: string, srcSteps: EventStep[], dstLocation: string, dstHint: string, dstSteps: EventStep[], spiritStones: number, reputation: number, reputationName: string, maxReputation: ReputationTier) => Quest;
+        /**
+         * Create a crafting hall mission
+         * @param recipe - Quest recipe
+         * @param cost - Spirit Stone acceptance cost
+         * @param location - Quest start location
+         * @param appraiser - Quest start confirmation NPC
+         * @param description - Quest description
+         * @param introSteps - Pre Crafting quest steps
+         * @param sublimeSteps - Sublime result quest steps
+         * @param perfectSteps - Perfect result quest steps
+         * @param basicSteps - Basic result quest steps
+         * @param failureSteps - Failure result quest steps
+         * @param favour - Sect favour granted on success
+         */
+        createCraftingMission: (recipe: Item, cost: number, location: string, appraiser: string, description: string, introSteps: EventStep[], sublimeSteps: EventStep[], perfectSteps: EventStep[], basicSteps: EventStep[], failureSteps: EventStep[], favour: number) => Quest;
+        /**
+         * Create a Q&A dialogue tree.
+         * @param key - Unique key for the dialogue
+         * @param questions - Array of questions/answers
+         * @param exit - Exit option
+         * @param showExitOnAllComplete - Show exit only after all questions
+         * @returns Event steps for the dialogue
+         */
         createQuestionAnswerList: (key: string, questions: QuestionAnswer[], exit: QuestionAnswer, showExitOnAllComplete?: boolean) => EventStep[];
+        /**
+         * Get expected health for a realm/progress.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected health value
+         * @example
+         * const health = getExpectedHealth('coreFormation', 'Middle');
+         */
         getExpectedHealth: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected power for a realm/progress.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected power value
+         * @example
+         * const power = getExpectedPower('coreFormation', 'Late');
+         */
         getExpectedPower: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected defense for a realm/progress.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected defense value
+         * @example
+         * const defense = getExpectedDefense('coreFormation', 'Early');
+         */
         getExpectedDefense: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected barrier for a realm/progress.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected barrier value
+         * @example
+         * const barrier = getExpectedBarrier('coreFormation', 'Early');
+         */
         getExpectedBarrier: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected toxicity resistance for a realm/progress.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected toxicity value
+         * @example
+         * const toxicity = getExpectedToxicity('coreFormation', 'Middle');
+         */
         getExpectedToxicity: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected qi pool for crafting.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected pool value
+         * @example
+         * const pool = getExpectedPool('coreFormation', 'Late');
+         */
         getExpectedPool: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected crafting intensity.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected intensity value
+         * @example
+         * const intensity = getExpectedIntensity('coreFormation', 'Late');
+         */
         getExpectedIntensity: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected crafting control.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected control value
+         * @example
+         * const control = getExpectedControl('coreFormation', 'Early');
+         */
         getExpectedControl: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected player combat power. This takes into account masteries, equipement, buffs, and other factors. Normally ~100x higher than getExpectedPower.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected power level
+         * @example
+         * const playerPower = getExpectedPlayerPower('coreFormation', 'Early');
+         */
         getExpectedPlayerPower: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Get expected artifact power.
+         * @param realm - Cultivation realm
+         * @param progress - Progress within realm
+         * @returns Expected artifact power
+         * @example
+         * const artifactPower = getExpectedArtefactPower('coreFormation', 'Middle');
+         */
         getExpectedArtefactPower: (realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Calculate charisma for breakthrough rewards.
+         * @param realm - Target realm
+         * @param mult - Multiplier (typically 1.0-3.0)
+         * @returns Charisma value
+         * @example
+         * const charisma = getBreakthroughCharisma('coreFormation', 1.5);
+         */
         getBreakthroughCharisma: (realm: Realm, mult: number) => number;
+        /**
+         * Calculate clothing defense value.
+         * @param realm - Required realm
+         * @param scale - Scale factor (0.5-2.0 typical)
+         * @returns Defense value
+         * @example
+         * const defense = getClothingDefense('coreFormation', 1.2);
+         */
         getClothingDefense: (realm: Realm, scale: number) => number;
+        /**
+         * Calculate clothing charisma value.
+         * @param realm - Required realm
+         * @param mult - Multiplier (1.0-3.0 typical)
+         * @returns Charisma value
+         * @example
+         * const charisma = getClothingCharisma('coreFormation', 2.0);
+         */
         getClothingCharisma: (realm: Realm, mult: number) => number;
+        /**
+         * Get max qi the player can hold in a realm.
+         * @param realm - Target realm
+         * @param realmProgress - Progress level
+         * @returns Qi amount
+         * @example
+         * const qi = getRealmQi('coreFormation', 'Late');
+         */
         getRealmQi: (realm: Realm, realmProgress: RealmProgress) => number;
+        /**
+         * Get qi cost for breakthrough.
+         * @param realm - Current realm
+         * @param realmProgress - Current progress
+         * @returns Qi cost
+         * @example
+         * const qiCost = getBreakthroughQi('coreFormation', 'Late');
+         */
         getBreakthroughQi: (realm: Realm, realmProgress: RealmProgress) => number;
+        /**
+         * Scale a numeric reward amount to a value appropriate for the player's realm and progress.
+         * @param base - Base reward amount
+         * @param realm - Player realm
+         * @param progress - Realm progress
+         * @returns Scaled reward
+         * @example
+         * const reward = getNumericReward(100, 'coreFormation', 'Middle');
+         */
         getNumericReward: (base: number, realm: Realm, progress: RealmProgress) => number;
+        /**
+         * Create a flag reference string.
+         * @param flag - Flag name
+         * @returns Flag reference for conditions
+         * @example
+         * const flagRef = flag('quest complete'); // Returns 'quest_complete'
+         */
         flag: (flag: string) => string;
+        /**
+         * Calculate crafting equipment stats.
+         * @param realm - Equipment realm
+         * @param realmProgress - Progress level
+         * @param factors - Stat multipliers for pool/control/intensity
+         * @param type - Equipment type ('cauldron' or 'flame')
+         * @returns Crafting statistics
+         * @example
+         * getCraftingEquipmentStats('coreFormation', 'Middle', { pool: 1.2, control: 1.0, intensity: 0.8 }, 'cauldron');
+         */
         getCraftingEquipmentStats: (realm: Realm, realmProgress: RealmProgress, factors: {
             pool: number;
             control: number;
@@ -241,17 +922,123 @@ export interface ModAPI {
         }, type: 'cauldron' | 'flame') => Partial<{
             [key in CraftingStatistic]: number;
         }>;
+        /**
+         * Evaluate an expression with game flags.
+         * @param exp - Expression string
+         * @param flags - Current flag values
+         * @returns Evaluated result (floored to integer)
+         * @example
+         * evalExp('10 * quest_stage + 50', { quest_stage: 3 }); // Returns 80
+         */
         evalExp: (exp: string, flags: Record<string, number>) => number;
+        /**
+         * Evaluate expression without flooring.
+         * @param exp - Expression string
+         * @param flags - Current flag values
+         * @returns Evaluated result (decimal allowed)
+         * @example
+         * evalExpNoFloor('charisma * 1.5', { charisma: 10 }); // Returns 15.0
+         */
         evalExpNoFloor: (exp: string, flags: Record<string, number>) => number;
+        /**
+         * Get pill effectiveness multiplier for realm.
+         * @param realm - Player realm
+         * @returns Multiplier value
+         * @example
+         * const mult = getPillRealmMultiplier('coreFormation');
+         */
+        getPillRealmMultiplier: (realm: Realm) => number;
     };
     hooks: {
+        /**
+         * Hook into enemy combat entity creation to modify stats.
+         * @param interceptor - Function to modify combat entity
+         * @example
+         * onCreateEnemyCombatEntity((enemy, combatEntity, flags) => {
+         *   if (flags.hard_mode) {
+         *     combatEntity.stats.hp *= 1.5;
+         *     combatEntity.stats.power *= 1.2;
+         *   }
+         *   return combatEntity;
+         * });
+         */
         onCreateEnemyCombatEntity: (interceptor: (enemy: EnemyEntity, combatEntity: CombatEntity, gameFlags: Record<string, number>) => CombatEntity) => void;
+        /**
+         * Hook to modify recipe difficulty calculations.
+         * @param interceptor - Function to adjust recipe stats
+         * @example
+         * onDeriveRecipeDifficulty((recipe, stats, flags) => {
+         *   if (recipe.basicItem.kind === 'pill' && flags.alchemy_mastery) {
+         *     stats.difficulty *= 0.8;
+         *   }
+         *   return stats;
+         * });
+         */
         onDeriveRecipeDifficulty: (interceptor: (recipe: RecipeItem, recipeStats: CraftingRecipeStats, gameFlags: Record<string, number>) => CraftingRecipeStats) => void;
+        /**
+         * Hook to add events after combat completion.
+         * @param interceptor - Function returning additional event steps
+         * @example
+         * onCompleteCombat((step, victory, playerState, flags) => {
+         *   if (victory && playerState.stats.hp < 10) {
+         *     return [{ type: 'text', text: 'That was close!' }];
+         *   }
+         *   return [];
+         * });
+         */
         onCompleteCombat: (interceptor: (eventStep: CombatStep | FightCharacterStep, victory: boolean, playerCombatState: CombatEntity, gameFlags: Record<string, number>) => EventStep[]) => void;
+        /**
+         * Hook to add events after tournament completion.
+         * @param interceptor - Function returning additional event steps
+         * @example
+         * onCompleteTournament((step, result, flags) => {
+         *   if (result === 'victory') {
+         *     return [{ type: 'addItem', item: { name: 'champion_medal' }, amount: "1" }];
+         *   }
+         *   return [];
+         * });
+         */
         onCompleteTournament: (interceptor: (eventStep: TournamentStep, tournamentState: 'victory' | 'second' | 'defeat', gameFlags: Record<string, number>) => EventStep[]) => void;
+        /**
+         * Hook to add events after dual cultivation.
+         * @param interceptor - Function returning additional event steps
+         * @example
+         * onCompleteDualCultivation((step, success, flags) => {
+         *   if (success && flags.dual_mastery) {
+         *     return [{ type: 'buff', buff: harmonyBonus }];
+         *   }
+         *   return [];
+         * });
+         */
         onCompleteDualCultivation: (interceptor: (eventStep: DualCultivationStep, success: boolean, gameFlags: Record<string, number>) => EventStep[]) => void;
+        /**
+         * Hook to add events after crafting completion.
+         * @param interceptor - Function returning additional event steps
+         * @example
+         * onCompleteCrafting((step, item, flags) => {
+         *   if (item && item.quality > 5) {
+         *     return [{ type: 'text', text: 'A masterpiece!' }];
+         *   }
+         *   return [];
+         * });
+         */
         onCompleteCrafting: (interceptor: (eventStep: CraftingStep, item: CraftingResult | undefined, gameFlags: Record<string, number>) => EventStep[]) => void;
+        /**
+         * Hook to add events after auction completion.
+         * @param interceptor - Function returning additional event steps
+         * @example
+         * onCompleteAuction((step, itemsBought, flags) => {
+         *   if (itemsBought.length > 5) {
+         *     return [{ type: 'flag', flag: 'big_spender', value: "1", global: true }];
+         *   }
+         *   return [];
+         * });
+         */
         onCompleteAuction: (interceptor: (eventStep: AuctionStep, itemsBought: AuctionItem[], gameFlags: Record<string, number>) => EventStep[]) => void;
+        /**
+         * Hook to add events after stone cutting.
+         * @param interceptor - Function returning additional event steps
+         */
         onCompleteStoneCutting: (interceptor: (eventStep: StoneCuttingStep, gameFlags: Record<string, number>) => EventStep[]) => void;
     };
 }

package/dist/quest.d.ts

@@ -15,6 +15,7 @@ export interface QuestProgressState {
     seenUpTo: number;
     completed: number[];
     killTally: Record<string, number>;
+    raidsComplete: number;
     waitMonths?: Record<number, number>;
 }
 export type QuestReward = ItemQuestReward | MoneyQuestReward | FavourQuestReward | ReputationQuestReward | GuildApprovalQuestReward;
@@ -42,7 +43,7 @@ interface GuildApprovalQuestReward {
     amount: number;
     guild: string;
 }
-export type QuestStep = EventQuestStep | ConditionQuestStep | CollectQuestStep | MissionHallQuestStep | FlagValueQuestStep | SpeakToCharacterQuestStep | KillQuestStep | WaitQuestStep;
+export type QuestStep = EventQuestStep | ConditionQuestStep | CollectQuestStep | MissionHallQuestStep | FlagValueQuestStep | SpeakToCharacterQuestStep | KillQuestStep | WaitQuestStep | RaidQuestStep;
 interface QuestStepBase {
     hint: string;
 }
@@ -88,4 +89,8 @@ interface WaitQuestStep extends QuestStepBase {
     kind: 'wait';
     months: number;
 }
+export interface RaidQuestStep extends QuestStepBase {
+    kind: 'raid';
+    amount: number;
+}
 export {};

package/dist/reduxState.d.ts

@@ -23,7 +23,7 @@ import { Realm } from './realm';
 export interface Viewport {
     x: number;
     y: number;
-    scale: number;
+    zoom: number;
 }
 export interface PlayerState {
     player: PlayerEntity;
@@ -81,6 +81,10 @@ export interface CombatState {
     customBgm?: string[];
     background: string;
     screenEffect: ScreenEffectType;
+    combatVictoryFlag?: {
+        flag: string;
+        value: number;
+    };
 }
 export type CraftingSliceState = ExistingCraftingState;
 export interface ResetFlag {

package/dist/stat.d.ts

@@ -62,6 +62,7 @@ export interface Scaling {
     stat: PhysicalStatistic | SocialStatistic | CombatStatistic | CraftingStatistic | TechniqueElement | undefined;
     scaling?: 'stacks' | 'consumed' | string;
     eqn?: string;
+    additiveEqn?: string;
     max?: Scaling;
     divideByStanceLength?: boolean;
     upgradeKey?: string;

package/dist/stat.js

@@ -149,7 +149,7 @@ export const combatStatToDescription = {
     lifesteal: '',
     critchance: 'Your chance to get a critical effect, increasing the power of your techniques.',
     critdam: '',
-    artefactpower: "The strength of your artefact's techniques.",
+    artefactpower: "The strength of your artefact's techniques and your Formation Parts.",
     fistBoost: '',
     blossomBoost: '',
     weaponBoost: '',

package/dist/technique.d.ts

@@ -38,6 +38,7 @@ export interface Technique {
     maxInstances?: number;
     stanceRestriction?: StanceRestriction;
     tooltip?: string;
+    additionalTooltip?: string;
     effects: TechniqueEffect[];
     triggeredEffects?: {
         trigger: string;

package/dist/trainingGround.d.ts

@@ -0,0 +1,10 @@
+import { EnemyEntity, Realm, RealmProgress } from '.';
+export interface PuppetType {
+    id: string;
+    name: string;
+    description: string;
+    image: string;
+    baseMultiplier: number;
+    multiplierGrowth: number;
+    createPuppet: (tier: number, realm: Realm, realmProgress: RealmProgress) => EnemyEntity;
+}

package/dist/trainingGround.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afnm-types",
-  "version": "0.6.11",
+  "version": "0.6.16",
   "description": "Type definitions for Ascend From Nine Mountains",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,6 +19,9 @@
     "@mui/icons-material": "^7.3.1",
     "@mui/material": "^7.3.1"
   },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
   "scripts": {
     "build": "tsc --project tsconfig.types.json",
     "prepublishOnly": "npm run build"