afnm-types 0.6.56 → 0.6.57

package/dist/auction.d.ts

@@ -18,6 +18,7 @@ export interface AuctionItemDef {
     condition: string;
     countOverride?: number;
     countMultiplier?: number;
+    costMultiplier?: number;
 }
 export interface AuctionCharacter {
     name: string;

package/dist/buff.d.ts

@@ -57,6 +57,20 @@ interface InventoryItemTechniqueCondition extends BaseTechniqueCondition {
     count: number;
     mode: 'more' | 'less' | 'equal';
 }
+/**
+ * Configures how a buff lives outside combat. Buffs without a `persistence`
+ * field are combat or event scoped only.
+ */
+export interface BuffPersistence {
+    /**
+     * When combat ends, the surviving stack count of this buff on the player is
+     * written back into `player.monthBuffs`. Existing entries are replaced, not
+     * additively merged. Stacks of zero or below remove the buff.
+     */
+    persistAfterCombat?: boolean;
+    /** Stacks of this buff lost at the end of every month. */
+    decayPerMonth?: number;
+}
 export interface Buff {
     name: string;
     displayName?: Translatable;
@@ -108,6 +122,7 @@ export interface Buff {
     /** Block specific triggers from executing. Used to prevent effects like celestial rotation. */
     blockTriggerEffects?: {
         trigger: string;
+        condition?: TechniqueCondition;
         effects: BuffEffect[];
     }[];
     damageInterceptorEffects?: {
@@ -122,6 +137,7 @@ export interface Buff {
         amplifier: {
             kind: 'multiply';
             value: number;
+            cantUpgrade?: boolean;
         };
         effects?: BuffEffect[];
         appliesTo: ('damage' | 'barrier' | 'heal' | 'tempHealth')[];
@@ -134,6 +150,7 @@ export interface Buff {
         modifier: {
             kind: 'add' | 'multiply';
             value: number;
+            cantUpgrade?: boolean;
         };
         effects?: BuffEffect[];
     }[];
@@ -144,6 +161,12 @@ export interface Buff {
     stacks: number;
     stacksAreDays?: boolean;
     stacksAreMonths?: boolean;
+    /**
+     * Marks the buff as carrying state on the player between events. When set,
+     * the buff opts out of the default daily monthBuffs decay (which treats
+     * stacks as days remaining) and follows the rules in this object instead.
+     */
+    persistence?: BuffPersistence;
     buffType?: string;
     buffTypeTooltip?: string;
     endurePercent?: number;
@@ -155,6 +178,11 @@ export interface Buff {
     guardianIntercept?: {
         percent: Scaling;
         maxHp: Scaling;
+        /** How re-application of the guardian buff combines with existing guardian HP.
+         *  'refresh' (default): maxHp = max(old, new); hp = maxHp (fully heal).
+         *  'extend': hp = oldHp + newMaxHp; maxHp = max(oldMaxHp, hp). Adds onto current and extends the cap. */
+        refreshMode?: 'refresh' | 'extend';
+        canUpgrade?: boolean;
     };
     /** Runtime guardian HP — set automatically from guardianIntercept.maxHp at buff creation */
     guardianHp?: number;
@@ -328,6 +356,7 @@ interface BaseBuff {
         [key in CombatStatistic]: Scaling;
     }>;
     hidden?: boolean;
+    cantUpgrade?: boolean;
 }
 interface DamageEffect extends BaseBuff {
     kind: 'damage';
@@ -372,6 +401,7 @@ interface ConsumeBuffSelfEffect extends BaseBuff {
     buff: Buff | string;
     silent?: boolean;
     hideBuff?: boolean;
+    targeting?: EffectTargeting;
 }
 interface CreateBuffTargetEffect extends BaseBuff {
     kind: 'buffTarget';
@@ -418,6 +448,9 @@ interface ModifyBuffGroupEffect extends BaseBuff {
     onTarget?: boolean;
     group: string;
     amount: Scaling;
+    /** Defaults to 'all'. 'highest'/'lowest' restrict the effect to a single matching buff
+     *  chosen by stack count. */
+    mode?: 'all' | 'highest' | 'lowest';
 }
 interface SetStateEffect extends BaseBuff {
     kind: 'setState';

package/dist/cli/extract-translations/extractors.js

@@ -537,6 +537,18 @@ function extractFromFile(filePath) {
                         });
                     }
                 }
+                else if (typescript_1.default.isBinaryExpression(arg) && arg.operatorToken.kind === typescript_1.default.SyntaxKind.PlusToken) {
+                    // String concatenation with + is supported - try to resolve it
+                    const resolved = (0, template_processor_js_1.tryResolveBinaryExpression)(arg, sourceFile, filePath);
+                    if (resolved !== null && resolved.trim().length > 0) {
+                        results.push({
+                            text: resolved,
+                            file: filePath,
+                            line: (0, template_processor_js_1.getLineNumber)(sourceFile, node.getStart()),
+                            context: `${funcName}-call`,
+                        });
+                    }
+                }
                 else if (typescript_1.default.isTemplateExpression(arg)) {
                     const templateText = arg.getText(sourceFile);
                     const processed = (0, template_processor_js_1.processTemplateExpression)(arg, sourceFile, filePath);

package/dist/cli/extract-translations/reporters.js

@@ -1037,20 +1037,31 @@ function buildTranslationLookup(langData) {
 function loadExistingLanguageFiles() {
     const languageFiles = new Map();
     const translationsDir = path_1.default.join('src', 'translations');
-    // List of language codes to look for
-    const languages = ['zh', 'de', 'fr', 'es', 'ru'];
-    for (const lang of languages) {
-        const langPath = path_1.default.join(translationsDir, `${lang}.json`);
-        if (fs_1.default.existsSync(langPath)) {
-            try {
-                const data = JSON.parse(fs_1.default.readFileSync(langPath, 'utf-8'));
-                languageFiles.set(lang, data);
-                console.log(`  Loaded existing translations from ${lang}.json`);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                console.warn(`  Warning: Failed to parse ${lang}.json: ${message}`);
-            }
+    // Discover languages by scanning the translations directory rather than maintaining
+    // a hardcoded list (which silently dropped ja/ko/vi/fi/pl/pt-BR/th/zh-CN/zh-TW).
+    // Filenames are <lang>.json; non-language files in this dir are explicitly excluded.
+    const NON_LANGUAGE_FILES = new Set([
+        'template.json',
+        'debug.json',
+        'custom-strings.json',
+        'technique-tooltip-templates.json',
+    ]);
+    const entries = fs_1.default.readdirSync(translationsDir);
+    for (const file of entries) {
+        if (!file.endsWith('.json'))
+            continue;
+        if (NON_LANGUAGE_FILES.has(file))
+            continue;
+        const lang = file.replace(/\.json$/, '');
+        const langPath = path_1.default.join(translationsDir, file);
+        try {
+            const data = JSON.parse(fs_1.default.readFileSync(langPath, 'utf-8'));
+            languageFiles.set(lang, data);
+            console.log(`  Loaded existing translations from ${lang}.json`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`  Warning: Failed to parse ${lang}.json: ${message}`);
         }
     }
     return languageFiles;

package/dist/entity.d.ts

@@ -333,6 +333,8 @@ export interface CombatEntity {
     partyId?: string;
     /** When true, critchance is forced to 0 for this entity (used in training ground) */
     noCrit?: boolean;
+    /** Maximum qi droplets for this entity (set during combat entity creation) */
+    maxqiDroplets?: number;
     /** Cached hash for getVariablesFromEntity. Cleared whenever stats or buffs mutate. */
     _cachedHash?: string;
 }

package/dist/event.d.ts

@@ -464,6 +464,10 @@ export interface SetAidBreakthroughCooldownStep extends BaseEventStep {
 export interface StoneCuttingStep extends BaseEventStep {
     kind: 'stoneCutting';
     realm: Realm;
+    /** Percentage discount to apply to stone cutting costs (0-100), evaluated as expression */
+    discountPercentage?: string;
+    /** Number of stones the player can cut for free, evaluated as expression */
+    freeCount?: string;
 }
 export interface GiveItemStep extends BaseEventStep {
     kind: 'giveItem';

package/dist/gameVersion.d.ts

@@ -15,4 +15,4 @@
  *   };
  * }
  */
-export declare const GAME_VERSION = "0.6.56";
+export declare const GAME_VERSION = "0.6.57";

package/dist/gameVersion.js

@@ -15,4 +15,4 @@
  *   };
  * }
  */
-export const GAME_VERSION = "0.6.56";
+export const GAME_VERSION = "0.6.57";

package/dist/item.d.ts

@@ -12,7 +12,7 @@ import type { Realm, RealmProgress } from './realm';
 import type { RecipeDifficulty } from './RecipeDifficulty';
 import type { CombatStatistic, CombatStatsMap, CraftingStatistic, CraftingStatsMap, PhysicalStatistic, Scaling, SocialStatistic } from './stat';
 import type { Technique, TechniqueEffect } from './technique';
-import { DelveRoom } from './soulShardDelve';
+import { DelveRoomConfig } from './soulShardDelve';
 export declare const itemKinds: readonly ["clothing", "talisman", "artefact", "mount", "cauldron", "flame", "upgrade", "fruit", "elixir", "recipe", "technique", "action", "transport_seal", "enchantment", "pill", "reagent", "concoction", "consumable", "recuperation", "formation", "breakthrough", "pillar_shard", "material", "flare", "mystical_key", "condensation_art", "blueprint", "trophy", "treasure", "token", "life_essence", "device", "manual", "pillar_pattern", "local_map"];
 export type ItemKind = (typeof itemKinds)[number];
 export declare const itemKindToName: {
@@ -43,6 +43,13 @@ interface ItemBase {
     qualityTier?: number;
     hiddenPotential?: number;
     minimumPotential?: number;
+    corruption?: ItemCorruption;
+}
+export interface ItemCorruption {
+    name: Translatable;
+    debuff: Buff;
+    threshold: number;
+    countPerCombat: number;
 }
 export interface ItemDesc {
     name: string;
@@ -223,6 +230,14 @@ export interface CombatItem extends ItemBase {
 export interface ConsumablePillItem extends BasePillItem {
     pillKind: 'consumable';
     max: number;
+    /**
+     * Optional shared consumption group. When set, the player can consume at most `groupCap`
+     * pills total across every pill that names the same `consumptionGroup`, in addition to
+     * each pill's individual `max` limit.
+     */
+    consumptionGroup?: string;
+    /** Lifetime cap for the entire consumption group. Required when `consumptionGroup` is set. */
+    groupCap?: number;
     physicalStats: Partial<Record<PhysicalStatistic, number>>;
     socialStats: Partial<Record<SocialStatistic, number>>;
     rawStats?: Partial<Record<CombatStatistic | CraftingStatistic, Scaling>>;
@@ -454,9 +469,9 @@ export interface PillarShardVariant {
 }
 export interface PillarShardItem extends ItemBase {
     kind: 'pillar_shard';
-    tooltip: Translatable;
+    tooltip?: Translatable;
     maxInstances?: number;
-    delveRoomConfig?: DelveRoom;
+    delveRoomConfig?: DelveRoomConfig;
     variants?: PillarShardVariant[];
     stability?: number;
     portal?: {

package/dist/itemAction.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import type { AppDispatch } from '../store';
+import type { BreakthroughState } from './breakthrough';
+import type { SoundEffectName } from './audio';
+import type { Item } from './item';
+import type { PlayerEntity } from './entity';
+import type { InventoryState } from './reduxState';
+interface OpenItem {
+    item: Item;
+    data: unknown;
+    onComplete: () => void;
+}
+export interface ItemActionContext {
+    item: Item;
+    player: PlayerEntity;
+    inventory: InventoryState;
+    breakthrough: BreakthroughState;
+    flags: Record<string, number | string | boolean>;
+    dispatch: AppDispatch;
+    setResult: (result: ReactNode) => void;
+    setClicked: (clicked: boolean) => void;
+    setOpenItem?: (openItem: OpenItem) => void;
+    setDoEnchant?: (doEnchant: boolean) => void;
+    setDoUpgrade?: (doUpgrade: boolean) => void;
+    setDoAppearanceChange?: (doAppearanceChange: boolean) => void;
+    playSfx: (sound: SoundEffectName) => void;
+    usageRestricted: boolean;
+}
+export interface ItemActionResult {
+    buttons: ReactNode[];
+}
+export type ItemActionHandler = (context: ItemActionContext) => ItemActionResult;
+export {};

package/dist/itemAction.js

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

package/dist/location.d.ts

@@ -146,8 +146,8 @@ export interface CraftingMission {
     condition: string;
 }
 export declare const exploresPerUnlock = 3;
-export type BuildingType = 'cultivation' | 'manual' | 'crafting' | 'mission' | 'craftingHall' | 'healer' | 'market' | 'favourExchange' | 'vault' | 'custom' | 'herbField' | 'mine' | 'recipe' | 'requestBoard' | 'compendium' | 'mysticalRegion' | 'expedition' | 'trainingGround' | 'library' | 'house' | 'altar' | 'research' | 'reforge' | 'guild' | 'tenThousandFlames' | 'soulShardDelve' | 'enchantmentShop' | 'challengeBoard' | 'modBuilding';
-export type LocationBuilding = CultivationBuilding | ManualBuilding | CraftingBuilding | MissionBuilding | CraftingHallBuilding | HealerBuilding | MarketBuilding | VaultBuilding | FavourExchangeBuilding | CustomBuilding | HerbFieldBuilding | MineBuilding | RecipeLibraryBuilding | RequestBoardBuilding | CompendiumBuilding | MysticalRegionBuilding | TrainingGroundBuilding | LibraryBuilding | HouseBuilding | CompressionAltarBuilding | ResearchBuilding | ReforgeBuilding | GuildBuilding | TenThousandFlamesBuilding | SoulShardDelveBuilding | EnchantmentShopBuilding | ChallengeBoardBuilding | ModBuilding;
+export type BuildingType = 'cultivation' | 'manual' | 'crafting' | 'mission' | 'craftingHall' | 'healer' | 'market' | 'favourExchange' | 'vault' | 'custom' | 'herbField' | 'mine' | 'recipe' | 'requestBoard' | 'compendium' | 'mysticalRegion' | 'expedition' | 'trainingGround' | 'library' | 'house' | 'altar' | 'research' | 'reforge' | 'guild' | 'tenThousandFlames' | 'soulShardDelve' | 'enchantmentShop' | 'challengeBoard' | 'jadeCutter' | 'modBuilding';
+export type LocationBuilding = CultivationBuilding | ManualBuilding | CraftingBuilding | MissionBuilding | CraftingHallBuilding | HealerBuilding | MarketBuilding | VaultBuilding | FavourExchangeBuilding | CustomBuilding | HerbFieldBuilding | MineBuilding | RecipeLibraryBuilding | RequestBoardBuilding | CompendiumBuilding | MysticalRegionBuilding | TrainingGroundBuilding | LibraryBuilding | HouseBuilding | CompressionAltarBuilding | ResearchBuilding | ReforgeBuilding | GuildBuilding | TenThousandFlamesBuilding | SoulShardDelveBuilding | EnchantmentShopBuilding | ChallengeBoardBuilding | JadeCutterBuilding | ModBuilding;
 export type LocationBuildingState = MissionBuildingState | CraftingHallBuildingState | ShopBuildingState | RequestBoardBuildingState | HouseBuildingState | CompressionAltarBuildingState;
 interface BuildingBase {
     kind: BuildingType;
@@ -200,6 +200,10 @@ export interface CraftingHallBuildingState {
 export interface HealerBuilding extends BuildingBase {
     kind: 'healer';
 }
+export interface JadeCutterBuilding extends BuildingBase {
+    kind: 'jadeCutter';
+    reputationName: string;
+}
 export interface ShopItem extends ItemDesc {
     stacks: number;
     reputation?: ReputationTier;
@@ -234,6 +238,8 @@ export interface HerbFieldBuilding extends BuildingBase {
 }
 export interface MineBuilding extends BuildingBase {
     kind: 'mine';
+    /** Identifier of the MineConfig that backs this building. */
+    mineId: string;
 }
 export interface RecipeLibraryBuilding extends BuildingBase {
     kind: 'recipe';

package/dist/location.js

@@ -28,5 +28,6 @@ export const buildingTypeToName = {
     soulShardDelve: 'Soul Shard',
     enchantmentShop: 'Enchantment Shop',
     challengeBoard: 'Challenge Board',
+    jadeCutter: 'Jade Cutter',
     modBuilding: '',
 };

package/dist/manual.d.ts

@@ -0,0 +1,8 @@
+import { Realm } from './realm';
+export interface Manual {
+    name: string;
+    icon: string;
+    realm: Realm;
+    techniques: string[];
+    stance: string[];
+}

package/dist/manual.js

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

package/dist/mineConfig.d.ts

@@ -0,0 +1,62 @@
+import type { Buff } from './buff';
+import type { EnemyEntity } from './entity';
+import type { FlareItem } from './item';
+import type { MineChamber } from './mine';
+import type { Realm, RealmProgress } from './realm';
+import type { Translatable } from './translatable';
+export interface MineStratum {
+    realm: Realm;
+    progress: RealmProgress;
+}
+export interface MineConfig {
+    /** Stable identifier used as the redux key for this mine's state. */
+    id: string;
+    /** Title shown on the mine chart dialog. */
+    chartTitle: Translatable;
+    /** Location name written into events that originate inside this mine. */
+    locationName: string;
+    /** Per-realm/progress chamber pools. */
+    chambers: {
+        [key in Realm]?: {
+            [key in RealmProgress]?: MineChamber[];
+        };
+    };
+    /** Per-realm pathing-monster pools used in inter-chamber combat. */
+    pathingMonsters: {
+        [key in Realm]?: EnemyEntity[];
+    };
+    /**
+     * Strata in depth order (top → bottom). The y/9 stratum index uses this
+     * directly, so the first entry is the surface stratum.
+     */
+    depthStrata: MineStratum[];
+    /**
+     * Optional sickness buff applied per delve. Stack count scales with the
+     * stratum's distance from the surface (same rule as Shadow Sickness:
+     * stratumIndex+1, minus 1 for the very first sub-stratum).
+     */
+    sicknessBuff?: Buff;
+    /** Game flag tracking the highest sickness-stack count ever applied. */
+    sicknessFlag?: string;
+    /**
+     * Stacks of `sicknessBuff` applied per delve. Receives the chamber's
+     * realm/progress so configs can scale by depth.
+     */
+    sicknessStacks?: (realm: Realm, progress: RealmProgress) => number;
+    /** Game flag tracking the deepest stratum the player has reached. */
+    depthFlag: string;
+    /** Flare item consumed when delving into a chamber. */
+    flareItem: FlareItem;
+    /** Combat intro flavor text used when fighting through corridors. */
+    combatIntroText: string;
+    /** Victory flavor text after pathing combat. */
+    combatVictoryText: string;
+    /** Defeat flavor text after pathing combat. */
+    combatDefeatText: string;
+    /** Music cue name (resolved against musicMap in AppRouter). */
+    music: string;
+    /** Ambience cue name (resolved against ambienceMap in AppRouter). */
+    ambience: string;
+}
+export declare const getMineStratumIndex: (y: number) => number;
+export declare const getMineStratumAt: (config: MineConfig, y: number) => MineStratum | undefined;

package/dist/mineConfig.js

@@ -0,0 +1,4 @@
+export const getMineStratumIndex = (y) => Math.floor(y / 9);
+export const getMineStratumAt = (config, y) => {
+    return config.depthStrata[getMineStratumIndex(y)];
+};

package/dist/mod.d.ts

@@ -7,9 +7,8 @@ import type { Background } from './background';
 import type { Breakthrough } from './breakthrough';
 import type { Buff } from './buff';
 import type { BreakthroughState } from './breakthrough';
-import type { CharactersState } from './reduxState';
 import type { CalendarEvent } from './calendar';
-import type { Character } from './character';
+import type { Character, CharacterDefinition, CharacterRelationship, CharacterRelationshipDefinition, CharacterState, CompanionCharacterDefinition, GiftCharacterInteraction } from './character';
 import type { CraftingTechnique, CraftingRecipeStats } from './craftingTechnique';
 import type { RecipeConditionEffect } from './crafting';
 import type { Destiny } from './destiny';
@@ -36,7 +35,7 @@ import type { CraftingCondition, HarmonyTypeConfig, RecipeHarmonyType } from './
 import type { ItemKind } from './item';
 import type { SoundEffectName } from './audio';
 import type { ScreenEffectType } from './ScreenEffectType';
-import type { RootState } from './reduxState';
+import type { RootState, CharactersState, InventoryState, FallenStarState } from './reduxState';
 import type { GameDialogFC, GameButtonExoticFC, GameIconButtonExoticFC, MemoBackgroundImageFC, GameTooltipFC, GameTooltipBoxFC, TooltipLineFC } from './components';
 import type { PuppetType } from './trainingGround';
 import type { TechniqueElement } from './element';
@@ -1449,6 +1448,15 @@ export interface ModAPI {
          * const maxQi = getMaxQi('coreFormation', 'Late');
          */
         getMaxQi: (realm: Realm, realmProgress: RealmProgress) => number;
+        /**
+         * Calculate the maximum Qi Droplets the player can hold based on their condensation art and breakthrough state.
+         * @param player - The player entity with realm and stats
+         * @param breakthrough - The current breakthrough state including condensation art and vessel
+         * @returns Maximum number of Qi Droplets the player can hold (0 if no vessel)
+         * @example
+         * const maxDroplets = utils.getMaxQiDroplets(player, breakthrough);
+         */
+        getMaxQiDroplets: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
         /**
          * Scale a numeric reward amount to a value appropriate for the player's realm and progress.
          * @param base - Base reward amount
@@ -1712,6 +1720,32 @@ export interface ModAPI {
          * const combatEntity = createEnemyCombatEntity(myEnemy, {});
          */
         createEnemyCombatEntity: (enemy: EnemyEntity, gameFlags: Record<string, number>) => CombatEntity;
+        /**
+         * Create a full CombatEntity from a player for combat tooltips and calculations.
+         * Applies breakthrough stats, scaling, destines, and mod hooks.
+         * @param player - Player entity definition
+         * @param breakthrough - Current breakthrough state
+         * @param gameFlags - (Optional) Current game flags
+         * @returns Fully resolved combat entity
+         * @example
+         * const combatEntity = createPlayerCombatEntity(player, breakthrough, {});
+         */
+        createPlayerCombatEntity: (player: PlayerEntity, breakthrough: BreakthroughState, gameFlags?: Record<string, number>) => CombatEntity;
+        /**
+         * Create a full CraftingEntity from a player for crafting tooltips and calculations.
+         * Applies breakthrough stats, crafting skill, characters, and mod hooks.
+         * @param player - Player entity definition
+         * @param breakthrough - Current breakthrough state
+         * @param characters - (Optional) Characters state for companion bonuses
+         * @param options - (Optional) Options such as noCompanionBuff
+         * @param gameFlags - (Optional) Current game flags
+         * @returns Fully resolved crafting entity
+         * @example
+         * const craftingEntity = createPlayerCraftingEntity(player, breakthrough);
+         */
+        createPlayerCraftingEntity: (player: PlayerEntity, breakthrough: BreakthroughState, characters?: CharactersState, options?: {
+            noCompanionBuff?: boolean;
+        }, gameFlags?: Record<string, number>) => CraftingEntity;
         /**
          * Convert a BattleLength enum value to a numeric time-to-kill multiplier.
          * @param battleLength - Battle length setting
@@ -1767,14 +1801,13 @@ export interface ModAPI {
          * @param defenderDefense - Defender's defense stat
          * @param defenderDr - Defender's damage reduction (0-1)
          * @param defenderDefenseFactor - Defense scaling factor
-         * @param maxReduction - Maximum damage reduction cap
          * @param defenderVulnerability - Vulnerability percentage
          * @param realm - Combat realm
          * @param realmProgress - Realm progress
          * @param defenderProtection - Defender's protection stat
          * @returns Final damage value
          */
-        calculateDamage: (attackPower: number, defenderDefense: number, defenderDr: number, defenderDefenseFactor: number, maxReduction: number, defenderVulnerability: number, realm: Realm, realmProgress: RealmProgress, defenderProtection: number, cultivatorResistance: number) => number;
+        calculateDamage: (attackPower: number, defenderDefense: number, defenderDr: number, defenderDefenseFactor: number, defenderVulnerability: number, realm: Realm, realmProgress: RealmProgress, defenderProtection: number, cultivatorResistance: number) => number;
         /**
          * Format a number for display (e.g. 1000 -> "1,000").
          * @param number - Number to format
@@ -2112,6 +2145,381 @@ export interface ModAPI {
          * @returns true if a save is currently loaded and game state is available, false otherwise.
          */
         getHasSaveLoaded: () => boolean;
+        /**
+         * Shuffle an array into a new random order.
+         * @param array - Array to shuffle
+         * @returns A new shuffled array (original is not mutated)
+         * @example
+         * const shuffled = shuffleArray([1, 2, 3, 4, 5]);
+         */
+        shuffleArray: <T>(array: T[]) => T[];
+        /**
+         * Get a random integer between min and max (inclusive).
+         * @param min - Minimum value (inclusive)
+         * @param max - Maximum value (inclusive)
+         * @returns Random integer
+         * @example
+         * const roll = randomInt(1, 100);
+         */
+        randomInt: (min: number, max: number) => number;
+        /**
+         * Capitalize the first letter of a string.
+         * @param str - String to capitalize
+         * @returns String with first letter uppercased
+         * @example
+         * capitalise('hello'); // 'Hello'
+         */
+        capitalise: (str: string) => string;
+        /**
+         * Generate a random Chinese-style name (surname + forename).
+         * @param sex - Optional gender bias: 'male', 'female', or undefined for random
+         * @returns Object with forename and surname strings
+         * @example
+         * const { forename, surname } = generateChineseName('female');
+         */
+        generateChineseName: (sex?: 'male' | 'female') => {
+            forename: string;
+            surname: string;
+        };
+        /**
+         * Get the combat stats of a character as an EnemyEntity.
+         * Useful for using character stats in custom combat encounters.
+         * @param character - The character definition
+         * @param characterData - The characters redux state
+         * @param flags - Current game flags
+         * @returns EnemyEntity built from the character's current stats
+         * @example
+         * const characterEntity = getCharacterStats(character, charactersState, flags);
+         * api.actions.startCombat([characterEntity], []);
+         */
+        getCharacterStats: (character: Character, characterData: CharactersState, flags: Record<string, number>) => EnemyEntity;
+        /**
+         * Get all active destinies for a player (applying upgradable destiny deduplication).
+         * @param player - The player entity
+         * @returns Array of active Destiny objects
+         * @example
+         * const destinies = getDestinies(player);
+         * for (const destiny of destinies) { ... }
+         */
+        getDestinies: (player: PlayerEntity) => Destiny[];
+        /**
+         * Calculate the player's total mastery points from dantian, month buffs, mount, clothing, and condensation art.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Total mastery points available
+         */
+        getMasteryPoints: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Get the player's total lifespan including destiny bonuses.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Total lifespan value
+         */
+        getLifeSpan: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Convert a battlesense stat value to its bonus amount.
+         * @param battlesense - The raw battlesense stat value
+         * @returns Bonus value (ceil(battlesense / 5))
+         * @example
+         * getBattlesenseBonus(25); // 5
+         */
+        getBattlesenseBonus: (battlesense: number) => number;
+        /**
+         * Calculate combat power from its component buckets.
+         * @param buckets - Power breakdown: basePower, enhancement, buffPower, affinityMult, boostMult, masteryMult
+         * @returns Total calculated power
+         */
+        calculatePower: (buckets: {
+            basePower: number;
+            enhancement: number;
+            buffPower: number;
+            affinityMult: number;
+            boostMult: number;
+            masteryMult: number;
+        }) => number;
+        /**
+         * Calculate raw qi absorption value for a player.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Raw qi absorption value
+         */
+        getQiAbsorption: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Calculate the qi absorption multiplier (how fast the player gains qi per tick).
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Absorption multiplier (e.g. 1.2 = 20% faster)
+         */
+        getQiAbsorptionMultiplier: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Calculate a mount's speed stat for a given realm and progress.
+         * @param realm - Cultivation realm
+         * @param realmProgress - Realm progress
+         * @param mult - Speed multiplier from the mount item
+         * @returns Mount speed value
+         */
+        getMountSpeed: (realm: Realm, realmProgress: RealmProgress, mult: number) => number;
+        /**
+         * Calculate the player's raw move speed value from mount, buffs, and condensation art enchantments.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Raw move speed value
+         */
+        getMoveSpeed: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Calculate the player's travel time multiplier from their move speed.
+         * Lower values mean faster travel. No mount is a significant penalty.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Travel time multiplier (e.g. 0.8 = 20% faster travel)
+         */
+        getMoveSpeedMultiplier: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Get a human-readable move speed string (e.g. "+20" or "-10").
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Formatted speed string
+         */
+        getReadableMoveSpeed: (player: PlayerEntity, breakthrough: BreakthroughState) => string;
+        /**
+         * Get the exploration bonus from the player's equipped mount.
+         * This is an additive bonus — a bonus of 1 means 1 explore counts as 2.
+         * @param player - The player entity
+         * @returns Exploration bonus count
+         */
+        getExplorationBonus: (player: PlayerEntity) => number;
+        /**
+         * Get the total exploration amount per explore action (base 1 + any bonuses).
+         * @param player - The player entity
+         * @returns Total exploration amount per action
+         */
+        getExplorationAmount: (player: PlayerEntity) => number;
+        /**
+         * Get the number of qi droplets produced per condensation action.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Number of droplets produced (0 if no vessel equipped)
+         */
+        getDropletProduction: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Calculate the effective toxicity of a pill before rounding.
+         * Applies toxicity resistance and realm-based scaling penalty.
+         * Use Math.ceil() in combat contexts and Math.floor() in crafting contexts.
+         * @param pill - Pill descriptor with toxicity and realm
+         * @param playerRealm - Player's current realm
+         * @param toxMultiplier - Player's toxicity resistance multiplier (1 = no resistance)
+         * @returns Effective toxicity before rounding
+         */
+        getEffectivePillToxicity: (pill: {
+            toxicity: number;
+            realm: Realm | 'any';
+        }, playerRealm: Realm, toxMultiplier: number) => number;
+        /**
+         * Get the additional toxicity multiplier when a player of consumerRealm takes a pill for pillRealm.
+         * Each realm above the consumer's realm adds 30% extra toxicity. Returns 0 for same or lower realm pills.
+         * @param consumerRealm - Player's current realm
+         * @param pillRealm - Realm the pill is intended for
+         * @returns Penalty multiplier (e.g. 0.3 = 30% extra toxicity per realm above)
+         */
+        getPillRealmPenalty: (consumerRealm: Realm, pillRealm: Realm) => number;
+        /**
+         * Get the expected physical stat value for a given realm.
+         * This is the base stat number before scaling.
+         * @param realm - Cultivation realm
+         * @returns Base physical stat number
+         */
+        getExpectedPhysicalStat: (realm: Realm) => number;
+        /**
+         * Get a scaled stat value for a given realm, progress and stat multiplier.
+         * Used to derive expected hp, power, defense etc. for enemies/items.
+         * @param realm - Cultivation realm
+         * @param progress - Realm progress
+         * @param statMultiplier - Multiplier for the specific stat (e.g. expectedHpPerFlesh)
+         * @returns Scaled stat value
+         */
+        getScaledStat: (realm: Realm, progress: RealmProgress, statMultiplier: number) => number;
+        /**
+         * Check whether two items match exactly (name, enchantment kind, enchantment rarity, quality tier, hidden potential).
+         * @param a - First item descriptor
+         * @param b - Second item descriptor
+         * @returns True if they match
+         */
+        itemsMatch: (a: ItemDesc | null | undefined, b: ItemDesc | null | undefined) => boolean;
+        /**
+         * Generate a unique string key for an item based on all identifying properties.
+         * Useful for Map keys and quick comparisons.
+         * @param item - Item descriptor
+         * @returns Unique key string
+         */
+        getItemKey: (item: ItemDesc) => string;
+        /**
+         * Find an item in an inventory array that exactly matches the desired item and has stacks > 0.
+         * @param desiredItem - Item descriptor to search for
+         * @param inventory - Array of inventory item states to search through
+         * @returns Matching inventory item or undefined
+         */
+        findMatchingItem: (desiredItem: ItemDesc, inventory: {
+            name: string;
+            stacks: number;
+            enchantment?: EnchantmentDesc;
+            qualityTier?: number;
+            hiddenPotential?: number;
+        }[]) => {
+            name: string;
+            stacks: number;
+            enchantment?: EnchantmentDesc;
+            qualityTier?: number;
+            hiddenPotential?: number;
+        } | undefined;
+        /**
+         * Compare two items for sorting purposes (techniques by subkind, enchantments by target, others alphabetically).
+         * @param a - First item
+         * @param b - Second item
+         * @returns Negative if a < b, positive if a > b, 0 if equal
+         */
+        compareItem: (a: Item, b: Item) => number;
+        /**
+         * Group items into realm-sorted buckets for list display.
+         * @param items - Items to group
+         * @param playerRealm - Player's current realm (items with realm 'any' appear here)
+         * @param categoryFilter - Filter by item kind or 'all'
+         * @param getValue - Optional sort-by-value function (descending); defaults to kind/rarity/name order
+         * @returns Object with sorted items array and group metadata
+         */
+        groupItems: (items: Item[], playerRealm: Realm, categoryFilter: 'all' | ItemKind, getValue?: (item: Item) => number) => {
+            items: Item[];
+            groups: {
+                realm: Realm;
+                count: number;
+            }[];
+        };
+        /**
+         * Group items into realm-sorted rows for grid display.
+         * @param items - Items to group
+         * @param itemsPerRow - How many items fit per row
+         * @param playerRealm - Player's current realm
+         * @param categoryFilter - Filter by item kind, 'all', or 'favourites'
+         * @param favoritedItems - Set of item keys for favourites filter
+         * @returns Object with rows and group metadata
+         */
+        groupItemsGrid: (items: Item[], itemsPerRow: number, playerRealm: Realm, categoryFilter: 'all' | 'favourites' | ItemKind, favoritedItems?: Set<string>) => {
+            rows: Item[][];
+            groups: {
+                realm: Realm;
+                count: number;
+            }[];
+        };
+        /**
+         * Group recipe items into realm-sorted buckets for list display.
+         * @param items - Recipe items to group
+         * @param playerRealm - Player's current realm
+         * @param categoryFilter - Filter by item kind, 'all', 'pinned', or 'pinned-upgrades'
+         * @param pinned - Optional array of pinned recipe names
+         * @returns Object with sorted items array and group metadata
+         */
+        groupRecipes: (items: RecipeItem[], playerRealm: Realm, categoryFilter: 'all' | 'pinned' | 'pinned-upgrades' | ItemKind, pinned?: string[]) => {
+            items: RecipeItem[];
+            groups: {
+                realm: Realm;
+                count: number;
+            }[];
+        };
+        /**
+         * Get the relationship category for a character based on their definition and state.
+         * @param def - Character definition (enemy/neutral/companion)
+         * @param relDef - Current relationship definition (from getRelationshipArray), if any
+         * @returns CharacterRelationship: 'Hostile', 'Neutral', or 'Friendly'
+         */
+        getCharacterRelationship: (def: CharacterDefinition, relDef: CharacterRelationshipDefinition | undefined) => CharacterRelationship;
+        /**
+         * Get the active relationship definition array for a character, accounting for relationship path branching.
+         * @param character - The character definition
+         * @param stateOrCharactersState - Either the full CharactersState or a single CharacterState
+         * @returns Array of CharacterRelationshipDefinition entries
+         */
+        getRelationshipArray: (character: Character, stateOrCharactersState: CharactersState | CharacterState) => CharacterRelationshipDefinition[];
+        /**
+         * Get the current active relationship definition for a character.
+         * @param character - The character definition
+         * @param stateOrCharactersState - Either the full CharactersState or a single CharacterState
+         * @returns The current CharacterRelationshipDefinition, or undefined if character has no data
+         */
+        getCurrentRelDef: (character: Character, stateOrCharactersState: CharactersState | CharacterState) => CharacterRelationshipDefinition | undefined;
+        /**
+         * Get the gift interaction available for a character at the current location.
+         * @param def - The companion character definition
+         * @param data - The character's current state data
+         * @param location - The current location name
+         * @param flags - Current game flags
+         * @returns The applicable GiftCharacterInteraction, or undefined if none available
+         */
+        getGiftInteraction: (def: CompanionCharacterDefinition, data: CharacterState, location: string, flags: Record<string, number>) => GiftCharacterInteraction | undefined;
+        /**
+         * Get the current location of a character based on their state and the player's position.
+         * @param character - The character definition
+         * @param state - The character's current state
+         * @param flags - Current game flags
+         * @param isFollowing - Whether the character is following the player
+         * @param currentPlayerLocation - The player's current location name
+         * @param starData - The fallen star state (for star-based character locations)
+         * @returns Location name string
+         */
+        getCharacterLocation: (character: Character, state: CharacterState, flags: Record<string, number>, isFollowing: boolean, currentPlayerLocation: string, starData: FallenStarState) => string;
+        /**
+         * Get the qi condense efficiency multiplier for a player.
+         * Higher values mean condensation costs less qi.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Efficiency multiplier (e.g. 1.2 = 20% more efficient)
+         */
+        getQiCondenseMultiplier: (player: PlayerEntity, breakthrough: BreakthroughState) => number;
+        /**
+         * Calculate the qi, money, and hp cost of a single condensation action.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @returns Object with qi, money, and hp costs
+         */
+        getCondensationCost: (player: PlayerEntity, breakthrough: BreakthroughState) => {
+            qi: number;
+            money: number;
+            hp: number;
+        };
+        /**
+         * Check whether the player can currently perform a condensation action.
+         * @param player - The player entity
+         * @param breakthrough - The current breakthrough state
+         * @param inventory - The current inventory state (for money check)
+         * @returns True if condensation can be performed
+         */
+        canCondense: (player: PlayerEntity, breakthrough: BreakthroughState, inventory: InventoryState) => boolean;
+        /**
+         * Discover all unlocked locations reachable from active root locations.
+         * Traverses the location graph following exploration and conditional links.
+         * @param flags - The current game flags
+         * @param unlocked - Array to populate with discovered locations (mutated in place)
+         */
+        discoverUnlockedLocations: (flags: Record<string, number>, unlocked: GameLocation[]) => void;
+        /**
+         * Get the flag name used to track whether an exploration link has been unlocked.
+         * @param location - The parent location
+         * @param child - The exploration link
+         * @returns Flag name string
+         */
+        getExplorationUnlockFlag: (location: GameLocation, child: ExplorationLink) => string;
+        /**
+         * Convert a PlayerEntity into an EnemyEntity that can be used in combat.
+         * Builds stance/rotation data from the player's stored stances and techniques.
+         * @param player - The player entity
+         * @param noEnhancement - If true, strips enhancement from all techniques (for fair mirror matches)
+         * @param breakthrough - The current breakthrough state
+         * @returns An EnemyEntity representing the player as an opponent
+         */
+        playerToEnemyEntity: (player: PlayerEntity, noEnhancement: boolean, breakthrough: BreakthroughState) => EnemyEntity;
+        /**
+         * The highest realm the player can normally reach through standard progression.
+         * Currently 'pillarCreation'. Use this to cap realm-scaled calculations.
+         */
+        maxRealm: Realm;
     };
     hooks: {
         /**

package/dist/reduxState.d.ts

@@ -220,7 +220,7 @@ export interface LocationHerbFieldState {
 export interface HerbFieldState {
     locations: Record<string, LocationHerbFieldState>;
 }
-export interface MineSliceState {
+export interface PerMineState {
     tiles: {
         [key: string]: MineTile;
     };
@@ -229,8 +229,15 @@ export interface MineSliceState {
     seed?: number;
     placedUniqueChambers?: string[];
 }
+export interface MineSliceState {
+    mines: {
+        [mineId: string]: PerMineState;
+    };
+}
 export interface MineViewportState {
-    mineViewport: Viewport | undefined;
+    viewports: {
+        [mineId: string]: Viewport | undefined;
+    };
 }
 export interface WorldMapViewportState {
     mapViewport: Viewport | undefined;
@@ -312,6 +319,12 @@ export interface StoneCuttingState {
     gainedItems: ItemDesc[];
     /** Snapshot of entire event state when stone cutting started, restored on completion */
     eventStateSnapshot?: GameEventState;
+    /** Percentage discount to apply to stone cutting costs (0-100) */
+    discountPercentage?: number;
+    /** Number of stones the player can cut for free */
+    freeCount?: number;
+    /** How many free stones have been used */
+    stonesBoughtForFree?: number;
 }
 export interface FallenStarState {
     activeSites: Record<string, FallenStarData>;
@@ -369,6 +382,16 @@ export interface HistoryItem {
     character?: string;
     buff?: Buff;
     items?: ItemDesc[];
+    money?: number;
+    favour?: number;
+    reputation?: {
+        name: string;
+        amount: number;
+    };
+    approval?: {
+        character: string;
+        amount: number;
+    };
     destiny?: string;
     quest?: string;
     craftingTechnique?: string;

package/dist/soulShardDelve.d.ts

@@ -55,6 +55,39 @@ export interface DelveRoom {
     description: string;
     stages: DelveRoomStage[];
 }
+/** Identifies the runtime behavior for a single step in a serialized DelveRoomConfig.
+ *  Each kind is bound to a builder in `buildDelveRoom` that produces the live `DelveRoomStage`. */
+export type CombatDelveRoomStepKind = 'mobCombat' | 'swarmCombat' | 'eliteCombat' | 'reinforcementCombat' | 'augmentedEliteCombat' | 'dualCombat' | 'tetheredCombat' | 'penaltyCombat';
+export type DelveRoomStepKind = CombatDelveRoomStepKind | 'reward' | 'blessing' | 'curse';
+interface BaseDelveRoomStepConfig {
+    kind: DelveRoomStepKind;
+}
+export interface CombatStepConfig extends BaseDelveRoomStepConfig {
+    kind: CombatDelveRoomStepKind;
+}
+export interface RewardStepConfig extends BaseDelveRoomStepConfig {
+    kind: 'reward';
+    pool: string;
+    increasedRarity: boolean;
+}
+export interface BlessingStepConfig extends BaseDelveRoomStepConfig {
+    kind: 'blessing';
+    count: number;
+}
+export interface CurseStepConfig extends BaseDelveRoomStepConfig {
+    kind: 'curse';
+    count: number;
+}
+export type DelveRoomStepConfig = CombatStepConfig | RewardStepConfig | BlessingStepConfig | CurseStepConfig;
+/** Pure-data, serializable description of a delve room. Lives on items. Functions
+ *  (such as enemy builders) are NOT stored here; they are looked up by step kind
+ *  via `buildDelveRoom`. */
+export interface DelveRoomConfig {
+    id: string;
+    displayName: Translatable;
+    description: string;
+    steps: DelveRoomStepConfig[];
+}
 /** A pre-placed cell in the soul shard grid (source, fixed node, or fixed routing shard). */
 export interface FixedGridCell {
     inputs?: {

package/dist/stat.d.ts

@@ -80,4 +80,5 @@ export interface Scaling {
     upgradeKey?: string;
     buff?: Buff;
     increment?: number;
+    cantUpgrade?: boolean;
 }

package/dist/stat.js

@@ -192,7 +192,7 @@ export const combatStatToDescription = {
     cloudBoost: '',
     bloodBoost: '',
     celestialBoost: '',
-    barrierMitigation: 'Controls how efficiently your barrier absorbs damage. Barrier always blocks damage first before health is lost.',
+    barrierMitigation: 'Controls how efficiently your barrier absorbs damage, with diminishing returns. Barrier always blocks damage first before health is lost.',
     qiDroplets: '',
     fistAffinity: '',
     blossomAffinity: '',

package/dist/technique.d.ts

@@ -88,6 +88,7 @@ interface ConsumeSelfTechniqueEffect extends BaseTechniqueEffect {
     buff: Buff;
     amount: Scaling;
     hideBuff?: boolean;
+    targeting?: EffectTargeting;
 }
 interface ConvertSelfTechniqueEffect extends BaseTechniqueEffect {
     kind: 'convertSelf';
@@ -153,6 +154,9 @@ interface ModifyBuffGroupEffect extends BaseTechniqueEffect {
     onTarget?: boolean;
     group: string;
     amount: Scaling;
+    /** Defaults to 'all'. 'highest'/'lowest' restrict the effect to a single matching buff
+     *  chosen by stack count. */
+    mode?: 'all' | 'highest' | 'lowest';
 }
 interface TriggerEffect extends BaseTechniqueEffect {
     kind: 'trigger';

package/dist/typeTests.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type Tests - These files ensure type compatibility across the codebase
+ * If any of these fail to compile, it means we have a type mismatch
+ */
+import type { RootState as StoreRootState } from '../store';
+import type { RootState as TypesRootState } from './reduxState';
+type TestExactMatch = StoreRootState extends TypesRootState ? TypesRootState extends StoreRootState ? true : false : false;
+export type RootStateIsConsistent = TestExactMatch;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "afnm-types",
-  "version": "0.6.56",
+  "version": "0.6.57",
   "description": "Type definitions for Ascend From Nine Mountains",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",