houserules/docs/user/modifier-profiles.md

Modifier Profiles

Modifier Profiles let you attach rule modifiers to pieces — either globally by piece type ("all white knights get +2 HP") or specifically by board position ("the knight that starts on b1 has +1 range"). Profiles are saved to a personal library, shareable via URL, and can be swapped mid-game.

---

Opening the Editor

From any game view: click the rules drawer (⚙ icon) → Modifier Profiles.

From the lobby: click Custom… in the Profile Picker next to the Layout Picker.

---

Per-Type vs Per-Instance

	Per-Type	Per-Instance
Targets	All pieces of a given type + color	One specific piece at a named board square
Example	"All white knights: HP +3"	"The knight starting on b1: Range +1"
Requires layout?	No	Yes — square must exist in the chosen layout

---

The 6 Modifier Categories

HP Bonus

Add or subtract hit points from a piece's base HP. Values: integer from −10 to +10. Stacks additively from all sources.

Example: Knight (white) HP +3 — the knight now requires 3 more attacks to eliminate.

---

Range Bonus

Extend the sliding distance of rooks, bishops, and queens. Values: integer 0–7. Capped at maximum board range.

Example: Rook (white) Range +1 — the rook can see one extra square per ray when unblocked.

---

Direction Additions

Add new movement directions to a piece (1-square step moves only). Values: a set of directional flags: forward, backward, left, right, diagonal-fl, diagonal-fr, diagonal-bl, diagonal-br.

Example: Pawn (white) + backward — pawns can also retreat one square to an empty square.

---

Capture Flags

Toggle special capture behavior. Flags:

• CAN_CAPTURE_OWN — piece may capture friendly pieces
• CANNOT_BE_CAPTURED — piece is immune to direct capture (cannot be used on kings)
• EN_PASSANT — future flag for custom en-passant rules

Example: Bishop + CANNOT_BE_CAPTURED — no enemy piece can legally capture it.

---

Promotion Override

Force a pawn to always promote to a specific piece, or disable promotion entirely. Values: queen, rook, bishop, knight, or disabled.

Example: Pawn + Promotion = bishop — any pawn reaching the back rank auto-promotes to bishop, no dialog shown.

---

Damage Resistance

Reduce all incoming damage by a percentage. Stacks multiplicatively across sources. Values: 0 (no resistance) to 1 (full immunity).

Example: Queen + 0.5 resistance — every attack deals half normal damage.

---

Editor Features

Undo / Redo

• Cmd/Ctrl+Z to undo, Cmd/Ctrl+Shift+Z to redo.
• Toolbar buttons in the editor header (↶ / ↷) with the same behaviour.
• History is capped at 50 actions per editing session.
• The stack is cleared when you Save or Cancel — the saved state becomes the new baseline, so there is no undo across sessions.

Copy / Paste

• Per-instance: select a square that already has modifiers, click Copy, then select another square and click Paste. Pasted modifiers replace any same-kind modifier already present on the target (so you won't end up with two HP-Bonus entries on the same piece).
• Per-type: each row has a Copy button. Use Paste at the top of the panel to apply the copied entry to a different piece type / color.
• The clipboard is editor-local (in-memory) and does not use your OS clipboard — copying modifiers cannot clobber anything you already copied outside the app.

Conflict Resolution

When the editor detects a problem — a king carrying the CANNOT_BE_CAPTURED flag, a per-instance entry pointing at an empty square, an attribute-limit overflow — a panel appears at the top of the editor listing every issue.

• Each issue has a Fix button that auto-resolves it where possible (e.g. drop the illegal flag, remove the orphan entry).
• Some issues (missing kings for a layout, attribute-limit overflow that requires a real decision) can't be fixed automatically; the Fix button is advisory and the panel directs you to the specific row that needs manual attention.
• Save is blocked while any hard error remains; warnings (orphan per-instance entries) don't block save but surface in the panel so they aren't silently ignored.

---

Hot-Swap

Modifier profiles can be changed mid-game. The flow:

1. Solo mode: Open the editor, change the profile, save. The new profile applies after the next move.
2. Multiplayer: Either player can propose a profile change. The opponent receives a notification with a 60-second window to approve or reject. If approved, the new profile applies after the next move; if rejected or timed out, no change occurs.

Profile changes always take effect at a turn boundary (after the next completed move), never mid-move. This guarantees both players' moves resolve under the same rule set they were planned with — the state at turn N is fully determined by the profile active at turn N plus moves 1..N.

In a multiplayer room, rapid successive proposals follow a last-write-wins rule: if you propose a swap and then send a second proposal before the opponent decides, the first is superseded and the opponent sees the new candidate.

---

Library & Sharing

• Save — click the Save button in the editor header. Up to 20 profiles stored locally.
• Star ⭐ — starred profiles are never evicted when the library is full.
• Share 🔗 — copies a URL containing the full profile. Profiles larger than 8 KB cannot be URL-shared (save to library and share the room code instead).
• Load — open the library drawer in the editor and click any entry.

---

In-Play Inspection

Hover any piece on the board to see a tooltip listing active modifiers.

Click a piece to pin a side panel with the full modifier breakdown. The panel stays pinned across turns until you dismiss it (×) or click another piece.

The pinned panel shows the source of each modifier so you can trace where a value comes from at a glance:

• per-instance: {square} — attached to this specific board position (survives captures of other pieces, but vanishes if this piece is captured).
• per-type: all {color} {type}s — applies to every piece matching this type + color combination.
• from {preset name} — the modifier comes from an active rule preset (e.g. a first-blood ruleset granting kings extra HP).
• default — the engine's baseline value with no modifier applied.

When multiple sources touch the same attribute, the panel lists each source and shows how they combine (HP additive, damage-resistance multiplicative, direction-additions unioned).

---

Board Indicators

Pieces with one or more active modifiers display a small fuchsia dot in the top-right corner of their square. The dot is visible without hover, so you can tell at a glance which pieces are running on modified rules.

• Hover the piece to see a tooltip with modifier details.
• Click to pin the inspection panel (see above).
• The dot stays visible across moves and updates live when a profile is hot-swapped at the next turn boundary.

---

Known Limitations

• Maximum 20 profiles in the local library per browser.
• Profiles larger than 8 KB cannot be URL-shared.
• CANNOT_BE_CAPTURED cannot be applied to kings.
• Deadlock detection (all legal moves blocked) not yet implemented.

Coming in T3

• Custom modifier authoring (defining new modifier categories from scratch).
• Cross-piece aura effects (e.g. "all pieces within 2 squares of this priest get +1 HP").
• Multi-profile stacking (combining two profiles in one game).