Location: Home / Lua Coding / Lua Functions

The core of the Lua coding system is its ability to interface with the MUD. Whenever Lua asks the MUD to perform a test or action, an 'actor' is necessary.

In some functions, that actor is assumed to be the mob the program is running on. For example, with 'say', we will only ever "say" as the mob a program running on - causing anyone else to say would be a "force". Example code snippets might be:

 say ("Hi!") -- mob says hi.
 echo ("This is an echo.") -- mob echos something
 rgoto ("aylor-0") -- mob goes somewhere

Other functions require the actor to be passed. For example, when we are testing if a character carries an item, we have to tell the MUD which character we are interested in.

--- mob transfers player to aylor recall.
transfer(ch,"aylor-231")

In test functions, we often want to test something on a character and the mob actually running the program is irrelevant (checing a player config flag or immunity). For other tests, we want to compare the player to the mob. For example:

--- Is player immune to fire?
if immune(ch,"fire") then ...
 
--- Is player my ally? - mob needed in this case.
if ally(ch) then ...

The function list below gives details on exactly what is required for each function and the options that can be used to modify their behavior

Lua / MUD Available Functions

We have tried to keep the syntax as close to the old mobprog syntax as possible for experienced builders. However, the extra options provided for in the Lua integration usually require option flags to be set. Where options are available, they are listed under each function.

The available functions to Lua can be broken down into a number of different categories:

Test Functions:

These types of function don't actually do anything, but are available to test for various conditions in the MUD. In many cases, simple tests can be done using variable properties directly such as "if ch.int > 100 then". In other cases, more complex tests are needed such as if immune(ch,"fire") then. These types of function only ever return true or false.

Mud Info Retrieval:

These types of function pull information from the MUD back into the Lua environment as needed. There are not many of these types of function as most of the data you will need is already available as variable properties. One example is temproom = getroom("aylor-0") which creates a ROOM type Lua variable for Aylor recall. Once temproom is available, you can use all the usual room properties on it such as temproom.healrate or temproom.people.

Actions:

These functions cause the MUD to actually do something, such as transfer a character, send a message, cast a spell etc.

Goals and Tasks:

This set of functions is used to control goal and task behaviour. They are documented separately on the goal and quest documentation page.

Object and Room Prog functions

Many functions require a "self" actor in order to operate and will not work with lua programs attached to objects and rooms unless those programs require a mob actor in the room. Each function is labeled to include their compatibility with object and room progs.

Note that many of the lua functions were originally created to be able to remove the old mobprog system as quickly as possible and are now being revisited for object and room progs. If you need a specific function to work on rooms or objects that is not yet available, please contact Lasher.

Table of functions

adddelay(seconds)	Sets a timer to call a 'delay' trigger on the mob.
addpet(ch,pet)	Assign a mob as a pet of 'ch'.
addstats(obj,stat,amount)	Adds stats to an item
affected(ch,flag)	Test if character has a specific affect flag set.
ally(ch)	Tests if ch is an ally of the current mob.
call(...)	Calls another lua program. Argument list in details.
cancel()	Cancel a delay - mprog compability
canseechar(ch1,ch2)	Test if ch1 can see ch2.
carries(ch1,item,opts)	Test if ch1 is carrying item in their inventory
cast(spell,targ,opts)	Casts a spell at the target given, or self.
clantalk(message)	Allows clan mobs and guards to talk on their channel.
channel(ch1,"channel",on|off)	Test or set value of a channel flag on a player.
config(ch1,"flag",on|off)	Test or set value of a configuration flag on a player.
countitems(ch,item,opts)	Counts how many of a specific item a player is wearing and/or carrying.
damage(...)	Inflict damage on CH. See details for argument list.
destroy(ch,obj,opts)	Destroy one of more instances of item [objkey] on CH.
doat(loc,action,opts)	Mob performs an action in another room.
echo(msg,about,opts)	Echo a message to CH, or about CH (to room). $ variables available.
echoat(ch,about,opts)	Echo a message to a specific character. $ variables available.
echoaround(ch,about,opts)	Echo a message to all rooms adjacent to ch.
emote(msg)	Emote a message to the room.
force(ch,command,opts)	Force a character, or group of characters, to perform an action.
forget()	Forget a previously remembered character - mprog compability
getchars(roomkey)	Returns a table of characters in the given room key.
getmob(mob,room,opts)	Find a character in the game or a single room. Return as ch type.
getobj(objkey,ch|obj|room,opts)	Find an object. Return as obj type.
getpet(ch)	Test if a player has a pet. Return it as CH var if so.
getroom(roomkey)	Get room if roomkey exists, returned as room type variable.
give(item,ch)	Give an item to character 'ch'
give(ch,amount)	Give experience to player 'ch'
giveqp(ch,amount)	Give quest points to player 'ch'
hasclass(ch,[class])	Tests whether CH has the given class.
hasdelay()	Tests whether the mob running the program has an old-style 'mob delay' set.
hasobj(ch,item)	Tests if character has the item type carried. For compatibility with old mobprog conversions.
immune(ch,focus,on|off)	Tests if character is immune to a specific damage focus.
info("message","channel")	Test or set value of an info channel setting.
infoflag(ch1,"info chan",on|off)	Test or set value of an info channel setting.
isplayer(ch)	Tests if ch is a player.
kill(ch,opts)	Attack another character.
mobflag(ch,flag)	Tests if mob has a flag set. Always false on a player.
mdo(command)	Causes the mob running the prog to execute a mud command.
mgoto(name)	Go to mob, if found.
mload(mobkey)	Create an instance of mobkey and place it in the current room. Return mob created.
mobexists(mobkey,room)	Tests if instances of mob exist, specific room or entire game.
movechar(ch,room,opts)	Transfer a character or group to another room from room progs.
objflag(obj,flag,[0|1])	Test for, or set, flags on an item.
objingame(objkey)	Tests if instances of obj exist anywhere in game.
objhere(objkey)	Tests if instances of obj exist in current room.
oload(objkey)	Create an instance of an object in inventory or room. Return obj created.
objresists(obj,focus,[amt])	Query and update item resistances.
peace( )	Stops all combat on a given character, or on character running the prog.
pgoto(name)	Go to player, if found.
plrflag(ch,flagname)	Tests if player has a specific flag set. Always false for mobs.
postnote(...)	Allows a mob to post a note from within lua progs.
purgemob(ch,opts)	Purge mob(s) in current room or in entire game.
purgeobj(obj,opts)	Purge various combinations of objects in room or game.
randchar(opts,[room])	Find a random charater in the current room. Return as ch type variable.
remember(ch)	Remember 'ch' for use with delay triggers - mprog compability
rgoto(roomkey)	Go to a specific room.
say(message)	Causes mob to say something to the room.
sayto(ch,message,opts)	Causes a "say" to be sent to single char and formatted for linebreaks. Used in Academy.
send(ch,message)	Send a message to ch. Useful for debug and in progs where echo is not available.
social(social,targ)	Causes the mob to execute a social.
summon(ch,opts)	Causes the character, if found, to be transferred to current room.
transfer(ch,loc,opts)	Transfers character(s) already in the current room to another location.
wearsobj(ch,item)	Tests if character has the item type worn. For compatibility with old mobprog conversions.
zecho(message)	Sends a message to all players in the current zone.

Test Functions

affected - syntax: affected(CH,"affect flag name")

Returns true if CH has the specified affect flag set.

if affected(ch,"flying") then say ("Hey, how's the view from up there?") elseif affected(ch,"diseased") then say ("Ugh, keep away from me please, I don't want to get sick!") end if not(affected(self,"sanctuary")) then say ("Uhoh, my sanctuary is down!") end

canseechar - syntax: canseechar(CH1,CH2)

Tests if CH1 can see CH2. A real example used when you say 'board' in Lands of Legend:

if not(canseechar(self,ch)) then say ("Hey! Who said that?!") return else ...

carries - syntax: carries(CH,"item")

Tests whether or not the character is carrying an item. The "item" variable can be either keywords or an object key. Usually it is better to use the object key so you can be sure the correct item is targeted. Using the keyword 'red sword' would mean any item with keywords 'red sword' would pass the test.

The only option is LP_ALL which will cause carries to look for an item in any wear location or in inventory.

--- Insult anyone not carrying item aylor-12 if not(carries(ch,"aylor-12")) then say("You suck!") end

channel - syntax: channel(CH,"channel name",["on"|"off"])

Without the third argument, returns TRUE if CH has the specified channel on/off. With the third argument, turns the channel on or off - used in academy to toggle channels are various stages.

--- Part of academy lesson on auction. Is skipped is CH already has auction on. if not(channel(ch,"auction")) then sayto(ch,"I see that you have the auction channel turned off "..ch.name..".") sayto(ch,"I am going to turn your auction channel on so that we can continue this lesson.") sayto(ch,"Feel free to turn it off when we are done.") echoat(ch,"") channel(ch,"auction","on") end

config - syntax: config(CH,"config flag name")

Returns true if CH has the specified config flag set. Always false on a mob.

--- Academy prog? if config(ch,"nohelp") then say("Go practice your sword skill then return to me."); else say("Practice your sword skill then return to me. You"); say("can increase it via use or at a trainer. Read the"); say("'HELP PRACTICE' file for more info."); end

countitems - syntax: countitems(CH,"object key",[option])

Like carries() but returns how many instances of the item the player is carrying. The only option is LP_ALLOBJS which will include worn items, otherwise only items in inventory are counted.

Usually we only care if a character carries an item at all and carries() is still preferable in those cases as it runs faster.

--- Character must have at least 10 iron ores to continue if countitems(ch,"dsr-2") < 10 then say("You need at least 10 iron ores for my services!") return end --- do whatever in the prog. --- Now we need to remove them. Can't just use destroy with obj key and all --- as they might be carrying more than 10. for onum = 1,10,1 do destroy(ch,"dsr-2",LP_SEEALL+LP_ONEONLY) end

hasclass - syntax: hasclass(ch,[class])

Returns true if the CH has the class given. For example, 'if hasclass(ch,CLASS_THIEF) then'...

hasdelay - syntax: hasdelay()

Returns true if the mob running the prog has a delay outstanding.

hasobj - syntax: hasobj(CH,"object type")

wearsobj - syntax: wearsobj(CH,"object type")

Hasobj returns true if the character is carrying an item of the given type in inventory (containers are not searched). Wears obj returns true only if the item is worn.

if hasobj(ch,"weapon") then say ("Looks like you came ready for a fight?") if not(wearsobj(ch,"weapon")) then say ("Here's a hint, your weapon will work better wielded!") end end

immune - syntax: immune(CH,"damage type")

Returns true if CH is immune to the given damage type.

--- switch weapons if target immune. if immune(ch,"fire")) then mdo("wield ice blade") end

For mobs only, you can also set or remove immunities using, for example:

--- set fire immunity on self immune(self,"fire","on") --- remove acid immunity on self immune(self,"acid",off)

infoflags - syntax: infoflag(CH,"info category",["on"|"off"])

Without the third argument, returns TRUE if CH has the specified channel on/off. With the third argument, turns the info on or off - used in academy to toggle info at various stages.

ally - syntax: ally(CH)

Returns true if the character is an ally of the mob's clan AND a raid on that clan is under way. Used on clan guards to avoid attacking defenders during a raid.

--- Only one person can pass at a time. if ally(ch) then say ("Hi " .. ch.name .. "! Please help defend us!") else say ("Go away mean old raider!") killsee(ch) end

isplayer - syntax: isplayer(CH)

Returns true if the character is a player.

if isplayer(ch) then say ("You're a player!") end if not(isplayer(self)) then say ("I'm not!") end

mobflag - syntax: mobflag(CH,"mobflag name")

Returns true if CH has the specified mob flag set. Always false on a player.

--- Imaginary prog triggered by consider: if mobflag(self,"nodamage") then say("Don't even think about it - I'm invincible!") end

mobexists - syntax: mobexists("mobkey",[room])

True if at least one mob with key [mobkey] is in the game or in the specified room. If room is given it can be either a room key or a ROOM type variable. No visibility checks are applied - this function has no actor.

--- Is ivar at recall? if mobexists("badtrip-99",getroom("aylor-0")) then say ("Uhoh, Ivar is at recall!") end --- Is there a guard right here? if mobexists("aylor-30",room) then ... --- Is there one in the game at all? if mobexists("aylor-30") then ...

objflag - syntax: objflag(obj,"flag-name",[0|1])

When called with an OBJ type variable and a flag name, returns true or false if that flag is set. If the third argument is set to 0 or 1, this turns the flag on and off respectively.

--- Is this item humming? if objflag(obj,"hum") then say("Cool! This item is humming.") end --- Remove rot-death from goal version of callhero portal. objflag(obj,"rot-death",0)

objingame - syntax: objingame("objkey")

Returns true if at least one instance of the object with the key provided exists in the game.

objhere - syntax: objhere("objkey")

True if at least one item with key [objkey] is in the room. Objkey also be a name but using an obj key is preferred to avoid keyword issues.

--- If there's a fountain... if objhere('fountain') then --- $n is always mob running the prog. echo ("$n pisses in the fountain!" end

plrflag - syntax: plrflag(CH,"player flag name")

Returns true if CH has the specified player flag set. Always false on a mob.

--- Clan guard? if plrflag(ch,"traitor") then say("Get out of my site before I attack you, traitor!") end

wears - syntax: wears(CH,"item")

Same as carries, but the item must be worn to return true.

Mud Info Retrieval Functions

getroom - syntax: getroom(roomkey)

Brings the room with 'roomkey' into lua as a ROOM type variable. From there, any other functions that take a ROOM type variable can accept this and all room properties are available.

Lua / MUD "Set" functions

Some of the most powerful functions in the Lua integration with the MUD are not actually used as functions - they are "set" functions called whenever you try to assign something to an object property.

For example, obj.owner can be used to get the current owner of an item. We have no equivalent of the mobprog 'objown' command because you can also do obj.owner = ch.name

Using assignment of this type causes Lua to look in a table of functions that are called back on the MUD to update an item. At the time of writing, the only other settable property is 'ch.gold' which replaces the mobprog 'addwealth' command : to increase a character's gold by 10000 we simply do 'ch.gold = ch.gold + 10000'.

Within the properties tables values that are settable will be prefixed with '*' in their name. All sets are logged mud-side for security reasons.

Actions

addstats - syntax: addstats(obj,stat,amount)

Prog Types: Mob, Object, Room

Addstats allows stats to be added to an object. It should not be used without consulting an imm first - all addstats are also logged to luasec.

For the first argument, an OBJ type variable is required. The second argument is the name of the stat, available stats are str, int, wis, dex, con, luck, hp, mana, move, hitroll, damroll and saves. The second argument can also be "random" in which case one of the 6 main stats is selected for each stat. The third argument is the amount to add - using Math.random this can also be random.

--- Used in academy, small skeleton loads skeleton bone at death with --- 2 random stats and random hp between 10 and 30. local tobj = oload("academy-36") addstats(tobj,"random",2) addstats(tobj,"hp",math.random(10,30)) --- Also, rarely, add two more random stats. if math.random(1,60) == 3 then addstats(tobj,"random",2) end

addpet - syntax: addpet(player,pet)

Prog Types: Mob, Object, Room

Assigns 'pet' as a pet of 'player'. Both must be CH variables of the correct type and 'player' cannot already have a pet.

--- Test if player has a pet. Make them one if not. local petmob = getpet(ch) if petmob == nil then say("You don't have a pet!") say("Let's get you a squirrel!") petmob = mload("tol-20") addpet(ch,petmob) else say("Your pet is " .. petmob.name) end

call - syntax: call("progid",[CH],[ROOM],[OBJ],[SELF]

Call is used to execute one Lua mud program from within another. For builders used to the mobprog system, the main difference in this call is that the character, room, object and even the actor (self) can be changed for that call only.

In the example below, the test mob running prog test-1 states the room it is in, then calls prog test-2 but with the room variable changed. Prog test-2 outputs some other information then returns to test-1. You can see that the room in test-1 was not affected.

--- prog test-1, running on an owl in room tol-30 --- (On a high branch) say("calling test-2") call ("tol-48",nil,getroom("tol-20")) say("done calling test-2") say("back in test-1 we are in " .. room.name .. "/" .. room.key) --- prog test-2 say("I am " .. self.name .. " you are " .. ch.name .. " we are in " > .. room.name .. "/" .. room.key) Running this prog gives the output: You say 'go' An owl says 'calling test-1' An owl says 'I am an owl you are Lasher we are in A Middle > Branch/tol-20' An owl says 'done calling test-2' An owl says 'back in test-2 we are in On a High Branch/tol-30'

Call is particularly important in replacing former 'mob call mob ...' commands, see the Lua Howto page for more on this.

cast - syntax: cast(spell,target,options)

Used to cause the mob to cast a spell on a character or an item. The first argument should be either a spell name or a spell number.

The second argument can be a CH type variable, an OBJ type variable, "all" or a name. If the target is a name, either a character or an item in the room will be searched for in the room depending on the spell type.

Options available with 'cast' are:

LP_SEEALL No visibility checks, if the target exists it will be found LP_PLRONLY Only attempt to cast on players - only used when target is a name or "all". LP_MOBONLY Only attempt to cast on mobs - only used when target is a name or "all". LP_ACTIVEONLY Only target players if they are in-game. Players in note or edit mode will be ignored.

--- Cast fireball at all players who enter. cast("fireball","all",LP_PLRONLY) --- Heal all mobs in room, including self. cast("heal","all",LP_MOBONLY+LP_SEEALL)

clantalk - syntax: clantalk("message")

If the mob is in a clan, "message" will be sent over that clan's channel. Used primarily on clan guards.

damage - syntax: damage(CH1,min,max,options)

Damage allows the mob to inflict invisible damage on a player or group of characters.

If the first argument is a CH variable, that character is selected and/or it's group based on the options. If the argument is a name or "all", characters in the room are searched based on the options set.

Damage should usually be the last thing in a program as it can kill the target and remove them from the game. If you need to access 'ch' after using it with damage, you should first test it is still in your room using 'if ch.roomkey == self.roomkey'.

Using a target of "all" will damage mobs in the room - use LP_PLRONLY to target only players.

LP_SEEALL No visibility checks, if the target exists damage will be attempted. LP_PLRONLY Use this option to restrict to players only. LP_MOBONLY Use this option to restrict to mobs only. LP_ACTIVEONLY Only damage target if they are in-game. Players in note or edit mode will be ignored. LP_GROUP When using with a CH variable or a name, if this option is set all group members in the room will be damaged.

--- Damage char who entered and all group members. echo("Have some damage!") damage(ch,500,1000,LP_GROUP)

destroy - syntax: destroy(CH,objkey,[options])

Destroy is like 'purgeobj' but destroys items on another character. Mostly used to remove quest components from a character. As with transfer, the first argument can be a name or a 'ch' variable. The second argument can be "all" or an object key. "All" cannot be used on a player.

By default, destroy removes all instances of the item. The only option used by this function is LP_ONEONLY which will cause only one instance of the item to be destroyed.

--- Lands of Legend prog. Tests if character has all 4 apples, --- loads portal (meeting mandatory 1 per area requirement), gives --- to char, removes the 4 apples from their inventory then --- transfers them to Aylor recall. if carries(ch,"legend-5") and carries(ch,"legend-6") and carries(ch,"legend-7") and carries(ch,"legend-37") then say("Congratulations! You found my apple trees!") local tobj = oload("legend-48") give(tobj,ch) social("shake",ch) destroy(ch,"legend-37") destroy(ch,"legend-5") destroy(ch,"legend-7") destroy(ch,"legend-6") echo ("*poof*") transfer(ch,"aylor-0") return end

doat - syntax: doat(location,"action",options)

Used to allow the mob to perform an action in a location other than its current room.

If the first argument is a ROOM type variable or a room key, the action is performed in that location. If the first argument is a CH type variable, the action is performed in the room that character is in.

If the first argument is a mob key, the first of that mob found is used as the location. You must also set the LP_MOBONLY option so the MUD knows the key argument is intended to be a mob key and not a room key.

If the first argument is a name, an attempt is made to locate that target. The scope of the search can be limited using the options below.

The options available with doat are:

LP_SEEALL No visibility checks, if the target exists the command will be executed. LP_PLRONLY Search for a player only. Used only when CH is a name. Removes the need for doatplr. LP_ZONEONLY Look for targets in current area only. Used only when CH is a name. LP_MOBONLY When used with name, means search mobs only. When CH is a key, tells the mud it is intended to be a mob key and not a room key.

--- Imaginary greet prog to annoy Lasher in multiple ways. --- warzone-0 is the key of Lasher's imm room. doat("warzone-0","say Hi Lasher! ") --- next line could fail if another mob has keyword 'lasher' doat("lasher","*smile") --- Will only target a player. doat("lasher","*chuckle",LP_PLRONLY)

echo - syntax: echo("message",aboutch,options)

Message will be sent to all characters in the same room as the mob. If 'aboutch' is set it must be a CH type variable and the message will not be sent to that character.

The variable $n is always 'self' - the mob the prog is running on. If aboutch is provided, this is the equivalent of the old 'echoaround'. In this case, the variable $N is the 'aboutch'. The variable $n is always the mob running the prog.

Echo does not capitalize by default - if you begin the sentence with a variable (mob name, etc) and would like it capitalized, add the option LP_CAPS.

--- Send one message to char, another to others --- in the room about the char. echo("As you enter, $n greets you!",) echo("$n greets $N as $E enters the room.",ch,LP_CAPS);

echoat - syntax: echoat(ch,"message",options)

Unlike echo which sends a message to the whole room, echoat sends a message to a single character, usually the person who triggered the prog. The variable 'ch' must be a CH type variable.

Echoat does not capitalize by default - if you begin the sentence with a variable (mob name, etc) and would like it capitalized, add the option LP_CAPS.

The variable $n is always 'self' - the mob the prog is running on. If an object is involved in the trigger, it can be referenced in the echo text using $p.

echoaround - syntax: echoaround("message")

Message will be sent to all characters in adjacent rooms to the mob. Note: This is different than the mob echoaround mobprog statement, that is echo with the 'aboutch' parameter provided.

emote - syntax: emote("message")

Causes the character running the program to emote something. As with 'mdo', more complex arguments can be created using Lua concatenation.

force - syntax: force(CH1,"commands",options)

If the first argument is a CH type variable, that character is forced directly.

If the first argument is a mob key, either the first mob found in scope with that key or all mobs of that type are forced.

If the first argument is a name or "all", a search is done in scope for mobs with that key. Be sure to use option LP_ROOMONLY if you only want to force mobs in the current room.

Options available with 'force' are:

LP_SEEALL No visibility checks, if the target exists it will be forced LP_ZONEONLY Only look in the current zone for targets. LP_ROOMONLY Only look in the current room for targets. LP_PLRONLY Only attempt to force players, ignore mobs. LP_MOBONLY Only attempt to force mobs, ignore players. LP_ACTIVEONLY Only force players if they are in-game. Players in note or edit mode will be ignored. LP_ALLMOBS Only used with mobkey - if this option is set, all mobs with the same key will be forced - this replaces 'mob vforce'. LP_GROUP If a player is found and this option is set, any other members of their group in the room will also be forced - this replaces 'mob gforce'.

--- Force all my guards to wield their sword, this room only force("aylor-212","wield sword",LP_ALLMOBS+LP_SEEALL+LP_ZONEONLY); --- Force the player who triggered me to bow. force(ch,"*bow") --- Force the player who triggered me and their group to recall. force(ch,"recall",LP_GROUP)

getmob - syntax: getmob(name|key,[room],[options])

Prog Types: Mob, Object, Room

Getmob is used to find a character in the game or a specific room and, if found, returns a CH type variable pointing to that character. The real power of this function is once you have the 'CH' type result, you can perform any other lua prog action on it.

Getmob does not require an actor, which means there are no visiblity checks. It is safe to use from object and room progs.

The first argument can either be a name or a mob key. Wherever possible, use a mob key as this is more efficient - only the internal list of instances for that mob is searched. It also avoids keyword issues.

The second argument is optional and can either be a ROOM type variable, or a room key. If either are set, only that room is searched.

The options available for the third argument are:

LP_PLRONLY Useful only when searching by name - restrict to player only. LP_MOBONLY Useful only when searching by name - restrict to mob only. LP_ACTIVEONLY Useful only on players - only return player if that are actively playing - not linkdead, in editors, etc. LP_EXACT Require exact match on name, no abbreviations.

Some examples:

--- If lasher is on, send him a debug message. local tmob = getmob("Lasher",nil,LP_PLRONLY) if tmob ~= nil then send(tmob,"TOL-49 is executing!") end --- See if we there's an elite yurgach guard anywhere. tmob = getmob("elite yurgach huge") if tmob ~= nil then say("There is a huge guard in " .. tmob.roomkey) end --- See if there's a forge worker at aylor recall. --- If not, see if there's one anywhere. tmob = getmob("aylor-20","aylor-0") if tmob ~= nil then say("There is an instance of aylor-20 at aylor-0!") else say("There is no aylor-20 in aylor-0") tmob = getmob("aylor-20") if tmob ~= nil then say("But I did find one at " .. tmob.roomkey) end end

getobj - syntax: getobj(key,[room|char|obj],[options])

Prog Types: Mob, Object, Room

Getobj is used to find an item in a room, on a specific character or inside another item. The value returned is either nil or an OBJ type variable that can be accessed and manipulated with other Lua functions.

Getobj does not require an actor, which means there are no visiblity checks. It is safe to use from object and room progs.

The first argument should be an object key - getobj intentionally does not work with keywords as builders have no way to predict what keywords will be added to future items. Accessing objects by keyword is unreliable.

The second argument is either a ROOM, a CH or another OBJ type variable. If a room is given, the item is searched for in that room. If a character is given, the item is searched for on that character and can be restricted to worn or carried only. If an obj is given, the contents of that object are searched.

The options available for the third argument only apply when searching a character, and are:

LP_CARRIEDONLY Only search carried inventory. LP_WORNONLY Only search worn inventory.

Some examples:

--- If there is an instance of aylor-123 in the room, the player --- may proceed north (pressure pads?) --- Exit trigger for north. local tobj = getobj("aylor-123",room,0) if tobj ~= nil then transfer(ch,"roomkey-1") end --- See if the gem has been placed in the statue in the room. --- Assume statue is key test-2 and the gem is test-3 --- Make sure the statue is still here, just in case local statue = getobj("test-2",room,0) if statue ~= nil then --- Is the gem inside it? local gem = getobj("test-3",statue,0) if gem ~- nil then --- The gem is here ... do something. end end

getchars - syntax: getchars(roomkey)

This function returns a lua table of all the characters in the given room key. You can then use this list to test for various attributes.

--- List all chars in the room and send a msg to the players only. local chars = getchars(room.key) for k, v in pairs(chars) do say("I see " .. v.name .. " in the room.") if isplayer(v) then send(v,"Hi " .. v.name .. " you appear to be a player!") end end

getpet - syntax: getpet(ch)

Tests whether or not player 'ch' has a pet, returns CH variable pointing to that pet if so. See addpet documentation for example use.

give - syntax: give(OBJ,[CH])

Give can be used for most cases where a mob needs to give an item to a player. Using an OBJ variable directly means that any keyword issues can be avoided and you will always target the correct item/character vs using mdo to build a mud command. The CH argument can either be a ch variable or a name. OBJ can also be an object key for cases where the mob is not returning an item but giving something it loaded/already has to a player - using the object key again avoids keyword issues.

--- Return item to player that was given in a prog give(obj,ch) --- Give Aylorian sword to ch give("aylor-321",ch)

giveexp - syntax: giveexp(ch,amount)

Gives experience points to player - mostly used to reward task / goal completion. All giveexp commands are logged to immfo luasec.

giveqp - syntax: giveqp(ch,amount)

Gives quest points to player - mostly used to reward task / goal completion. All giveqp commands are logged to immfo luasec.

info - syntax: info("message","info channel")

Sends a message across the info channel. Most of the time you will use the "quests" info channel. However, if you have a rarely killed "epic quest mob" you could also announce it's death over info deaths.

The info channels are: levels, deaths, newbies, claninfo, notes, raiding, pkdeaths, classchanges, helperinfo and quests

-- Announce graduation. info(ch.name.." has graduated from the Aylorian Academy!","quests") --- Announce death of epic mod. info("The giant weasel has been murdered by "..ch.name.."!","deaths")

kill - syntax: kill(CH1,options)

Causes the mob running the program to attack a character.

If the first argument is a CH variable in the room, they are the target. If the first argument is a name, the room is checked for a character by that name.

Options available with 'kill' are:

LP_SEEALL No visibility checks, if the target is in the room the attack will be attempted. Replaces 'mob killsee'. LP_NOERR Suppresses error messages if target not found - depending on the prog this will or will not be ok. LP_ACTIVEONLY Only attack if the target is an active player - not in note or edit mode. LP_ONEONLY Instead of a full round of combat, the mob will attempt just one attack.

--- Kill whoever triggered me, ignore visibility (killsee) kill(ch,LP_SEEALL)

mdo - syntax: mdo("command")

mdo is the main function used to make the mob a program is running on execute a mud command. Using lua concatenation (..) you can build commands with multiple arguments. For example:

--- Wear the object just given --- Note the single quotes to make sure all keywords are grouped. mdo("wear '" .. obj.keywords.. "'") --- if it's level 1, drop/sac it. if (obj.level == 1) then mdo("drop '" .. obj.keywords .. "'") mdo("sacrifice '" .. obj.keywords .. "'") end

mload - syntax: mload("mobkey",ROOM)

Creates an instance of "mobkey" and places it in the same room as the character running the prog. There are no additional options on this command.

By default, mload assumes there is a 'self' actor and will load the new mob in the current room. In room progs, there may not be an actor so the second argument can be either a ROOM type variable or a room key to indicate where the new mob should be loaded.

--- If there is no aylor-20 in the room, create one. if not(mobexists("aylor-20",room)) then mload("aylor-20") end

Mload also returns a CH type variable with the mob created. Most of the time this will be ignored, but can be useful with the 'call' function or other functions that take a CH variable. For example, if you want to load a mob then transfer it somewhere, rather than dealing with keyword issues you could do:

--- Create a mob local newmob = mload("aylor-20") --- Use the ch variable for transfer. transfer(newmob,"aylor-321") --- Or, if you want to use the newmob in an echo --- $n is the mob running the prog. $N is whatever char is given. echo("$n waves $s arms and $N appears!",newmob)

movechar - syntax: movechar(CH1,ROOM,options)

Prog Types: Mob, Object, Room

Movechar is used to transfer a character or group to a different room without requiring an "actor". Movechar is mostly of use from within room or object progs. If the first argument is a CH variable, that character is targeted directly. If the first argument is "all", all characters in the room may be transferred if not filtered out by additional options (see below).

The second argument can either be a ROOM type variable or a room key. The options argument (optional) can be used to limit the targets selected. With the exception of SEEALL, these options are ignored if a CH type variable is given rather than a name:

LP_PLRONLY Transfer can target mobs also. Use this option to restrict to players. LP_MOBONLY Only mobs will be checked when a name is given or the target is "all". LP_GROUP When used with a name or a CH variable, will cause all group members in the room to be transferred. LP_NOERR Sometimes a mob will want to transfer a target if it is there, but no target is not considered an error. Set this option to suppress errors. LP_ACTIVEONLY Only transfer target if they are in-game. Players in note or edit mode will be ignored.

--- Move the character from a "push button" trigger --- Trigger on room: --- --- Trigger Type Program Phrase Actor --- ============ ============= ==================== ============== --- Command tol-49 push button send(ch,"Ooops, you shouldn't have done that!") movechar(ch,"aylor-2") --- Alternative version: --- If something could make the player move rooms before this code is reached --- you may need to make sure they're still in the room. --- --- Remember that 'room' is always the room the prog fired in. --- if ch.room.key == room.key then send(ch,"Ooops, you shouldn't have done that!") movechar(ch,"aylor-2") end

oload - syntax: oload("objkey",level,location,[TARG])

Prog Types: Mob, Object, Room

Creates an item with key objkey. Level and location are both optional. If level is given, item is set to that level. By default, the item goes to the mob's inventory if takeable and to the room if not. A location of "room" will make the item always go to the room. A location of "wear" will cause the mob to wear the item. Targ is a CH variable to be used when oload is called from a prog in which there is no actor - targ is the char on which the item will be placed.

--- Create a portal, give it to the character. oload("aylor-123") give("portal",ch) --- You could also just use: give(oload("aylor-123"),ch) --- Oload with no actor. --- Prog in orchard when user types 'shake tree' if carries(ch,"orchard-0") then send(ch,"You give the tree a good shake, but no apples fall.") else send(ch,"You give the tree a good shake.nrA shiny red apple falls and you quickly catch it.") oload("orchard-0",0,nil,ch) end

Oload also returns an OBJ variable with the item created. Most of the time, this will be ignored. If needed, it can be assigned to a local variable then manipulated. For example, if a mob loads an item then sets ownership on it, you would use:

local newobj = oload("aylor-123") newobj.owner = ch.name

Note that when using the location of "wear" or "room", the quotes are required around the location value:

oload("aylor-123", nil, "wear") oload("aylor-123", nil, "room")

objresists - syntax: objresists(obj,damtype,[modify amount])

When called with 2 arguments, returns the number of resistances the item has in the given damtype. When a third numeric argument is added, the item resistances are increased or reduced by that amount. Some examples of use:

--- Return number of resistances the item has in fire: say("Fire resistance on this item is: " .. objresists(obj,FOCUS_FIRE) --- Increase the number of resistances in Acid by 3 objresists(obj,FOCUS_ACID,3) --- Reduce resistance in bash by 5 objresists(obj,FOCUS_BASH,-5) --- Set the item to 100 resists in cold whatever the current value is local coldres = objresists(obj,FOCUS_COLD) objresists(obj,FOCUS_COLD,100 - coldres)

The constants that can be used for damage types are:

FOCUS_BASH 0 FOCUS_PIERCE 1 FOCUS_SLASH 2 FOCUS_ACID 3 FOCUS_AIR 4 FOCUS_COLD 5 FOCUS_DISEASE 6 FOCUS_EARTH 7 FOCUS_ENERGY 8 FOCUS_FIRE 9 FOCUS_HOLY 10 FOCUS_LIGHT 11 FOCUS_ELECTRIC 12 FOCUS_MAGIC 13 FOCUS_MENTAL 14 FOCUS_NEGATIVE 15 FOCUS_POISON 16 FOCUS_SHADOW 17 FOCUS_SONIC 18 FOCUS_WATER 19 FOCUS_ALLMAGIC 26 FOCUS_ALLPHYSICAL 27

peace - syntax: peace([ch])

Stops all combat on the character given. If not character is given, the mob the program is running on (self) is assumed.

if ch.level < 100 then say ("I will not fight you. No competition.") peace() end

pgoto - syntax: pgoto("player name")

mgoto - syntax: mgoto("mob name")

Transfers the mob running the program to specified player or mob if found. Returns true/false to indicate success or failure.

if pgoto("Lasher") then say ("Hi Lasher!") --- now in lasher's room. else say ("I can't find Lasher!") end

postnote - syntax: postnote("board name","to","subject","message body",days)

Causes the character running the prog to post a note. Should only be used with advanced permission from imms.

--- Aaeron's line in the academy that posts note to user with --- how to continue on to the next lesson. postnote("personal",ch.name,"Communications Lesson", "To continue with your lesson, please type: tell aaeron dragons")

prompt - syntax: prompt(ch)

Causes the players prompt to be sent - mostly only useful in delay story scripts that prompt the user to enter something, displaying the prompt makes it more obvious the mob is waiting for something, and breaks up the output a little.

purgemob - syntax: purgemob(CH,options)

Purgemob allows a program to purge various combinations of mobs in the room/area/game.

If the first argument is a CH type variable, it is purged and all other options besides LP_SEEALL are ignored.

If the first argument is a mob key, the first instance of the mob found in scope will be purged. If LP_ALLMOBS is set, all instances of that mob found in scope will be purged. The default scope is the current room. If LP_WORLD is set with LP_ALLMOBS, all instances of that mob in the game will be purged. If LP_ZONEONLY is set, all instances in the current area will be purged.

If the first argument is "all", all mobs in the room except the mob the prog is running on will be purged.

If the first argument is a name, the first mob found in the room with that name is purged. ALLMOBS does not work with a name - you have to use a mob key.

A summary of the options available with purgemobs

LP_SEEALL No visibility checks, if the mob exists and is not flagged NOPURGE, it will be purged. LP_ROOMONLY Only purge mobs in the current room. LP_ZONEONLY Only purge mobs in the current area. LP_WORLD Purge mobs globally - used with LP_ALLMOBS. Usually requires LP_SEEALL to catch everything. LP_NOERR Do not report an error if a target is not found. LP_ALLMOBS When uses with an object key, purges all instances of that mob in scope.

Notes:

Purgemob will not purge a mob that is flagged as 'nopurge'.

If a mob purges itself, any attempts to use a function that requires the 'self' actor will fail with an 'already extracted' error.

--- Purge all instances of tol-25 in the room. purgemob("tol-25",LP_SEEALL+LP_ALLMOBS) --- Purge first "owl" found in the room. purgemob("owl"); --- Purge self purgemob(self)

purgeobj - syntax: purgeobj(OBJ,options)

Prog Types: Mob, Object, Room

Used to allow the mob to purge various combination of objects. By default, the room the mob is in and it's inventory/worn items are searched.

If the first argument is an OBJ type variable, it is purged and all other options are ignored. If the first argument is an object key, the first of that item type is purged, or all if LP_ALLOBJS is set (see below).

If the first argument is a keyword, an item is search for based on options. Keywords can also be "all.[item]" or just "all".

Purgeobj will not purge precious items. If a container that is purged holds these items, they will go to the room/mob holding the container. The options available with purgeobj are:

If purgeobj is used with no actor, the only valid argument is a direct OBJ type variable. From a lua prog, this will usually either by the object that triggered the program (objprogs) or an item retrieved using getobj. Note that if purgeobj is used on the 'obj' variable when an object prog is used, it should be the last statement in the prog that accesses obj.

LP_SEEALL No visibility checks, if the object exists it will be purged. LP_ROOMONLY Only purge items in the room. LP_WORNONLY Only purge items worn by the mob. LP_CARRIEDONLY Only purge items carried by the mob. LP_ALLOBJS Only used with objkey - if this option is set, all objects with the same key will be purged.

--- Purge all tickets carried by self. purgeobj("all.ticket",LP_CARRIEDONLY) --- Purge all instances of aylor-321 in room, visible or not. purgeobj("aylor-321",LP_ROOMONLY+LP_SEEALL) --- Purge the item that triggered this prog (give trigger) purgeobj(obj)

randchar - syntax: randchar(options,[room])

Returns a random char from the current room as a CH type variable. Candidates for selection are filtered based on the options provided. It is essential always to test for nil result after using randchar.

If the 'room' variable is given it must be a ROOM type. When ROOM is provided no 'self' variable is necessary, making the command available from roomprogs and object progs where there may be no actor. In this case, LP_SEEALL is ignored as there is no character to check for visibility.

LP_SEEALL No visibility checks, all chars in the room can be selected. LP_MOBONLY Only consider mobs in the room. LP_PLRONLY Only consider players in the room.

--- Select a random player, inform the room and the target. local rchar = randchar(LP_PLRONLY) --- If this were a room prog, we would use: --- local rchar = randchar(nil, room) --- If we didn't find anyone, bail. if rchar == nil then return end --- Note how with rchar passed to echo as the 'about' char, --- it becomes the base char for $N/$S/etc variables. echo("$n has picked $N as $s target!",rchar) --- Now send a message to the character themselves. echoat(rchar,"Congratulations, you're the lucky target!")

remember - syntax: remember(ch)

For compatibility with old mobprogs - causes a mob to 'remember' the provided character. The 'ch' variable can either be an existing character variable, or a name.

targ = self.target if targ == nil then say ("I don't have a target") remember(ch) else if (targ.gid == ch.gid) then say ("Hi! You're my target!") else say ("My target's name is " .. targ.name) end end

forget - syntax: forget()

Clears the mob's current 'target' pointer - equivalent of 'mob forget'

adddelay - syntax: adddelay(seconds) - Mob triggers only

Adds a delay on the mob - once 'seconds' are up mob will execute any prog attached to a delay trigger on it. Within those progs you can see if the prog has a previosuly remembered character who is still in the room.

cancel - syntax: cancel()

Cancels any outstanding delay timer on the mob.

--- On a greet trigger, ask character to wait in waiting room. --- If I'm already paused for someone else, do nothing. if not(hasdelay()) then say("Hi " .. ch.name .. ". Wait here please."); remember(ch) adddelay(10) --- 10 seconds. end --- In the delay prog. targ = self.target if (targ == nil) { --- Target left, how rude. social("mutter") } else { say("His lordship will meet you now " .. targ.name); mdo("unlock gate"); mdo("open gate"); } --- forget existing target. forget() --- In seperate prog if character tries to enter without waiting. say ("Don't be so rude! Now you can just sit and wait!") cancel() --- prog that opens door won't fire.

rgoto - syntax: rgoto("roomkey")

Mob will go to the room with the key given.

--- Remember where I am, goto aylor recall, purge guards --- return to start.Not the best example, mob could just --- use 'doat' if it was converted yet :) local chroom = ch.room rgoto("aylor-0") purge("guard") rgoto(chroom)

say - syntax: say("message")

Causes the character running the program to say something. As with 'mdo', more complex arguments can be created using Lua concatenation.

--- A mob to tell the time? say ("Hi " .. ch.name .. "! The time is " .. mud.hour .. ".") say ("It is the season of " .. mud.season)

send - syntax: send(CH,"message")

Used to send a message directly to a character - mostly for debugging purposes. A single new line is appended automatically. To add more, end the message with nr for each additional newline.

--- a very basic identify mob say("Here are the stats of your " .. obj.name) send(ch,"Level : " .. obj.level) send(ch,"Type : " .. obj.typestr) send(ch,"Value : " .. obj.value) send(ch,"Weight : " .. obj.weight)

social - syntax: social("socialname",[CH])

Causes the character to perform a social. If the option CH is given, it can be either a name or a CH type variable. Wherever possible, using a CH type variable directly is always more efficient and less error-prone than using a name.

--- smile $n in old mobprog could be: social("smile",ch) --- CH type variable : Preferred method. social("smile",ch.name) --- CH.name is a string, also works. --- Nudge a guard if they're here. social("nudge","guard")

summon - syntax: summon(CH1,options)

Note: Summon cannot be used in room or object progs. See 'movechar' for equivalent function.

Summon is used to transfer another mob or player to the mob the program is running on. In mobprogs, transfer was used for this purpose. Because of the added complexity in transfer, creating a separate function to bring characters to the mob was more intuitive.

Summon is typically used when a prog needs to transfer helpers to itself, but can also be used to check if the mob has an active target and summon it back to the room. Any potential target that is already in the same room as the mob will be ignored.

The CH1 argument can either be an existing variable of type 'CH', a character name or a mob key. Options can be used to limit the targets selected. With the exception of SEEALL, these options are ignored if a CH type variable is given rather than a name:

LP_SEEALL No visibility checks, if the target exists it will be transferred. LP_ZONEONLY Only look in the current zone for targets. LP_PLRONLY Only summon players, ignore mobs. LP_MOBONLY Only summon mobs, ignore players. LP_ACTIVEONLY Only summon target if they are in-game. Players in note or edit mode will be ignored. LP_ALLMOBS Only used with mobkey - if this option is set, all mobs with the same key will be summoned. LP_NOERR By default, an error is thrown is target is not found. Set this option to suppress error messages on target not found.

The CH1 argument can either be an existing variable of type 'CH', or a character name. Options can be used to limit the targets selected:

--- Summon all my guards, but only in current area. --- Summon even if I can't see them. summon("aylor-212",LP_ALLMOBS+LP_SEEALL+LP_ZONEONLY);

transfer - syntax: transfer(CH1,ROOM,options)

Note:Transfer cannot be used in room or object progs. See 'movechar' for equivalent function.

Transfer is used to send characters at the mob somewhere else. If the first argument is a CH variable, that character is targeted directly. If the first argument is a name, the room is searched for a character with that name. If the first argument is "all", all characters in the room may be transferred if not filtered out by additional options (see below).

The second argument can either be a ROOM type variable or a room key. The options argument (optional) can be used to limit the targets selected. With the exception of SEEALL, these options are ignored if a CH type variable is given rather than a name:

LP_SEEALL No visibility checks, if the target exists it will be transferred. LP_PLRONLY Transfer can target mobs also. Use this option to restrict to players. LP_MOBONLY Only mobs will be checked when a name is given or the target is "all". LP_GROUP When used with a name or a CH variable, will cause all group members in the room to be transferred. LP_NOERR Sometimes a mob will want to transfer a target if it is there, but no target is not considered an error. Set this option to suppress errors. LP_ACTIVEONLY Only transfer target if they are in-game. Players in note or edit mode will be ignored.

--- Transfer the char that triggered me to Aylor recall --- even if I can't see them. transfer(ch,"aylor-0",LP_SEEALL);

--- Transfer all mobs in room to legend-12, and --- all players to aylor-2. Only transfer players if I can --- see them and they're active. Transfer all mobs visible or not. transfer("all","legend-12",LP_SEEALL+LP_MOBONLY); transfer("all","aylor-0",LP_PLRONLY+LP_ACTIVEONLY);

Note: Builders used to the old mobprog system should be aware that transfer is no longer used to bring targets TO the mob - a 'summon' function exists for that:

zecho - syntax: zecho("message")

Message will be sent to all characters in the same area as the mob.