diff --git a/docs/plans/experience-roadmap.rst b/docs/plans/experience-roadmap.rst new file mode 100644 index 0000000..b2a7e2f --- /dev/null +++ b/docs/plans/experience-roadmap.rst @@ -0,0 +1,316 @@ +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 `` 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 + +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/`` 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 from `` +- ``get all from `` +- ``get 2.armour from corpse`` +- ``put in `` +- 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 +- ``'s corpse is here.`` in room display +- Decomposition timer (configurable, default ~5 min) +- ``'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 `` 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 `` 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** -- player-owned zones, crafting +- **Phase 18: The DSL** -- in-world scripting language +- **Phase 19: 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