Adding Mod Resolvers

Overview

Mod resolvers are push* functions defined inside resolveModsForOffenseSkill in src/tli/calcs/offense.ts. They read from the mods array (and optionally config, prenormMods, resourcePool, defenses) and push new derived mods based on game mechanics. Each resolver handles one mechanic (e.g., frostbite, numbed, tangles, infiltrations).

When to Use

Adding a new combat mechanic that derives mods from existing mods or configuration
Adding conditional damage bonuses based on presence of a flag mod (e.g., IsTangle, WindStalker)
Adding enemy debuff calculations (e.g., numbed stacks, frostbite, frail)
Adding buff/aura effect calculations with effect multipliers

Project File Locations

Purpose	File Path
Resolver function location	`src/tli/calcs/offense.ts` (inside `resolveModsForOffenseSkill`)
Mod type definitions	`src/tli/mod.ts` (`ModDefinitions` interface)
Configuration interface & defaults	`src/tli/core.ts` (`Configuration`, `DEFAULT_CONFIGURATION`)
Mod helper utilities	`src/tli/calcs/mod-utils.ts`
Tests	`src/tli/calcs/offense.test.ts`

Architecture

applyModFilters preprocesses all mods into four groups:

mods — non-per mods without condThreshold or resolvedCond (ready to use immediately)
prenormMods — all mods without resolvedCond (source for per-stackable normalization)
condThresholdMods — non-per mods with condThreshold (pushed back by normalize() when threshold is met)
resolvedCondMods — mods with resolvedCond (pushed back by individual push* resolvers when condition is met)

IMPORTANT: Mods with a per field are filtered into prenormMods only — they do NOT appear in mods. The per field (from ModBase) triggers automatic per-stackable normalization via normalize(). If a mod needs custom resolver logic (e.g., applying an effect multiplier before scaling by stacks), do NOT use per on the mod type. Instead, store the scaling info in a custom field (e.g., perFervorAmt: number) so the mod stays in mods and the resolver can find it via filterMods().

resolveModsForOffenseSkill then runs a sequence of push* resolver functions that push new derived mods into mods via pm(). Each push* function is a closure that captures:

mods: Mod[] — the shared mutable array of resolved mods
prenormMods — mods needing per-stackable normalization
condThresholdMods — mods held back until their stackable threshold is evaluated by normalize()
resolvedCondMods — mods held back until their resolved condition is evaluated by a push* resolver
config: Configuration — user-configured combat parameters
resourcePool — stats, mana, blessings, etc.
defenses — armor, evasion, resistances, etc.
loadout: Loadout — full parsed loadout
Helper functions: pm() (push mods), normalize() (normalize stackables), step() (dependency tracking)

The execution sequence begins with normalizeFromConfig(), which normalizes all stackables whose values come purely from config fields (e.g., level, num_enemies_nearby, enemy_numbed_stacks). This runs before pushStatNorms() and all other resolvers. Normalize calls whose values depend on mods, stats, defenses, or resourcePool remain in their respective push* functions or inline in the execution sequence.

Available Helpers

From closure (defined in resolveModsForOffenseSkill):

pm(...ms: Mod[]) — shorthand for mods.push(...ms)
normalize(stackable, value) — normalizes per-stackable mods from prenormMods and pushes satisfied condThresholdMods for that stackable
normalizeFromConfig() — calls normalize() for all stackables whose values come purely from config fields; called once at the start of the execution sequence before pushStatNorms()
step(stepName) — registers a step for dependency tracking (only needed if other steps depend on this one)
resolvedCondMods: Mod[] — mods with resolvedCond, separated out by applyModFilters; push matching ones into mods via pm() when the condition is met
condThresholdMods: Mod[] — non-per mods with condThreshold, separated out by applyModFilters; pushed back automatically by normalize() when their stackable threshold is met

From src/tli/calcs/mod-utils.ts:

modExists(mods, "ModType") — returns boolean, checks if any mod of that type exists
findMod(mods, "ModType") — returns first mod of type or undefined
filterMods(mods, "ModType") — returns all mods of type as ModT<T>[]
sumByValue(mods) — sums .value of all mods in array
calcEffMult(mods, "ModType") — calculates (1 + sum_of_inc) * product_of_addn multiplier
multModValue(mod, multiplier) — returns new mod with .value multiplied

Implementation Checklist

1. Ensure the Trigger Mod Type Exists

Check src/tli/mod.ts under ModDefinitions. If the flag mod (e.g., IsTangle) doesn't exist, add it:

// In ModDefinitions
IsTangle: object;  // flag mod, no fields

For mods with data:

NumbedEffPct: { value: number };

2. Ensure Configuration Fields Exist (if needed)

If the resolver needs user-configurable values, ensure they exist in src/tli/core.ts. Use the /add-configuration skill if they don't.

3. Write the push* Function

Define the function inside resolveModsForOffenseSkill, near related resolvers. Follow these patterns:

Simple flag-based resolver (multiplies damage by a config value):

const pushTangle = (): void => {
  if (!modExists(mods, "IsTangle") || config.numActiveTangles <= 1) return;
  mods.push({
    type: "DmgPct",
    dmgModType: "global",
    addn: true,
    value: (config.numActiveTangles - 1) * 100,
    src: "Tangle",
  });
};

Debuff with effect multiplier:

const pushNumbed = (): void => {
  if (!config.enemyNumbed) return;
  const numbedStacks = config.enemyNumbedStacks ?? 10;
  const numbedEffMult = calcEffMult(mods, "NumbedEffPct");
  const baseValPerStack = 5;
  const numbedVal = baseValPerStack * numbedEffMult * numbedStacks;
  mods.push({
    type: "DmgPct",
    value: numbedVal,
    dmgModType: "lightning",
    addn: true,
    isEnemyDebuff: true,
    src: "Numbed",
  });
};

Buff with effect multiplier (e.g., aggression, mark):

const pushMark = (): void => {
  if (!config.targetEnemyMarked) return;
  const markEffMult = calcEffMult(mods, "MarkEffPct");
  const baseValue = 20;
  mods.push({
    type: "CritDmgPct",
    value: baseValue * markEffMult,
    addn: true,
    modType: "global",
    isEnemyDebuff: true,
    src: "Mark",
  });
};

Resolver with per-stackable normalization:

const pushPactspirits = () => {
  const addedMaxStacks = sumByValue(filterMods(mods, "MaxPureHeartStacks"));
  const maxStacks = 5 + addedMaxStacks;
  const stacks = config.pureHeartStacks ?? maxStacks;
  normalize("pure_heart", stacks);
};

Config-only normalization (add to normalizeFromConfig):

If the stackable value comes purely from config fields (no dependency on mods, stats, defenses, or resourcePool), add the normalize() call inside normalizeFromConfig() instead of creating a separate push* function or placing it inline in the execution sequence:

const normalizeFromConfig = (): void => {
  // ... existing config-based normalizes ...
  normalize("new_stackable", config.newStackableValue ?? defaultValue);
};

Only use a separate push* function or inline normalize() when the value depends on computed data (mods, stats, etc.), or when the value has a config override with a mod-computed fallback (e.g., config.stacks ?? maxStacksFromMods).

Resolved condition resolver (conditions that depend on calculated values):

Some mod conditions can't be evaluated statically from configuration — they depend on values calculated earlier in resolveModsForOffenseSkill (e.g., sealed mana/life percentages come from resourcePool.sealedResources, not config). These use resolvedCond on the mod (see ResolvedCondition in mod.ts) instead of cond (which is for static Configuration-based conditions evaluated in filterModsByCond).

Mods with resolvedCond are separated out by applyModFilters into resolvedCondMods. The push* resolver filters for its condition and pushes matching mods into mods via pm() when the condition is met.

const pushHasSealedLifeAndManaCond = (): void => {
  const { sealedManaPct, sealedLifePct } = resourcePool.sealedResources;
  if (sealedManaPct <= 0 || sealedLifePct <= 0) return;
  pm(
    ...resolvedCondMods.filter(
      (m) => m.resolvedCond === "have_both_sealed_mana_and_life",
    ),
  );
};

To add a new resolved condition:

Add the condition string to ResolvedConditions in src/tli/mod.ts
In the mod parser template (src/tli/mod-parser/templates.ts), use resolvedCond: "condition_name" instead of cond: "condition_name"
Write a push* resolver that filters resolvedCondMods and pushes matching mods via pm(), and call it at the appropriate point in the execution sequence

Resolver with step dependencies (when one resolver produces mods consumed by another):

Use step() and stepDeps whenever a resolver pushes mods that another resolver later reads. For example, pushFervor generates SkillAreaPct mods, so pushSkillArea depends on it. The dependency graph is validated at test time — if pushSkillArea runs before pushFervor, an error is recorded.

const stepDeps = createSelfReferential({
  // ... existing steps ...
  fervor: [],
  skillArea: ["fervor"],  // skillArea must run after fervor
});

Call step() at the top of each resolver:

const pushFervor = () => {
  step("fervor");
  if (resourcePool.hasFervor) {
    mods.push(calculateFervorCritRateMod(mods, resourcePool));
    mods.push(...calculateFervorBaseEffSkillArea(mods, resourcePool));
    normalize("fervor", resourcePool.fervorPts);
  }
};

const pushSkillArea = (): void => {
  step("skillArea");
  const skillAreaPct = sumByValue(filterMods(mods, "SkillAreaPct"));
  normalize("skill_area", skillAreaPct);
};

Ensure the call order in the execution sequence matches the dependency graph (dependent runs after dependency):

pushFervor();    // must come first
pushSkillArea(); // depends on fervor

step() always goes at the top of the resolver, before any early returns, so the step is registered even if the resolver short-circuits.

4. Call the Function

Add the call in the execution sequence inside resolveModsForOffenseSkill. Place it near related mechanics.

5. Verify

pnpm test
pnpm typecheck
pnpm check

Common Patterns

Pattern	When to Use	Key Helper
Check flag mod exists	Mechanic only applies when a specific support/skill mod is present	`modExists(mods, "FlagMod")`
Check config boolean	Mechanic depends on user toggle	`if (!config.someToggle) return`
Effect multiplier	Buff/debuff has mods that scale its effectiveness	`calcEffMult(mods, "SomeEffPct")`
Config stacks with default	User can override stack count, defaults to max	`config.someStacks ?? maxStacks`
Normalize stackable	Mechanic involves per-stackable scaling with computed value	`normalize("stackable_name", value)`
Config-only normalize	Stackable value comes purely from config	Add to `normalizeFromConfig()`
Filter by resolved condition	Condition depends on calculated values, not static config	`pm(...resolvedCondMods.filter(...))`
`addn: true` on DmgPct	More multiplier (multiplicative with other `addn: true` mods)	—
`addn: false` on DmgPct	Increased multiplier (additive with other `addn: false` mods)	—
`isEnemyDebuff: true`	Damage increase from enemy debuff (for display grouping)	—
`src: "Name"`	Label for debug/display panel	—

DmgPct addn Field

The addn (additional) field on DmgPct controls how the damage bonus stacks:

addn: false — Increased damage. All addn: false mods sum together into one multiplier: (1 + sum).
addn: true — More damage. Each addn: true mod is its own separate multiplier: (1 + value1) * (1 + value2) * ...

Most resolvers use addn: true because their effects are multiplicative with other damage sources.

Common Mistakes

Mistake	Fix
Forgetting early return when flag/config is absent	Always guard with `if (!condition) return`
Using `addn: false` when the mechanic should be multiplicative	Use `addn: true` for separate "more" multipliers
Pushing mods without `src`	Always include `src` for debug panel visibility
Forgetting to add config field	Use `/add-configuration` skill first
Missing `step()` when a resolver produces mods consumed by another	Add both steps to `stepDeps` with the dependency, and call `step()` at the top of each resolver
Not matching execution order to `stepDeps`	The call order must satisfy the dependency graph — dependent resolvers run after their dependencies
Not handling undefined config with `??`	Optional config values need fallback: `config.stacks ?? defaultMax`
Placing config-only normalize inline in execution sequence	Add to `normalizeFromConfig()` instead; only use inline/push* for computed values
Using `per` on a mod that needs custom resolver logic	Mods with `per` go to `prenormMods`, not `mods`, so `filterMods(mods, ...)` won't find them. Use a custom field (e.g., `perFervorAmt: number`) instead so the mod stays in `mods` for the resolver to read

add-mod-resolver