Aardwolf MUD Home Page Link

Location: Home / Lua Coding / Lua Triggers

In designing the Lua / Mud trigger system we have tried to keep it as consistent with mobprogs as possible so it will be familiar to existing builders. The mobprog trigger types were also necessary to convert the old ROM areas to V3 as their flow is based on these trigger types. There are a number of new trigger types and options available with triggers, details are listed below.

Character Triggers

Character triggers are the type you will be most familiar with, and most work the same. Some have additional arguments that are passed through to Lua. The important thing to note is that most triggers in place so far exist only to support the conversion of mobprogs to Lua or for the academy. The Lua system can trigger on pretty much anything - post to the Aardwolf Lua forum if you have a need to trigger on something unavailable here.

An 'act' trigger allows a mob to respond to actions in the room such as socials, or room echos from many commands. In ROM mobprogs, 'act' was widely used to catch social output. The need for 'act' triggers is reduced in v3 due to being able to trap command input in room progs. However, it still has its uses.
Note that some mud actions output messages to mobs in the room only, specificaly so that act progs can be triggered. If you have to capture act messages on a command that does not echo anything to the room, and roomprogs won't meet your need for whatever reason, contact Lasher to discuss adding mob-only output to the command. A good example of mob only output is when a player drops an item in a room.
Syntax to add: add act [prog id] "trigger phrase"
A 'bribe' trigger allows a mob to respond only when given a minimum amount of gold.
Syntax to add: add bribe [prog id] [min gold]
A 'death' trigger gives a mob a percentage chance to run a lua program upon death, before its corpse is created and it is removed from the game. Death triggers are often used to randomly load a piece of equipment or transfer a character to the next part of an area quest.
Syntax to add: add death [prog id] [percent chance]
A 'delay' trigger has a percentage chance to run after a mob executes an adddelay(seconds) statement from another prog. Usually a delay prog looks for a previously remembered char before continuing.
Syntax to add: add delay [prog id] [percent]
An 'entry' trigger is executed when a mob moves, not a player. Exit triggers are commonly used to keep a specific mob within a small group of rooms, or on a wandering guard to attack as it enters.
Syntax to add: add entry [prog id] [percent chance]
An 'exall' trigger runs when a player moves in a specific direction. N,E,S,W,U,D correspond to 0 through 5 for directions. Unlike 'exit' triggers, 'exall' triggers fire even if the mob is busy, and visibility is ignored.
Syntax to add: add exall [prog id] [dir]
An 'exit' trigger runs when a player moves in a specific direction. N,E,S,W,U,D correspond to 0 through 5 for directions. For 'exit' triggers to fire, the mob must not be occupied and must be able to see the player.
Syntax to add: add exit [prog id] [dir]
A 'fight' trigger gives a random chance for the program to be executed while the mob is actually in combat. Often used to cast spells, summon helpers or run away.
Syntax to add: add fight [prog id] [percent chance]
A 'give' trigger caused the program to run when a mobile is given either a specific items, or if the last argument is 'all', any item. The item given to the mob is variable 'obj' in Lua and all functions that use an obj type variable can be applied to it. 'All' is commonly used with give triggers to cause the mob to return items other than those it is specifically interested in.
Syntax to add: add give [prog id] [objkey, or, "all"]
A 'grall' trigger adds a percentage chance to run a lua program when a player enters the room. The chance to trigger takes place regardless of the mob's current condition or whether or not the mob can see the player.
Syntax to add: add grall [prog id] [percent chance]
A 'greet' trigger adds a percentage chance to run a lua program when a player enters the room. The mob must not already be busy/sleeping and must be able to see the player for a chance to trigger the prog. See 'grall' for other options.
Syntax to add: add greet [prog id] [percent chance]
A 'hpcnt' trigger causes a program to run when the mobile is in combat and its hit points fall below the percentage given.
Syntax to add: add hpcnt [prog id] [percent hp]
A 'kill' trigger adds a percentage chance to run a lua program when someone initiates combat with the mob. Usually used to stop combat or summon help. The academy guards have a 'kill' prog that transfers away anyone not level 201.
Syntax to add: add kill [prog id] [percent chance]
A 'listen' trigger has a percent chance to execute when a player uses the listen command on a mob.
Syntax to add: add listen [prog id] [percent]
A 'random' trigger sets an event to run a program on a mob. For compatibility with old mobprogs, a 100% random runs, on average, every 3 seconds. 50% runs every 6 seconds etc.
Note that with random progs, the prog is triggered without a player causing it, so 'ch' is not defined. Random triggers usually cause a mob to echo or do something not involving another player, or find a random player in the room using randchar().
Syntax to add: add random [prog id] [percent]
A 'speech' trigger allows a prog to be called when the player says something. Speechexact requires the exact phrase to be entered whereas 'speech' will trigger if any part of the player's speech contains the trigger phrase.
There is a special case to 'speech' triggers - if the trigger phrase is set to 'all', the prog will be triggered on any speech in the room and what was actually said will be available in lua as a string using the variable 'charg'. Regular speech triggers are always checked before an 'all' trigger so they can be mixed. More than one 'all' trigger is pointless.
Syntax to add: add speech [prog id] [trigger phrase]
Syntax to add: add speechexact [prog id] [trigger phrase]
A 'tell' trigger allows a prog to be called when the player sends a tell to the mob. Tellexact requires the exact phrase to be entered whereas 'tell' will trigger if any part of the player's tell contains the trigger phrase.
There is a special case to 'tell' triggers - if the trigger phrase is set to 'all', the prog will be triggered on any tell to the mob and what was actually sent will be available in lua as a string using the variable 'charg'. This is how the academy decides whether or not you answer correctly during the quiz sections.
Syntax to add: add tell [prog id] [trigger phrase]
Syntax to add: add tellexact [prog id] [trigger phrase]
A 'transfer' trigger executes when a player is transfered into the room by another lua prog. Greet/grall progs are not triggered by transfer, this trigger type is used instead. Note that imm transfers, portals, etc do not run transfer triggers - only transfer from within another prog.
Syntax to add: add transfer [prog id] [percent]
A 'timer' trigger sets a trigger to run a program on a mob every X number of seconds. Timer triggers are similar to 'Random' triggers but the time is fixed.
Note that with timer progs, the prog is triggered without a player causing it, so 'ch' is not defined. Timer triggers are useful to combine with mobdata (saves over a reboot) and the time commands to set a specific time at some point in the future then check periodically is that timer has expired. See the section on Timers in the Lua Howto page for an example.
Syntax to add: add timer [prog id] [seconds] (cannot set a timer for less than 60 seconds)

Room Triggers

Room triggers are split into two main types: Room triggers that act as arbitrary commands on a room. For example, allowing a player to 'pick apple' in the Orchard or 'board' the train in lands of legend. The second type of trigger is actions performed by the room itself - perhaps a room damages chars on entry if they dont have enough resists to fire, or an "onrepop" trigger runs when the area repops, basically allowing you to create your own reset types. At the time of writing, only the first type of triggers are in place. These are listed below.

Room triggers/progs have some important differences from standard mobprogs. Firstly, each trigger type has an additional (optional) argument for 'actor'. The actor is the key of a mob that much be in the room for the prog to be able to run - this mob then becomes 'self' as if a mobprog had been called. Lands of Legend uses this - 'board' only works if the conductor is there. The academy progs that wait for you to type a command before continuing also use this - they will only run if the trainer is present.

Another important difference with room progs is that unless an actor is given (see above), there is no "self" when the prog runs. Many of the existing luaprog functions require/assume that 'self' is present and either will not run at all (echo - WHO is doing the echo in this case?) or require an extra argument (oload - requires char to put the object on if there is no self).

The 'command' trigger is the main way to trigger progs from arbitrary room actions. A trigger of 'push rock' on the room will fire if the player types 'push rock'. A command trigger of only 'push' will trigger on 'push' by itself or 'push' with any other argument.
This means that command progs which do nothing but return can be used to block a specific command in a room, or even change its function completely (as 'board' does in lands of legend - you board the train instead of seeing the list of MUD boards). Wherever possible, COMMAND type triggers show now be replaced with CMDABBREV triggers (see below)
Syntax to add: add command [prog id] "trigger phrase" [optional - mobkey for actor]
The 'after' trigger allows a mud command to be run, but then runs the program afterwards. The academy programs that require new users to type a command to try it rely on this type of prog. For example, Claire requires new players to type 'help kill' and 'score' in basic training - the output of these commands is displayed then the trigger calls a prog which causes Claire to move on to the next part of the lesson.
Syntax to add: add after [prog id] "trigger phrase" [optional - mobkey for actor]
The 'repop' trigger in a room will cause that prog to be executed whenever the room is reset - which is usually whenever the area resets. A numerical argument can be used as a percentage 'chance' to fire. If an actor (mob keyword) is given, the trigger will only fire if that mob is in the room at the time of repop.
Note that this trigger runs after other resets, so if the 'actor' is a mob that resets in the room, it will almost always run. Also note that other than a possible mob actor, there is nothing triggering this, any 'ch', 'obj', etc variable required inside the prog will have to be fetched using getmob(), getobj(), and similar commands.
Syntax to add: add repop [prog id] [optional - % chance] [optional - mobkey for actor]
Not currently used.
The 'block' trigger was superceded by 'cmdabbrev' type triggers. It remains in place only for compatibility with some early lua progs that use it.
The 'cmdabbrev' trigger is a new type of trigger designed to solve the problem of needing many triggers to capture a single event. For example, 'open' and (on the test port) 'unblock' are the same command. As directions can also be abbreviated with the open command, using room progs to completely intercept an 'open south' would require many combinations of triggers such as the list below:
op south
ope south
open south
open s
open so
ope sou
unblock south
unblock s
unb s 
... etc ...
Even if every combination of 'open south' and 'unblock south' is added in a trigger, there is still the issue that a new global alias for open could be added in future and no triggers will be in place for it - the intent of the program to capture someone trying to open the door to the South is ruined.
The 'cmdabbrev' type trigger matches on the actual command name that will be executed and is also aware of global aliases. In the example above, 'unblock southopen' alias because the MUD engine knows that 'unblock' is the same as 'open'. Note this would not work in reverse - open is the main command so that is what the trigger should be on.
Any argument the player adds after the command is passed through to the Lua program in the variable 'charg'. If the player used 'open south' and the trigger is set for 'open', the value 'south' is passed into the prog.
If the lua program called via a cmdabbrev trigger returns false, the underlying command will continue to run as usual. If the lua program returns 'true' the command execution is blocked. This allows basic lua string matching to be used to parse arguments.
The example program below puts these three things together in an example scenario. This is on Silvermist Road in Aylor (test port - run 19s3w). The high level flow of the program is:
  • If the player tries to open the door to the South, we only want to allow the open if they are a Giant. They should still be able to open the North door unhindered.
  • If they enter no argument or the door is already open we just return false and let the open command handle it.
  • Next we use 'string.find' to see if the value entered is a prefix of "South" and if so check if the player race is giant.
  • If they are not a giant we send a message and block the command (return true), otherwise we let the 'open' command run as usual.
  • If the charg value is not a prefix of "South" then either they did an open 'north', or are trying to open an container - we also just let the 'open' command handle it.
This program will work with any abbreviation of 'open south' or 'unblock south' and only requires a single trigger. Any future global aliases added for open will be set to be the 'same as' open and will also trigger the program to fire.
if charg == nil then
   --- No argument given, let MUD command handle it.
   return false

if room.south.open == 1 then
   --- Room is already open. Let MUD command handle it.
    return false
--- is ch.arg a prefix or match on 'south' ?
local i = string.find("south","^"..string.lower(charg))
if i ~= nil then
   --- Trying to open south
   if ch.race ~= RACE_GIANT then
      send(ch,"Ony a giant is strong enough to clear the way South.")
      return true -- Block the open command.
      return false -- Let the open command continue
   --- Not trying to open south. Let the command continue
   return false
The trigger that goes with this is simply:
No   Trigger Type Program       Phrase               Actor
==   ============ ============= ==================== ==============
 1 - Cmdabbrev    test-141      open                     

Object Triggers

See the Object Progs page for a list of object prog triggers.