afnm-types 0.6.25 → 0.6.27

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

@@ -95,13 +95,36 @@ export interface RequirementResult {
     done: boolean;
     preview: ReactNode;
 }
+/**
+ * Defines which items are allowed in breakthrough slots.
+ * Each slot type maps to an array of allowed item names.
+ * When a breakthrough defines allowed items for a slot, those items
+ * will be available in that slot's UI.
+ */
+export interface BreakthroughAllowedSlotItems {
+    awakeningPill?: string[];
+    brain?: string[];
+    heart?: string[];
+    pill?: string[];
+    groin?: string[];
+    minorMeridian?: string[];
+    greaterMeridian?: string[];
+    vessel?: string[];
+}
 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);
     getNumDone: (args: RequirementArgs) => number;
     extraEffects?: string[];
+    /**
+     * Defines which items are allowed in breakthrough slots for this breakthrough.
+     * When breakthroughs specify allowed items, those items become available in the slot UI.
+     * The game aggregates allowed items from ALL breakthroughs in a realm, including mod-added ones.
+     */
+    allowedSlotItems?: BreakthroughAllowedSlotItems;
     dynamicStats?: (args: RequirementArgs) => {
         physicalStats: Partial<{
             [key in PhysicalStatistic]: number;

package/dist/buff.d.ts

@@ -249,6 +249,7 @@ interface CleanseToxicityEffect extends BaseBuff {
 }
 interface ModifyBuffGroupEffect extends BaseBuff {
     kind: 'modifyBuffGroup';
+    onTarget?: boolean;
     group: string;
     amount: Scaling;
 }

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

@@ -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

@@ -254,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';

package/package.json

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