Experience Layer Roadmap
========================

Phases 8+ build the player-facing experience on top of the engine
foundation (phases 1-7). Each phase leaves the MUD playable. Priority
order: visual experience first, then combat polish, then parser depth,
then content tools.

Stats model: two resources, PL and stamina.

- PL (power level) is both power and health. Determines damage output
  (attacker PL * move damage_pct). 0 = unconscious. Someone can finish
  you off while KO'd.
- Stamina is fuel. Spent by combat moves and powering up. 0 = pass out
  (unconscious). Recovered by resting (slow, eyes open), sleeping
  (fast, blind to room), or natural slow tick.
- Powering up spends stamina per tick to raise PL. Trade endurance for power.
- Unconscious triggered by either stat hitting 0. PL and stamina tick up
  slowly on their own. You "come to" when both are above 0.
- Stamina drop is visible: sweat messages broadcast to room, escalating.


Phase 8: Room display overhaul
------------------------------

Redesign the ``look`` output into a structured, information-rich room view.

Output format::

    Where: The Overworld
    ~~~~~~~~~~~...................^^
    ~~~~~~~~~~~......*.....@......^^
    ~~~~~~~~~~~....................^
    Location: northeast 47, 53
    Nearby: (3) saibaman / Master Roshi / Goku
    Exits: north east south west up

    Vegeta is standing here.
    Krillin is sitting here.
    Piccolo is flying above.
    Tien is fighting here.

Deliverables:

- ``Where:`` header from zone name
- ``Location:`` with human-readable quadrant (derived from coords relative
  to zone center) plus raw coordinates
- ``Nearby:`` counts and names all entities in viewport, excluding those
  on your tile
- ``Exits:`` all passable directions from current tile, including up/down.
  Impassable directions omitted
- Entity state lines: one per entity on your tile, reflecting current state
  (standing, sitting, resting, flying, fighting, unconscious)
- ``look <thing>`` routes to examine for objects/entities on your tile

Files: ``commands/look.py``, possibly new ``render/room.py``.


Phase 9: Prompt system
----------------------

Implement the prompt system per ``docs/how/prompt-system.txt``.

Default prompts::

    normal:  <100%> / <200/200>
    combat:  <100%> / <200/200> vs <WEAK>

Format: stamina% / current_pl/max_pl. Combat adds opponent condition tag.

Deliverables:

- ``src/mudlib/prompt.py`` with ``render_prompt(player)``
- Modal templates with variable substitution (``{stamina_pct}``,
  ``{pl}``, ``{max_pl}``, ``{opponent}``)
- Color markup engine (``{red}``, ``{bold}``, etc.) respecting client
  color_depth
- ``prompt`` command: bare shows syntax, with args customizes format
- GMCP Char.Vitals wired up

Files: new ``src/mudlib/prompt.py``, extend ``render/colors.py``,
modify ``server.py``.


Phase 10: Combat overhaul + power system
-----------------------------------------

Make combat read better, add power-up mechanic, fix combat rules.

POV template engine
~~~~~~~~~~~~~~~~~~~

Single templates that adapt to viewer perspective. Lives in
``render/pov.py`` or similar, used by combat and anything needing
POV-aware text.

Substitutions:

- ``{attacker}`` / ``{defender}`` -> "You" for self, name for others
- ``{s}`` -> "" / "s" (third person)
- ``{es}`` -> "" / "es"
- ``{y|ies}`` -> explicit irregular forms (left = you-form, right = they-form)
- ``{his}`` / ``{him}`` -> pronoun table based on POV

Example: ``{attacker} parr{y|ies} the air!``

- Attacker sees: "You parry the air!"
- Others see: "Jared parries the air!"

Three-beat combat output
~~~~~~~~~~~~~~~~~~~~~~~~~

Each attack produces three messages: telegraph, announce, resolve.
Each has its own color, defined per-move in TOML::

    telegraph:  Jared retracts his right arm...          (muted)
    announce:   Jared throws a right-handed punch at Goku!  (default)
    resolve:    Jared's punch thrashes Goku!             (intense)

TOML format gains ``announce`` template and ``[colors]`` section::

    [colors]
    telegraph = "dim"
    announce = "default"
    resolve = "bold_red"

    telegraph = "{attacker} retract{s} {his} right arm..."
    announce = "{attacker} throw{s} a right-handed punch at {defender}!"

Combat rule fixes
~~~~~~~~~~~~~~~~~

- Cannot quit during combat (quit command checks combat state)
- 30s no-damage-landed timeout ends combat (blocking for 30s earns
  your escape window, then you can quit)
- Z-axis check: must be same altitude (both grounded or both flying)
  to start combat or land hits
- Flying during opponent's timing window dodges incoming attack
- Unconscious state at PL=0 or stamina=0
- Snap neck finisher on unconscious targets

Visible stamina cues
~~~~~~~~~~~~~~~~~~~~

Broadcast sweat/strain messages as stamina drops, escalating in
intensity. Everyone in the room sees them.

Power system
~~~~~~~~~~~~

``power up/down/stop/<number>`` command.

- Power up: tick-based loop, spends stamina per tick to raise PL
- Power down: lower PL to a specific number (hide from scouters)
- Power to N: set PL to exact number within your range
- Bare ``power`` shows syntax
- Visible aura/strain messages during power-up
- Prompt updates live as PL changes

Rest and recovery
~~~~~~~~~~~~~~~~~

- ``rest``: stamina recovers faster than idle, can still see room events
- ``sleep``: stamina recovers fastest, blind to room events (cannot see
  who enters, vulnerable to attack)
- Coming to from unconscious: PL and stamina tick up naturally, "come to"
  message when both above 0

Files: new ``render/pov.py``, modify ``combat/engine.py``,
``combat/commands.py``, all combat TOMLs, new ``commands/power.py``,
modify ``entity.py``.


Phase 11: Parser + targeting + aliases
--------------------------------------

Make the command parser handle real MUD grammar.

Target resolution
~~~~~~~~~~~~~~~~~

- ``punch right goblin`` finds "goblin" on your tile, same z-axis
- ``look goblin`` finds "goblin" on your tile
- Prefix matching on entity/thing names (first match wins)
- ``2.goblin`` ordinal disambiguation (second goblin)

Container grammar
~~~~~~~~~~~~~~~~~

- ``get <thing> from <container>``
- ``get all from <container>``
- ``get 2.armour from corpse``
- ``put <thing> in <container>``
- Preposition-aware parsing: split on "from" / "in" / "to"

Alias command
~~~~~~~~~~~~~

- ``alias`` lists all aliases
- ``alias pr punch right`` creates alias
- ``unalias pr`` removes
- Persisted per-player in SQLite
- Resolved before command dispatch

Files: new or extended ``src/mudlib/parser.py``, modify
``commands/__init__.py``, new ``commands/alias.py``, modify persistence.


Phase 12: Corpses + loot
-------------------------

- Entity dies -> corpse container spawned on tile with entity's inventory
- ``<name>'s corpse is here.`` in room display
- Decomposition timer (configurable, default ~5 min)
- ``<name>'s corpse decomposes.`` broadcast on expiry
- Standard container commands work (``get sword from corpse``)
- Loot tables: TOML-defined per mob template, random drops placed in corpse

Files: modify ``combat/engine.py`` (death handling), corpse Thing
subclass or factory, modify mob TOML format for loot tables.


Phase 13: Score + progression
-----------------------------

Score command
~~~~~~~~~~~~~

- ``score`` / ``stats`` / ``profile`` shows character sheet
- K/D ratio, total kills, deaths
- Current PL, max PL, stamina, max stamina
- Time played
- Unlocked skills list

Skill unlocking
~~~~~~~~~~~~~~~

- Commands/moves gated by unlock state
- Triggers: kill count, specific mob kills, quest completion, milestones
- TOML-defined unlock conditions per move/command
- ``help <command>`` shows if locked and what unlocks it
- New moves/commands announced on unlock

Files: new ``commands/score.py``, modify entity/player model for stats
tracking, modify command registry for unlock gating, new unlock trigger
system.


Phase 14: World building toolkit
---------------------------------

Tools for building zones, placing things, and creating interactive content.
The creative work (Grimm's Library, etc.) is done by hand using these tools.

Zone building
~~~~~~~~~~~~~

- ``@dig`` and related builder commands for creating rooms/zones
- Paint mode for terrain editing (stub exists from phase 6 branch)
- Zone TOML export/import
- The phase 6 HTML map editor outputs YAML; import path from that

Thing placement and interaction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Place objects in zones via builder commands
- Readable objects (``read <thing>`` shows text content)
- Import tool for bulk loading text content into object DB
  (e.g. 210 fairy tale .txt files as readable book objects)

NPC placement
~~~~~~~~~~~~~

- Mob home regions: bounding box within a zone that a mob returns to
  when combat ends or they've strayed too far::

      [[mobs]]
      template = "librarian_monk"
      home_region = { x = [10, 20], y = [5, 15] }

- Mob paths back to home region after losing aggro
- Zone-level mob definitions in TOML

Zone properties
~~~~~~~~~~~~~~~

- Safe zones: flag on zone or sub-region where combat cannot start
- Zone boundaries with trigger hooks (e.g. anti-theft detection)

Files: extend builder commands, zone TOML format, mob spawning system,
import scripts.


Phases 15+: Original roadmap continuation
------------------------------------------

The engine roadmap's later phases, renumbered:

- **Phase 15: NPC evolution** -- dialogue trees, behavior, schedules.
  Grimm's Library librarians may pull some dialogue work into phase 14.
- **Phase 16: World systems** -- time of day, weather, seasons
- **Phase 17: Player creation + housing** -- character creation flow
  (description prompt for new players), personal home zones with
  persistence (TOML in ``data/player_zones/``), home command for
  teleportation to/from personal zone
- **Phase 18: Housing expansion + crafting** -- furniture placement,
  home zone customization (terrain editing, descriptions), crafting
  system, decorative objects
- **Phase 19: The DSL** -- in-world scripting language
- **Phase 20: Horizons** -- web client, compression, inter-MUD, AI NPCs


Key references
--------------

- ``docs/how/combat.rst`` -- combat state machine and TOML format
- ``docs/how/prompt-system.txt`` -- prompt design doc
- ``docs/how/object-model.rst`` -- class hierarchy
- ``docs/plans/roadmap.rst`` -- original engine roadmap (phases 1-7)
- ``docs/research/dbzfe-combat.log`` -- DBZFE combat reference
- ``BRAINSTORM.txt`` -- raw feature ideas
- ``DREAMBOOK.md`` -- vision and philosophy
