adding-support-mod-parsers: Скилл преобразования строк в объекты

--- name: adding-support-mod-parsers description: Use when adding support mod parsers to convert support skill affix strings to typed SupportMod objects - guides the template-based parsing pattern (project) --- # Adding Support Mod Parsers ## Overview Support mod parsers convert raw support skill affix strings (e.g., `"+15% additional damage for the supported skill"`) into typed `SupportMod` objects at runtime. Unlike active/passive skills which use level-scaling factories, support skills parse their affixes directly using templates. ## When to Use - Adding support for new support skill affix patterns - Extending support mod parsing to handle new variants ## Project File Locations | Purpose | File Path | |---------|-----------| | Support mod templates | `src/tli/skills/support-mod-templates.ts` | | Mod type definitions | `src/tli/mod.ts` | | SupportMod type | `src/tli/core.ts` | | Template/spec helpers | `src/tli/mod-parser/` | | Calculation handlers | `src/tli/calcs/offense.ts` | ## 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 first (see `adding-mod-parsers` skill). ### 2. Add Template in `support-mod-templates.ts` Templates use the same DSL as the main mod parser: ```typescript // In allSupportParsers array t("{value:dec%} additional damage for the supported skill").output( "DmgPct", (c) => ({ value: c.value, dmgModType: "global" as const, addn: true, }), ), ``` **Template capture types:** | Type | Matches | Example Input → Output | |------|---------|------------------------| | `{name:int}` | Unsigned integer | `"5"` → `5` | | `{name:dec}` | Unsigned decimal | `"21.5"` → `21.5` | | `{name:int%}` | Unsigned integer percent | `"30%"` → `30` | | `{name:dec%}` | Unsigned decimal percent | `"96%"` → `96` | | `{name:+int}` | **Signed** integer (requires `+` or `-`) | `"+5"` → `5`, `"-3"` → `-3` | | `{name:+dec}` | **Signed** decimal (requires `+` or `-`) | `"+21.5"` → `21.5` | | `{name:+int%}` | **Signed** integer percent | `"+30%"` → `30`, `"-15%"` → `-15` | | `{name:+dec%}` | **Signed** decimal percent | `"+96%"` → `96` | **Signed vs Unsigned Types:** - Use **unsigned** (`dec%`, `int`) when input does NOT start with `+` or `-` (e.g., `"0.8% additional damage"`) - Use **signed** (`+dec%`, `+int`) when input STARTS with `+` or `-` (e.g., `"+19.8% additional damage"`) - Signed types will NOT match unsigned inputs, and vice versa - **IMPORTANT:** Some support skills have signed inputs, others have unsigned - you may need BOTH templates (see examples below) **Optional syntax:** - `[additional]` - Optional literal, sets `c.additional?: true` - `(effect|damage)` - Alternation (regex-style) - `\(` and `\)` - Escaped parentheses for literal matching ### 3. SupportMod Structure Each parsed mod is wrapped in `SupportMod`: ```typescript interface SupportMod { mod: Mod; } ``` The `parseSupportAffix` function handles this wrapping: ```typescript return mods.map((mod) => ({ mod })); ``` ### 4. Multi-Output Parsers For affixes that produce multiple mods: ```typescript t("{value:dec%} additional attack and cast speed for the supported skill") .outputMany([ spec("AspdPct", (c) => ({ value: c.value, addn: true })), spec("CspdPct", (c) => ({ value: c.value, addn: true })), ]), ``` ### 5. Add a Test Add a test case to `src/tli/skills/support-mod-templates.test.ts` using the example input string given to you: ```typescript test("parse <skill name> <description of what it parses>", () => { const result = parseSupportAffixes([ "<exact input string from the skill data>", ]); expect(result).toEqual([ [ { mod: { type: "<ModType>", // ... expected mod properties }, }, ], ]); }); ``` ### 6. Verify Run tests to ensure parsing works: ```bash pnpm test pnpm typecheck pnpm check ``` ## Examples ### Damage Mod with BOTH Signed and Unsigned Variants Some support skills use `+{value}%` templates (e.g., Increased Area) while others use `{value}%` (e.g., Haunt). You need BOTH templates: **Inputs:** - `"+19.8% additional damage for the supported skill"` (Increased Area - signed) - `"0.8% additional damage for the supported skill"` (Haunt - unsigned) ```typescript // Signed version (e.g., "+19.8% additional damage...") t("{value:+dec%} additional damage for the supported skill").output( "DmgPct", (c) => ({ value: c.value, dmgModType: "global" as const, addn: true, }), ), // Unsigned version (e.g., "0.8% additional damage...") t("{value:dec%} additional damage for the supported skill").output( "DmgPct", (c) => ({ value: c.value, dmgModType: "global" as const, addn: true, }), ), ``` ### Typed Damage Mod (Signed) **Input:** `"+20% additional melee damage for the supported skill"` ```typescript t("{value:+dec%} additional melee damage for the supported skill").output( "DmgPct", (c) => ({ value: c.value, dmgModType: "melee" as const, addn: true, }), ), ``` ### Attack Speed (Signed - can be negative) **Input:** `"-15% Attack Speed for the supported skill"` (Steamroll) ```typescript t("{value:+dec%} attack speed for the supported skill").output( "AspdPct", (c) => ({ value: c.value, addn: false, }), ), ``` Note: `+dec%` matches both `+` and `-` signs. ### Conditional Mod **Input:** `"The supported skill deals +30% additional damage to cursed enemies"` ```typescript t("the supported skill deals {value:dec%} additional damage to cursed enemies") .output("DmgPct", (c) => ({ value: c.value, dmgModType: "global" as const, addn: true, cond: "enemy_is_cursed" as const, })), ``` ### Per-Stackable Mod **Input:** `"+5% additional damage for the supported skill for every stack of buffs while standing still"` ```typescript t("{value:dec%} additional damage for the supported skill for every stack of buffs while standing still") .output("DmgPct", (c) => ({ value: c.value, dmgModType: "global" as const, addn: false, per: { stackable: "willpower" as const }, })), ``` ### Mod with No Value **Input:** `"The supported skill cannot inflict wilt"` ```typescript t("the supported skill cannot inflict wilt").output("CannotInflictWilt"), ``` ### Escaped Parentheses **Input:** `"Stacks up to 5 time(s)"` ```typescript t("stacks up to {value:int} time(s)").output("MaxWillpowerStacks", (c) => ({ value: c.value, })), ``` Note: Literal `(` and `)` don't need escaping when they don't contain alternations. ### Complex Pattern with Ignored Values **Input:** `"When the supported skill deals damage over time, it inflicts 10 affliction on the enemy. Effect cooldown: 3 s"` ```typescript t("when the supported skill deals damage over time, it inflicts {value:int} affliction on the enemy. effect cooldown: {_:int} s") .output("AfflictionInflictedPerSec", (c) => ({ value: c.value, })), ``` Use `{_:type}` to capture but ignore values. ### Shadow Quantity (Signed Flat Integer) **Input:** `"+2 Shadow Quantity for the supported skill"` ```typescript t("{value:+int} shadow quantity for the supported skill").output( "ShadowQuant", (c) => ({ value: c.value, }), ), ``` ## Template Ordering **IMPORTANT:** More specific patterns must come before generic ones in `allSupportParsers` array. ```typescript // Good: specific before generic t("{value:dec%} additional melee damage for the supported skill").output(...), t("{value:dec%} additional damage for the supported skill").output(...), // Bad: generic would match first t("{value:dec%} additional damage for the supported skill").output(...), t("{value:dec%} additional melee damage for the supported skill").output(...), // never matches ``` ## Common Mistakes | Mistake | Fix | |---------|-----| | Using `dec%` for input with `+` prefix | Use `+dec%` for inputs like `"+25% damage"` | | Using `+dec%` for input without sign | Use `dec%` for inputs like `"0.8% damage"` | | Only one template when inputs vary | Add BOTH signed and unsigned templates (see examples) | | Generic template before specific | Move specific templates earlier in array | | Missing `as const` on string literals | Add `as const` for type narrowing | | Handler doesn't account for new mod type | Update `offense.ts` to handle new mod types | | Forgot the wrapper structure | `parseSupportAffix` already wraps in `{ mod }` | ## Data Flow ``` Support skill affix: "+15% additional damage for the supported skill" ↓ parseSupportAffixes() ↓ normalize (lowercase, trim) "15% additional damage for the supported skill" ↓ template matching (allSupportParsers) [{ mod: { type: "DmgPct", value: 15, dmgModType: "global", addn: true } }] ↓ resolveSelectedSkillSupportMods() in offense.ts Applied to skill calculations ``` ## Difference from Main Mod Parser | Aspect | Main Mod Parser | Support Mod Parser | |--------|-----------------|-------------------| | File | `src/tli/mod-parser/templates.ts` | `src/tli/skills/support-mod-templates.ts` | | Source | Gear affixes, talents, etc. | Support skill affixes only | | Output | `Mod[]` | `SupportMod[]` (wrapped in `{ mod }`) | | Usage | `parseMod()` | `parseSupportAffixes()` | Both use the same template DSL (`t()`, `spec()`, `outputMany()`).