Scripting in CoffeeMud 5.3

coffeemud logo

Introduction to Scripting

Scripting is the ability to makes something behave proactively, or respond to game stimuli, in a way specified by the game builders. A Script is the set of commands written by the builders to perform this function. In CoffeeMud, any object may be scripted. This means that rooms, areas, items, and especially MOBs can be scripted.

Scripting is accomplished through the Scriptable Behavior. Giving an object this behavior makes it capable of running scripts on its behalf. The parameters of the Scriptable behavior define the source of the script itself.

The most common parameter for the Scriptable behavior is the LOAD command, which specifies a text file containing the script. The syntax for this is as follows:

load=path/file name

The starting path for the Scriptable behavior is the /resources/ directory in your CoffeeMud package. Any further paths will branch from that directory. The file specified is a text file containing the script. You can also specify more than one script in the Scriptable parameters by separating LOAD= commands with the ~ character like so:

load=progs/mrinfo.script~load=progs/strangetrader.script~

A less common way to specify a script for the Scriptable behavior is to enter the script itself into the parameter. Scripts entered in this way differ from scripts entered into text files for the LOAD parameter in one significant sense: Every line of a script entered in this way must be terminated by a semicolon. Here is an example.

RAND_PROG 50;bounce;say "hi!";~;

Scripts which are entered into text files for the LOAD parameter have their lines terminated by carriage returns (ENTER) instead of semicolons. The script syntax is, in all other ways, identical. If you need to put special characters (like ; ~ or LOAD=) into particular commands, you may need to escape those characters by putting a \ character before them, to tell the Scriptable behavior not to consider them line or script delimiters.

When the Scriptable behavior loads a file using the LOAD= syntax, it automatically keeps a copy of it in memory for future use. This memory cache is called the CoffeeMud Resources. If you have a Scriptable prog you have entered using the LOAD= syntax, you can see its entry in the cache by using your Archon character to enter LIST RESOURCES from the CoffeeMud command line. Because the script files from disk are kept in memory for quick access, any changes or additions to your script on disk will not be immediately noticed by the CoffeeMud engine. To force the engine to notice your changes, you must first UNLOAD your script file from the Resources cache. This is done by using the Archon command UNLOAD. Check the ahelp entry for that command for more information on how to use it when developing Scriptable behavior files on disk.

Those who are familiar with the mobprog scripting language in other mud codebases will have no trouble picking up on the CoffeeMud scripting language. In fact, most of your existing scripts will probably work without changes.

Script Structure

The CoffeeMud scripting language is an "event-based" language. Each script may contain one or more event "triggers". Each trigger defines the conditions of its occurrence on a single line. This line is followed by commands underneath it which are executed only when the trigger event occurs. Each event trigger/command grouping is terminated by a ~ character, which should appear on a line by itself. Putting this together, we have a high level syntax that looks like this:

EVENT_TRIGGER parameter1 parameter2 ...
command1
command2
...
commandN
~

ANOTHER_EVENT_TRIGGER parameter1 parameter2 ...
command1
command2
...
commandN
~
etc.

Scripting Events

Below are a list of the valid event triggers, along with their parameters, and a description of the events or circumstances under which the events occur. These docs borrow heavily from the nicely written MOBPROG Tutorial at: http://www.pandapub.com/tutorial/MobprogTutorial.htm.

all_greet_prog

Usage:

all_greet_prog [integer percentage]

This type of mobprog checks a percentage chance every time someone enters the room that the mob is currently in. If the random number generated between 1 and 100 is equal to or below the percentage of the all_greet_prog, the prog is triggered. Note that all_greet_progs are triggered by both players and mobs, and a mob in a maze can actually sometimes end up triggering itself! This type of mobprog has all sorts of uses, ranging from giving in-zone quest information to people entering the room, creating aggressive progs, etc.

EXAMPLES:

all_greet_prog 25

This prog will be triggered 25% of the time when someone enters the room where the mob currently is.

all_greet_prog 100

This prog will be triggered 100% of the time when someone enters the room where the mob currently is. This means every time.

SPECIAL NOTES: You'll probably want to do a large number of if checks in all_greet_progs, specifically in the difference between mobs and player characters. Note that all_greet_progs will trigger even if a person is sneaking, though the mob must have detect invisibility to see invisible people, infravision to see people in the dark, sense sneaking to see sneakers, and will not see people if blinded.

act_prog

mask_prog

Usage:

act_prog [trigger message]
act_prog p [trigger message]

This type of mobprog will trigger when the mob sees a certain string of text. When the 'p' is inserted into the trigger line, the string of text must be precise, while if it is not, any of the words in the list can trigger the mobprog. This type of mobprog has many uses, one of which is communication between mobs. There are a few socials which create a message only to the person performing them and to the one receiving them. You can use these and act_progs to safely have mobs trigger each other, without people seeing what is going on. Other uses include triggering off of people fleeing, moving out of the room, etc. The possibilities are endless.

EXAMPLES:

act_prog wolf dog coyote

This will trigger whenever the mob sees a segment of text containing any of the words wolf, dog, or coyote. If the string contains more than one of these, the prog will be triggered multiple times.

act_prog p A wolf howls at the moon.

This will trigger the prog when it sees this precise message. Note that punctuation is important here as well.

MULTIPLE PROGS: You can have more than one act_prog on a mob, but you shouldn't have multiple act_progs that trigger off of the same message.

SPECIAL NOTES: ANSI colors on objects don't seem to work well with act_progs, so avoid using ANSI colors in anything that may be part of your act_prog trigger. Variables and Codes are not used in act_progs, so do not try to use them; it won't work.

bribe_prog

Usage:

bribe_prog [money value]

This type of mobprog is triggered when a value of money is given to the mob. If the amount of money is equal to or more than the money value of the bribe_prog, the prog will go off. If it is less than the value of the bribe_prog, or the money is not in the local currency, it will not go off. This type of prog is normally used for in-zone quests, perhaps bribing guards to let a prisoner free or bribing a bartender to give you some information. It can also be used for larger, special mob behavior, such as a ferryman who will move a player to another spot in the world for a fee. The money value is always expressed in absolute gold value of the default currency. See the Archon's Guide under currency if you don't know what that means.

EXAMPLES:

bribe_prog 1

This bribe_prog will trigger whenever the mob is given an amount of gold equal to or greater than 1 coin. Of course, this means that the prog will be triggered if any amount of money is given to the mob at all.

bribe_prog 500

This bribe_prog will trigger if someone gives the mob an amount of money equal to or greater than 500 coins.)

MULTIPLE PROGS: You can have multiple bribe_progs on the same mob. However, these must be listed in order from largest gold amount to smallest gold amount. So if you have a bribe_prog 250 and a bribe_prog 100, the 250 must be listed first, and then the 100. If you don't do this your larger sum bribe_progs will never be triggered.

buy_prog

Usage:

buy_prog [keyword list]
buy_prog p [keyword phrase]
buy_prog all

This type of mobprog is triggered by buying an item from a shopkeeper. If the item being bought has any of the keywords of the buy_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the item must exactly match that of the buy_prog. If there is not, then any item with any of the keywords in the list in it will trigger it. If a buy_prog all is used, then the buy_prog will trigger for any item at all being bought. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

buy_prog orange apple banana

This will trigger if the item being bought has any of the keywords orange, apple, or banana. This means that it would be triggered by buying a banana, an apple pie, or even an orange shield.

buy_prog p apple pie delicious

This will trigger if the item being bought has the exact keywords apple pie delicious. The prog would not be triggered by buying anything with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

buy_prog all

This will trigger if any sort of item is bought.

MULTIPLE PROGS: You can have more than one buy_prog on a mob. Generally it is best not to have buy_progs with the same keywords in them, unless they are a buy_prog p with different keyword lists but some of the same keywords – for example a buy_prog p apple red juicy and a buy_prog p apple red poisoned.

channel_prog

Usage:

channel_prog [channel name] [trigger words]
channel_prog [channel name] p [trigger message]

This type of mobprog will trigger when the mob sees a certain string of text over the specified channel. When the 'p' is inserted into the trigger line, the string of text must be precise, while if it is not, any of the words in the list can trigger the mobprog. This type of mobprog has many uses, one of which is communication between mobs. The possibilities are endlessly finite.

EXAMPLES:

channel_prog help me

This will trigger whenever the mob sees a segment of text containing any of the words help or me. If the string contains more than one of these, the prog will be triggered multiple times.

channel_prog p GOSSIP hello.

This will trigger the prog when it sees this message channeled. Note that punctuation is important here as well.

MULTIPLE PROGS: You can have more than one channel_prog on a mob, but you shouldn't have multiple channel_progs that trigger off of the same message.

SPECIAL NOTES: ANSI colors on objects don't seem to work well with channel_progs, so avoid using ANSI colors in anything that may be part of your channel_prog trigger. Variables and Codes are not used in channel_progs, so do not try to use them; it won't work.

close_prog

Usage:

close_prog [keyword list]
close_prog p [keyword list]
close_prog all

This type of mobprog is triggered by closing a container or door. If the script is on a container-type object, such as a door or container item, it will trigger only if the object being closed is the scripted one. Otherwise, if the target matches the keywords of the close_prog, the prog is triggered. If there is a 'p' placed before the keyword list, the keywords of the object must exactly match that of the close_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If the scripted item is not a container or door, and a "close_prog all" is used, then the close_prog will trigger from any object at all being opened. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses. As is normal, if the scripted object is a mob, this event will not trigger if the scripted mob is the originator of the activity.

EXAMPLES:

close_prog door gate

This will trigger if the object closed has any of the keywords door gate. This means that it would be triggered by closing a door or gate.

close_prog p a large chest

This will trigger if the object closed has the exact keywords a large chest.. The prog would not be triggered by closing an object with keywords large or chest or anything except the exact order and wording of the keyword list.

close_prog all

This will trigger if any object is closed.

MULTIPLE PROGS: You can have more than one close_prog on an item, mob, or room. Generally it is best not to have close_progs with the same keywords in them, unless they are a close_progs p with different keyword lists but some of the same keywords - for example a close_progs p door gate and a close_prog p door to the gate.

cnclmsg_prog

Usage:

cnclmsg_prog [message code] [commands/keyword list]
cnclmsg_prog [message code] p [commands/keyword list]
cnclmsg_prog [message code] all

This type of mobprog is definitely for those very familiar with CoffeeMud. In fact, I'd recommend at least a cursory knowledge of the Programmer's Guide to consider using it. The purpose of this trigger is that it executes before a particular event or "message" occurs in the mud. The kind of event is called the "message code". The trigger also requires either the word "all" to always execute before the desired message does, or a list of player command line words matches those typed by the player most recently to the arrival of this message. Since mobs, unlike players, do not enter commands on a command line, you should use the ALL form liberally.

The body of the trigger executes before the given message occurs, and the fact that the trigger executes is no guarentee that the event will end up occuring at all. For instance, this trigger may execute when a player tries to leave the room while under the effects of the "Hold" spell, meaning the player will not actually be allowed to leave regardless of what is done in your trigger. However, this type of trigger is most useful as a means of testing and cancelling certain types of event messages; thus the name. To cause the triggered event to be cancelled, you need only add a RETURN CANCEL command to the body of this script.

See also execmsg_prog. Valid message codes include the following:

AREAAFFECT, PUSH, PULL, RECALL, OPEN, CLOSE, PUT, GET, UNLOCK, LOCK, WIELD, GIVE, BUY, SELL, DROP, WEAR, FILL, DELICATE_HANDS_ACT, VALUE, HOLD, NOISYMOVEMENT, QUIETMOVEMENT, WEAPONATTACK, LOOK, READ, NOISE, SPEAK, CAST_SPELL, LIST, EAT, ENTER, FOLLOW, LEAVE, SLEEP, SIT, STAND, FLEE, NOFOLLOW, WRITE, FIRE, COLD, WATER, GAS, MIND, GENERAL, JUSTICE, ACID, ELECTRIC, POISON, UNDEAD, MOUNT, DISMOUNT, OK_ACTION, OK_VISUAL, DRINK, HANDS, PARALYZE, WAND_USE, SERVE, REBUKE, ADVANCE, DISEASE, DEATH, DEPOSIT, WITHDRAW, EMOTE, QUIT, SHUTDOWN, VIEW, RETIRE, RETREAT,PANIC, THROW, EXTINGUISH, TELL, SITMOVE, KNOCK, PRACTICE, TEACH, REMOVE, EXPCHANGE, DAMAGE, HEALING, ROOMRESET, RELOAD, SNIFF, ACTIVATE, DEACTIVATE, FACTIONCHANGE, LOGIN, LEVEL, EXAMINE, ORDER, EXPIRE, BORROW, HUH

And here are some general message code types that may also be used:

TOUCH,MOVE,EYES,MOUTH,SOUND,GENERAL,MAGIC,DELICATE,MALICIOUS,CHANNEL,OPTIMIZE

EXAMPLES:

cnclmsg_prog hands p smile
  mpechoat $n No smiling is allowed here!
  return cancel
~

This will trigger if a player (not a mob) around the scripted object attempts to smile.

cnclmsg_prog GET p get rock
  mpechoat $n You may not get the rock.
  return cancel
~

This will trigger if a player (not a mob) enters the command "get rock" at the command line, this will trigger and cancel he attempt..

The CNCLMSG_PROG is especially useful for creating new command that only apply in particular rooms or with respect to particular mobs. This is because entering an incorrect command, which normally generates a "Huh?" message, can also be canceled and re-applied. For instance, suppose you wanted users to be able to enter "plastify sword" at some part in your quest and have it do something. In this case, you'd need to capture the HUH message as so:

cnclmsg_prog HUH p plastify sword
  mpechoat $n The sword has been plastified! Thank you!
  return cancel
~

MULTIPLE PROGS: You can have more than one cnclmsg_prog, not only in the same script, but regarding the very same message codes if you like.

consume_prog

Usage:

consume_prog [keyword list]
consume_prog p [keyword list]
consume_prog all

This type of mobprog is triggered eating or drinking from an object. If the object used matches the keywords of the consume_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the consume_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If a consume_prog all is used, then the consume_prog will trigger from any object at all. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

consume_prog orange apple banana

This will trigger if the object eaten has any of the keywords orange, apple, or banana. This means that it would be triggered by eating a banana, an apple pie, or even an orange shield.

consume_prog p apple pie delicious

This will trigger if the object eaten has the exact keywords apple pie delicious. The prog would not be triggered by eating an object with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

consume_prog all

This will trigger if any object is ate or drank.

MULTIPLE PROGS: You can have more than one consume_prog on a mob. Generally it is best not to have consume_progs with the same keywords in them, unless they are a consume_prog p with different keyword lists but some of the same keywords – for example a consume_prog p apple red juicy and a consume_prog p apple red poisoned.

damage_prog

Usage:

damage_prog

This type of mobprog is triggered whenever the scripted mob is damaged, or the scripted item is used to deliver damage. The source and target mobs will be as you expect. The secondary item will be the weapon used to deliver the damage, if it was a physical item (spells are not items). The string returned in $g will be the amount of damage taken.

EXAMPLES:

damage_prog

This program will trigger when damage is taken by a mob, or given by the scripted item.

day_prog

Usage:

day_prog [list of integer day of the month]

This type of mobprog triggers once per mud day, on the days of the month listed. This allows you to have a script which triggers very infrequently indeed. There are 30 days per month in CoffeeMud.

EXAMPLES:

day_prog 20 21 22

This will trigger if day of the month is 20, 21, or 22.

day_prog 10

This will trigger on the 10th day of every month.

death_prog

Usage:

death_prog

This mobprog type triggers on the mob's death. The death_prog has a wide range of uses. The death_prog is queued just before the mob dies, so it is considered to be the mob's last gasp. At the end of the death-prog, however, the mob dies. Even if the mob sets its hit points to full, it will die. Other than that, the mob can mpjunk equipment it has, mpgoto a new room to die, unlock a door, load an object of some kind, etc.

MULTIPLE PROGS: You can have multiple death_progs on the same mob.

delay_prog

Usage:

delay_prog [integer, minimum number of ticks] [integer, maximum number of ticks]

This kind of mobprog triggers after a random number of ticks have elapsed. The number of random ticks is between the two integers provided. This trigger is used to take some of the load off of rand_prog type programs.

EXAMPLES:

delay_prog 10 20

This delay_prog will be triggered after 10-20 ticks have elapsed.

delay_prog 1 11

This delay_prog will be triggered after 1-11 ticks have elapsed.

drop_prog

Usage:

drop_prog [keyword list]
drop_prog p [keyword list]
drop_prog all

This type of mobprog is triggered by dropping an object. If the object dropped matches the keywords of the drop_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the drop_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If a drop_prog all is used, then the drop_prog will trigger from any object at all being dropped. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

drop_prog orange apple banana

This will trigger if the object dropped has any of the keywords orange, apple, or banana. This means that it would be triggered by dropping a banana, an apple pie, or even an orange shield.

drop_prog p apple pie delicious

This will trigger if the object dropped has the exact keywords apple pie delicious. The prog would not be triggered by dropping an object with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

drop_prog all

This will trigger if any object is dropped.

MULTIPLE PROGS: You can have more than one drop_prog on a mob. Generally it is best not to have drop_progs with the same keywords in them, unless they are a drop_prog p with different keyword lists but some of the same keywords – for example a drop_prog p apple red juicy and a drop_prog p apple red poisoned.

entry_prog

Usage:

entry_prog [integer percentage]

This type of prog checks a percentage chance every time the mob moves into a new room. If the random number generated is equal to or below the percentage of the entry_prog when the mob steps into a new room, then the prog is triggered. This prog has a variety of uses, for instance, you can use it in conjunction with the inroom function to make sure a mob stays in the same room or never oversteps a boundary, or to have the mob attack players as it enters the room. There are many possibilities.

EXAMPLES:

entry_prog 25

This will trigger 25% of the time when the mob enters a room.

entry_prog 100

This will trigger 100%, or every time, the mob enters a room.

execmsg_prog

Usage:

execmsg_prog [message code] [commands/keyword list]
execmsg_prog [message code] p [commands/keyword list]
execmsg_prog [message code] all

This type of mobprog is definitely for those very familiar with CoffeeMud. In fact, I'd recommend at least a cursory knowledge of the Programmer's Guide to consider using it. The purpose of this trigger is that it executes while a particular and valid event or "message" occurs in the mud. The kind of event is called the "message code". The trigger also requires either the word "all" to always execute whenever the desired message does, or a list of player command line words matching those typed by the player most recently to the arrival of this message. Since mobs, unlike players, do not enter commands on a command line, you should use the ALL form liberally.

See also cnclmsg_prog. Valid message codes include the following:

AREAAFFECT, PUSH, PULL, RECALL, OPEN, CLOSE, PUT, GET, UNLOCK, LOCK, WIELD, GIVE, BUY, SELL, DROP, WEAR, FILL, DELICATE_HANDS_ACT, VALUE, HOLD, NOISYMOVEMENT, QUIETMOVEMENT, WEAPONATTACK, LOOK, READ, NOISE, SPEAK, CAST_SPELL, LIST, EAT, ENTER, FOLLOW, LEAVE, SLEEP, SIT, STAND, FLEE, NOFOLLOW, WRITE, FIRE, COLD, WATER, GAS, MIND, GENERAL, JUSTICE, ACID, ELECTRIC, POISON, UNDEAD, MOUNT, DISMOUNT, OK_ACTION, OK_VISUAL, DRINK, HANDS, PARALYZE, WAND_USE, SERVE, REBUKE, ADVANCE, DISEASE, DEATH, DEPOSIT, WITHDRAW, EMOTE, QUIT, SHUTDOWN, VIEW, RETIRE, RETREAT,PANIC, THROW, EXTINGUISH, TELL, SITMOVE, KNOCK, PRACTICE, TEACH, REMOVE, EXPCHANGE, DAMAGE, HEALING, ROOMRESET, RELOAD, SNIFF, ACTIVATE, DEACTIVATE, FACTIONCHANGE, LOGIN, LEVEL, EXAMINE, BORROW

And here are some general message code types that may also be used:

TOUCH,MOVE,EYES,MOUTH,SOUND,GENERAL,MAGIC,DELICATE,MALICIOUS,CHANNEL,OPTIMIZE

EXAMPLES:

execmsg_prog get all
  mpecho $n likes $p.
~

This will trigger if a player or a mob attempts to get something.

execmsg_prog GET p get rock
  mpecho $n has gotten a rock!
~

This will trigger if a player (not a mob) enters the command "get rock" at the command line, this will trigger.

MULTIPLE PROGS: You can have more than one execmsg_prog, not only in the same script, but regarding the very same message codes if you like. However, only the first one that triggers will count.

exit_prog

Usage:

exit_prog [integer percentage]

This type of prog checks a percentage chance every time a mob moves out of a the room the scripted mob is in. If the random number generated is equal to or below the percentage of the exit_prog when the mob steps out of the room, then the prog is triggered. This prog has a variety of uses, for instance, you can use it in conjunction with the inroom function to make sure other mobs stay in the same room or never oversteps a boundary, or to have the mob attack remaining players when one leaves. There are many possibilities.

EXAMPLES:

exit_prog 25

This will trigger 25% of the time when a mob leaves the room.

exit_prog 100

This will trigger 100%, or every time, a mob leaves the room.

fight_prog

Usage:

fight_prog [integer percentage]

This type of mobprog checks a percentage chance every round of combat that the mob is in. If the random number generated between 1 and 100 is equal to or less than the percentage of the fight_prog, then it will be triggered. This type of mobprog is generally used to have the mob do certain things in combat, for instance, cast spells or use skills. Sometimes it is used to ensure a mob doesn't fight at all, or to perform special, more complicated actions in combat.

EXAMPLES:

fight_prog 10

This will trigger 10% of the time each round of combat the mob is in. That means that it is probable that this mobprog will go off every 10 rounds or so, although it is not guaranteed to do so.

fight_prog 75

This will trigger 75% of the time each combat round. That means it's a safe bet that the trigger will go off 3 out of every 4 rounds.

function_prog

Usage:

function_prog [string name of the function]

This type of prog provides a named placeholder for the series of commands that follows. This type of mobprog is never independently triggered, but instead relys on one of the commands, MPCALLFUNC, to trigger it manually. The usefulness of doing this will become apparent in the discussion of MPCALLFUNC.

EXAMPLES:

function_prog Destroy Everyone

This will trigger only when called by MPCALLFUNC.

get_prog

Usage:

get_prog [keyword list]
get_prog p [keyword list]
get_prog all

This type of mobprog is triggered by getting an object. If the object picked up matches the keywords of the get_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the get_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If a get_prog all is used, then the get_prog will trigger from any object at all being picked up. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

get_prog orange apple banana

This will trigger if the object picked up has any of the keywords orange, apple, or banana. This means that it would be triggered by getting a banana, an apple pie, or even an orange shield.

    get_prog p apple pie delicious

This will trigger if the object picked up has the exact keywords apple pie delicious. The prog would not be triggered by getting an object with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

get_prog all

This will trigger if any object is picked up.

MULTIPLE PROGS: You can have more than one get_prog on a mob. Generally it is best not to have get_progs with the same keywords in them, unless they are a get_prog p with different keyword lists but some of the same keywords – for example a get_prog p apple red juicy and a get_prog p apple red poisoned.

give_prog

Usage:

give_prog [keyword list]
give_prog p [keyword list]
give_prog all

This type of mobprog is triggered by the mob being given an object. If the object given to the mob matches the keywords of the give_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the give_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If a give_prog all is used, then the give_prog will trigger from any object at all being given to the mob. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

give_prog orange apple banana

This will trigger if the object given to the mob has any of the keywords orange, apple, or banana. This means that it would be triggered by being given a banana, an apple pie, or even an orange shield.)

give_prog p apple pie delicious

This will trigger if the object given to the mob has the exact keywords apple pie delicious. The prog would not be triggered by being given an object with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

give_prog all

This will trigger if any object is given to the mob.

MULTIPLE PROGS: You can have more than one give_prog on a mob. Generally it is best not to have give_progs with the same keywords in them, unless they are a give_prog p with different keyword lists but some of the same keywords – for example a give_prog p apple red juicy and a give_prog p apple red poisoned.

SPECIAL NOTES: More often than not, you'll want to remember to have the mob use the mpjunk command to get rid of the object given so people cannot steal the item back and use it again. It does depend on what you are doing of course, but it is something to keep in mind. It is also not a bad idea to have a give_prog all to have the mob drop items other than the ones it will accept in other give_progs.

greet_prog

Usage:

greet_prog [integer percentage]

This type of mobprog checks a percentage chance every time someone enters the room that the mob is currently in. If the random number generated between 1 and 100 is equal to or below the percentage of the greet_prog, the prog is triggered. Note that greet_progs are triggered by both players and mobs, and a mob in a maze can actually sometimes end up triggering itself! This type of mobprog has all sorts of uses, ranging from giving in-zone quest information to people entering the room, creating aggressive progs, etc.

EXAMPLES:

greet_prog 25

This prog will be triggered 25% of the time when someone enters the room where the mob currently is.

greet_prog 100

This prog will be triggered 100% of the time when someone enters the room where the mob currently is. This means every time.

SPECIAL NOTES: You'll probably want to do a large number of if checks in greet_progs, specifically in the difference between mobs and player characters. Note that greet_progs will trigger except if a person is sneaking. Also, the mob must have detect invisibility to see invisible people, infravision to see people in the dark, and will not see people if blinded.

hitprcnt_prog

Usage:

hitprcnt_prog [integer percentage]

This type of mobprog checks every round of combat to see if the mob's hit points are equal to or under the percentage given to the hitprcnt_prog. This type of prog is used mainly to have the mob do something at a certain percentage of hit points. Keep in mind, however, that this prog will trigger EVERY round of combat in which the mob's hit points are under the percentage. So if you want the mob to do only one thing, you will have to set up the mobprog that way with if checks.

EXAMPLES:

hitprcnt_prog 50

This will trigger if the mob's hit points are 50% or under every round of combat.

hitprcnt_prog 100

This will trigger if the mob's hit points are 100% or under every round of combat. This means, more or less, every round of combat the mob will ever be in.

imask_prog

Usage:

imask_prog [trigger message]
imask_prog p [trigger message]

This type of mobprog will trigger when the mob does a thing that generates a certain string of text. When the 'p' is inserted into the trigger line, the string of text must be precise, while if it is not, any of the words in the list can trigger the mobprog. This type of mobprog has many uses, one of which is to have one action trigger another. The possibilities are almost endless, except that this trigger is meaningless unless the scripted object is a mob, since only mobs can generate events.

EXAMPLES:

imask_prog wolf dog coyote

This will trigger whenever the mob does something that generates a segment of text containing any of the words wolf, dog, or coyote. If the string contains more than one of these, the prog will be triggered multiple times.

act_prog p A wolf howls at the moon.

This will trigger the prog when mob does something that generates this precise message. Note that punctuation is important here as well.

MULTIPLE PROGS: You can have more than one imask_prog on a mob, but you shouldn't have multiple imask_progs that trigger off of the same message.

SPECIAL NOTES: ANSI colors on objects don't seem to work well with imask_progs, so avoid using ANSI colors in anything that may be part of your imask_prog trigger. Variables and Codes are not used in imask_progs, so do not try to use them; it won't work.

kill_prog

Usage:

kill_prog

This mobprog type triggers when the mob causes death. The kill_prog has a wide range of uses. The kill_prog is queued just before the target dies, so it is considered to be the target's last gasp. At the end of the kill-prog, however, the target dies. Even if the target sets its hit points to full, it will die. Other than that, the mob can mpjunk equipment it has, mptrasnfer a new room to die, unlock a door, load an object of some kind, etc.

MULTIPLE PROGS: You can have multiple kill_progs on the same mob.

level_prog

Usage:

level_prog [integer percentage]

This type of mobprog checks a percentage chance every time a player gains a level anywhere in the game. If the random number generated between 1 and 100 is equal to or below the percentage of the level_prog, the prog is triggered.

EXAMPLES:

level_prog 25

This prog will be triggered 25% of the time when someone levels.

level_prog 100

This prog will be triggered 100% of the time when someone levels. This means every time.

SPECIAL NOTES: This program will trigger every time a player levels, regardless of whether they are in the same room, or even whether the scripted monster can see or detect the player. The exception to this is cloaked admins, which will not trigger.

lock_prog

Usage:

lock_prog [keyword list]
lock_prog p [keyword list]
lock_prog all

This type of mobprog is triggered by locking a container or door. If the script is on a container-type object, such as a door or container item, it will trigger only if the object being locked is the scripted one. If the target matches the keywords of the lock_prog, the prog is triggered. If there is a 'p' placed before the keyword list, the keywords of the object must exactly match that of the lock_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If the scripted item is not a container or door, and a "lock_prog all" is used, then the lock_prog will trigger from any object at all being locked. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses. As is normal, if the scripted object is a mob, this event will not trigger if the scripted mob is the originator of the activity.

EXAMPLES:

lock_prog door gate

This will trigger if the object locked has any of the keywords door gate. This means that it would be triggered by locking a door or gate.

lock_prog p a large chest

This will trigger if the object locked has the exact keywords a large chest.. The prog would not be triggered by locking an object with keywords large or chest or anything except the exact order and wording of the keyword list.

lock_prog all

This will trigger if any object is locked.)

MULTIPLE PROGS: You can have more than one lock_prog on an item, mob, or room. Generally it is best not to have lock_progs with the same keywords in them, unless they are a lock_prog p with different keyword lists but some of the same keywords - for example a lock_prog p door gate and a lock_prog p door to the gate

login_prog

Usage:

login_prog [integer percentage]

This type of mobprog checks a percentage chance every time someone enters the game. If the random number generated between 1 and 100 is equal to or below the percentage of the login_prog, the prog is triggered.

EXAMPLES:

login_prog 25

This prog will be triggered 25% of the time when someone enters the game.

login_prog 100

This prog will be triggered 100% of the time when someone enters the game. This means every time.

SPECIAL NOTES: This program will trigger every time a player enters the game, regardless of whether they are in the same room, or even whether the scripted monster can see or detect the player. The exception to this is cloaked admins, which will not trigger

logoff_prog

Usage:

logoff_prog [integer percentage]

This type of mobprog checks a percentage chance every time someone leaves the game. If the random number generated between 1 and 100 is equal to or below the percentage of the logoff_prog, the prog is triggered.

EXAMPLES:

logoff_prog 25

This prog will be triggered 25% of the time when someone leaves the game.

logoff_prog 100

This prog will be triggered 100% of the time when someone leaves the game. This means every time.

SPECIAL NOTES: This program will trigger every time a player leaves the game, regardless of whether they are in the same room, or even whether the scripted monster can see or detect the player. The exception to this is cloaked admins, which will not trigger.

llook_prog

look_prog

Usage:

look_prog [keyword list]
look_prog p [keyword list]
look_prog all
llook_prog [keyword list]
llook_prog p [keyword list]
llook_prog all

This type of mobprog is triggered by looking at the scripted item. The "llook" version triggers if the item is "examined". If the target matches the keywords of the lock_prog, the prog is triggered. If there is a 'p' placed before the keyword list, the keywords of the object must exactly match that of the look_prog. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses. As is normal, if the scripted object is a mob, this event will not trigger if the scripted mob is the originator of the activity.

EXAMPLES:

llook_prog all

This will trigger if any the scripted item, room, or mob is examined.

look_prog all

This will trigger if any the scripted item, room, or mob is looked at.

MULTIPLE PROGS: It is generally useless to have more than one look_prog on an item, mob, or room.

once_prog

Usage:

once_prog

This type of mobprog is triggered immediately by the script engine under all circumstances, but is never triggered again. This makes it useful for doing initialization or other tasks which only need to be done once after the mud boots. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

once_prog

This will trigger once, right away

MULTIPLE PROGS: You can have only one once_prog on a mob.

open_prog

Usage:

open_prog [keyword list]
open_prog p [keyword list]
open_prog all

This type of mobprog is triggered by opening a container or door. If the script is on a container-type object, such as a door or container item, it will trigger only if the object being opened is the scripted one. Otherwise, if the target matches the keywords of the open_prog, the prog is triggered. If there is a 'p' placed before the keyword list, the keywords of the object must exactly match that of the open_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If the scripted item is not a container or door, and a "open_prog all" is used, then the open_prog will trigger from any object at all being opened. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses. As is normal, if the scripted object is a mob, this event will not trigger if the scripted mob is the originator of the activity.

EXAMPLES:

open_prog door gate

This will trigger if the object opened has any of the keywords door gate. This means that it would be triggered by opening a door or gate.

open_prog p a large chest

This will trigger if the object opened has the exact keywords a large chest.. The prog would not be triggered by opening an object with keywords large or chest or anything except the exact order and wording of the keyword list.

open_prog all

This will trigger if any object is opened.

MULTIPLE PROGS: You can have more than one open_prog on an item, mob, or room. Generally it is best not to have open_progs with the same keywords in them, unless they are a open_progs p with different keyword lists but some of the same keywords - for example a open_prog p door gate and a open_prog p door to the gate.

quest_time_prog

Usage:

quest_time_prog [quest name] [number of minutes remaining]

This kind of mobprog triggers only if the script is part of an official Quest, and only if the number of minutes remaining in the quest is equal to the number of minutes specified. This is used as part of a quest plot line, to allow the mobs to give warnings about a quest that is running out of time. If the Scriptable behavior was granted as part of a Quest, then * may be substituted for the questname.

EXAMPLES:

quest_time_prog 'my quest' 20

This quest_time_prog will be triggered on the final 20th minute of the quest 'my quest'.

quest_time_prog 'my quest' 1

This quest_time_prog will be triggered on the final minute of the quest 'that quest'.

put_prog

Usage:

put_prog [keyword list]
put_prog p [keyword list]
put_prog all

This type of mobprog is triggered by putting something in a container. If the container being used matches the keywords of the put_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the put_prog. If there is not, then any container with any of the keywords in the list in it will trigger it. If a put_prog all is used, then the put_prog will trigger from any container at all being used. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

put_prog orange apple banana

This will trigger if the container used has any of the keywords orange, apple, or banana. This means that it would be triggered by putting something into a banana, an apple pie, or even an orange shield.

put_prog p apple pie delicious

This will trigger if the container used up has the exact keywords apple pie delicious. The prog would not be triggered by putting anything into a container with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

put_prog all

This will trigger if any container is used.

MULTIPLE PROGS: You can have more than one put_prog on a mob. Generally it is best not to have put_progs with the same keywords in them, unless they are a put_prog p with different keyword lists but some of the same keywords – for example a put_prog p apple red juicy and a put_prog p apple red poisoned.

rand_prog

Usage:

rand_prog [integer percentage]

This kind of mobprog checks a percentage chance every tick. If the random number generated between 1 and 100 is equal to or below the percentage of the rand_prog, then it will be triggered. This type of mobprog can be triggered at any time, so long as the mob is alive, including while it is sleeping or fighting. They are very useful for setting up certain elements of your zone, or for giving personality to your mobs, such as having a blacksmith who pounds out a sword. This kind of mobprog ONLY goes off when a player is in the same zone that your mob is in.

EXAMPLES:

rand_prog 20

This rand_prog will be triggered 20% of each tick.

rand_prog 75

This rand_prog will be triggered 75% of each tick.

SPECIAL NOTES: While using rand_progs seems really easy, having a lot of them can slow down your zone. Having extremely long rand_progs on many, many mobs is generally not a good idea. If possible, consider other options, and only use rand_progs that go off at a high rate on mobs that will perform the rand_prog once and then never again, either because they have some sort of internal check, or because they go and mppurge themselves afterwards.

regmask_prog

Usage:

regmask_prog [java regular expression]
regmask_prog p [exact, case sensitive message]

This type of mobprog will trigger when the mob sees a certain string of text. When the 'p' is inserted into the trigger line, the string of text must be precisely the same, case included, as the string generated. If 'p' is not the first character, then the trigger will attempt to find the first match of the given java regular expression string. This type of mobprog has many uses, one of which is communication between mobs. There are a few socials which create a message only to the person performing them and to the one receiving them. You can use these and act_progs to safely have mobs trigger each other, without people seeing what is going on. Other uses include triggering off of people fleeing, moving out of the room, etc. The possibilities are endless.

EXAMPLES:

regmask_prog a*be

This will trigger whenever the mob sees a segment of text starting with the lowercase letter a, then containing 0 or more other letter as followed by the string "be". This would match aaaaabe

regmask_prog p A wolf howls at the moon.

This will trigger the prog when it sees this precise message. Note that punctuation and case is important here as well.

MULTIPLE PROGS: You can have more than one regmask_prog on a mob, but you shouldn't have multiple regmask_progs that trigger off of the same message.

SPECIAL NOTES: ANSI colors on objects don't seem to work well with regmask_progs, so avoid using ANSI colors in anything that may be part of your regmask_prog trigger. Variables and Codes are not used in regmask_progs, so do not try to use them; it won't work.

remove_prog

Usage:

remove_prog [keyword list]
remove_prog p [keyword list]
remove_prog all

This type of mobprog is triggered by removing an object. If the object removed matches the keywords of the remove_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the remove_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If a remove_prog all is used, then the remove_prog will trigger from any object at all being removed by the mob. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

remove_prog orange apple banana

This will trigger if the object removed has any of the keywords orange, apple, or banana. This means that it would be triggered by removing a banana, an apple pie, or even an orange shield.

remove_prog p apple pie delicious

This will trigger if the object removed has the exact keywords apple pie delicious. The prog would not be triggered by removing an object with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

remove_prog all

This will trigger if any object is removed.

MULTIPLE PROGS: You can have more than one remove_prog on a mob. Generally it is best not to have remove_progs with the same keywords in them, unless they are a remove_prog p with different keyword lists but some of the same keywords – for example a remove_prog p apple red juicy and a remove_prog p apple red poisoned.

sell_prog

Usage:

sell_prog [keyword list]
sell_prog p [keyword phrase]
sell_prog all

This type of mobprog is triggered by selling an item to a shopkeeper. If the item being sold has any of the keywords of the sell_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the item must exactly match that of the sell_prog. If there is not, then any item with any of the keywords in the list in it will trigger it. If a sell_prog all is used, then the sell_prog will trigger for any item at all being sold. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

sell_prog orange apple banana

This will trigger if the item being sold has any of the keywords orange, apple, or banana. This means that it would be triggered by selling a banana, an apple pie, or even an orange shield.

sell_prog p apple pie delicious

This will trigger if the item being sold has the exact keywords apple pie delicious. The prog would not be triggered by selling anything with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

sell_prog all

This will trigger if any sort of item is sold.

MULTIPLE PROGS: You can have more than one sell_prog on a mob. Generally it is best not to have sell_progs with the same keywords in them, unless they are a sell_prog p with different keyword lists but some of the same keywords – for example a sell_prog p apple red juicy and a sell_prog p apple red poisoned.

social_prog

Usage:

social_prog [social name]

This type of mobprog is triggered by a social of the looked for name being done in the same room. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

social_prog smile

This will trigger if the smile social is done in the same room as the scripted object.

MULTIPLE PROGS: You can have more than one social_prog on a mob. Generally it is best not to have social_progs with the same social trigger in them.

speech_prog

Usage:

speech_prog [trigger message]
speech_prog p [trigger message]

This type of mobprog is triggered by someone saying the trigger line, be it mob or player. If a 'p' is inserted in the prog as above, the line spoken must exactly match the trigger message; if it is not, then any of the keywords listed will trigger the mobprog. A keyword of ALL will trigger on any speech. This type of mobprog is useful for setting up internal quests, giving out background information to people exploring your zone, or setting up passwords that must be spoken. This type of prog can also be used to have a mob trigger itself if you want to have multiple connected progs – see complex progs for details. Note that this kind of mobprog is only triggered by someone using the say command.

EXAMPLES:

speech_prog dog wolf coyote

This will trigger the prog whenever dog, wolf, or coyote is said in the room with the mob. If more than one of the keywords is spoken in the same line, the prog will trigger more than once.

speech_prog p The dog barks at the cat

This will trigger the prog only if the exact expression is said. Note that punctuation counts, although you don't *have* to use it.

MULTIPLE PROGS: You can have more than one speech_prog on a mob. It is generally not a good idea to have more than one speech_prog be triggered by the same expression.

time_prog

Usage:

time_prog [list of hours in the day]

This type of mobprog triggers once per mud hour, on the hours of the day listed. This allows you to have a script which triggers infrequently. There are 16 hours per day (0-15) in CoffeeMud.

EXAMPLES:

time_prog 10 1 2

This will trigger if hour of the day is 10, 1, or 2.

time_prog 3

This will trigger on the 3rd hour of every day.

unlock_prog

Usage:

unlock_prog [keyword list]
unlock_prog p [keyword list]
unlock_prog all

This type of mobprog is triggered by unlocking a container or door. If the script is on a container-type object, such as a door or container item, it will trigger only if the object being unlocked is the scripted one. If the target matches the keywords of the unlock_prog, the prog is triggered. If there is a 'p'; placed before the keyword list, the keywords of the object must exactly match that of the unlock_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If the scripted item is not a container or door, and a "unlock_prog all" is used, then the unlock_prog will trigger from any object at all being unlocked. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses. As is normal, if the scripted object is a mob, this event will not trigger if the scripted mob is the originator of the activity.

EXAMPLES:

unlock_prog door gate

This will trigger if the object unlocked has any of the keywords door gate. This means that it would be triggered by unlocking a door or gate.

unlock_prog p a large chest

This will trigger if the object unlocked has the exact keywords a large chest.. The prog would not be triggered by unlocking an object with keywords large or chest or anything except the exact order and wording of the keyword list.

unlock_prog all

This will trigger if any object is unlocked.

MULTIPLE PROGS: You can have more than one unlock_prog on an item, mob, or room. Generally it is best not to have unlock_progs with the same keywords in them, unless they are a unlock_prog p with different keyword lists but some of the same keywords - for example a unlock_prog p door gate and a unlock_prog p door to the gate.

wear_prog

Usage:

wear_prog [keyword list]
wear_prog p [keyword list]
wear_prog all

This type of mobprog is triggered by wearing, wielding, or holding an item. If the object worn matches the keywords of the wear_prog, the prog is triggered. If there is a ‘p' placed before the keyword list, the keywords of the object must exactly match that of the wear_prog. If there is not, then any object with any of the keywords in the list in it will trigger it. If a wear_prog all is used, then the wear_prog will trigger from any object at all worn. This type of prog is usually used for in-zone quests and special mob behavior, and has a variety of uses.

EXAMPLES:

wear_prog orange apple banana

This will trigger if the object worn has any of the keywords orange, apple, or banana. This means that it would be triggered by wearing a banana, an apple pie, or even an orange shield.

wear_prog p apple pie delicious

This will trigger if the object worn has the exact keywords apple pie delicious. The prog would not be triggered by wearing an object with keywords red apple or blackberry pie or anything except the exact order and wording of the keyword list.

wear_prog all

This will trigger if any object is worn.

MULTIPLE PROGS: You can have more than one wear_prog on a mob. Generally it is best not to have wear_progs with the same keywords in them, unless they are a wear_prog p with different keyword lists but some of the same keywords – for example a wear_prog p apple red juicy and a wear_prog p apple red poisoned.

Scripting Codes

Most commands in your scripts allow you to use variable-like scripting Codes instead of literals. A literal is a specific static string or number, such as 'the hairy blog' or 'green' or '72'. A scripting code, however, is a special string which represents a literal and stands for it in your scripts.

Understanding scripting codes is absolutely necessary for you to write scripts successfully. When a DEATH_PROG triggers, for example, it is impossible for the commands that execute to guess the name of the mobs killer. Therefore the name of the killer is stored in a scripting code for you. In this case, that code is $n. This allows you to use the code $n in your DEATH_PROG commands and be sure that wherever you use it, it is referring to "the creature that killed me".

Also, when using commands that cause strings to echo, you may want to use a pronoun to refer to the creature who triggers an event. Guessing, however, won't work here either. In the case of our DEATH_PROG example, we could use the code $m and be sure that, whever it appears, the word 'his', 'her', or 'it' will replace it appropriately.

Below is a list of the simple scripting codes, along with their meaning. The term 'monster' below refers to whatever object, mob, item, room, exit, etc actually has the Scriptable behavior and is running the script. Otherwise, we also refer to the source of the trigger event and the target of the trigger event. For instance, when someone 'A' gets a sword off the ground in front of a mob 'B' with the Scriptable behavior, the MASK_PROG might trigger with the monster being the mob 'B', the source being the someone 'A', and the target being the sword.

$a Name of the area the monsters in.
$b Name of last mob or item loaded with MPMLOAD or MPOLOAD commands
$B Display text of last mob or item loaded with MPMLOAD or MPOLOAD commands
$c A random pc or npc inhabitants name
$C A random pc or npd inhabitants name
$i The Monsters name.
$I The Monsters display text.
$n The Source of the triggers name.
$N The Source of the triggers name.
$t The Target of the triggers name.
$T The Target of the triggers name.
$r A random pc inhabitants name.
$R A random pc inhabitants name.
$j The pronoun he/she of the monster.
$e The pronoun he/she of the source of the trigger.
$f Name of the person which the monster follows.
$E The pronoun he/she of the trigger target.
$F The he/she of the person which the monster follows.
$J The pronoun he/she of a random pc inhabitant.
$k The possessive pronoun his/her of the monster.
$l A list of all mobs (excluding monster). See "." syntax below.
$L A list of all Items in room. See "." syntax below.
$m The pronoun his/her of the source of the trigger.
$M The pronoun his/her of the target of the trigger.
$d The title of the room of the scripted monster.
$D The long description of the room of the scripted monster.
$K The pronoun his/her of a random pc inhabitant.
$o The name of item#1.
$O The name of item#1.
$p The name of item#2.
$P The name of item#2.
$w The name of the owner of item#1.
$W The name of the owner of item#2.
$g The lowercase form of the message or parameters from a MPCALLFUNC, MASK_PROG or SPEECH_PROG.
$G The uppercase form of the message or parameters from a MPCALLFUNC, MASK_PROG or SPEECH_PROG.
$x Displays a random (or specified) exit by the exits direction code (north, south, etc)
$X Displays a random (or specified) exit by the exits direction name (door, etc etc)
$xN Specified directions name (Where N may be N, S, E, W, U, or D). Will display the direction Code. Use $X for exit name.
$0 .. $9 Temporary variables used by other commands, especially FOR, MPARGSET command.
$<[code] [var name]> The variable of the given name, and the given code. Where code is $i, $n, $t, $o, $w, $W, or $p. See MPSETVAR below.
${[num] [*/quest name]} A mob name from the given quest, if the quest is running. The number corresponds to the order in which mobs were designated in the quest script. Counting starts at 1.
$[[num] [*/quest name]] An item name from the given quest, if the quest is running. The number corresponds to the order in which items were designated in the quest script. Counting starts at 1.

Any of the above codes may be followed by a period and a literal number to designate a particular word inside a string of many words. For instance, if $o evaluates to "a magic wand", then $o.1 would evalulate to "magic". If $l evaluated to "orc bob hassan", then $l.2 would give "hassan". This can be very useful when used with the $l or $L codes to iterate through the contents of a room. This syntax can also be used to generate substrings by following the number with two periods "..". For instance, of $l evaluates to "orc bob hassan", then $l.1.. would give "bob hassan".

The last code we are going to discuss is also the most powerful. It allows you to fill in a value from a function call. The format of this code is as follows:

$%[function name]([parameters])% This will replace the code with a value from one of the internal functions listed below. While the names are the same as the eval functions used in IF statements, their parameters will be slightly different.

The [function name] must be the name of one of the functions listed in the following chart. All functions must have parenthesis after their names, and most functions require one or more parameters inside the parenthesis.

The parameters usually include a [code]. This may be either the string name of either a mob or an item (whichever is appropriate to the function), or a code from the previous chart which represents a mob or an item. The description for each function will specify whether mob names or codes representing mobs are more appropriate, or whether item names or codes representing items are more appropriate.

Here is an example of this code being used in a say statement:

say I am $%isgood($i)% and my favourite number is $%rand()%.

This string would replace the $%.. codes with the results of the given function calls.

Here is the list of accepted functions for the $% code. Where 'monster' is referred to below, you may assume this to be whatever object (mob, item, room, exit) which has the Scriptable behavior on it. Usually this is an npc mob. In the case of an item, it refers to a mob who takes the place of the item for scripting purposes. For this reason, using $i and $I codes, or using functions which only return information about the scripted monster when an item is being scripted is totally useless.

AFFECTED([code]) Returns the name of a random spell affect on the given mob or item.
BASECLASS([code]) Returns the base class of the given mob.
CALLFUNC([function name] [parms]) Calls the FUNCTION_PROG of the given name, with the given parameters, and returns the value returned by the program using the RETURN statement.
CLAN([code]) Returns the clan of the given mob.
CLANRANK([code]) Returns the rank of the given mob in their clan.
CLANDATA([clan code] [variable]) Returns data about the given clan. See CLANDATA function below for variables.
CLASS([code]) Returns the class of the given mob.
CURRENCY([code]) Returns the native currency of the given mob or coins.
DATETIME([TYPE]) Returns the hour, day, month, or year. For type, use HOUR, DAY, MONTH, or YEAR.
DEITY([code]) Returns the deity of the given mob.
EVAL() Not implemented -- do not use.
EXP([code]) Returns the experience points of the given mob.
EXPLORED([code] [areaname or world]) Returns the % the given mob has explored of the world or the specified area.
FACTION([mob code] [faction id]) Returns the range name for the given mob within the given faction.
GOLDAMT([code]) Returns the total value of the money the given mob has, or value of item, expressed in base gold.
GSTAT([code] [stat variable]) Value of the given stat variable for the given mob or item. For example: $%GSTAT($i strength)% See the MPGSET command below for a complete list of variables.
HAS([code]) Returns the name of a random item in the scripted monsters inventory.
HASNUM([code] [item name]) Returns the number of a given item in the given mob or rooms inventory.
HASTITLE([code]) Returns the selected title of the given player mob.
HITPRCNT([code]) Return the % of hit points remaining for the given mob.
INAREA() Returns the name of the area the scripted monster is in.
INCONTAINER([code]) Teturns the name of the container of the given item, or the mount of the given mob, depending on the code.
INLOCALE() Returns the name of the room type the monster is in (plains, city, mountains, hills, watersurface, etc).
INROOM() Returns the raw id of the room the scripted monster is in.
IPADDRESS([code]) Returns the ipaddress of the player.
ISABLE([code] [skill name]) Returns the given mobs proficiency in the given skill/spell/ability.
ISALIVE([code]) Returns the health of the given mob.
ISBEHAVE([code]) Returns the class ids of the behaviors on the given mob or item.
ISBIRTHDAY([code]) Returns a description of the given mobs birthday date.
ISCHARMED([code]) Returns the name of the charm spell the mob is under.
ISDAY() Returns word the word day or the word evening.
ISEVIL([code]) Returns the short alignment string of the given mob.
ISFIGHT([code]) Returns the name of the creature the given mob is fighting, or nothing otherwise.
ISFOLLOW([code]) Returns the name of the creature the given mob is following, or nothing otherwise.
ISGOOD([code]) Returns the alignment string of the given mob.
ISHERE() Returns the name of the area the scripted monster is in.
ISIMMORT([code]) not implemented.
ISLIKE([zapper mask]) Returns human-readable description of the given mask.
ISLOCKED([code or direction]) Returns the key name if the given container name or direction has a lock. The code may refer to an item container with a lock, or a direction name, such as north, south, east, etc.
ISMOON() Returns the moon phase description.
ISNAME([code]) Returns the real/full name of the given object.
ISNEUTRAL([code]) Returns the alignment number of the given mob (0-1000).
ISNPC([code]) Not implemented -- do not use.
ISODD([number]) Echoes back the number if it is an odd whole number.
ISOPEN([code or direction]) Returns "true" if the container item is open, or the exit in the given direction name is open.
ISPC([code]) Not implemented -- do not use..
ISQUESTMOBALIVE() Not implemented -- do not use..
ISRECALL([code]) Returns the start room of the given mob.
ISSEASON() Returns the name of the season.
ISSERVANT([code]) Returns the name of the creature the given mob is serving, or nothing otherwise.
ISTIME() Returns the approximate time of day in words.
ISWEATHER() Returns a description of the weather in a short sentence.
LEVEL([code]) Returns the level of the given mob.
MATH([expression]( Returns result of evaluated mathematical expression. Use +, -, *, or \
MOBITEM([code] [integer number]) Returns the nth item owned by the given mob.
MOOD([code]) Returns the mood of the given mob.
NUMBER([integer number or code]) Returns the numeric value of the given argument.
NUMITEMSMOB([code]) Returns the number of items the given mob has.
NUMITEMSROOM() Returns the number of items in the room.
NUMMOBS([name]) Returns the number of mobs in the world matching the given mob name.Can also use MASK=<zapper mask> to pick out certain kinds of mobs.
NUMMOBSINAREA([name]) Returns the number of mobs in the scripted monsters area matching the given mob name.Can also use MASK=<zapper mask> to pick out certain kinds of mobs.
NUMMOBSROOM([*/name]) Returns the number of mobs in the same room as the scripted monster, including the monster, whose name or display text matches the name pattern. Can also use MASK=<zapper mask> to pick out certain kinds of mobs.
NUMPCSAREA() Returns the number of pcs in the same area as the scripted monster.
NUMPCSROOM() Returns the number of pcs in the same room as the scripted monster.
NUMRACEINAREA([race name]) Returns the number of mobs in the same area as the scripted monster whose race matches the given string.
NUMRACES([race name]) Returns the number of mobs in the world whose race matches the given string.
POSITION([code]) Returns the sitting/standing/sleeping position name of the given mob.
PRACS([code]) Returns the number of practices the given mob has.
QUESTOBJ() Not implemented -- do not use.
QUESTMOB() Not implemented -- do not use.
QUESTPOINTS([code]) Returns the number of quest points the given mob has.
QUESTWINNER() Not implemented -- do not use.
QVAR([*/quest name] [var]) Returns value of one of the internal Quest variable strings, See MPQSET for more info.
RACE([code]) Returns the name of the race of the given mob.
RACECAT([code]) Returns the racial category of the given mob.
RAND() Returns random number between 1 and 100.
RAND0NUM([integer number or code]) Returns a random number from 0..given value-1.
RANDNUM([integer number or code]) Returns a random number from 1..given value.
ROOMITEM([integer number]) Returns the name of the nth item in the same room as the scripted monster.
ROOMMOB([integer number]) Returns the name of the nth mob in the same room as the scripted monster.
SEX([code]) Returns the sex of the given mob.
STAT([code] [stat variable]) Returns the value of the given stat for the given object, mob, or item. See MPSTAT in the section on Commands for more information.
STRIN([string] [string]) Returns the word number (0..n) where the second string appears in the first. This function deals in whole words only.
TRAINS([code]) Returns the number of training points the given mob has.
VALUE([code] [currency name]) Returns the base value of the mob or coins but only in the given currency.
VAR([code] [variable name]) Returns the value of the given variable. See MPSETVAR in the section on Commands for more information.
WORN([code]) The name of a random worn item in the given mobs inventory.

Scripting Commands

Commands inside your scripts should each be terminated by a carriage return (ENTER) or a semicolon, depending upon the manner in which your script is presented.

Commands are of two general types: MUD Commands, and MOBPROG (MP) Commands.

MUD Commands you should already be familiar with, as they include commands such as GET, PUT, SAY, DROP, etc. It is not within the scope of this document to list or describe the standard MUD Commands. The help files inside the mud itself can do a far better job. It is sufficient to say that issuing the command in your script cause the scripted mob to attempt to perform the command exactly as it is written. If you enter a script line such as:

get sword

.. and there is a sword, the mob will get it. If there is NO sword, the mob will not appear to be doing anything at all.

MP Commands are what we will be discussing in more detail here. Like MUD Commands, they each have a syntax and structure which must be followed.

commandword parameter1 parameter2 ... parametern

Like MUD Commands, MP Commands all have a key command word followed by one or more parameters. As in MUD Commands, those parameters are delimited by spaces. If you need to specify a single parameter which contains a space, you would put double quotes (") around the parameter.

say "the scary monster" hi!

In an MP Command, however, this is not true. In an MP Command, the single quote (') is used around a parameter when it contains spaces. Keep this difference in mind when writing your scripts, lest you run into problems. This difference is actually more important with MP Functions. This is because most MP Commands only have one parameter, so that parameter word grouping using quotes is usually not necessary.

if, else, endif

Usage:

if [condition]
[commands]
else
[commands]
...
endif

The if command is the cornerstone of Scripting, and the only other condition mechanism outside of the MPWHILE command. The way the if command works is by deciding whether or not the condition that is given is true, and if so, executing the commands following the if condition. When the condition is not true, the commands before an endif statement or, (if given), an else statement are not executed. If an else statement lies between an if statement and the endif statement, then the statements between the else statement and the endif statement will be executed whenever the condition is false, but not ever if the condition is true. Either way, statements after an endif statement are executed regardless.

Every if statement MUST have a corresponding endif statement somewhere after it. The else statement is completely optional, but if it is used, it must be between the if statement and the endif statement. A BREAK statement may be included inside an IF..ENDIF block to skip the remaining statements in that block.

Of course, everything that happens or doesn't happen in an if condition depends on the condition itself. Every condition consists of a valid function name followed by an open parenthesis, followed by any parameters required by that function, and a close parenthesis. A simple example is below:

if sex($n == M)

In this example, the sex function is called to determine whether $n (which is a variable representing the cause of a trigger) is male. If the mob who caused the trigger is male, the condition is true. Otherwise it is false. In the particular function above, the '==' symbols mean 'equal to'.

Conditional statements may be negated using the "!" character as follows:

if !sex($n == M)

In this case, the condition evaluates to false if the mob who caused the trigger is male, and true otherwise.

Conditional statements may contain more than one function call if they are separated by the key words 'and' or 'or'. In the case of an 'and' key word, the condition evaluates to true if the functions on either side both evaluate to true, and it evaluates to false otherwise. In the case of the 'or' key word, the condition evaluates to true if either of the functions on either side evaluate to true, and false otherwise. Here are some examples of those in use:

if sex($n == F) or race($n == Harpy)

if sex($n == M) and isevil($n)

Lastly, conditional statements may group together their function calls using parenthesis. This can be used to ensure that certain sets of function calls are evaluated together, while others are not. For instance:

if sex($n == M) or isevil($n) and race($n == Harpy)

if ( sex($n == M) or isevil($n) ) and race($n == Harpy)

In these examples, if $n happens to refer to a Good Male Gnome, then the first statement would evaulate to true, while the second statement would evaluate to false. This is because the parenthesis force the sex and isevil checks to be evaulated first in the second example.

Please see the section below on functions for a list of the conditional functions and their uses.

switch, case, default, endswitch

Usage:

switch [variable]
case [value]
[commands]
case [value]
[commands]
case [value]
[commands]
...
endswitch
The switch command is an alternative to the if/endif syntax above for comparing a single variable to many different variables. A switch statement is essentially a stand-in for this syntax: 
if VAR($i MYVAR == 'value1')
  [commands1]
else
  if VAR($i MYVAR == 'value2')
    [commands2]
  else
    if VAR($i MYVAR == 'value3')
      [commands3]
    else
      [commands4]
    endif
  endif
endif
Notice how, in the above example, we are comparing the same variable over and over again to different values, and doing something different depending on that value. This is what the switch command allows you to do without having to nest so many if-statements. Here would be the equivalent switch statement to the above: 
switch $%VAR($i MYVAR)%
case 'value1'
[commands1]
case 'value2'
[commands2]
case 'value3'
[commands3]
default
[commands4]
endswitch
In the above switch statement, we declare the value we wish to check after the key word switch, which is the value of the variable $i MYVAR. In the ensueing case statements, we declare what we want the value of $i MYVAR to be equal to in order for the commands which follow the case statement to be executed. Each case statement defines its own value which $i MYVAR must be equal to in order for its following commands to be executed. The default statement is a special case is executed only if a value of $i MYVAR did not match any of the previous case values. Finally, the endswitch declares that no more cases will be given. Consider another example: 
switch $%RANDNUM(5)%
case 1
  [commands1]
case 2
  [commands2]
case 3
  [commands3]
case 4
  [commands4]
case 5
  [commands5]
endswitch
In this example, we are comparing a randomly generated number from 1-5 to each of the possible values in our case statements. Since we have covered all possible values of $%RANDNUM(5)%, we do not need to include a default case.

for, next

Usage:

for $[digit] = [number] to [number]
[commands]
...
next

The for command is the simplest way to execute one or more other commands numerous times. It allows you to specify a numeric range for the scripting engine to count from and to, executing the commands after the for statement (and before the next statement) as many times as is required to complete the counting. The value of the current digit during counting is stored in one of the temporary variables $0, $1, $2, $3, ... $9. Here's an example:

for $0 = 1 to 10
   mpecho I have done this $0 times!
next

If you execute the above script, you will see the mpecho command repeated 10 times, which is one time for every digit between 1 and 10. Each time it executes the mpecho command, the value of the temporary variable $0 will be incremented. That's the basics, simple huh?

For loops can be nested, so long as all of the outer for loops are using different temporary variables than the inner ones. Since there are 10 temporary variables, this gives you a limit of a nested depth of 10.

The two number expressions can be literal numbers as shown above, or any expression which might evaluate to a number, such as $% syntax. Here's an example of what I mean:

for $0 = 1 to '$%NUMMOBSROOM(*)%'
   mpecho $%ROOMMOB($0)% is here.
next

You'll see that the NUMMOBSROOM() function is used here to return the number of mobs in the room, so we can count them. Each one we count, we can pass the $0 variable used in this loop to the ROOMMOB() function to get their name.

Please see the section below on functions for a list of the functions and their uses.

<SCRIPT>

This command denotes the beginning of a section of ECMA Javascript. Any lines of text following this command, and before the adjoining </SCRIPT> command will be assumed to be executable Javascript. These commands can only be embedded in standard event handlers as described above.

Javascript is a wholly different language than the standard Scriptable/MOBPROG language described in this document. You should read the JavaScripting section of the CoffeeMud Programming Guide for more information, as well as the following web sites which discuss the usage and syntax of the Javascript language itself: http://www.mozilla.org/js/ and http://www.mozilla.org/rhino/.

After you've read the above documentation, there are still a few small details to be aware of before getting started. One is that the Scriptable behavior will provide certain methods for accessing important event-related objects from inside your Javascript. These include the object functions source(), target(), host(), monster(), item1(), item2(), and message(). Another important detail is that Javascript variables defined will be lost from execution to execution, even of the same script. For this reason, additional methods String getVar(String host, String variableName), and void setVar(String host, String variableName, String value) have been provided to save the variables globally. The last important detail relates to semicolon characters. It is lucky that Javascript does not require them, because the Scriptable behavior will strip them out as part of its command parsing process. For this reason, if you absolutely must keep a semicolon ANYWHERE in your javascript, whether as part of a displayable string, or a line delimeter, it must be escaped: \;

Here is an example:

GREET_PROG 100
mpecho Greetings $n! This command is mpecho, a mobprog command!

<SCRIPT>
var greetedBefore=getVar(source().Name(),"GREETEDBEFORE");
source().tell("However, this greeting comes from Javascript!");
if(greetedBefore == 'true')
  source().tell("We've met before\; we will meet again!!");
else
  setVar(source().Name(),"GREETEDBEFORE","true");
</SCRIPT>

if var($n GREETEDBEFORE == true)
  mpecho The variable set in Javascript can be read here in mobprog land also!
endif
~

mpaffect

Usage:

mpaffect [spell name] [target] [parameters]

This command will put the target under the affect of the given spell, chant, prayer, song, skill, or CoffeeMud property. This is not the same as someone casting the given spell on the target. Instead, this command causes the target simply to come under the affect (as if the whole casting process were skipped). This means that not all spells will work with this command. Fireball, for instance, since it has no effect after casting, would do nothing under this command. The parameters given apply specifically to CoffeeMud properties, and are unnecessary for most spells, chants, etc.

EXAMPLES:

mpaffect Invisibility $n
mpaffect Prop_PracticeDummy $n KILLABLE

mpalarm

Usage:

mpalarm [ticks] [command]

This very simple command will wait the given number of ticks (4 second intervals) before executing the command given in the