compw00ter — Hero Builder Data-Model Upgrade

Date: 2026-06-21 Status: Design — for confirmation before implementation (touches the live DB).

Bring the Hero Builder's schema in line with the Main Game Loop spec: traits become (meter, direction) and abilities gain a flavour. Non-destructive and reversible.

Why

The loop spec replaced loose "vice states" with four meters (Food / Booze / Sleep / Unusualness) and trait triggers at a meter extreme (HIGH/LOW), and split abilities into three flavours (fight / cleanse / provide). The builder still stores the old shape, so the roster can't yet express the model we agreed.

Schema changes (additive — keep legacy columns)

• New vocab meters (seeded, editable): Food, Booze, Sleep, Unusualness. (The old vice_states table is kept but deprecated — no longer used by the UI.)
• traits — add:
  • trigger_meter TEXT → meters.name (nullable: blank = event-driven, deferred)
  • trigger_direction TEXT → high | low
  • (keep legacy trigger_state, populated by migration, hidden in the UI)
• abilities — add:
  • flavour TEXT → fight | cleanse | provide (default fight)
  • provides_meter TEXT → meters.name (only for provide; nullable)
  • (keep counters_type — meaningful for fight; target, power, cooldown unchanged)

UI changes

• Trait row: replace the Trigger state dropdown with Trigger meter (Food/Booze/ Sleep/Unusualness, or blank = event-driven) + Direction (High / Low).
• Ability row: add a Flavour dropdown (fight / cleanse / provide). When provide, show a Provides meter dropdown; when fight, the existing Counters type applies; cleanse needs no extra field.
• Vocabularies page: edit meters; keep incident_types; drop the vice-states editor (legacy table remains in the DB, just unmanaged).

Migration (run once, on a backed-up copy)

1. Back up data/compw00ter.db first.
2. Add the new columns + seed meters.
3. Map existing trait trigger_state → (meter, direction): | old state | → meter | direction | |---|---|---| | Drunk | Booze | high | | High / Tripping | Unusualness | high | | Wired | Unusualness | high (flag for review) | | Sleepy | Sleep | low | | Angry / Tilted | (blank) | — (event-driven, deferred) |
4. Classify ability flavour: known providers → provide (Feed Everyone→Food, Dispense Edibles→Unusualness); social/morale abilities (Hype Man, Inspiring Trainer, Social Motivator, Creates Hilarity, Alleviate Boredom, Comfort Cooking, Rally) → cleanse; everything else (has a counters_type / technical) → fight. All editable afterward — the migration just sets sensible defaults for the user to fine-tune in the builder.
5. Re-run the smoke test; the user reviews the roster in the builder.

Out of scope (still deferred)

• Incident modelling in the builder (incidents aren't authored here yet).
• Numeric thresholds for meters (tuning, not builder content).
• Event-driven trait triggers (left blank now; a later trigger-kind field).