Areth areaprog documentation By Hades, updated 3/7/04 Areth's area programs (aprogs) consist of five types: Area Progs Exit Progs Mobile Progs Object Progs Room Progs Some day, it may prove useful to create area progs which trigger during resets, when players enter/leave areas, etc etc. Aprogs originated with the "Mirror Realm" area. Back in summer of '97, I was looking for areas on the web, and found a collection of Merc format areas. One of them was Mirror Realm... but when I loaded it, I noticed numerous format differences. Namely, the inclusion of mobprogs. With a bit of research, I found a mobprog format spec which had apparently been written either for Mirror Realm or for the mud for which Mirror Realm was written. In a moderate amount of time, Mirror Realm's mobprogs were loosely supported and causing splendid crashes. The next area to use mobprogs were a couple of Maelstrom's areas. Later on, Emberle's Blood Harvest area came about with needs for more advanced mobprogs than were presently possible. Instead of stripping down the area's goals, the mobprog system was enhanced and expanded to include numerous features which have recently been fully exploited. As of 7/27/02, the mud only contained examples of mobprogs. As of 3/7/04, exit_progs, room_progs, and obj_progs are being well utilized and area_progs and event_progs are unutilized. Emberle has continued on her aprog coding binge, and under her guidance the ability of Areth to utilize aprogs continues to be further refined. It is my eventual goal that Areth's source code become much like the source to Quake. Although the source is nice and pretty to look at, almost all the game's puzzled and complexity will be contained in its area files. When it becomes possible to fully port the game of Zork to run on Areth via aprogs, my goal will have been accomplished. When you've read through this aprog document, you may see how to implement what you want in your area - or you may not. My philosophy as a coder and as the person who maintains the aprog system is that you, as an area designer, should design your area and decide what you want it to do. You shouldn't limit your vision to the constraints of the existing aprog system any more than strictly necessary. If you want to be able to have a prog fire when a player does X, I'd rather enhance the existing system by adding the aprog support for what you want, than have you strip down your creative vision. That having been said, you *may* not actually need a new event type in order to achieve what you want - talk to me, I may be able to help you. All aprogs have a common syntax - that is, they appear at the end of a normal in-game entity (room, exit, mobile, or object) and before the start of the next. The fact that an aprog follows, is indicated by the > symbol. After that comes the type of aprog which follows (this determines what event triggers it) and after that comes any information required in order to determine if it should fire or not. These parameters may be strings or a number, depending on which type of aprog it's being given to. The parameters are terminated with a tilde. Each line thereafter, until another tilde is encountered on a line by itself, is considered to be part of the aprog. An aprog may be followed by another aprog. Beneath, I'll provide an example aprog: >speech_prog p score~ mpoload 31 mposet portal value0 6654 mpforce $n enter portal mppurge portal ~ Aprog syntax is uncomplicated, and can almost be thought of as a special form of alias with support for variables, simple arithmetic comparisons, and if...then...else statements. Some day I will add 'select' support, but that some day has yet to come. =============== APROG VARIABLES =============== Some programs have a need to store data, more or less temporarily. Any variables used during the execution of an aprog are not cleared at the prog's end, because otherwise it would prove difficult to debug. Cleanup takes place before the aprog executes again. Each object (room, character, etc) has its own variable space, and each aprog has access to only its own variables. There is not presently a global or area-specific data space for variables, although this may happen eventually. Before any line of an aprog is evaluated, it is parsed for variables. The syntax for said substitution is {variable}. The data type of the variable greatly affects what is shown. If the data type is one of the special ones ('cause', for example, is defined as any player character who triggered the event in question), a large number of sub-variables are defined. Sub-variables will be defined later on, but {cause.name} will return the target's 'name' field, {cause.vnum} will return 0 for any player character and an appropriate number for any mobile, etc. Any variable which you set in an aprog will be a Perl-style typeless variable, which could be either a string or a number. Internally, it's all strings, but that's another story. All arithmetic operations must be enclosed in parenthesis, and there must be only two operations within any given set of parenthesis. You can use parenthesis grouping to sum up more items though - ((1+2)+(3+4)) instead of (1+2+3+4). Any attempt to access a variable which has not previously been set will generate a bug message, but using the appropriate declaration commands will result in a new variable being set up and initialized appropriately. Any destroyable object (character or object) will lose its variables upon death or destruction, respectively. Any variables not flagged as permanent via the permset command will also be removed upon the prog's exit. Temporary variables are often used to store the results of random rolls or whatnot, and permanent variables are most commonly used to remember what state of a mini-quest or whatnot a player is at. The set and permset commands are subject to the same variable substitution system as the rest of aprogs. This can be used to your advantage. Consider 'permset queststage_{cause.name} 2'. Because all aprogs on the same object share the same data space, an entry_prog could be set to examine the variable queststate_{cause.name} so that the mobile can greet the player differently based on how far along in the quest he/she is. But you're more likely to use things such as 'set damage (4*{cause.hp})' or 'set morons ({morons}+1)'. There are four types of variables which are presently supported: 'number', 'string', 'object', and 'char' (character, either player or mob). ================= SPECIAL VARIABLES ================= In order to access certain system based lookup tables and such, use the array notation to indicate which element you wish to look at. For example, {race[0].whole_name} is "Human". In practical terms, you'll almost always be using nested lookups - for example, the spider in mudschool uses {race[{cause.race}].whole_name}. In order to see what numbers are available for any of these special variables, try 'execute describe [table]' or 'select * from [table]'. Below will be listed some of the most useful system tables for variable lookup. race - race-specific stats. class - class-specific stats. skills - skill-specific information, as used in potions/scrolls/whatnot. liquids - as used in drink containers and fountains. There are also certain globally pre-defined variables which can be used in your progs. {rand} : Produces a different 0-99 random number each time it's invoked. {hour} : Returns the hour of day (in mud time). Can be seen by typing time. {hour0}: Returns the hour of day (in mud time), with a 0 prefixed before any single-digit time. Useful for stating that it is {hour0}00 hours, which at 1pm would be displayed as 1300 hours. {day} : Returns the day of the mud month. {month}: Returns the mud month of the year. {pulse}: Returns the current 'pulse'. Game pulses happen several times per second, and can be thought of as 'turns' of game time. ======= HANDLES ======= This is presently only valid in obj_progs, but it is possible to use a 'handle' with all of the typical commands (both normal, such as 'get', and the special mp* commands). It is guaranteed that a handle will reference one specific object, even if there are other objects with the same name in the game. A handle is valid across reboots as well, because it is a combination of the object's vnum and 'uniqueid' number, which is a 32-bit random number. The probability of two items existing with the same uniqueid *and* vnum, and both being online at the same time, is astronomically small. On a side note, any object which is running an objprog may be referenced as {obj} within that prog. get {obj}, etc. It's the same syntax as referencing sub-fields (like {obj.level}, just leaving off the '.' and sub-field). ================== APROG FLOW CONTROL ================== Aprogs support if/else/endif, but the syntactical rules are a little tight. Any use of the if statement must be followed by a space, then an arithmetic expression which will evaluate to a numeric result. If the result is non-zero, the if is considered to have succeeded, and if the result is zero, the parser will skip to either the else statement which matches the if or, if there is no else, the endif which matches it. 'Else if' is not explicitly supported, but can be achieved through use of nested if statements. For an example, see below: if ({damage}>{cause.hp}) mpechoto {cause.name} You are going to die when this hits you. else mpechoto {cause.name} You will survive this hit. if (({cause.hp}-{damage})<100) mpechoto {cause.name} However, you are going to be very badly hurt. endif endif ============== APROG COMMENTS ============== Just like in Perl or bash, you can comment out lines in aprogs by putting the # character as the first non-space character on the line. ================ APROG STATEMENTS ================ declare, declareperm This command creates a variable of the type you specify (see above, 'Aprog Variables'). 'Declare' creates a temporary variable which does not persist across mobprogs or during the next mobprog's execution. 'Declareperm' creates a permanent variable which will not only save across executions, but even get written to pfiles. Use 'declareperm' sparingly in objects and on players (yes, you can store variables on them as well). The syntax is 'declare weartnl number 27500', where weartnl is the name of the variable and 27500 is the number. Bear in mind that declare does not perform arithmetic evaluation, so if you want to have weartnl have some additions or subtractions done to it, use 'setv' on the variable after you declare it. mpaecho [char] [message] mpechoto [char] [message] mpechoat [char] [message] mpechoaround [char] [message] mpechoroom [char] [message] These commands are all for managing mobprog output. mpaecho sends a message to everyone in the area [char] is in but not in the same room. mpechoto sends a message directly to the character executing the aprog. Note however that this is the only echo command that can send a message to a character which is sleeping or otherwise incapacitated. mpechoat sends a message to [char] and only to [char] mpechoaround sends a mesage to everyone in the room except for [char] mpechoroom sends a message to everyone in [char]'s room, including [char]. mpcallbackup [radius] [vnum] This command causes the character invoking it to call for backup from nearby mobiles against the character it is fighting. [radius] is how many rooms away the call should go out. If [vnum] is not specified, any non-sentinel mobiles will respond to the call for assistance. If [vnum] is specified, all mobiles of that vnum within range (regardless of whether or not they're sentinels) will respond by walking to the room backup was called for in, and attacking the character backup was called against. mpcast mpcontrol [victim] [action] [target] Where action is one of: drag, guard, kill, subdue, seekroom, seekchar. Drag causes the mob to grab onto the target and haul the target wherever they're going. Guard causes the mob to attempt to take any incoming damage for the target and assist immediately, like the guard skill. Kill causes the mob to attack the target, seeking if necessary. Seekchar causes the mob to home in on, but not attack, the target. Seekroom causes the mob to travel to the room specified - this is the only action which uses a number as a target instead of a character. mpmset, mposet These are identical to the immortal mset and oset commands. mpevent [eventname] This indicates that an event has taken place, which other progs in the game are set to respond to. This allows a mob, object, room, or any other prog to trigger events for anything which has had an event prog attached. For example, going through a motion sensor might trigger an alarm event which calls guards who have been set to respond to 'armory_motion_sensor' and react appropriately. Any event by a given name will trigger on *all* receptors for that event, subject to the percentage-probability modifier on the event_prog itself. So if had a spellcaster whose magic is providing sanctuary to an army of 12 or so lesser mobs, its death could trigger a 'jimbob_died' event. The lesser mobs could be equipped with 'jimbob_died' event_progs that remove the mobs' sanctuary affects via mpmset. mperl Do not use this. mpforce [victim] [command] Same as imm force command, comparable to mortal 'order' command. mpgohome This causes the mobile, if it repopped instead of being mloaded, to set a walking path back to the place it was initially loaded at and follow it. This is highly recommended in order to return sentinels to their positions after an mpcallbackup. mpgoto [destination] This command is identical to the Immortal goto command, which accepts a room vnum, character name, or other valid target. mpjunk [obj] This is identical to the junk command, except that it works on objects in inventory and produces no output to the rest of the room when the object is destroyed. mpmload [vnum] [level] This is a mob counterpart to the immortal mload command, which creates a mobile of the specified vnum and level. If the mobile has a load_prog, it will trigger that program's event. Note that the loading mobile is defined as {cause} to the loaded mobile, so that the load_progs can set their descs appropriately (example: mpmset self desc a demon invoked by {cause.name}). mpoload [vnum] [level] [room] [var X] Identical to the immortal oload command, it creates an object of vnum [vnum] and level [level]. If the optional 'room' command is specified, it will load the object on the ground instead of the inventory of the character running the command. If the optional 'var' command is given, a variable of type object will be assigned to the newly loaded object. This would allow for manipulation, etc. If you want the variable to be permanent, then declare it before you specify it to mpoload. mppeace This command stops all fights which are happening in the room. Note that it does not permanently stop them - aggressive mobiles will attack immediately afterwards. It merely stops fights currently in progress. mpprohibit This command is a simple command which takes no arguments. All it does, is exit the current aprog and prevent the action which triggered the aprog from actually happening. So if you try to go through an exit, but the aprog attached to the exit doesn't like you for some reason, it can use 'mpprohibit' and your attempt to go through the exit will in fact be cancelled. This also works for wear_progs, and pretty much any type of prog. Any time you want to specially restrict an action, this could well be able to do the job. mppurge [target] This is identical to the immortal 'purge' command, and will eradicate either objects or mobiles. If used without arguments, it will purge all mobiles and objects in the room. That would probably be bad. It will not purge player corpses unless they are explicitly named, however, so purging rooms is pccorpse-safe. mpslag [target] [location] This command allows a mobile to selectively slag any piece of equipment positioned at the named location on a player. To see the available locations to slag gear from, execute select name from wearnames. There will be no written form of this, as it is subject to change when equipment slots are changed. mpslay [target] [tnl] Identical to the immortal slay command. If the word "tnl" is added after the target name, the slay will incur the same experience loss as a normal death. mpterminal [target] [timer] [mobile] [desc-on-death] This command afflicts [target] with an affect of 'terminal illness'. [timer] ticks from infection, the target dies. If [mobile] is not zero, then upon the player's death, a mob of vnum [mobile] is created. The mobile has access to the name of the player who it killed upon loading, as a variable named {trigger}. mptransfer [target] [destination] This is identical to the immortal transfer command, which is used to move characters from place to place. It differs from goto only in that you specify who is being moved, as opposed to being moved yourself. set, setv This command adds a variable to the object's temporary variable space. The next aprog the object runs will overwrite all temporary variables. Use set in most cases, unless you want to be performing mathematical operations on the variable. If that is the case, use setv and make sure you enclose the mathematical part in parenthesis. For example, 'setv damage ({cause.hit}+4)'. The parenthesis are NOT optional. Use them. ========== APROG FLOW ========== ADVANCED APROG TRICKS: The whole 'fail this test, try that one' business. Usable for multiple death progs, catch-all responses, etc. =========== EVENT PROGS =========== This is a special form of prog, which is available in exits, rooms, mobs, areas, etc. All prog'able objects in the game support event_progs. An event_prog essentially provides the ability to call subroutines on other objects on comamnd from another prog. Event progs are *only* triggered by progs, there is no way for an event to be called by a player action. Except, of course, for a player action which trips a prog that invokes the event. To set an event, use the mpevent command. That will invoke a search through all event_progs, looking for progs which are geared to answer to that event. For example, you could have a situation where throwing a lever in one room opens an otherwise-unopenable door in another room. The syntax for event progs is very simple: EVENT_PROG [x] [s] In this, X is the percent chance of the event firing, and [s] is the name of the event. Bear in mind that event_progs are *global* events, so care must be taken to ensure that your events are uniquely named. Example, setting foot in a certain room could set off an event_prog on a guard in the next room. That will trigger the event_prog on the guard - now, if you had the foresight to give him a bottle of rum ("WHERE IS RUM?!? RUM IS GONE!!!"), the event_prog detects that his sobriety level is low enough that he doesn't care that you're in the room. On the other hand, if he's sober, he sets off another event that causes some other guards to come running. You could name the event in the other room 'armory_sensor_tripped', or just 'sensor_tripped' - but bear in mind that events are global. Name conflicts with other areas will cause your progs to fire other areas' events. Therefore, it is a good practice to unmistakeably unique names on your areas. ============= MOBPROG TYPES ============= Mobprogs have been around the longest of all the types of aprogs. They're the most mature, and most of them have been tested and deployed in areas ranging from mudschool to Blood Harvest. The character which executes a mobprog is always the mobile which has the mobprog attached to it. The 'cause' variables are set to the character (if any) which triggered the mobprog event to fire. RAND_PROGs and LOAD_PROGs never have target variables set. DEATH_PROGs *usually* have causes set, but under certain circumstances might not (mobiles dealing due to poison). In the case of there being no valid cause variable, the cause is usually set to the mobile itself to avoid null pointers. ACT_PROG [s] This is like a speech program, but it matches specific text strings. Of all the formatting strings, it's the most like a traditional mud client trigger, and could perhaps be used to script reactions to socials. ALL_GREET_PROG [x], GREET_PROG [x], ENTRY_PROG [x] These three aprogs are triggered when a player enters the same room as a mobile which is equipped with one of them. Between the two greet progs, there is no difference except for the historical difference between them exhibited in Merriman's Mirror Realm area. An entry prog, however, is only for when walking into a room and cannot be triggered by portal/nexus/whatnot like the greet_progs. The number X is the percentage probability that the aprog will execute when a player character enters the room. BRIBE_PROG [x] This prog is very simple: if you give the mobile X or more gold coins, it will execute this program. DEATH_PROG [x] This program is X percent likely to be executed if the mobile equipped with it bites the big one. DEST_PROG [x] This program is only usable by mobiles. When a mobile enters a room with the vnum X, this aprog is fired (100% of the time). This can be a very effective means of scripting a mobile which does something when it's taken to a specific room. The best-known example of this is Cassity, when she's lead to the street outside the Dragon Cult. FIGHT_PROG [x], PREROUND_PROG [x] This program has X percent chance of happening every round of combat. This has a chance to execute at the end of a round of combat. A FIGHT_PROG takes its chance of execution after the in-round melee attacks and a PREROUND_PROG executes before the in-round melee attacks. FIGHTSTART_PROG [x], FIGHTWON_PROG [x] These programs execute when a fight is started or ended, respectively, that involves the aprog-equipped mobile. A suitable fightstart_prog could be a taunt, or in some cases a simple mpslay command. A fightwon_prog could be truly diabolical and involve casting 'create undead' on the victim's corpse... GIVE_PROG [x] [s], SHOW_PROG [x] [s] Give_progs and show_progs are identical except for the fact that in a give_prog you lose the object you're giving to the mobile, and in a show_prog you don't. If X is provided, it is expected to be the vnum of an object. This is strongly encouraged, as it is both CPU-efficient and prevents accidentally havin additional objects match your criteria. S may be either the word 'all' (which means *any* object you give/show the mobile will trigger this response) or a set of keywords, any one of which will trigger a match if the object possesses them. If you wanted to create a mobile who is looking for any common bladed weapon, you could set S as 'sword knife dagger axe' and it would match with any object possessing one or more of these keywords. HITPRCNT_PROG [x] This program is invoked at the time when a mobile's damage takes it below X percent. This is how Primus summons his secundii when his own hit points drop below 50%. A mobile which has executed this program will not execute it again until its health increases above the trigger point, and then it sustains damage which drops it back below it. IDLESELF_PROG [x] This aprog is fired whenever a mobile has been standing in the same room for X seconds without moving. I recommend using this to fidget or complain about sitting in one place. As with the roomprog events, if X is positive, this prog will only have a chance to fire once per room. However, if X is negative, it will fire once every X seconds. IDLEPC_PROG [x] This aprog triggers whenever a player character in the room has an idle timer which matches the number X. It also follows the convention of repeating every X seconds if X is negative. INTERP_PROG [s] This program is NOT IMPLEMENTED, but when it *is* implemented, it will act as if there's another command in the command interpreter. If a mobile had an interp_prog called 'assimilate' and the player typed 'assimilate', this prog would trigger. No, this isn't planned for Borg support, that was just what came to mind. So sue me. LEAVEROOM_PROG [x] This is the opposite of an ENTRY_PROG, and is executed right as the player is leaving from the room with the mob which has this trigger. LOAD_PROG [x] This program is X percent likely to be executed as soon as the mobile bearing it is loaded. It's how buttroaches set themselves up with the name of the person they killed upon hatching. If the load_prog is invoked by terminal illness, the name of the target is passed to the new mobile in the variable {trigger}. Load_progs execute upon either the mob's loading naturally via resets or when the mpmload command is executed. Load_progs do *not* trigger when Immortals use the mload command; there are just too many ways for that to be a bad thing. MEETMOB_PROG [x] This program is executed when the tagged mobile meets a mobile with the vnum X. The 'watched' mobile may be in the room which the mobile enters, or it may enter the watcher's room - either way will set off this program. An example of a good use for this would be a special courier mobile giving any object in its possession named 'message' to the king mob (vnum X), or perhaps soldiers saluting their commanding officer whenever he enters the room. RAND_PROG [x] This program has X percent chance of happening every combat-round-duration tick. Bear in mind that rand_progs are disabled whenever a mobile is in combat; if you want combat actions, use a fight_prog. Or if you want both, then write identical rand_ and fight_ progs with the same percentage chance of firing. RANDPC_PROG [x] This prog has X percent chance of firing every tick that one or more players is in the room with this mobile. It picks a player character at random from the room to use as the {cause} variable. NOT YET IMPLEMENTED. SPEECH_PROG [s], ASK_PROG [s] A speech_prog is triggered when a character says something to a mobile equipped with this aprog. The string S is what the character must say in order to trigger the aprog. If the string begins with 'p' and a space, then the rest of the trigger source is allowed to be *anywhere* in what the character said. If 'p' is not provided, then the character must say it exactly as said. This function is not case sensitive. An 'ask_prog' is exactly the same as a speech_prog in triggering event, except that from the player's perspective it's done with the ask command. For example, 'ask worf batleth'. TARGFLEE_PROG [x] There is an X percent chance, on any successful flee attempt, that the mobile will execute it when the target it's fighting runs away. This can be used for taunts... or perhaps to lob a fireball spell into the room after them. Another thing with this prog is that mpprohibit can be used to turn the successful flee into a failure after all. TICK_PROG [x] This program is used to trigger events based on time of day in aprogs. If it is fed a non-negative number (0-23), that will be taken as the hour of game time, per day, to trigger on. As in, "tick_prog 19" would fire every day at 7pm. Yes, it is in 24-hour military/european time, and no that won't change no matter who whines about it. If the number is negative, it will be taken as "every X ticks, starting at midnight". So a value of -6 would cause the prog to fire at midnight, 6am, 12pm, and 6pm. You can use numbers which do not evenly divide into 24, and the system won't complain - it'll just reset the counter at midnight. For example, -9 would fire three times a day: 12am, 9am, and 6pm. If you have issues with that, do complicated things with counter variables and firing every 3 hours (24/3=8, 3*3=9, thus if you fire the prog every time your counter reaches 3...) for example. TEACH_PROG [s] This program is executed whenever you practice skill S at the mobile in question. When a mobile has a teach_prog for skill S, skills marked hidden can be practiced at that mobile - provided the student is ready (at a high enough level to learn it). The only current instance of this is Dragon Technique. More skills should be learned this way. ========== ROOM PROGS ========== Room progs are triggered by rooms. Because all aprogs are interpreted like normal mud commands, and thus require a character object to execute them, room progs are actually executed as the character who sets them off and not as some other character. The best way to think of this is that you are scripting actions which a player performs when they are set off, somewhat like a string of 'force' commands. Room_progs have not been extensively tested, because so far no one has made use of them in area files. SECNPC_PROG [x], SECPC_PROG [x] These aprogs fire when a PC or NPC, respectively, has been standing in the room for a certain amount of time. If you wanted a room to scorch someone every 20 seconds of standing in the same room, you'd just set X to -20. If you wanted a booming voice to announce, 'None shall pass!' after 5 seconds, then announce '...unless you bring me a shrubbery!' after 10 have elapsed, then your first prog would read 5 and the second would read 10. The reason these two progs are seperate is that often you would like only players standing in an elemental plane of fire to suffer burn damage, and not the elementals in the room which can be assumed to be used to living there. TICK_PROG [x] This program is used to trigger events based on time of day in aprogs. If it is fed a non-negative number (0-23), that will be taken as the hour of game time, per day, to trigger on. As in, "tick_prog 19" would fire every day at 7pm. Yes, it is in 24-hour military/european time, and no that won't change no matter who whines about it. If the number is negative, it will be taken as "every X ticks, starting at midnight". So a value of -6 would cause the prog to fire at midnight, 6am, 12pm, and 6pm. You can use numbers which do not evenly divide into 24, and the system won't complain - it'll just reset the counter at midnight. For example, -9 would fire three times a day: 12am, 9am, and 6pm. If you have issues with that, do complicated things with counter variables and firing every 3 hours (24/3=8, 3*3=9, thus if you fire the prog every time your counter reaches 3...) for example. This prog is not guaranteed to always fire, because if there is no character (PC or NPC) in the room, there will be no character to execute the commands. This is not necessarily a bad thing; it can save CPU cycles with descriptive-only commands. However, if you're relying on your TICK_PROG to set state information, you may want to consider a different mechanism. WALKIN_PROG [x], WALKOUT_PROG [x] This program is triggered when a player *walks* into or out of a room. This is not triggered by mobiles or by players who enter the room via transport spells or immortal commands. X is the percentage chance it will happen. PCDIE_PROG [x], NPCDIE_PROG [x] These programs are triggered when a player (PC) or mobile (NPC) dies in the room with this prog. An example of this might be room of poles/whatnot for martial artists to duel on top of, where death means your corpse plummetts to the ground to be devoured/guarded/animated/something-really-nasty. As usual, X is the percentage chance this program will be executed upon death. RAND_PROG [x], RAND_PERCHAR_PROG [x] As with its mobprog counterpart, a rand_prog stands X percent chance of being executed every round a player is standing in the room which has it. There are two variants of this rand_prog: rand_prog can execute a maximum of once per round, regardless of how many players are in the room, and a rand_perchar_prog will roll once per player character in the room. A perchar_prog is suitable for a volcanic core which has a random chance of blasting anyone in the party with magma, but an eerie forest with growls and chirps in the background should have its events trigger at the same time for everyone in the party, as eveyone would hear it at the same time. GATEIN_PROG [x], GATEOUT_PROG [x] This program is executed whenever anyone either casts a transportation spell into the room or enters a portal/nexus into it. This could be used for... heck, I dunno, use your own imagination. As usual, X is the percentage chance this roomprog will fire. INTERP_PROG [x] As with most interp_progs, this basically adds a new command to the game for any character in this particular room, with X percent chance of being triggered every time the player types that. Granted, it is not implemented, but bug me enough and it might be. ========== EXIT PROGS ========== Exit progs have not seen testing of any description. Like room_progs, they should be looked at somewhat like 'force' scripts for the character that sets them off. OPEN_PROG [x], CLOSE_PROG [x] This aprog is X percent likely to trigger any time someone opens/closes the exit in question. Please refrain from exits that load monsters every time someone opens a door, as it could readily become an infinite source of monsters. Unless of course the door becomes bashed/damaged in the process and thus it's not possible to produce more monsters. Note that an exitprog on one side of a door does not trigger when the exit is opened from the other side. This is intentional, but if bi-directional progs are needed, I can implement a bi-directional progtype too. PASSTHRU_PROG [x], NPCPASSTHRU_PROG [x], PCPASSTHRU_PROG [x] These aprogs are X percent likely to trigger any time someone travels through the exit in question. In these progs, the mpprohibit command will stop a character from passing through the exit. The PC variant only triggers for player characters, the NPC variant only triggers for mobs, and lastly the non-specific variant triggers fro both. LOOK_PROG [x] This aprog is X percent likely to trigger any time someone looks into/through the exit in question. PICK_PROG [x], PICKFAIL_PROG [x] This program is X percent likely to trigger every time someone picks or unsuccessfully tries to pick the lock on the exit. ============ OBJECT PROGS ============ Object progs have also not seen testing of any sort. The aprog always uses the character holding it as the scripting source. In the case of when it's being transferred, given, etc, it will use the character which is about to not be holding it. OBJUSEDON_PROG [vnum] This program triggers whenever the object having the vnum [vnum] is used on this object, via the 'use' command. This is useful for objects which can be modified or transformed by the use of other objects. For example, it's possible to simulate a real-life Desert Eagle's changeable barrel system by the use of barrel objects you can use on the gun object. Using a barrel on the DE results in the creation of a new barrel object corresponding to the barrel originally on the DE, and the DE osetting its attributes to change its caliber and descriptions where appropriate, then destroying the barrel object which was used on the DE (to reflect that it's now installed on the gun, rather than a seperate object). Before any of you start drooling over this, bear in mind that I own a real life Desert Eagle 50cal and it might be wise not to pester me TOO much for one on the mud. ;) OBJUSEONOBJ_PROG [vnum] This is not yet implemented, but it would be used the opposite way from the OBJUSEDON_PROG. In the above case of using an alternative barrel on a pistol, this would be a prog which is on the barrel itself, and not the pistol. OBJUSEONCHAR_PROG [vnum] This is not yet implemented, but this would be a way to implement things such as using a bucket of water to purge the Wicked Witch of the West. If vnum is zero, this will trigger on any character the object is used on. LOAD_PROG [x] This program is X percent likely to be executed as soon as the object bearing it is given to a character as part of a reset or mpoload. Load_progs do *not* trigger when Immortals use the oload command; there are just too many ways for that to be a bad thing. PICKUP_PROG [x], DROP_PROG [x], SHOW_PROG [x], GIVE_PROG [x], WEAR_PROG [x], REMOVE_PROG [x], EXAMINE_PROG [x] When these trigger events happen are entirley self-explainatory. In all cases, X is a percentage chance that the program will go off if the trigger event is performed. DESTROY_PROG [x] This trigger event has an X percent chance of going off when the object in question is junked. TOUCH_PROG [x] This event is X percent likely to be triggered when the object in question is touched by a character with the touch command. The object does not have to be in inventory. TIMER_PROG [x] This event goes off when the object's timer reaches X. This could be used for light sources that sputter or dim before they go out, for example. CONSUME_PROG [x] This event is X percent likely to go off when an object is eaten or quaffed, or if a scroll is recited, etc. It is not hurk-safe, so try not to use it with objects of type food unless you don't mind players being able to do it infinitely. One of these days I'll modify this to only fire the first time one eats it. BUY_PROG [x] This prog is X percent likely to be triggered whenever the object is bought. PCSTRIKE_PROG [x], NPCSTRIKE_PROG [x] This prog is X percent likely to be triggered when this object is used to strike a PC or NPC, respectively. GAINEXP_PROG [x] This program is fired X percent of the time when the character who has equipped the object gains experience. This is triggered upon killing mobs, upon practicing, upon dying - anything which grants or takes away experience. There is no way to tell what mobile has been killed, but the amount of experience gained from the kill is stored in the variable {Exp}. KILLMOB_PROG [x] This is triggered whenever the wearer kills a mob with the vnum X. KILLPC_PROG [x], KILLNPC_PROG [x] This is triggered whenever the wearer kills any PC or NPC, respectively, X percent of the time. Use this sparingly, I anticipate it would eat a *lot* of cycles if there was much gear out there which used this. WEARPCDIE_PROG [x], WEARNPCDIE_PROG [x] This is triggered whenever the wearer (PC or NPC, respectively) dies while wearing it.