afnm-types 0.6.24 → 0.6.26

package/dist/alternativeStart.d.ts

@@ -0,0 +1,101 @@
+import { Tutorial } from './tutorial';
+import { TriggeredEvent, GameEvent } from './event';
+import { ItemDesc } from './item';
+import { PlayerEntity } from './entity';
+/**
+ * Configuration for an alternative game start.
+ * Mods can register alternative starts to provide different opening experiences,
+ * starting locations, and initial player setups.
+ */
+export interface AlternativeStart {
+    /**
+     * Unique identifier for this start (e.g., "defaultStart", "rogueStart")
+     */
+    name: string;
+    /**
+     * Display name shown in the UI (e.g., "Standard Start", "Rogue Cultivator")
+     */
+    displayName: string;
+    /**
+     * Description shown in the selection UI explaining this start option
+     */
+    description: string;
+    /**
+     * The root event that plays when starting the game.
+     * This replaces the default newGameEvent.
+     */
+    rootEvent: GameEvent;
+    /**
+     * The starting location name. This becomes the root for location discovery
+     * (used by discoverUnlockedLocations). All location searches will branch
+     * from this location.
+     */
+    startLocation: string;
+    /**
+     * Flags to set when starting the game (regardless of skip tutorial).
+     * These are set before the root event plays.
+     */
+    startFlags?: Record<string, number>;
+    /**
+     * Items to give the player at game start.
+     */
+    startItems?: ItemDesc[];
+    /**
+     * Technique names to teach the player at game start.
+     */
+    startTechniques?: string[];
+    /**
+     * Recipe names to teach the player at game start.
+     */
+    startRecipes?: string[];
+    /**
+     * Destiny names to grant the player at game start.
+     */
+    startDestinies?: string[];
+    /**
+     * Quest names to add to the player's quest log at game start.
+     */
+    startQuests?: string[];
+    /**
+     * Spirit stones to give at game start.
+     */
+    startMoney?: number;
+    /**
+     * Sect favour to give at game start.
+     */
+    startFavour?: number;
+    /**
+     * Custom tutorials for this start. If undefined, uses base game tutorials.
+     * These define what tutorials will play during the game.
+     */
+    tutorials?: Tutorial[];
+    /**
+     * Custom tutorial triggers for this start. If undefined, uses base game triggers.
+     * These are the triggered events that form the opening sequence.
+     */
+    tutorialTriggers?: TriggeredEvent[];
+    /**
+     * Additional flag names to set when the player chooses "Skip Tutorial".
+     * The system will automatically set the standard skip flags for the
+     * tutorials and tutorialTriggers arrays. Use this for any extra flags
+     * specific to your alternative start.
+     */
+    skipTutorialFlags?: string[];
+    /**
+     * Condition expression for this start to be available.
+     * If undefined, the start is always available.
+     * Example: "completedGameOnce" to require a previous completion.
+     */
+    condition?: string;
+    /**
+     * Optional function to modify the player entity after base setup.
+     * Called after backgrounds are applied but before the game starts.
+     */
+    modifyPlayer?: (player: PlayerEntity) => PlayerEntity;
+}
+/**
+ * Generates the flags that should be set when skipping tutorials.
+ * For each tutorial: sets {name}, {name}Started, {name}Completed
+ * For each trigger: sets {name}, {name}Started
+ */
+export declare const generateSkipTutorialFlags: (tutorials: Tutorial[], triggers: TriggeredEvent[]) => Record<string, number>;

package/dist/alternativeStart.js

@@ -0,0 +1,18 @@
+/**
+ * Generates the flags that should be set when skipping tutorials.
+ * For each tutorial: sets {name}, {name}Started, {name}Completed
+ * For each trigger: sets {name}, {name}Started
+ */
+export const generateSkipTutorialFlags = (tutorials, triggers) => {
+    const flags = {};
+    for (const tutorial of tutorials) {
+        flags[tutorial.name] = 1;
+        flags[tutorial.name + 'Started'] = 1;
+        flags[tutorial.name + 'Completed'] = 1;
+    }
+    for (const trigger of triggers) {
+        flags[trigger.name] = 1;
+        flags[trigger.name + 'Started'] = 1;
+    }
+    return flags;
+};

package/dist/breakthrough.d.ts

@@ -97,6 +97,7 @@ export interface RequirementResult {
 }
 export interface Breakthrough extends BreakthroughBase {
     unlocked?: (flags: Record<string, number>, args: RequirementArgs) => boolean;
+    hide?: string;
     hint?: ReactNode;
     requirements: ((args: RequirementArgs) => RequirementResult)[];
     totalRequirements: number | ((args: RequirementArgs) => number);

package/dist/buff.d.ts

@@ -56,7 +56,7 @@ export interface Buff {
     speed?: number;
     applicationStats?: Record<CombatStatistic, number>;
     applicationVariables?: Record<string, number>;
-    appliedByPlayer?: boolean;
+    appliedByOpponent?: boolean;
     allowMultipleInstances?: boolean;
     storedVariables?: Record<string, string>;
     uniqueId?: string;
@@ -79,6 +79,8 @@ export interface Buff {
     triggeredBuffEffects?: {
         trigger: string;
         effects: BuffEffect[];
+        /** If true, this trigger will also fire when the opponent triggers the same event */
+        listenToOpponent?: boolean;
     }[];
     damageInterceptorEffects?: {
         trigger?: TechniqueCondition;
@@ -247,6 +249,7 @@ interface CleanseToxicityEffect extends BaseBuff {
 }
 interface ModifyBuffGroupEffect extends BaseBuff {
     kind: 'modifyBuffGroup';
+    onTarget?: boolean;
     group: string;
     amount: Scaling;
 }

package/dist/craftingTechnique.d.ts

@@ -113,7 +113,7 @@ export interface CraftingRecipeStats {
     conditionType: RecipeConditionEffect;
     harmonyType: RecipeHarmonyType;
 }
-export type CraftingTechniqueMastery = ControlMastery | IntensityMastery | CritChanceTechniqueMastery | CritDamageTechniqueMastery | EffectTechniqueMastery | UpgradeCraftingTechniqueMastery | PoolCostMastery | StabilityCostMastery | SuccessChanceMastery;
+export type CraftingTechniqueMastery = ControlMastery | IntensityMastery | CritChanceTechniqueMastery | CritMultiplierTechniqueMastery | EffectTechniqueMastery | UpgradeCraftingTechniqueMastery | PoolCostMastery | StabilityCostMastery | SuccessChanceMastery;
 interface BaseCraftingTechniqueMastery {
     condition?: CraftingTechniqueCondition;
     tooltip?: string;
@@ -131,8 +131,8 @@ interface CritChanceTechniqueMastery extends BaseCraftingTechniqueMastery {
     kind: 'critchance';
     percentage: number;
 }
-interface CritDamageTechniqueMastery extends BaseCraftingTechniqueMastery {
-    kind: 'critdam';
+interface CritMultiplierTechniqueMastery extends BaseCraftingTechniqueMastery {
+    kind: 'critmultiplier';
     percentage: number;
 }
 interface EffectTechniqueMastery extends BaseCraftingTechniqueMastery {

package/dist/entity.d.ts

@@ -7,6 +7,15 @@ import { ArtefactItem, CombatItem, CombatPillItem, ConcoctionItem, CraftingEquip
 import { Realm, RealmProgress } from './realm';
 import { CombatStatsMap, CraftingStatsMap, PhysicalStatistic, SocialStatistic } from './stat';
 import { KnownTechnique, Technique, TechniquePriority } from './technique';
+export interface CombatEffectTracking {
+    icon: string;
+    background: string;
+    damage: number;
+    healing: number;
+    barrier: number;
+}
+export declare const entityTypes: readonly ["Player", "Lifeform", "Enemy"];
+export type EntityType = (typeof entityTypes)[number];
 export declare const sexes: readonly ["male", "female"];
 export type Sex = (typeof sexes)[number];
 export interface PlayerEntity {
@@ -209,7 +218,7 @@ export interface CombatArtefact extends ArtefactItem {
     animations: ('bump' | 'buff' | 'debuff' | 'attack')[];
 }
 export interface CombatEntity {
-    isPlayer: boolean;
+    entityType: EntityType;
     image: string;
     supportImage?: {
         image: string;
@@ -278,6 +287,7 @@ export interface CombatEntity {
         y: number;
     };
     disableBreathing?: boolean;
+    effectTracking: Record<string, CombatEffectTracking>;
 }
 export type StanceRule = SingleStance | RandomStance;
 export interface SingleStance {

package/dist/entity.js

@@ -1 +1,2 @@
+export const entityTypes = ['Player', 'Lifeform', 'Enemy'];
 export const sexes = ['male', 'female'];

package/dist/item.d.ts

@@ -357,6 +357,15 @@ export interface CondensationArtItem extends ItemBase {
     maxDroplets: number;
     restoredDroplets?: number;
     statChange: Partial<Record<PhysicalStatistic, number>>;
+    socialStatsChange?: Partial<Record<SocialStatistic, number>>;
+    combatBuffs?: {
+        buff: Buff;
+        buffStacks: Scaling;
+    }[];
+    craftingBuffs?: {
+        buff: CraftingBuff;
+        buffStacks: Scaling;
+    }[];
     lifespanMult?: number;
     charismaMult?: number;
 }

package/dist/mod.d.ts

@@ -33,6 +33,9 @@ import { ScreenEffectType } from './ScreenEffectType';
 import { RootState } from './reduxState';
 import { GameButtonFC, GameDialogFC, GameIconButtonFC, MemoBackgroundImageFC } from './components';
 import { PuppetType } from './trainingGround';
+import { TechniqueElement } from './element';
+import { AlternativeStart } from './alternativeStart';
+import { Tutorial } from './tutorial';
 export interface ModMetadata {
     name: string;
     version: string;
@@ -329,6 +332,26 @@ export interface ModAPI {
         itemTypeToHarmonyType: Record<ItemKind, RecipeHarmonyType>;
         puppets: PuppetType[];
         monsters: EnemyEntity[];
+        /**
+         * Registry of alternative game starts.
+         * The first entry is always the default start.
+         */
+        alternativeStarts: AlternativeStart[];
+        /**
+         * Tutorial system data for creating alternative starts.
+         */
+        tutorials: {
+            /**
+             * The tutorials that play during a new game (base game set).
+             * Use this as a reference when creating alternative starts.
+             */
+            newGameTutorials: Tutorial[];
+            /**
+             * The triggered events that form the opening sequence (base game set).
+             * Use this as a reference when creating alternative starts.
+             */
+            tutorialTriggers: TriggeredEvent[];
+        };
     };
     actions: {
         /**
@@ -608,6 +631,24 @@ export interface ModAPI {
          * @param puppet - Puppet configuration
          */
         addPuppetType: (puppet: PuppetType) => void;
+        /**
+         * Register an alternative game start.
+         * Alternative starts provide different opening experiences, starting locations,
+         * and initial player setups. Players can select from available starts when
+         * creating a new game.
+         * @param start - Alternative start configuration
+         * @example
+         * addAlternativeStart({
+         *   name: 'rogueStart',
+         *   displayName: 'Rogue Cultivator',
+         *   description: 'Begin as a wandering cultivator with no sect affiliation.',
+         *   rootEvent: rogueOpeningEvent,
+         *   startLocation: 'Liang Tiao Village',
+         *   startItems: [{ name: 'Tattered Robes', count: 1 }],
+         *   startMoney: 50,
+         * });
+         */
+        addAlternativeStart: (start: AlternativeStart) => void;
     };
     utils: {
         /**
@@ -961,6 +1002,85 @@ export interface ModAPI {
          * const mult = getPillRealmMultiplier('coreFormation');
          */
         getPillRealmMultiplier: (realm: Realm) => number;
+        /**
+         * Wrap text in a colored span for event text.
+         * @param text - Text to color
+         * @param col - CSS color value
+         * @returns HTML string with colored text
+         * @example
+         * col('Important!', '#ff0000');
+         */
+        col: (text: string | number, col: string) => string;
+        /**
+         * Format text as a location name (purple color).
+         * @param text - Location name
+         * @returns HTML string with location styling
+         * @example
+         * loc('Liang Tiao Village');
+         */
+        loc: (text: string | number) => string;
+        /**
+         * Format a realm with optional progress as styled text.
+         * @param realm - Cultivation realm
+         * @param progress - Optional realm progress
+         * @returns HTML string with realm styling
+         * @example
+         * rlm('coreFormation', 'Middle');
+         */
+        rlm: (realm: Realm, progress?: RealmProgress) => string;
+        /**
+         * Format a number with styling for event text.
+         * @param number - Number to format
+         * @returns HTML string with number styling
+         * @example
+         * num(1000); // Returns formatted "1,000" with styling
+         */
+        num: (number: string | number) => string;
+        /**
+         * Format text as a buff name (pink color).
+         * @param buff - Buff name
+         * @returns HTML string with buff styling
+         * @example
+         * buf('Empowered Blood');
+         */
+        buf: (buff: string) => string;
+        /**
+         * Format text as an item name (pink color).
+         * @param item - Item name
+         * @returns HTML string with item styling
+         * @example
+         * itm('Spirit Core (III)');
+         */
+        itm: (item: string) => string;
+        /**
+         * Format text as a character name (green color).
+         * @param text - Character name
+         * @returns HTML string with character styling
+         * @example
+         * char('Elder Zhang');
+         */
+        char: (text: string | number) => string;
+        /**
+         * Format a technique element with styling.
+         * @param element - Technique element type
+         * @returns HTML string with element styling
+         * @example
+         * elem('fire');
+         */
+        elem: (element: TechniqueElement) => string;
+        /**
+         * Generate the flags that should be set when skipping tutorials.
+         * For each tutorial: sets {name}, {name}Started, {name}Completed
+         * For each trigger: sets {name}, {name}Started
+         * Use this when creating alternative starts to ensure proper skip behavior.
+         * @param tutorials - Array of tutorials
+         * @param triggers - Array of triggered events
+         * @returns Record of flag names to values (all set to 1)
+         * @example
+         * const skipFlags = generateSkipTutorialFlags(myTutorials, myTriggers);
+         * // Returns { 'tutorialName': 1, 'tutorialNameStarted': 1, 'tutorialNameCompleted': 1, ... }
+         */
+        generateSkipTutorialFlags: (tutorials: Tutorial[], triggers: TriggeredEvent[]) => Record<string, number>;
     };
     hooks: {
         /**

package/dist/reduxState.d.ts

@@ -319,6 +319,12 @@ export interface NewGameState {
 export interface GameDataState {
     flags: Record<string, number>;
     mapExploration: Record<string, number>;
+    /**
+     * The root location name for location discovery.
+     * Defaults to "Nine Mountain Sect" if not set.
+     * Can be changed by alternative starts.
+     */
+    discoveryRoot?: string;
 }
 export interface HistoryItem {
     text: string;

package/dist/stat.d.ts

@@ -3,7 +3,7 @@ import { TechniqueElement } from './element';
 export declare const physicalStatistics: readonly ["eyes", "meridians", "dantian", "muscles", "digestion", "flesh"];
 export declare const socialStatistics: readonly ["age", "lifespan", "charisma", "battlesense", "craftskill", "artefactslots", "talismanslots", "condenseEfficiency", "pillsPerRound"];
 export declare const craftingStatistics: readonly ["maxpool", "pool", "maxtoxicity", "toxicity", "resistance", "itemEffectiveness", "control", "intensity", "critchance", "critmultiplier", "pillsPerRound", "poolCostPercentage", "stabilityCostPercentage", "successChanceBonus"];
-export declare const combatStatistics: readonly ["maxhp", "hp", "maxbarrier", "barrier", "maxtoxicity", "toxicity", "resistance", "pillsPerRound", "itemEffectiveness", "power", "artefactpower", "critchance", "defense", "dr", "barrierMitigation", "lifesteal", "critdam", "vulnerability", "fistBoost", "blossomBoost", "weaponBoost", "cloudBoost", "bloodBoost", "celestialBoost", "fistAffinity", "blossomAffinity", "weaponAffinity", "cloudAffinity", "bloodAffinity", "celestialAffinity", "noneAffinity", "qiDroplets", "fistDisabled", "bloodDisabled", "blossomDisabled", "cloudDisabled", "celestialDisabled", "weaponDisabled", "fistResistance", "blossomResistance", "weaponResistance", "cloudResistance", "bloodResistance", "celestialResistance"];
+export declare const combatStatistics: readonly ["maxhp", "hp", "maxbarrier", "barrier", "maxtoxicity", "toxicity", "resistance", "pillsPerRound", "itemEffectiveness", "power", "artefactpower", "critchance", "defense", "dr", "barrierMitigation", "lifesteal", "critmultiplier", "vulnerability", "weakness", "fistBoost", "blossomBoost", "weaponBoost", "cloudBoost", "bloodBoost", "celestialBoost", "fistAffinity", "blossomAffinity", "weaponAffinity", "cloudAffinity", "bloodAffinity", "celestialAffinity", "noneAffinity", "qiDroplets", "fistDisabled", "bloodDisabled", "blossomDisabled", "cloudDisabled", "celestialDisabled", "weaponDisabled", "fistResistance", "blossomResistance", "weaponResistance", "cloudResistance", "bloodResistance", "celestialResistance"];
 export type PhysicalStatistic = (typeof physicalStatistics)[number];
 export type SocialStatistic = (typeof socialStatistics)[number];
 export type CraftingStatistic = (typeof craftingStatistics)[number];
@@ -63,6 +63,11 @@ export interface Scaling {
     scaling?: 'stacks' | 'consumed' | string;
     eqn?: string;
     additiveEqn?: string;
+    customScaling?: {
+        multiplier: number;
+        scaling: 'stacks' | 'consumed' | string;
+        upgradeKey?: string;
+    };
     max?: Scaling;
     divideByStanceLength?: boolean;
     upgradeKey?: string;

package/dist/stat.js

@@ -50,8 +50,9 @@ export const combatStatistics = [
     'dr',
     'barrierMitigation',
     'lifesteal',
-    'critdam',
+    'critmultiplier',
     'vulnerability',
+    'weakness',
     'fistBoost',
     'blossomBoost',
     'weaponBoost',
@@ -106,8 +107,9 @@ export const combatStatToName = {
     dr: 'Damage Resistance',
     barrierMitigation: 'Barrier Effectiveness',
     lifesteal: 'Life Steal',
-    critdam: 'Crit Damage',
+    critmultiplier: 'Crit Multiplier',
     vulnerability: 'Vulnerability',
+    weakness: 'Weakness',
     fistBoost: 'Fist Boost',
     blossomBoost: 'Blossom Boost',
     weaponBoost: 'Weapon Boost',
@@ -149,9 +151,10 @@ export const combatStatToDescription = {
     defense: 'Your resistance to damage.',
     dr: '',
     lifesteal: '',
-    critchance: 'Your chance to get a critical effect, increasing the power of your techniques. Crit chance over 100% enables additional crits.',
-    critdam: '',
+    critchance: 'Your chance to get a critical effect on damage, healing, and barrier. Crit chance over 100% converts to bonus crit damage at a 1:3 ratio.',
+    critmultiplier: '',
     vulnerability: '',
+    weakness: '',
     artefactpower: "The strength of your artefact's techniques and your Formation Parts.",
     fistBoost: '',
     blossomBoost: '',
@@ -202,7 +205,7 @@ export const craftingStatToName = {
 export const craftingStatToDescription = {
     maxtoxicity: 'The quantity of pills you can take before your body becomes unable to digest any more.',
     toxicity: '',
-    critchance: 'Your chance to get a critical effect on increasing perfection or completion. Crit chance over 100% enables additional crits',
+    critchance: 'Your chance to get a critical effect on increasing perfection or completion. Crit chance over 100% converts to bonus crit multiplier at a 1:3 ratio.',
     maxpool: 'The amount of <b>Qi</b> you have available during crafting to spend on crafting actions.',
     pool: '',
     control: 'The <b>perfection</b> your refinement actions impart during crafting, making it easier to perfect a recipe.',
@@ -251,7 +254,7 @@ export const physicalStatToDescription = {
     muscles: 'Your ability to use your body to project force. Affects your crafting <b>Qi Intensity</b> and combat <b>Power</b>.',
     dantian: 'Your ability to store and channel Qi. Affects your combat <b>Max Barrier</b>, crafting <b>Max Qi Pool</b>, <b>Qi Absorption</b>, and <b>Technique Mastery Points</b>.',
     meridians: 'Your ability to control Qi. Affects crafting <b>Qi Control</b> and combat <b>Artefact Power</b>.',
-    eyes: 'Your ability to perceive the fine details in the world around you. Affects <b>Critical Chance</b> and <b>Critical Damage</b>.',
+    eyes: 'Your ability to perceive the fine details in the world around you. Affects <b>Critical Chance</b> and <b>Critical Multiplier</b>.',
 };
 export const reputationDescription = 'Reputation affects a factions attitude towards you. High reputation reduces prices, unlocks quests, and allows the purchase of valuable items.';
 export const reputationPerTier = 5;

package/dist/technique.d.ts

@@ -62,6 +62,7 @@ interface BaseTechniqueEffect {
     kind: TechniqueEffectKind;
     condition?: TechniqueCondition;
     triggerKey?: string;
+    isAdditionalTooltip?: boolean;
 }
 interface BuffSelfTechniqueEffect extends BaseTechniqueEffect {
     kind: 'buffSelf';
@@ -139,7 +140,7 @@ interface TriggerEffect extends BaseTechniqueEffect {
     amount: Scaling;
     triggerTooltip?: string;
 }
-export type TechniqueMastery = PowerTechniqueMastery | EffectTechniqueMastery | CritChanceTechniqueMastery | CritDamageTechniqueMastery | UpgradeTechniqueMastery;
+export type TechniqueMastery = PowerTechniqueMastery | EffectTechniqueMastery | CritChanceTechniqueMastery | CritMultiplierTechniqueMastery | UpgradeTechniqueMastery;
 interface BaseTechniqueMastery {
     condition?: TechniqueCondition;
     tooltip?: string;
@@ -153,8 +154,8 @@ interface CritChanceTechniqueMastery extends BaseTechniqueMastery {
     kind: 'critchance';
     percentage: number;
 }
-interface CritDamageTechniqueMastery extends BaseTechniqueMastery {
-    kind: 'critdam';
+interface CritMultiplierTechniqueMastery extends BaseTechniqueMastery {
+    kind: 'critmultiplier';
     percentage: number;
 }
 interface EffectTechniqueMastery extends BaseTechniqueMastery {

package/package.json

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