400 lines
14 KiB
ReStructuredText
400 lines
14 KiB
ReStructuredText
roadmap — order of operations
|
|
=============================
|
|
|
|
the master plan. what to build and in what order.
|
|
|
|
current state: the engine works. command system, game loop, mode stack,
|
|
combat (state machine + TOML moves), persistence (SQLite), editor mode,
|
|
IF/z-machine (dfrotz + embedded interpreter), terrain generation, content
|
|
loading — all built. what's unbuilt is the object model and everything it
|
|
enables: zones, things, inventory, containers, portals, verbs, multi-zone
|
|
worlds, rich NPCs, player building, and eventually the DSL.
|
|
|
|
the architecture-plan.txt priority list (items 1-8) is essentially done.
|
|
this plan picks up from there.
|
|
|
|
each phase builds on the one before it. the MUD stays functional
|
|
throughout — no phase leaves things broken.
|
|
|
|
|
|
phase 1: object foundation
|
|
--------------------------
|
|
|
|
the base class everything inherits from. pure additive — nothing breaks,
|
|
existing tests keep passing.
|
|
|
|
build:
|
|
|
|
- Object base class: name, location (Object | None), x (int | None),
|
|
y (int | None)
|
|
- contents property — reverse lookup: everything whose location is self
|
|
- can_accept(obj) method — default: False
|
|
- Entity inherits from Object instead of being a standalone dataclass
|
|
- Player, Mob unchanged externally — they still work exactly as now
|
|
|
|
the location field exists but isn't wired up yet. Entity still has x, y
|
|
from before, they just come through Object now. no behavioral change.
|
|
|
|
depends on: nothing
|
|
enables: everything below
|
|
refs: object-model.rst (hierarchy, containment mechanics)
|
|
|
|
|
|
phase 2: zones + overworld migration
|
|
-------------------------------------
|
|
|
|
the big migration. the overworld becomes a Zone object. players live
|
|
inside it. movement, rendering, persistence, mob spawning all update.
|
|
|
|
build:
|
|
|
|
- Zone class: width, height, toroidal flag, terrain data, generator
|
|
- Zone.can_accept() returns True (zones accept everything)
|
|
- Zone.contents_at(x, y) for spatial queries
|
|
- convert current World terrain generator into Zone initialization — the
|
|
procedural overworld becomes a Zone instance loaded at startup
|
|
- Entity.location = zone (players and mobs live in the overworld zone)
|
|
- movement system goes through zone: wrapping, passability checks come
|
|
from player.location (the zone), not a global world reference
|
|
- viewport rendering reads terrain from player.location
|
|
- persistence adds zone name to save/load schema
|
|
- mob spawning sets location=zone
|
|
- remove world injection into command modules — commands access
|
|
player.location instead of module-level globals
|
|
- send_nearby_message uses zone.contents_at() instead of iterating the
|
|
global players dict
|
|
|
|
the global ``_world`` singleton goes away. ``players`` dict can stay for
|
|
session management but spatial queries go through zones.
|
|
|
|
migration strategy:
|
|
|
|
- keep World class temporarily as Zone's terrain generator
|
|
- migrate one system at a time (movement → rendering → persistence →
|
|
broadcasting) with tests green at every step
|
|
- object-model.rst "how existing code maps in" section traces each path
|
|
|
|
depends on: phase 1
|
|
enables: multi-zone, portals, interior spaces
|
|
refs: object-model.rst (Zone section, migration paths),
|
|
zones-and-building.rst (zone properties, wrapping, generators)
|
|
|
|
|
|
phase 3: things + inventory
|
|
---------------------------
|
|
|
|
items exist. you can carry them. the world has stuff in it.
|
|
|
|
build:
|
|
|
|
- Thing class: description, portable flag (from Object)
|
|
- Entity.can_accept() allows portable Things (inventory)
|
|
- pick up / drop commands
|
|
- inventory command (list Things whose location is the player)
|
|
- items on the ground: Thing at location=zone, x=5, y=10
|
|
- look shows nearby items at your coordinates
|
|
- thing templates in TOML (content/things/) loaded at startup
|
|
- thing spawning: template → instance with location=zone
|
|
- viewport shows ground items (new symbol or marker)
|
|
- persistence: player inventory persists to SQLite; ground items respawn
|
|
from templates on restart
|
|
|
|
depends on: phase 2 (things need zones to exist in)
|
|
enables: equipment, crafting ingredients, quest items, loot
|
|
refs: object-model.rst (Thing section), things-and-building.rst (decorator
|
|
pattern, content format)
|
|
|
|
|
|
phase 4: containers + portals
|
|
-----------------------------
|
|
|
|
nesting and zone transitions. both depend on Thing existing.
|
|
|
|
containers:
|
|
|
|
- Container class: capacity, closed (bool), locked (bool)
|
|
- Container.can_accept() checks capacity + open state
|
|
- put / get commands (move Thing into/out of Container)
|
|
- open / close commands
|
|
- lock / unlock (requires key item — first real item interaction)
|
|
- nested inventory display (backpack contains: ...)
|
|
|
|
portals:
|
|
|
|
- Portal class: target_zone, target_x, target_y, portable=False
|
|
- zone transition: step on portal → location changes to target zone,
|
|
position changes to target coords
|
|
- enter / go command for explicit portal use
|
|
- build at least one interior zone (tavern or test room) with hand-built
|
|
tile data from TOML
|
|
- two-way portals (portal in each zone pointing at the other)
|
|
- look shows portal presence, portal descriptions
|
|
|
|
depends on: phase 3 (portals and containers are Things)
|
|
enables: multi-zone world, interior spaces, locked doors, bags, keys
|
|
refs: object-model.rst (Container, Portal sections),
|
|
zones-and-building.rst (zone data format, hand-built zones)
|
|
|
|
|
|
phase 5: verbs + interaction
|
|
----------------------------
|
|
|
|
the layer that makes the world feel alive. drink from a fountain, pet a
|
|
mob, read a sign. anything can have verbs.
|
|
|
|
build:
|
|
|
|
- @verb decorator on Object — any object in the world can have verbs
|
|
- @thing decorator for spawnable templates with verbs pre-attached
|
|
- verb resolution: "drink fountain" → find fountain at player's
|
|
coordinates → call its drink verb handler
|
|
- verb dispatch integrates with command system — verbs checked as
|
|
fallback after global commands fail to match
|
|
- content format: verbs defined in TOML alongside thing definitions,
|
|
or in python via the decorator
|
|
- default verbs: look at / examine (work on everything with a
|
|
description)
|
|
|
|
depends on: phase 4 (need objects with verbs to interact with)
|
|
enables: rich interaction, builder content, puzzle creation
|
|
refs: things-and-building.rst (@thing/@verb decorator system, full
|
|
PepsiCan example)
|
|
|
|
|
|
phase 6: multi-zone content + building
|
|
--------------------------------------
|
|
|
|
the world has places. builders can create more.
|
|
|
|
build:
|
|
|
|
- zone loading from TOML files (hand-built zones with tile grids)
|
|
- hub / phone-switch zone with portals to different areas
|
|
- tutorial zone for new players
|
|
- tavern / social zone (interior, bounded, not toroidal)
|
|
- paint mode: admin tool for editing zone terrain tile-by-tile
|
|
- zone TOML export (runtime state → version-controlled files)
|
|
- spawn points per zone (where you appear on entry)
|
|
- zone-specific ambient messages
|
|
- per-zone mob spawning rules (what mobs live here, density, respawn)
|
|
|
|
depends on: phase 4 (portals connect zones)
|
|
enables: a world with actual geography, builder workflow
|
|
refs: zones-and-building.rst (zone format, paint mode, building tools,
|
|
portal network design)
|
|
|
|
|
|
phase 7: GMCP + rich client support
|
|
------------------------------------
|
|
|
|
structured data for graphical MUD clients (Mudlet, Blightmud, etc.).
|
|
independent of the object model — can be done earlier if desired.
|
|
|
|
build:
|
|
|
|
- GMCP option negotiation in telnet handshake (telnetlib3 supports this)
|
|
- Char.Vitals package: pl, stamina, max_stamina
|
|
- Char.Status package: flying, resting, mode, combat state
|
|
- Room.Info package: zone name, x, y, terrain type
|
|
- MSDP for real-time variable updates (client-side HP bars, gauges)
|
|
- map data for clients that support structured map rendering
|
|
|
|
telnetlib3 already handles the protocol layer. this phase is defining the
|
|
data packages and wiring them to game state changes.
|
|
|
|
depends on: nothing (can start anytime)
|
|
enables: rich MUD client experience alongside raw telnet
|
|
refs: DREAMBOOK.md (things to explore: GMCP, MSDP)
|
|
|
|
|
|
phase 8: NPC evolution
|
|
----------------------
|
|
|
|
mobs become characters, not just combat targets.
|
|
|
|
build:
|
|
|
|
- dialogue trees: TOML-defined, triggered by "talk to" or "ask" commands
|
|
- non-combat behaviors: patrol, wander, idle, shopkeeper, guard
|
|
- behavior trees or state machines defined in TOML
|
|
- mob reactions to verbs ("pet" the cat, "ask" the bartender about X)
|
|
- spawn/respawn system using location=None as template state (die →
|
|
location=None, timer → respawn at zone with fresh stats)
|
|
- mob schedules (bartender appears in tavern during the day, gone at
|
|
night)
|
|
- shopkeeper mobs (buy/sell interface using inventory system)
|
|
|
|
depends on: phase 5 (verbs for interaction), phase 6 (zones for mobs
|
|
to inhabit)
|
|
enables: living world, quests, commerce
|
|
refs: architecture-plan.txt (entity model section),
|
|
object-model.rst (location=None for templates/despawned)
|
|
|
|
|
|
phase 9: world systems
|
|
----------------------
|
|
|
|
time, weather, seasons. the world breathes.
|
|
|
|
build:
|
|
|
|
- game time cycle: ticks → hours → days → seasons
|
|
- time of day affects descriptions ("the tavern is dim in the evening
|
|
light" vs "sunlight streams through the windows")
|
|
- weather system: rain, wind, storms (per zone or global)
|
|
- weather affects gameplay: rain slows movement, storms block flying,
|
|
cold water is worse in winter
|
|
- seasonal terrain variation: snow in winter, flowers in spring, color
|
|
palette shifts
|
|
- ambient messages tied to time/weather ("a cold wind picks up")
|
|
|
|
depends on: phase 6 (zones with descriptions to vary)
|
|
enables: atmosphere, seasonal events, weather-dependent gameplay
|
|
refs: DREAMBOOK.md (seasons, weather, time of day)
|
|
|
|
|
|
phase 10: player creation + housing
|
|
------------------------------------
|
|
|
|
players shape the world. the MOO dream.
|
|
|
|
build:
|
|
|
|
- player-owned zones (personal rooms, houses, pocket dimensions)
|
|
- building commands: create zone, set dimensions, paint terrain, place
|
|
things
|
|
- in-world editing via editor mode (descriptions, verb scripts)
|
|
- player-created content stored in SQLite
|
|
- admin review + export to files (sqlite → TOML for version control)
|
|
- permissions: who can build, who can edit what, visitor access controls
|
|
- crafting system: combine things → new thing, recipes in TOML
|
|
- IF creation tools: use the IF primitives to build small adventures
|
|
from inside the MUD
|
|
|
|
depends on: phase 6 (zones), phase 5 (verbs), persistence
|
|
enables: the MOO vision — player-built, player-programmed world
|
|
refs: DREAMBOOK.md (user-created content, presence and community),
|
|
architecture-plan.txt (player-created content in sqlite,
|
|
engine/content boundary)
|
|
|
|
|
|
phase 11: the DSL
|
|
-----------------
|
|
|
|
replace python callables with a scripting language writable from inside
|
|
the MUD. this is the hardest design challenge in the project.
|
|
|
|
build:
|
|
|
|
- language design: informed by what phases 1-10 needed to express
|
|
- interpreter/runtime: sandboxed, no file/network access
|
|
- content definitions gain ``body: dsl:script_name`` option alongside
|
|
``body: python:module.function``
|
|
- DSL scripts editable in-world via editor mode
|
|
- help system teaches the DSL from inside the MUD
|
|
- standard library: common verbs, triggers, conditions
|
|
- migration path: existing python handlers get DSL equivalents over time
|
|
|
|
defer specifics until phases 1-10 reveal exactly what the DSL needs to
|
|
express. the ecosystem research (dsls.md) catalogs prior art: MOO's
|
|
language, LPC, MUSH softcode.
|
|
|
|
depends on: everything above being stable
|
|
enables: non-programmers creating game content from a telnet session
|
|
refs: architecture-plan.txt (DSL section, content definition format),
|
|
docs/research/dsls.md (prior art)
|
|
|
|
|
|
phase 12: horizons
|
|
------------------
|
|
|
|
things from the dreambook's "explore later" list. order is flexible —
|
|
tackle based on interest and what the world needs.
|
|
|
|
- web client: xterm.js terminal emulator pointed at telnet port. honor
|
|
the protocol even in the browser
|
|
- MCCP compression for bandwidth-heavy sessions
|
|
- inter-MUD communication (IMC2, I3)
|
|
- AI-driven NPCs: LLM-backed conversation, personality, memory
|
|
- alternate screen buffer: split views (map panel + text panel)
|
|
- sound via MSP or links
|
|
- procedural dungeon generation: zones with random layout per visit
|
|
- quest system: objectives, tracking, rewards, quest-giver NPCs
|
|
|
|
|
|
dependency graph
|
|
----------------
|
|
|
|
::
|
|
|
|
phase 1: object foundation
|
|
│
|
|
▼
|
|
phase 2: zones + migration
|
|
│
|
|
▼
|
|
phase 3: things + inventory
|
|
│
|
|
▼
|
|
phase 4: containers + portals
|
|
│
|
|
▼
|
|
phase 5: verbs + interaction
|
|
│ phase 7: GMCP (independent)
|
|
▼
|
|
phase 6: multi-zone content
|
|
│
|
|
├────────────────┐
|
|
▼ ▼
|
|
phase 8: NPCs phase 9: world systems
|
|
│ │
|
|
└───────┬────────┘
|
|
▼
|
|
phase 10: player creation
|
|
│
|
|
▼
|
|
phase 11: DSL
|
|
│
|
|
▼
|
|
phase 12: horizons
|
|
|
|
|
|
notes
|
|
-----
|
|
|
|
**the phase 2 migration is the riskiest step.** it touches movement,
|
|
rendering, persistence, mob spawning, and message broadcasting. the
|
|
strategy is incremental: migrate one subsystem at a time, keep tests
|
|
green, keep the MUD playable. the object-model.rst doc has a detailed
|
|
"how existing code maps in" section for this.
|
|
|
|
**phase 7 (GMCP) floats.** it doesn't depend on the object model and
|
|
can be done whenever energy or interest is there. it's slotted at 7
|
|
because the data it reports (zone name, position, combat state) gets
|
|
richer as the object model matures, but basic vitals work anytime.
|
|
|
|
**phases 8-10 have some flexibility.** world systems (weather, time)
|
|
could come before NPC evolution. player creation could come before
|
|
either. the dependency shown is the tightest path — if housing needs
|
|
NPCs (shopkeepers, guards), then 8 before 10. if not, reorder freely.
|
|
|
|
**the DSL (phase 11) is intentionally last.** the architecture-plan.txt
|
|
says "defer it until we know exactly what it needs to express." phases
|
|
1-10 discover that organically.
|
|
|
|
|
|
related docs
|
|
-------------
|
|
|
|
- ``DREAMBOOK.md`` — vision, philosophy, wild ideas
|
|
- ``docs/how/architecture-plan.txt`` — engine/content boundary, original
|
|
priority list (items 1-8 now complete)
|
|
- ``docs/how/object-model.rst`` — class hierarchy, containment, verbs,
|
|
migration paths
|
|
- ``docs/how/zones-and-building.rst`` — zone format, building tools,
|
|
paint mode, portal network
|
|
- ``docs/how/things-and-building.rst`` — @thing/@verb decorator system
|
|
- ``docs/how/combat.rst`` — combat system (built, referenced by phase 8)
|
|
- ``docs/how/commands.txt`` — command system (built, extended by new
|
|
phases)
|
|
- ``docs/research/dsls.md`` — scripting language catalog (phase 11)
|