Adding Mod Parsers

Overview

The mod parser converts raw mod strings (e.g., "+10% all stats") into typed Mod objects used by the calculation engine. It uses a template-based system for pattern matching.

When to Use

• Adding support for new mod string patterns
• Extending existing mod types to handle new variants
• Adding new mod types to the engine

Project File Locations

Implementation Checklist

1. Check if Mod Type Exists

Look in src/tli/mod.ts under ModDefinitions. If the mod type doesn't exist, add it:

typescript
1interface ModDefinitions {
2  // ... existing types ...
3  NewModType: { value: number; someField: string };
4}

2. Add Template in templates.ts

Templates use a DSL for pattern matching. Do not add comments to templates.ts - the template string itself is self-documenting.

typescript
1t("{value:dec%} all stats").output((c) => ({
2  type: "StatPct",
3  value: c.value,
4  statModType: "all",
5})),
6t("{value:dec%} {statModType:StatWord}")
7  .enum("StatWord", StatWordMapping)
8  .output((c) => ({ type: "StatPct", value: c.value, statModType: c.statModType })),
9t("{value:dec%} [additional] [{modType:DmgModType}] damage").output((c) => ({
10  type: "DmgPct",
11  value: c.value,
12  dmgModType: c.modType ?? "global",
13  addn: c.additional !== undefined,
14})),
15t("{value:dec%} attack and cast speed").outputMany([
16  spec((c) => ({ type: "AspdPct", value: c.value, addn: false })),
17  spec((c) => ({ type: "CspdPct", value: c.value, addn: false })),
18]),

Template capture types:

Signed vs Unsigned vs Optional-sign Types:

• Use unsigned (dec%, int) when input NEVER has + or - (e.g., "8% additional damage applied to Life")
• Use signed (+dec%, +int) when input ALWAYS has + or - (e.g., "+25% additional damage")
• Use optional-sign (?dec%, ?int) when input MAY OR MAY NOT have a sign — this avoids needing two separate templates for signed/unsigned variants
• Signed types will NOT match unsigned inputs, and unsigned will NOT match signed inputs
• Prefer ?dec% over two separate dec%/+dec% templates when the same mod can appear with or without a sign

Optional syntax:

• [additional] - Optional literal, sets c.additional?: true
• [{modType:DmgModType}] - Optional capture, sets c.modType?: DmgModType
• {(effect|damage)} - Alternation (regex-style)

3. Add Enum Mapping (if needed)

If you need custom word → value mapping, add to enums.ts:

typescript
1export const StatWordMapping: Record<string, string> = {
2  strength: "str",
3  dexterity: "dex",
4  intelligence: "int",
5};
6
7registerEnum("StatWord", ["strength", "dexterity", "intelligence"]);

4. Add Handler in offense.ts (if new mod type)

If you added a new mod type, add handling in calculateOffense() or relevant helper:

typescript
1case "NewModType": {
2  break;
3}

For existing mod types with new variants (like adding statModType: "all"), update existing handlers to also filter for the new variant:

typescript
1const flat = sumByValue(
2  statMods.filter((m) => m.statModType === statType || m.statModType === "all"),
3);

5. Add Tests

Add test cases in src/tli/mod_parser.test.ts:

typescript
1test("parse percentage all stats", () => {
2  const result = parseMod("+10% all stats");
3  expect(result).toEqual([
4    {
5      type: "StatPct",
6      statModType: "all",
7      value: 10,
8    },
9  ]);
10});

6. Verify

bash
1pnpm test src/tli/mod_parser.test.ts
2pnpm typecheck
3pnpm check

Template Ordering

IMPORTANT: More specific patterns must come before generic ones in allParsers array.

typescript
1// Good: specific before generic
2t("{value:dec%} all stats").output(...),           // Specific
3t("{value:dec%} {statModType:StatWord}").output(...), // Generic
4
5// Bad: generic would match first and fail on "all stats"

Examples

Simple Value Parser (Signed)

Input: "+10% all stats" (starts with +)

typescript
1t("{value:+dec%} all stats").output((c) => ({
2  type: "StatPct",
3  value: c.value,
4  statModType: "all",
5})),

Simple Value Parser (Unsigned)

Input: "8% additional damage applied to Life" (no sign)

typescript
1t("{value:dec%} additional damage applied to life").output((c) => ({
2  type: "DmgPct",
3  value: c.value,
4  dmgModType: "global",
5  addn: true,
6})),

Parser with Condition (Signed)

Input: "+40% damage if you have Blocked recently"

typescript
1t("{value:+dec%} damage if you have blocked recently").output((c) => ({
2  type: "DmgPct",
3  value: c.value,
4  dmgModType: "global",
5  addn: false,
6  cond: "has_blocked_recently",
7})),

Parser with Per-Stackable (Signed in "deals" position)

Input: "Deals +1% additional damage to an enemy for every 2 points of Frostbite Rating the enemy has"

Note: The + appears AFTER "deals", so use {value:+dec%}:

typescript
1t("deals {value:+dec%} additional damage to an enemy for every {amt:int} points of frostbite rating the enemy has")
2  .output((c) => ({
3    type: "DmgPct",
4    value: c.value,
5    dmgModType: "global",
6    addn: true,
7    per: { stackable: "frostbite_rating", amt: c.amt },
8  })),

Multi-Output Parser (Signed)

Input: "+6% attack and cast speed"

typescript
1t("{value:+dec%} [additional] attack and cast speed").outputMany([
2  spec((c) => ({ type: "AspdPct", value: c.value, addn: c.additional !== undefined })),
3  spec((c) => ({ type: "CspdPct", value: c.value, addn: c.additional !== undefined })),
4]),

Flat Stat Parser (Signed)

Input: "+166 Max Mana"

typescript
1t("{value:+dec} max mana").output((c) => ({ type: "MaxMana", value: c.value })),

Optional-Sign Parser

Input: "12.5% Sealed Mana Compensation for Spirit Magus Skills" OR "+12.5% Sealed Mana Compensation for Spirit Magus Skills"

Use ?dec% when the same mod string can appear with or without a +/- sign, avoiding the need for two separate templates:

typescript
1t("{value:?dec%} sealed mana compensation for spirit magus skills").output(
2  (c) => ({ type: "SealedManaCompPct", value: c.value, addn: false, skillType: "spirit_magus" }),
3),

No-Op Parser (Recognized but produces no mods)

Input: "Energy Shield starts to Charge when Blocking"

Use outputNone() when a mod string should be recognized (not flagged as unparsed) but has no effect on calculations:

typescript
1t("energy shield starts to charge when blocking").outputNone(),

Common Mistakes

Data Flow

Raw string: "+10% all stats"
    ↓ normalize (lowercase, trim)
"10% all stats"
    ↓ template matching (allParsers)
{ type: "StatPct", value: 10, statModType: "all" }
    ↓ calculateStats() in offense.ts
Applied to str, dex, int calculations