houserules/docs/user/custom-modifiers.md

Custom Modifiers — User Guide

Houserules ships with six built-in modifiers (HP Bonus, Range Bonus, Direction Additions, Capture Flags, Promotion Override, Damage Resistance). Custom modifiers let you author your own from a fixed catalog of 15 reusable effect primitives — no programming required.

A custom modifier is a named, reusable bundle of primitive effects that any modifier profile can reference, exactly the same way it references a built-in.

---

Opening the editor

1. Open the Modifier Profile editor (+ Modifier Profile from the rules drawer, or via the layout's modifier-profile picker).
2. In the editor's header, click + Custom Modifier. The Custom Modifier editor opens as a nested modal.
3. The Custom Modifier editor is a 3-column workspace:
   • Left: primitive palette, grouped by category. Hover any entry for a full tooltip with the primitive's long description and a worked example.
   • Center: the descriptor's primitive tree (the composition you're building).
   • Right: parameter inspector for the selected primitive. The top of the inspector shows an in-editor docs panel — a longer behaviour explanation plus one or more concrete example configurations you can copy. Click Hide docs & examples to collapse it when you want only the form.

Each descriptor needs a name (1-40 chars) and an optional description (0-200 chars). The header exposes Templates, Load, Save, and live validation status.

Templates — starter recipes

The Templates button opens a picker with pre-composed recipes drawn from the examples below (Boosted Pawn, 3-Charge Shield, Aura King, Vampire, Low-HP Fortress). Picking a template replaces the current draft with a fresh copy — the id is regenerated so you can save the loaded template as your own library entry without collisions.

Attribute-name autocomplete

Primitives that target an attribute (seed-attribute, add-to-attribute, multiply-attribute, absorb-damage-with-attribute, add-aura) render their attr / targetAttr field as a combobox with grouped suggestions:

• Core numeric attributes — Hp, HpBonus, RangeBonus, DamageResistance, ReflectDamagePercent, AbsorbDamageRate, HalfmoveClock, FullmoveNumber. Safe targets for add/multiply/aura/absorb primitives.
• Core non-numeric attributes — CaptureFlags, DirectionAdditions, PromotionOverride, BlockedMoveTypes, AbsorbDamageAttr, HasMoved. Seed-only for most; avoid add/multiply.
• User-defined examples — ShieldCharges, ArmorPlates, BloodStacks, ManaPool. Illustrative names matching the recipes; invent your own.

The combobox is free-form — type any name and hit Enter to accept it, even if it isn't in the list. Numeric-context primitives (add, multiply, aura, absorb) rank numeric suggestions first.

Declare vs. consume sites. The combobox distinguishes between primitives that declare a new attribute and primitives that consume an existing one:

• seed-attribute.attr is a declare-site — any name is fine, including inventing brand new counters. The illustrative "User-defined examples" group is surfaced for inspiration. Typed values outside both the schema and the examples catalog carry an amber user-defined badge.
• add-to-attribute.attr, multiply-attribute.attr, absorb-damage-with-attribute.attr, and add-aura.targetAttr are consume-sites — they read an attribute that must already exist. The illustrative examples group is hidden because those names are fiction until something seeds them. Instead, a "Seeded in this descriptor" group surfaces attrs that seed-attribute primitives elsewhere in the current tree actually declare. Typed names that aren't built-in and aren't seeded carry a red not seeded warning; names that are seeded carry an emerald seeded confirmation.

---

The 15 effect primitives

Primitives are atomic, composable, and pure data. Click any palette entry to add it to the current descriptor's tree.

State primitives

These mutate facts on the piece at apply time.

seed-attribute

Seeds a fact { attr, value } on the piece. Overwrites any existing value.

Example: attr=Hp, value=5 — gives the piece 5 HP regardless of the baseline.

add-to-attribute

Reads the existing numeric value of attr (treats absent as 0) and writes existing + delta.

Example: attr=HpBonus, delta=2 — adds +2 to whatever HpBonus is already there.

multiply-attribute

Reads the existing numeric value of attr (no-op if absent) and writes existing * factor.

Example: attr=Hp, factor=2 — doubles HP.

add-direction

Appends named directions into DirectionAdditions. Composes additively with the built-in Direction Additions modifier — both write to the same fact and deduplicate by direction name.

Example: directions=[backward] — adds backward movement.

set-capture-flag

ORs a CaptureFlag bitflag into the piece's CaptureFlags.

Example: flag=CANNOT_BE_CAPTURED — makes the piece untargetable.

Mechanic primitives

These plug into the engine's existing pipelines (damage, movement, promotion).

absorb-damage-with-attribute

Seeds { AbsorbDamageAttr, AbsorbDamageRate }. Each incoming damage point consumes rate of attr instead of HP, until attr is exhausted.

Example: attr=ShieldCharges, rate=1 — paired with a seed-attribute for ShieldCharges=3 produces a 3-charge shield.

reflect-damage

Seeds ReflectDamagePercent. When this piece takes damage, percentage% is reflected back to the attacker.

Example: percentage=50 — half-reflective armour.

modify-movement-range

Composes additively with the built-in Range Bonus.

Example: delta=1 — adds +1 to the piece's range.

block-move-type

Filters out moves matching the given type (capture / step / slide).

Example: moveType=capture — pacifist piece, can move but not capture.

override-promotion

Sets PromotionOverride to a target piece type. Mirrors the built-in Promotion Override modifier.

Example: target=knight — pawns promote to knights only.

Advanced primitives

These compose other primitives.

add-aura

Seeds an AuraSpec entry. Every piece within radius (Chebyshev / king-move distance) gets delta added to targetAttr.

Example: radius=2, targetAttr=HpBonus, delta=1 — every piece within 2 squares gets +1 HP.

Auras recompute after every move. A piece moving INTO range picks up the contribution; a piece moving OUT loses it on the next pass.

on-turn-start

Wraps a list of nested primitives that run when this piece's color begins a turn.

Example: primitives=[{kind: 'add-to-attribute', params: {attr: 'Hp', delta: 1}}] — heals 1 HP each turn.

on-capture

Wraps a list of nested primitives that run when this piece captures another.

Example: primitives=[{kind: 'add-to-attribute', params: {attr: 'Hp', delta: 1}}] — vampire piece, heals on capture.

on-damaged

Wraps a list of nested primitives that run when this piece takes damage.

Example: primitives=[{kind: 'reflect-damage', params: {percentage: 25}}] — auto-reflects on damage.

conditional

Branches on a condition and runs the matching primitive list.

Supported condition types:

• attr-lt / attr-gt — numeric comparison
• attr-eq — exact match (string / number / boolean / null)
• always — runs then
• never — runs else (or no-op if no else)

Example:

condition: { type: 'attr-lt', attr: 'Hp', value: 2 }
then:     [{ kind: 'set-capture-flag', params: { flag: 'CANNOT_BE_CAPTURED' }}]

— when low on HP, becomes invulnerable.

Note (T3 limitation): Trigger primitives (on-turn-start, on-capture, on-damaged) and conditional currently SEED their hook facts on the piece but the engine pipeline that fires them at the corresponding game phase is not yet wired in T3. The data is correct; the runtime trigger evaluation ships in a follow-up.

---

Composing primitives — simple to complex

Simple: a "boosted pawn"

One add-to-attribute primitive with attr=HpBonus, delta=2. Save as "Boosted Pawn". Reference from a profile's per-type entry to give every white pawn +2 HP.

Medium: a "shield"

Two primitives:

1. seed-attribute: attr=ShieldCharges, value=3
2. absorb-damage-with-attribute: attr=ShieldCharges, rate=1

Pieces start with 3 shield charges; each damage point depletes one charge before HP.

Complex: an "aura king"

One primitive:

1. add-aura: radius=2, targetAttr=HpBonus, delta=1

Apply to the king's per-type entry. Every piece within 2 squares of the king gets +1 HP.

---

Saving and loading

The editor's Save button writes the current descriptor to your local custom modifier library (storage key houserules:custom-modifiers:v1). Load from library opens a picker to recall any saved descriptor.

The library is local to your browser. To share, paste the JSON shape of a saved descriptor — or use the modifier profile sharing flow (which embeds the custom descriptor in the share payload).

Library limits

• 20 descriptors per library — same FIFO eviction rule as profiles (oldest non-starred entry is evicted; star to protect).
• 10 descriptors per multiplayer room — a room can register up to 10 custom descriptors. Servers reject the 11th.

---

Using a custom modifier in a profile

Open the Modifier Profile editor, add a Per-Type or Per-Instance entry (left or center panel), and pick your custom descriptor from the Kind dropdown. Custom descriptors appear in the dropdown under a Custom (from library) group.

Custom modifiers don't take a per-instance value — the descriptor's primitive list is the entire payload. The editor displays a small summary card ("Custom modifier — N primitives") instead of a value input.

---

Multi-profile stacking

The lobby's profile picker stays single-select for the primary profile. Below it, a Stacked (solo only) list lets you append additional profiles in order. Use the up/down arrows to reorder.

When multiple profiles are active, contributions stack across profiles per the same per-kind rules used within a single profile. The "priority-wins" rule (promotion override, capture flags) gives the LAST profile in the list precedence.

Limitation (T3): Multi-profile stacking is solo-only on the wire. Multiplayer rooms still send one profile per room.create. Wire-level stacking is a follow-up.

---

Aura effects in detail

add-aura measures distance with the Chebyshev metric (king-move distance): two squares are within radius R when max(|file_a − file_b|, |rank_a − rank_b|) ≤ R. Radius 1 covers the 8 neighbours; radius 2 covers a 5×5 box minus the source square.

Auras recompute after every successful move. If a source piece moves OUT of range of a target, the contribution is retracted on the next compute. Multiple auras to the same targetAttr accumulate additively.

Self-application is skipped — an aura's source piece never affects itself.

Limitation (T3): AuraContributions are written correctly, but most attribute consumers (HP/Range read points) don't yet layer the aura contribution on top of the directly-seeded value. The data is there; consumer wiring is a follow-up.

---

Limits and DoS guards

• 50 primitives total per descriptor (counted recursively across nested trees).
• Recursion depth ≤ 3 — on-turn-start containing on-capture containing conditional is the maximum nesting depth allowed.
• 20 descriptors per library with starred-aware FIFO eviction.
• 10 descriptors per multiplayer room, server-enforced.
• Name 1-40 chars, description 0-200 chars — descriptor metadata.

The editor's footer shows live validation against all of these. A descriptor that fails any check is rejected on Save with the failing rule highlighted.