← MegaMOO Guide

Verbs

Where commands live, and how to add your own.

Where verbs live

A verb is a command, stored as a short Python file attached to an object.

Everyday commands — look, go, get, open — are attached to the room prototypes, not to players. That is the key idea: a verb on a room is offered to everyone standing in that room. Walk into a room and you can use its commands; walk out and you cannot.

The two room prototypes are #12 for out-of-character rooms and #13 for in-character ones. Put a verb on #13 and every IC room in your world has it. Put it on one room, and only that room does.

Staff verbs and the auth system

Staff commands are the exception. All 81 of them live on #3, the base character object, so every character inherits them — and they are kept in check by an authority level rather than by where you are standing. They are listed in full in the Command Reference.

Only gm5 may grant levels — the power to hand out authority is itself the top of the ladder. Levels are cumulative: gm3 can do everything gm1 and gm2 can.

Each staff verb begins by checking the level and, if the player is short, simply answers Do what? — the same reply as a command that does not exist. Staff commands do not advertise themselves to people who cannot use them.

Your own verbs can require a level too. Set it when you create the verb and the engine refuses the command before your code runs:

Exception verbs

This is how one object behaves unlike every other object of its kind, and it is the most useful pattern in MegaMOO.

A shared verb does its normal job, but first it offers the object a chance to handle the command itself — by calling a verb of the same name with a trailing underscore. If that exception verb exists and returns True, the shared verb stops. If the object has no such verb, nothing happens and the normal behaviour continues.

A worked example: the statue and the bookcase

Say you want a pull command. Normally it just reports that nothing happens, with slightly different wording depending on what was pulled. Put this on #13 and every IC room has it:

Now the exception. A marble statue in the library gets its own pull_, and pulling its arm swings a bookcase aside:

And in play:

Notice what did not happen. Nothing in pull knows the statue exists. The bookcase has no special code either — it is an ordinary door. The exception lives on the object that is exceptional, and everything else stays simple.

Shared verbs pass extra information when the exception needs it — the shipped give passes the recipient as call_verb(item, 'give_', dobj=recipient), and lock passes the key. The exception reads them as dobj and iobj, exactly as a normal verb would.

The engine ships exceptions for most everyday actions: look_, go_, get_, put_, drop_, give_, examine_, open_, close_, latch_, unlatch_, lock_, unlock_, sit_, lay_, and the in_/on_/under_/behind_ container variants.

A world of your own adds its own. Shadowfall carries eat_, drink_, wear_ and remove_, for instance, because it has the commands to call them; the shipped world has neither.

Verb types and parsing

Before your verb runs, the typed line is broken into pieces. That job belongs to the verb's type, and almost every verb uses the standard one, MasterVerb.

MasterVerb splits the line at the first preposition it finds:

These are text, not objects. Turning "blue sword" into an actual object is pmatch's job, and it stays your verb's decision — which is why a verb can choose to search the room, your hands, or inside a container.

Single-character prepositions work without spaces, which is why @desc #201=A room parses the same as @desc #201 = A room.

Verbs nobody types: Type: function

A hook or a utility verb is never typed. look_here, in_get, $string_utils:capitalise — these are reached from other code through call_verb, which hands them their arguments positionally. There is no command line behind them, so there is nothing for the parser to split.

Declaring one a function says so, in the verb file itself:

"""
name_match on $match_utils.

Type:    function
"""

That skips the whole command-parsing lifecycle. Measured against MasterVerb on the same verb, parsing was 2.06µs of a 6.02µs call — 34% of it, spent deciding that an empty argument string contains no direct object. It is not a new execution path: a verb with no type instance was always legal, and this reaches that state deliberately rather than by a verb type failing to build.

at_pre_cmd() does not fire on a function verb either, and for the same reason: the veto exists to stop a typed command before its body runs, and there is no typed command here to stop.

When you need a custom type

Write your own type when the standard split gets in the way. The usual reason is a command whose argument is free text that must not be broken at a preposition: a whisper that would otherwise split "meet me at the gate" at at, or a command taking name: value pairs.

A custom type is a small Python class in the engine's source that overrides one method — parse() — and writes its results into the same named slots. Because it is engine code rather than a verb, adding one needs a server restart, and it is a rare thing to need. Full details are in Writing Verbs in docs/manual/.

Running something before and after every use

A verb type can also wrap the verbs that use it. Two methods fire around every use of such a verb — whether typed by a player, reached through call_verb, or triggered as an exception:

The use for this is a check that many verbs share. Rather than opening thirty combat verbs with the same "are you still recovering?" guard, give them a type that does it once:

The verb body does not start at all, so there is no path through your code that can forget the check — and it applies to verbs reached from other verbs, which a guard pasted at the top of each one would miss. Use it for facts about the actor: recovering, stunned, seated. A check that needs to know what was targeted belongs in the verb itself.

Hidden verbs

Exception verbs are machinery, not commands. Nobody should be able to type pull_ and fire one directly — it would run without the checks the shared verb does first, and it makes no sense as a command in its own right.

Hiding is separate from authority levels: a hidden verb cannot be typed by anyone, whatever their level, and can only be reached by other code.

The trailing underscore is a naming convention that reminds you; it is @hideverb that actually enforces it. A hook you forget to hide is a command your players can type.

Adding a verb

Two commands, in this order. @adverb creates the verb; @program opens an editor for its code.

Aliases and minimums

A verb can answer to several names, and each name can be abbreviated. The number in brackets is the fewest letters that will do:

A minimum of 0 — the default — means the name must be typed in full. Set one later with @min #13.examine = 3. Abbreviations count the @: @article with a minimum of 4 answers to @art.

Who may read and run it

Every verb carries a short permission string, and the default — rx — is what you want almost every time: anyone may read its code, anyone may execute it. Add w only if others should be able to rewrite it.

Permissions are about the verb's code. Whether a player may use the command is decided by auth, above, and by hiding.

Waiting, and talking to the outside

One verb runs at a time. That is deliberate: verb code freely reads a property, changes it, and writes it back, and two verbs interleaving would silently lose one of the changes. Everything you write can assume it has the world to itself.

The catch is that anything a verb waits for, the whole game waits for — every player, every ticker. So there are three ways to wait, and picking the wrong one freezes your world.

suspend

suspend(n) hands your turn back. Other verbs run while you are parked, and execution picks up on the very next line with your variables exactly as you left them:

pobj.msg("You begin meditating...")
suspend(5)
pobj.msg("You feel refreshed.")

That makes patrols, slow rituals and staged events straightforward — a guard can walk its round without anyone else noticing:

for _step in ('north', 'east', 'south', 'west'):
    call_verb(this, 'gmove', args=_step)
    suspend(10)

A single suspend is capped at 300 seconds. For anything longer, schedule a fresh task with delay(seconds, code, context) instead of holding a parked verb open for an hour. All three arguments are required — context is the namespace the code runs in, usually globals().

request

request() is for reaching something outside the server — a web service, a local model, anything that answers over HTTP. It returns immediately, and the answer comes back by calling a verb of your choosing:

# in a verb on the NPC
request('http://127.0.0.1:11434/api/generate',
        reply='npc_said', on=this, method='POST',
        json={'model': 'llama3.2', 'prompt': argstr, 'stream': False},
        tag=pobj.objnum)

The reply verb receives what happened as ordinary variables — ok, status, body, error, and whatever you passed as tag:

# npc_said, on the same object, some time later
if not ok:
    this.msg_room("&S looks momentarily vacant.", sub=this)
    return

import json as _j
this.msg_room(_j.loads(body).get('response', ''), sub=this)

tag comes back untouched, which is how you match an answer to the question that prompted it — the player who spoke, say, when several conversations are in flight at once.

The response body is never run as code. It arrives as a value, so a model that happens to emit something resembling Python — or an endpoint that does so on purpose — cannot get it executed.

Editing verbs on disk

The in-game editor is fine for a few lines. For anything longer you will want your own editor, and verbs can live as ordinary files:

The folder is named after the object's number, the file after the verb. When you start a world with megamoo --dev, MegaMOO watches that tree and loads changes within about two seconds — save the file and the next player to type the command runs your new code. No reload, no restart.

To get an object's verbs onto disk in the first place, use @reload once. If the folder does not exist it is created and the object's existing verbs are written into it:

You only need @reload when a file changed by some means other than the watcher — a git pull, say. After an ordinary save, the watcher has already done it.

Your editor, and the names it cannot see

Verb code is ordinary Python, but the engine hands the verb its context — pobj, this, db, call_verb and about 330 others — instead of the file importing it. Your editor does not know that, so it marks every one of them undefined: dozens in a single verb, all of them wrong. Across the starter world that was 4,683 false errors.

Your game ships with a ruff.toml in the verb tree that declares those names, and a verb_context.pyi so a language server can complete them rather than merely tolerate them. Both are already there; you do not have to do anything. If you upgrade MegaMOO and want the list refreshed:

The list is assembled from the places the engine actually defines those names, so it cannot drift out of step with the engine you are running.

Both files sit inside the verb tree rather than at the top of your game, and deliberately: a linter uses the nearest config to each file, so your own Python under game/ gets none of these declarations. An undefined name there is still a real mistake, and should still be reported.

Your own Python: the game/ package

Verbs are the world's behaviour. Some things are not behaviour — combat tables, chargen rules, price lists, anything that is data or shared helpers — and those do not want to be a verb on an object. They go in game/, the Python package megamoo init creates beside your world:

A verb imports from it the ordinary way:

That is the same spelling verbs already use for engine modules like moo.objects. There is no plugin registry, no hook to register, nothing new to learn — the engine puts your game directory on sys.path when it finds a game package beside the world file, and normal Python does the rest.

Writing verbs with an AI assistant

Verbs suit this unusually well. Each one is a short, self-contained file with a fixed set of variables available and no imports to resolve — a small, bounded problem. With the tooling connection open, an assistant holds the live world: it can write the verb, run it as a test character, read what the game printed back, and fix it, without you retyping anything.

Three things make it work in practice:

• Work on a scratch world. Start a copy with megamoo --dev scratch.db and have the assistant confirm which world it is on before it writes.
• Name the object and the behaviour. "Add a pull_ to #204 that opens the bookcase and reveals the passage" is a complete request. "Make the statue do something" is not.
• Have it verify by playing. Ask it to pull the statue and show you the output. A verb that looks right and does nothing is the common failure, and only playing it catches that.