Play

Builder Documentation

MUDProg Scripting

Give any mob, room, or item a life of its own - greeters, guards, quest-givers, bosses, traps, whole scripted dungeons - in plain text, with no code and no reboot. This is the complete guide: 24 chapters and 772+ worked examples, every one tested live in the game.

CoffeeMUD-compatible60 triggers100+ commands130+ functions

In game, the same guide lives under help mudprog. Test any example on yourself with scripttest, or attach it to a mob with mudprog <target> edit.

Overview & Quick Reference

Related: scripttest, mudprog-basics, mudprog-triggers, mudprog-commands, mudprog-functions, mudprog-variables, mudprog-flow, mudprog-bus, mudprog-cookbook, mudprog-reference

MUDProg is Rogue's text scripting system for builders, modelled on CoffeeMUD's Scriptable/MOBPROG engine. Any mob, room, or item can carry a script that runs when things happen to it or around it - a shopkeeper that greets customers, a boss that taunts at half health, an altar that rewards a spoken password, a trapped room that damages intruders. Scripts are plain text stored in the object's mudprog property; you attach and edit them with the mudprog command. No LPC and no recompiling required.

This page is the quick reference. The full guide is a set of chapters, each its own help page - if you have never scripted before, start with help mudprog-basics and follow the reading order in help mudprog-glossary.

The Guide Chapters

mudprog-basics          - Scripting for absolute beginners.
mudprog-triggers        - Every trigger, explained with examples.
mudprog-commands        - Every mp command reference.
mudprog-functions       - Every function reference.
mudprog-variables       - Dollar codes, variables, substitution.
mudprog-flow            - If, switch, loops, and decisions.
mudprog-bus             - Cancelling and observing game actions.
mudprog-cookbook        - Complete working scripts to copy.
mudprog-reference       - The one-page cheat sheet.
mudprog-workbook1       - Guided exercises: beginner.
mudprog-workbook2       - Guided exercises: intermediate.
mudprog-workbook3       - Guided exercises: advanced.
mudprog-troubleshooting - When scripts do not work.
mudprog-shopkeepers     - Deep-dive: merchants and shops.
mudprog-guards          - Deep-dive: guards and gatekeepers.
mudprog-questcraft      - Deep-dive: quest scripting.
mudprog-dungeons        - Deep-dive: rooms, traps, dungeons.
mudprog-companions      - Deep-dive: pets, followers, mounts.
mudprog-events          - Deep-dive: world events and schedules.
mudprog-combatai        - Deep-dive: combat and boss scripting.
mudprog-dialogue        - Deep-dive: dialogue, cutscenes, memory.
mudprog-patterns        - The idiom library.
mudprog-faq             - One hundred questions, answered.
mudprog-glossary        - Glossary and master index.

A First Script

A script is one or more PROG blocks. Each block starts with a trigger name and its argument, then a body of commands, and ends with a line containing just a tilde:

GREET_PROG 100
say Welcome to my shop, $N! Have a look around.
emote dusts off the counter.
~

SPEECH_PROG password
if hastitle($n) == 'the Initiate'
    say Ah, one of us. The vault is yours.
    mpopen north
else
    say That word means nothing to one like you.
endif
~

The first block greets every player who enters (100% of the time). The second fires when someone says a line containing "password", and branches on whether the speaker holds a title.

The mudprog Command

mudprog <target> - View a target's script and its triggers. mudprog <target> edit - Open the line editor (replaces the script). mudprog <target> set <inline> - Set the whole script from one line. mudprog <target> append <inline> - Append one line to the script. mudprog <target> clear - Remove the script. mudprog <target> test <TRIGGER> - Fire a trigger now, with you as the source.

The target is a mob or item in the room by name, or the word here for the current room, or self for you. In set and append, a semicolon becomes a new line, so you can write a whole block on one command line:

mudprog guard set GREET_PROG 100 ; say Halt! State your business. ; ~

In the editor, type lines normally, end each PROG block with a tilde, and finish with a single dot on its own line. Type @abort to cancel.

To test scripts quickly on yourself without attaching them, use scripttest (see help scripttest).

Triggers

Every block begins with a trigger and an argument. The argument is usually a percent chance to fire (an integer 1-100), the word all (or blank) for always, keywords to match for speech-like triggers, or a zapper mask (see below). These triggers fire automatically on live game events. Put the script on the object noted in brackets - the mob, the item, the room, or a container/door.

GREET_PROG <pct|mask>     - A player enters the room [mob, room].
ALL_GREET_PROG <pct|mask> - As greet, including sneakers [mob, room].
GROUP_GREET_PROG <pct>    - As greet, once for a whole entering group [mob].
SPEECH_PROG <keywords>    - Someone speaks a matching line nearby [mob].
SPEAK_PROG <keywords>     - The scripted mob itself speaks a line [mob].
ACT_PROG / MASK_PROG      - As speech; match on spoken/acted text [mob].
SOCIAL_PROG <keywords>    - Someone performs a social/emote nearby [mob].
RAND_PROG <pct>           - Rolls each of the mob's heartbeats [mob].
ONCE_PROG                 - Once, when the mob first loads [mob].
FIGHT_PROG <pct>          - Each combat round while the mob fights [mob].
HITPRCNT_PROG <pct>       - A round where the mob is at or below <pct> hp [mob].
DAMAGE_PROG               - The mob takes damage [mob].
DEATH_PROG                - The mob is about to die [mob].
KILL_PROG                 - The mob has just killed its target [mob].
GIVE_PROG <keywords>      - The mob is given an item (item is $o) [mob].
GIVING_PROG               - Someone gives an item away (item is $o) [item].
BRIBE_PROG <amount>       - The mob is given coins (amount in $g) [mob].
LOOK_PROG / LLOOK_PROG    - A player looks at the mob or item [mob, item].
GET_PROG / GETTING_PROG   - An item is picked up [item, room, mob / getter].
DROP_PROG / DROPPING_PROG - An item is dropped [item, room, mob / dropper].
PUT_PROG / PUTTING_PROG   - An item is put in a container [item, container].
WEAR_PROG / WEARING_PROG  - An item is worn or wielded [item / wearer].
REMOVE_PROG               - An item is removed or unwielded [item].
CONSUME_PROG              - Food is eaten or a drink drunk [item].
OPEN_PROG / CLOSE_PROG    - A container or door is opened/closed [container].
LOCK_PROG / UNLOCK_PROG   - A container or door is locked/unlocked [container].
BUY_PROG / SELL_PROG      - A player buys from / sells to the vendor [vendor].
CAST_PROG / CASTING_PROG  - A spell resolves on the mob / the mob casts (spell in $g).
FOLLOW_PROG / UNFOLLOW_PROG- Someone starts/stops following the mob [mob].
RIDE_PROG / RIDING_PROG   - The mount is mounted / a rider mounts [mount / rider].
LOGIN_PROG / LOGOFF_PROG  - A player enters or leaves the game [any scripted object].
LEVEL_PROG                - A player gains a level (new level in $g) [any].
CHANNEL_PROG <chan words> - Traffic on a comm channel (channel+text in $g) [any].
TIME_PROG <hours>         - The mud clock reaches one of the listed hours [mob].
DAY_PROG <days>           - A new mud day begins (day # in $g) [any].
AGE_PROG                  - A player crosses a new hour of played age [any].
ENTRY_PROG / EXIT_PROG    - The scripted mob enters/leaves a room [mob].

CNCLMSG_PROG <code> [mask] - CANCEL a game action before it happens; the
                            block runs INSTEAD of the action. Codes: GET,
                            DROP, PUT, GIVE, WEAR, REMOVE, OPEN, CLOSE,
                            LOCK, UNLOCK, EAT, DRINK, BUY, SELL, CAST,
                            ENTER, LEAVE, ATTACK [any object in the room].
EXECMSG_PROG [code] [mask] - Observe any of those actions after they
                            happen, without interfering [any object].
IMASK_PROG [text]          - The scripted object's OWN output contains the
                            text (blank matches everything) [mob, item].
REGMASK_PROG <regexp>      - Any text the object sees matches a regular
                            expression [mob, item].
CMDFAIL_PROG <pct>         - A player's command fails nearby (the failed
                            command is $g) [mob, room].
QUEST_TIME_PROG <q> <mins> - A timed quest reaches the listed minutes
                            remaining [any object].

A FUNCTION_PROG block is a named routine you invoke yourself with mpcallfunc (or callfunc()) and never fires on its own. See help mudprog-bus for the full cancel/observe model.

Zapper Masks

Any trigger that takes a chance can instead take a CoffeeMUD-style zapper mask to restrict WHO may set it off. A mask is a set of clauses, each a -TYPE followed by the values that qualify:

GREET_PROG -class mage -level 30
FIGHT_PROG -race troll -race ogre

Supported clause types: -class, -race, -level (a number means at-or-above; 30-40 a range), -sex, -name, -deity, -player, and -npc. All clauses must pass for the trigger to fire.

Variables and Substitution

Inside any line, dollar codes are replaced with live values. The source of the trigger (usually the acting player) is $n, the mob or object running the script is $i, and the target is $t:

$n $N  source name          $t $T  target name        $i  this mob's name
$I  this mob's short desc    $q  this object's name    $Q  its short desc
$o $O  first item name       $p $P  second item name
$e $s $m  source he / him / his      $E $S $M  target forms
$j $h $k  this mob he / him / his    $y $Y  source / target sir-or-madam
$r $R  a random player        $c $C  a random inhabitant here
$H $J $K  random player him / he / his    $f $F  the mob's leader name / he
$w $W  owner of item 1 / 2    $l  list of mobs here    $L  list of items here
$a  area name   $d  room title   $D  room description   $x $X  a random exit
$b $B  last mpmload/mpoload name / desc
$g $G  the message, lower / original case
$$  a literal dollar sign

The $ codes match CoffeeMUD's exactly, so a script written from CoffeeMUD's own guide substitutes identically on this mud.

Two extended forms read data at runtime:

$<obj var>        - the value of a stored variable (see mpsetvar).
$%FUNC(args)%     - the result of a function, inserted into the text.

For example, say You have $%goldamt($n)% gold and I know you, $<$i note>. The temporary slots $0 through $9 are set by FOR loops and by mpargset.

Control Flow

if <condition>            Branch. Optional else. Close with endif.
    ...
else
    ...
endif

switch <value>            Match a value against cases.
case A
    ...
case B
    ...
default
    ...
endswitch

for $1 = 1 to 5           Loop, counting into a $-slot.
    ...
next

while <condition>         Loop while a condition holds.
    ...
endwhile

break                     Leave the nearest loop or case.
return                    Stop the script (a value after it is the
                          function-prog result).

Blocks nest freely. Loops are capped at a safe iteration count and each trigger run has a step budget, so a runaway script stops itself rather than hanging the mob.

Conditions

A condition is a function, optionally compared to a value, and conditions can be joined with and, or, and not:

if rand(30)                       30% chance.
if level($n) >= 40                Numeric comparison.
if class($n) == mage              String comparison (case-insensitive).
if hastitle($n) and goldamt($n) > 500
if isnpc($t) or ispc($t)

Comparison operators: == != > < >= <= and .in. (substring). A bare function with no comparison is true when it returns non-zero and non-empty.

Commands

Any line that is not control flow is a command. If it is not one of the mp commands below, it is run as an ordinary game command by the mob, so say, emote, yell, whisper, socials, wield, wear, and cast all work exactly as a player would type them.

Messaging:

mpecho <text>                  - To everyone in the room.
mpechoat <who> <text>          - To one target only.
mpechoaround <who> <text>      - To the room except one target.
mpasound <text>                - To the adjacent rooms.
mpchannel <channel> <text>     - Onto a comm channel.
mpspeak <text>                 - The mob says it aloud.
mpllm <text>                   - To online staff only.
mplog <text>                   - To the server log.
mpprompt / mpconfirm / mpchoose <text> - Ask the player; the reply lands in
                                 their prompt_answer / confirm_answer var.

Movement and combat:

mpgoto <room>                  - Move this mob to a room path.
mpat <room> <command>          - Run a command as if in another room.
mptransfer <who> [room]        - Move a target to a room (or here).
mpwalkto <dir...>              - Step the mob in directions.
mpkill <who>                   - Start a fight with a target.
mphit <who>                    - Land one attack.
mpdamage <who> <amount> [type] - Deal direct damage (blunt, heat, magic...).
mpheal <who> <amount>          - Restore health.
mpcast <spell> [target]        - Cast a spell.
mpslay <who>                   - Kill a target outright.
mprejuv / mpreset [who]        - Restore a mob to full.
mpstop [who]                   - End combat.
mpflee                         - Make the mob flee.
mpforce <who> <command>        - Force a target to run a command.
mpbehave / mpunbehave <flag>   - Toggle aggression and other flags.
mppossess <player> <mob>       - Have a player control a mob.
mpbeacon / mpalarm <secs> <command> - Run a command after a delay.
mpsleep <seconds>              - Pause HERE; the rest of the script resumes
                                 after the delay (also: mpwait).
mpcondition <who> <id> <type> <secs> [mag] [pct] - Apply a full Rogue
                                 condition (buff or debuff) with magnitude.

Loading and the world:

mpmload <path>                 - Clone an NPC into the room ($b afterwards).
mpoload <path>                 - Clone an item onto the mob.
mpoloadroom <path>             - Clone an item into the room.
mpjunk <item> / mppurge <who>  - Destroy an item or mob.
mpput <item> <container>       - Put an item in a container.
mphide / mpunhide [who]        - Hide or reveal.
mplink <dir> <room> / mpunlink <dir> - Add or remove a room exit.
mpopen / mpclose / mplock / mpunlock <dir> - Doors and containers.

Character and progression (target is usually $n):

mpset <who> <property> <value> - Set a property, stat, level, or short.
mpexp <who> <amount>           - Grant (or remove) experience.
mpmoney <who> [type] <amount>  - Give or take currency.
mptitle <who> <title>          - Award a name title.
mpfaction <who> <faction> <n>  - Change Brinewarren reputation.
mptrains / mppracs <who> <skill> <n> - Credit skill progress.
mpaffect <who> <id> [seconds]  - Apply a condition (rooted, poisoned...).
mpunaffect <who> <id>          - Remove a condition.
mptattoo <who> <text>          - Give a visible tattoo.
mpachieve <who> <id>           - Flag an achievement.
mpplayerclass <who> <class>    - Change class.

Quests:

mpstartquest <who> <quest>     - Begin a quest (this mob is the giver).
mpendquest <who> <quest>       - Turn in, or drop if unfinished.
mpquestwin <who> <quest>       - Complete a quest.
mpquestpoints <who> <amount>   - Award quest points.
mploadquestobj <path>          - Give the source a quest item.

Variables and structure:

mpsetvar <obj> <name> <value>  - Store a variable on any object.
mpsavevar <obj> <name> <value> - As setvar; player vars persist.
mpgset <name> <value>          - Set a mud-wide global.
mpargset <0-9> <value>         - Set a temporary $-slot.
mpcallfunc <name> [args]       - Run a FUNCTION_PROG block by name.
mpscript <line>                - Run one script line immediately.

Functions

Functions are used in conditions and in $%...% substitution. They usually take an object as the first argument (a $-code or a name); many default to this mob if omitted. A selection - see the examples for typical use:

Actor:   isnpc ispc isalive isfight isimmort ischarmed isfollow isservant
         isgroup ispkill sex position level class baseclass race name deity
         mood hitprcnt exp questpoints goldamt currency stat isable
Items:   has hasnum worn wornon itemcount objtype value isopen islocked
         incontainer mobitem
Room:    nummobsroom numitemsroom numpcsroom roommob roomitem roompc
         numraces inroom ishere inlocale inarea numpcsarea areapc
Time:    istime ishour isday ismonth isyear isseason isweather ismoon
         datetime isrlhour isrlday isrlmonth isrlyear
Quest:   questwinner questscripted questobj qvar faction hastitle hastag
         hastattoo clan clanrank isname isbehave
Shop:    shophas shopitem numitemsshop
Utility: rand randnum rand0num number isodd math eval strin strcontains
         islike callfunc var affected
Rogue:   hp maxhp sp maxsp ep maxep skill factionrep weather season
         timeofday isnight groupsize (extensions beyond CoffeeMUD)

Worked Examples

A boss that heals allies below half health and taunts at 25%:

FIGHT_PROG 40
if hitprcnt($i) <= 50
    mpcast heal $i
    mpecho $I channels a dark restoration.
endif
~

HITPRCNT_PROG 25
yell You will NOT take this keep while I draw breath!
mpaffect $t bleeding 20
~

A quest giver keyed on speech:

SPEECH_PROG quest
if questwinner($n cellar_rats)
    say You have already cleared my cellar. My thanks stand.
else
    say Rats have overrun my cellar. Clear them and I will pay you well.
    mpstartquest $n cellar_rats
endif
~

A trapped room that fires once and rewards the brave:

GREET_PROG 100
if var($i sprung) == 1
    mpechoat $n The pit has already been sprung; you step around it.
else
    mpsetvar $i sprung 1
    mpechoat $n The floor gives way beneath you!
    mpdamage $n 40 blunt
    mpoloadroom /obj/torch.c
endif
~

Notes

Scripts never crash their host; a bad argument simply does nothing. After editing an object's script the engine reparses automatically. For deeper testing use scripttest to run raw lines on yourself, and mudprog <target> test <TRIGGER> to fire a specific block.

Back to top