151 lines
5.4 KiB
ReStructuredText
151 lines
5.4 KiB
ReStructuredText
=============================
|
|
content loading pipeline
|
|
=============================
|
|
|
|
the content pipeline converts static TOML definitions into runtime Python objects
|
|
at startup. all loading happens once before accepting player connections — no hot-reload.
|
|
|
|
startup sequence
|
|
================
|
|
|
|
from ``server.py run_server()``, in order::
|
|
|
|
1. init_db() → database
|
|
2. init_game_time() → game clock
|
|
3. World() + terrain → procedural terrain
|
|
4. Zone (overworld) → overworld from terrain
|
|
5. load_zones() → content zones (hub, tavern, etc) from content/zones/
|
|
6. load_commands() → TOML commands from content/commands/
|
|
7. load_help_topics() → help topics from content/help/
|
|
8. register_combat_commands() → combat moves from content/combat/
|
|
9. load_mob_templates() → mob definitions from content/mobs/
|
|
10. load_thing_templates() → thing/container definitions from content/things/
|
|
11. load_recipes() → crafting recipes from content/recipes/
|
|
12. load_all_dialogues() → NPC dialogue trees from content/dialogue/
|
|
|
|
common loader pattern
|
|
=====================
|
|
|
|
every content type follows the same pattern::
|
|
|
|
1. load_X(path) → parse single TOML file into dataclass
|
|
2. load_Xs(directory) → iterate .toml files, call load_X each, return dict
|
|
3. At startup: global_registry.update(load_Xs(dir))
|
|
|
|
the loader functions are synchronous. they read files, parse TOML, validate data,
|
|
and populate module-level registries. errors during load are logged but don't
|
|
crash the server (graceful degradation).
|
|
|
|
content directory structure
|
|
===========================
|
|
|
|
all content lives under ``content/``::
|
|
|
|
content/commands/ → command definitions (name, aliases, handler or message)
|
|
content/combat/ → combat moves (attacks, defenses, variants)
|
|
content/things/ → thing/container templates
|
|
content/mobs/ → mob templates with loot and schedules
|
|
content/zones/ → zone definitions (terrain grids, portals, spawns, ambient)
|
|
content/recipes/ → crafting recipes
|
|
content/dialogue/ → NPC dialogue trees
|
|
content/help/ → help topic files
|
|
content/stories/ → z-machine game files (not TOML, loaded separately)
|
|
|
|
each subdirectory contains multiple ``.toml`` files. the loader iterates them
|
|
all and merges results into a single registry.
|
|
|
|
global registries
|
|
=================
|
|
|
|
module-level dicts, populated at startup, read-only during play::
|
|
|
|
commands/__init__.py: _registry dict
|
|
combat/commands.py: combat_moves dict
|
|
things.py: thing_templates dict
|
|
mobs.py: mob_templates dict, mobs list
|
|
zones.py: zone_registry dict
|
|
crafting.py: recipes dict
|
|
commands/help.py: _help_topics dict
|
|
commands/talk.py: dialogue_trees dict
|
|
|
|
these dicts are never mutated after startup. new content requires a server restart.
|
|
|
|
handler resolution
|
|
==================
|
|
|
|
commands and thing verbs can reference Python functions via ``"module:function"``
|
|
strings. at load time, the loader uses ``importlib`` to resolve the string into
|
|
a callable.
|
|
|
|
commands can also have inline message text instead of a handler. in that case,
|
|
the loader wraps the message in a simple async handler that sends the text.
|
|
|
|
if handler resolution fails, the loader logs a warning and continues. the command
|
|
is registered but won't work (graceful degradation).
|
|
|
|
template vs instance
|
|
====================
|
|
|
|
templates are immutable definitions stored as dataclasses. spawning creates mutable
|
|
runtime objects (``Thing``, ``Mob``, etc).
|
|
|
|
templates stay in the registry forever. instances are created and destroyed during
|
|
play. when a mob dies, the template remains — you can spawn another.
|
|
|
|
this separation keeps content definitions clean and allows multiple instances of
|
|
the same template (ten wolves from one ``wolf`` template).
|
|
|
|
validation
|
|
==========
|
|
|
|
different content types validate at different levels:
|
|
|
|
dialogue trees
|
|
--------------
|
|
|
|
validate all node references at load time. if a choice points to a nonexistent node,
|
|
``load_dialogue()`` raises ``ValueError`` and the server won't start.
|
|
|
|
combat moves
|
|
------------
|
|
|
|
validate ``countered_by`` references. if a move references a nonexistent counter,
|
|
the loader logs a warning but continues. the move is still usable, just without
|
|
that counter.
|
|
|
|
zone portals
|
|
------------
|
|
|
|
parse ``"zone_name:x,y"`` target format at load time. if the format is invalid,
|
|
the portal won't work. if the zone doesn't exist yet (load order), it's fine —
|
|
the portal stores the string and runtime lookup happens when someone uses it.
|
|
|
|
code
|
|
====
|
|
|
|
startup sequence::
|
|
|
|
src/mudlib/server.py (run_server function)
|
|
|
|
loaders::
|
|
|
|
src/mudlib/commands/__init__.py (load_command, load_commands)
|
|
src/mudlib/combat/commands.py (load_combat_move, register_combat_commands)
|
|
src/mudlib/things.py (load_thing_templates)
|
|
src/mudlib/mobs.py (load_mob_template, load_mob_templates)
|
|
src/mudlib/zones.py (load_zone, load_zones)
|
|
src/mudlib/crafting.py (load_recipes)
|
|
src/mudlib/commands/help.py (load_help_topic, load_help_topics)
|
|
src/mudlib/commands/talk.py (load_dialogue, load_all_dialogues)
|
|
|
|
content directories::
|
|
|
|
content/commands/
|
|
content/combat/
|
|
content/things/
|
|
content/mobs/
|
|
content/zones/
|
|
content/recipes/
|
|
content/dialogue/
|
|
content/help/
|
|
content/stories/
|