← 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 #16 for out-of-character rooms and #17 for in-character ones. Put a verb on #17 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 75 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 #17 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: go_, look_, get_, drop_, eat_, drink_, open_, close_, lock_, wear_, remove_, and the in_/on_/under_/behind_ container variants.

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 #14=A room parses the same as @desc #14 = A room.

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 #17.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(n, code) instead of holding a parked verb open for an hour.

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 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.