Adding Mod Parsers

Overview

The mod parser converts raw mod strings (e.g.,

"+10% all stats"

Mod

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

src/tli/mod.ts

src/tli/mod-parser/templates.ts

src/tli/mod-parser/enums.ts

src/tli/calcs/offense.ts

src/tli/mod-parser.test.ts

Implementation Checklist

1. Check if Mod Type Exists

Look in

src/tli/mod.ts

ModDefinitions

interface ModDefinitions {
  // ... existing types ...
  NewModType: { value: number; someField: string };
}

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.

t("{value:dec%} all stats").output("StatPct", (c) => ({
  value: c.value,
  statModType: "all" as const,
})),
t("{value:dec%} {statModType:StatWord}")
  .enum("StatWord", StatWordMapping)
  .output("StatPct", (c) => ({ value: c.value, statModType: c.statModType })),
t("{value:dec%} [additional] [{modType:DmgModType}] damage").output("DmgPct", (c) => ({
  value: c.value,
  dmgModType: c.modType ?? "global",
  addn: c.additional !== undefined,
})),
t("{value:dec%} attack and cast speed").outputMany([
  spec("AspdPct", (c) => ({ value: c.value, addn: false })),
  spec("CspdPct", (c) => ({ value: c.value, addn: false })),
]),

Template capture types:

{name:int}

"5"

5

{name:dec}

"21.5"

21.5

{name:int%}

"30%"

30

{name:dec%}

"96%"

96

{name:+int}

+

-

"+5"

5

"-3"

-3

{name:+dec}

+

-

"+21.5"

21.5

{name:+int%}

"+30%"

30

"-15%"

-15

{name:+dec%}

"+96%"

96

{name:EnumType}

{dmgType:DmgChunkType}

Signed vs Unsigned Types:

• Use unsigned (

  dec%

  ,

  int

  ) when input does NOT start with

  +

  or

  -

  (e.g.,

  "8% additional damage applied to Life"

  )
• Use signed (

  +dec%

  ,

  +int

  ) when input STARTS with

  +

  or

  -

  (e.g.,

  "+25% additional damage"

  )
• Signed types will NOT match unsigned inputs, and vice versa

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

export const StatWordMapping: Record<string, string> = {
  strength: "str",
  dexterity: "dex",
  intelligence: "int",
};

registerEnum("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()

case "NewModType": {
  break;
}

For existing mod types with new variants (like adding

statModType: "all"

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

5. Add Tests

Add test cases in

src/tli/mod_parser.test.ts

test("parse percentage all stats", () => {
  const result = parseMod("+10% all stats");
  expect(result).toEqual([
    {
      type: "StatPct",
      statModType: "all",
      value: 10,
    },
  ]);
});

6. Verify

pnpm test src/tli/mod_parser.test.ts
pnpm typecheck
pnpm check

Template Ordering

IMPORTANT: More specific patterns must come before generic ones in

allParsers

// Good: specific before generic
t("{value:dec%} all stats").output(...),           // Specific
t("{value:dec%} {statModType:StatWord}").output(...), // Generic

// Bad: generic would match first and fail on "all stats"

Examples

Simple Value Parser (Signed)

Input:

"+10% all stats"

+

t("{value:+dec%} all stats").output("StatPct", (c) => ({
  value: c.value,
  statModType: "all" as const,
})),

Simple Value Parser (Unsigned)

Input:

"8% additional damage applied to Life"

t("{value:dec%} additional damage applied to life").output("DmgPct", (c) => ({
  value: c.value,
  dmgModType: "global" as const,
  addn: true,
})),

Parser with Condition (Signed)

Input:

"+40% damage if you have Blocked recently"

t("{value:+dec%} damage if you have blocked recently").output("DmgPct", (c) => ({
  value: c.value,
  dmgModType: "global" as const,
  addn: false,
  cond: "has_blocked_recently" as const,
})),

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

+

{value:+dec%}

t("deals {value:+dec%} additional damage to an enemy for every {amt:int} points of frostbite rating the enemy has")
  .output("DmgPct", (c) => ({
    value: c.value,
    dmgModType: "global" as const,
    addn: true,
    per: { stackable: "frostbite_rating" as const, amt: c.amt },
  })),

Multi-Output Parser (Signed)

Input:

"+6% attack and cast speed"

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

Flat Stat Parser (Signed)

Input:

"+166 Max Mana"

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

No-Op Parser (Recognized but produces no mods)

Input:

"Energy Shield starts to Charge when Blocking"

Use

outputNone()

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

Common Mistakes

dec%

+

+dec%

"+25% damage"

+dec%

dec%

"8% damage applied to life"

as const

as const

statModType: "all" as const

offense.ts

statModType === "all"

allParsers

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