See vision.md for the goal, design.md for the core and plugins.md for the plugin system.
- Restart the codebase (Go modules).
- Write the design docs.
- Port reusable packages:
ansi,random,auth. - Language-neutral scripting layer; gopher-lua engine with sandbox and interruption.
dragon new makes a game directory; dragon serve runs it; players connect
over telnet and the web and talk to each other.
-
dragon newanddragon serve,dragon.tomlwith transport toggles. - Game loop, sessions, messages.
- Telnet transport with ANSI color.
- Web transport: page, WebSocket, htmx client, color as HTML.
- Plugin loading: embedded built-ins plus the game's own plugin.
- Commands from Lua (
commands.luareturns a table), with explicitoverride(nowreplace). - Hot reload of Lua on file change.
- Objects: id, parent, location, properties; SQLite storage.
- Accounts and login with
auth. - Objects across the scripting boundary (
player:send(...)). - Views:
views/<name>.txt.tmpland.html.tmpl, with blocks the sender picks. - Entities in messages:
{{entity .x}},<dragon-entity>, tooltips (dragon:get_tooltip) and default actions (dragon:get_default_action). -
#idobject references in command input. - Message sections other plugins add to (
{{section "exits"}}, filled by thesection:room.exitshook). - Hooks and notifications with plugin ordering (
before/after) and game wiring (order,disable). -
dragon events [<name>](wasdragon hooks). - Hook redirection in game wiring (
redirect). - Input parser: command forms, slot types (
slots.lua), maximal munch, quoting, additive forms withreplace. -
builtinsindragon.toml: which built-in plugins a game loads. - Input modes (editors, menus, pending prompts); login as a mode, then
character select and creation as game-controlled modes
(
dragon:characters, with creation steps fromdragon:character_steps). - Text layout: telnet wrapping, and layout helpers (
columns,table, ...) with HTML equivalents. -
dragon:unmatched_inputhook: input no command matches is offered to plugins before the player sees an error (design.md §2). - Form sets in Lua (
forms.new,set:parse): the command parser for entity scripts and anything else with its own vocabulary. -
actor:is_player(). - Feed views:
room,say,emote,ambient,echo. -
game.run(actor, line): commands by another name, and NPCs acting through the commands players use. -
game.broadcast_to(location, ...): messages to what's directly inside an object. - Article and case helpers in templates (
{{the .x}},{{A .x}},{{cap}}). - Declared hook fields: one name per role (
actorfor whoever acts), fields documented bydragon events <name>, and events that error on a field the hook doesn't have.
-
Local plugins in
game/plugins/<name>/, made withdragon gen plugin <name>. -
requirefor a plugin's own modules. -
Manifests are
plugin.toml, read without running the plugin; the game's settings aredragon.toml. -
init.luareturns everything a plugin provides, built from its modules inlua/, so file names are the plugin's own business. -
"Event" names both kinds, hooks and notifications:
dragon.events,events.declare,events.handlers,dragon events. -
Manifest
[provides]and[uses]: API versions and Cargo-style constraints, checked at startup, one provider per API. -
Manifest capabilities, checked where a system feature is used (tasks first). The world-state check in bindings comes with entity scripts.
-
require("@name")imports a plugin API by name, never by plugin;init.luanames the API's module (api = "api"). API names are namespaced by the contract's owner (johns:skills), anddragon:APIs are the built-ins'. First use:dragon:chatprovidesdragon:chatwithchat.say(actor, message, target)andchat.emote, so games stop reusing itssayview and coupling to its data shape (lesson 3 below). -
Schema types and extensions; namespaced added fields (
mapping.coords). An object can have several types, and inherits its parents'; a typed object only takes its types' fields, which catches typos likedescrition(lesson 6 below). -
Tasks (
dragon <task>,dragon tasks), named as written with rake-style namespaces, each run in its own copy of the game. Live tasks, run inside the running server, wait for the admin API (Milestone 5). -
dragon add/update/remove/list,dragon.lock, vendoring.[dependencies]indragon.tomlandplugin.tomllist sources and constraints, resolved together intodragon.lock. -
Import maps, plugin JS, the
dragonclient API, client events. -
dragon testwith scripted sessions. Conformance suites for APIs are still to come. -
Plugin introspection:
dragon plugin <name>shows everything a plugin provides (APIs, dependencies, capabilities, commands and forms, slot types, modes, the events it sends and handles and where its handlers run, views and templates, types and added fields, tasks, and what it adds to the web client), so a game author knows what they can add to, replace or wire fromgame/.dragon pluginlists every plugin. Generating reference docs from the same data is still to come. -
No automatic prefixes: client events (
mapping:pan) and fields added to another plugin's type (mapping.coords) get their plugin's name put in front today. Names should be as written, like events, modes and tasks, so anyone reading the code knows what to reference: a plugin extending a type writes the field's full name (["mapping.coords"]), and two plugins adding the same field to a type is a startup error naming both.
- Entity scripts (design.md §2): stored on objects, edited in-game and
in the admin editor,
o:handlewith parent inheritance,o:sendcalling the view's handler. - Event audiences (design.md §2): a hook's declaration names who hears
it (
audience = { "room.contents", "actor" }), the engine callso:handleon each, and games adjust it in wiring withdeliver. Builds on declared hook fields and entity scripts. -
dragon:rooms: rooms, exits, movement,can_move; rooms deliver views to their contents and offer unmatched input to them. Moving isrooms:can_move(hook),rooms:leftin the old room,move_to, thenrooms:enteredin the new one (notifications carryingactor, so mobs moving count too). - Built-in actions come in pairs: a hook before (change or cancel)
and a notification after (react).
dragon:chatgetsdragon:saidanddragon:emoted, so NPCs answer after the player's line, not insidedragon:before_say(lesson 2 below). -
dragon:chatanddragon:presencereach the actor's location withgame.broadcast_to, falling back to the whole game for actors who are nowhere (lesson 4 below). - Speech triggers: a plugin helper for "react when someone says X" (lesson 5 below).
-
dragon:items. -
dragon:mapping(validates the plugin design end to end). - State updates, slots, web panels, tooltips; telnet prompt and GMCP.
- Game-defined vitals.
- Fixtures in
#context: scope, priority, fallback, dismissal. - Windows (design.md §6): sending a view to a window or slot, windows
updating in place,
<ui-window>; settle whether fixtures are windows. - Web forms that send an event (
<form action="mygame:register">) with their inputs as fields, and screens per mode, so login and character select can be pages before the game view. - A rich text editor component that writes color codes, for
describeand anything else using the editor mode. -
game/web/layout.htmlandlayout.css: copied bydragon new, validated at startup,{{.Head}}injection, CSS theme properties. - The default layout: a terminal in the web with richer features (clickable entities, prompts as buttons, windows), and its phone version. Book-style layouts are games' own.
- Layouts as plugins;
dragon layout:diff. - Reconnect with resume.
- Tell open browsers when a reload changed plugins' web files (push
dragon:client_updated), so they reload for the new import map, which a page can't swap once loaded. With resume, the client can reload itself without logging the player out. -
world:export/world:import(JSONL).
- Admin UI generated from schemas.
- Admin extensions (map editor).
- Tasks page in admin.
-
dragon console.
- Plugin development outside a game: commands that work on a plugin by
itself, such as
dragon testin a plugin's repository (a bare game of the built-ins plus the plugin),dragon pluginanddragon servefor trying it, anddragon export plugin <name> <dir>to turn a local plugin into its own repository (copy it,git init, tag its version, and optionally switch the game todragon addit). - Kits (
--kit diku|mush|moo) anddragon eject. The MOO kit finds verbs on the objects a line names; the MUSH kit has$-commands and exits matched by name. - Script limits a game can set for its builders' entity scripts (quotas, module sets), for games that open scripting widely.
- Importers (
dragon:import-diku,dragon:import-circle). - A
dragoncommand that generates a docs site from doc comments (LuaDoc or LuaLS annotations) in plugins' API modules, sodragon:chat's API can be read without openinglua/api.lua. - Dice notation: modifiers, keep highest, drop lowest; dice objects.
- Fairness features: rate limits, cooldowns.
- Transactions scripts opt into, like
store.transaction(function() ... end): if the function fails, nothing it changed is saved. Today a failed task still saves what it changed, so tasks are written to run again safely. - Engine upgrades: deprecations,
dragon upgrade. - Go extensions and
xdragon build. - A second scripting language behind
scripting, and a conformance suite every scripting engine must pass. - TLS for telnet.
- Plugin index.
What building test_dragon (a two-room tavern with a bartender and a
hermit, built on the engine as it was on 2026-10-03) showed.
- NPCs had to send views by hand to speak. The keeper rendered a
hailview to each player itself. NPCs should act through the same commands players use: nowgame.run(npc, "say ..."). - NPC reactions ran before what they reacted to. The only hook on
speech was
dragon:before_say, so the keeper answered before the player's line appeared. Every built-in action needs a notification after it, not only a hook before. - Reusing another plugin's view couples you to its data. Sending
saywithspeakerinstead ofactorbroke twice. Missing data is now an error, but plugins should offer functions (chat.say) rather than games reusing their views. - Speech reached the whole game.
say,emoteand custom actions usedgame.broadcast, so the cellar heard the tavern. Locations are core, sogame.broadcast_tonow exists; the built-ins should use it. - Matching speech was hand-rolled (
string.find(message, "hail")). Keyword triggers are worth a helper, as a plugin. - Freeform properties hide typos.
descritionwent unnoticed; schemas will catch it. - Silent failures cost the most time. A template reading data that
wasn't sent, a blocks-only view sent without a block,
actor.namefor a property, and<no value>in telnet all looked like other bugs. Each is now an error saying what to change; keep finding these. - Names carried their articles ("the bartender", "a dingy hermit"), which reads wrong as soon as a sentence needs the other article or a capital. Names should be bare, with article helpers in templates.
The engine is only as usable as its docs. Each of these needs a reference, plus guides for the common paths.
- Getting started: install,
dragon new,dragon serve, the 15-minute MUD. - Game directory: layout,
dragon.toml, the game as a plugin, overrides. - Lua API reference: every module and function.
- Manifest reference: fields, provides, uses, capabilities, dependencies.
- Views: sections, telnet and HTML templates, layout helpers, color codes.
- Events and wiring: hooks and notifications, declarations, ordering,
dragon events. - Web client: slots, the
dragonJS API, import maps, custom elements, client events. - Layouts and themes: editing
layout.html, required and optional slots, CSS theme properties, fixtures, sharing a layout as a plugin. - Admin and schemas: schema format, type extensions, admin components.
- Tasks and CLI: every core command, writing tasks.
- Plugin authoring and publishing: layout, versioning, conformance tests.
- Export and import: JSONL format, importers and mapping configs.
- Upgrading: engine versions and deprecations.
The pre-restart engine is in git history before commit 0ad383a.
| Old package | New package | Changes |
|---|---|---|
ansi |
ansi |
Same behavior; tests moved to testing; HTML output added. |
random |
random |
Seedable Rand; fixed Range never returning max. |
scripting/modules/password.go |
auth |
Plain Go API; fixed fallback cost of up to 31. |
Worth consulting later: scripting/modules/* (Lua APIs for events, log,
config, die, tmpl), scripting/modules/cli.go (the original plugin
CLI commands), scripting/lua/repl.go (console), fs (game directory
layout).
Not coming back: talon (Neo4j), events (replaced by hook), the Lua
engine pool, text/tmpl (velvet is archived), logger (use log/slog).