DARKOVER 2.1 Proc (aka Procedure) Documentation for DarkoverMUD Version 1.0 Written by: Shalla, Danar Last Updated: June 23, 2003 Index: ------------------------------------------------------------------------------- 1.........Introduction 2.........Example 3.........DarkoverMUD Procs 1.........Introduction ------------------------------------------------------------------------------- First things first: what on earth is a "proc"? "Proc" is a piece of technical jargon from Diku muds, the same way "mob" is. Say the word "mob" to someone who doesn't play Diku muds, and he's going to look at you funny. "Mob", technically, is short for "mobile"... even though a lot of mobs are not mobile, and objects are mobile too! But we understand that it means, more or less, "characters, the kinds of things that can execute commands, have hps, that kind of stuff... well the ones that aren't players are called mobs." The meaning of "proc" is similarly weird. It is short for "procedure", based on the view that code is made out of things called "procedures" or "functions". They are often called "special procs", because in Diku code, they are usually custom written to do something for a specific mob, making them "special". In any case, that is where the word comes from, although like "mob", the origin of the word and its literal meaning are not very important! In fact, the coders on Darkover don't even call them procs anymore; we call them "behaviors". But everyone else calls them procs, so here you go! So what do procs do, and what are they good for? To some extent, procs are "the old way of doing things", back before mob progs. Mob progs let you get just about anything done that you want, to make a mob do something special. If what you want isn't possible, we can add a new command or construct to the mobprog language. But there are advantages to procs. Sometimes we do the same thing, over and over again, like "make this dragon breathe fire" or "make this guard block the west gate". Instead of having to cut and paste the same mobprog code, over and over again, we have pre-written procs you can put on a mob. You just fill in a few values, such as which types the dragon breathes, or which directions the guard blocks, and it is done for you. This is convenient, and it cuts down on bugs, since you don't have to try to reinvent the wheel on every new dragon you make, possibly making a mistake along the way. It is already done for you, and works. The other time we make procs is when something is much easier to get done in the hard C code of the game, instead of in mob progs. Guildmasters, mudmail messengers, and boards are things like this. They need access to a lot of special things, like the mail database and the exp tables, that aren't available in mob progs. Rather than spend tons of time making all this clutter avaiable to mob progs, we just write the few procs that need this level of access in C, pre-packaged, for you to assign when you need them. 2.........Example ------------------------------------------------------------------------------- Your mob, obj, and wld files can contain "P directives". These directives "request" a proc to be "assigned" to the thing in question. If you have written mobprogs or read the mobprog documentation, you will notice that they also use the P directive. In fact, mobprogs are just one kind of proc you can assign, although they are the most common one. The P directive is placed in slightly different areas of the various files. In mob files, the P directive comes after the last line of pure numbers, the line that has (load position, default position, gender). In obj files, the P directive goes after any A directives you have to add "+stat affects" to a piece of equipment. If you have no A directives on an object, put it after where they would be if they were there. Most likely, this is at the bottom of the object's data. In wld files, the P directive goes after the D directives for exits (if you have any), and before the E directives for extra descriptions (if you have any). The format of the P directive itself is very simple, P <proc name> <args>~ As you can see, in relation to mobprogs, "mob_prog" is the <proc name> part, and everything else, your stuff like "text hello" and all your lines of commands is the <args> part! Most procs are much easier to request than a full mobprog, and the args will only be a word or two... perhaps no args at all. Usually it all fits on one line. Some examples: P dragon fire~ P block west~ P assist_by_keyword queen~ P mailer~ P receptionist~ 3.........DarkoverMUD Procs ------------------------------------------------------------------------------- name: assist_by_keyword [mob] usage: 'P assist_by_keyword <name|all>' Long ago, when alignment ruled the world of Darkover, many of the mobs in the world would assist each other based each other's alignment. Well, when DO2 came about, that all went out the window with the removal of alignment all together. We were left with a HELPER flag that didn't do anything. So, we created this proc which is a bit more versatile. When you specify a name (say 'queen' for instance), every time someone in the room with the mob is attacked it will in essence echo 'assist <name>'. If that person is the one that got attacked, it'll assist them, otherwise (since they aren't fighting), nothing will happen. The one exception to this is the word 'all'. If you use that, it will help any mob no matter it's stats or specs that gets attacked. This is especially helpful for guards and the like. You are allowed to have more than one of these entries, so if you need to protect 'king' and 'queen' both, you can have: P assist_by_keyword king P assist_by_keyword queen However, note that if both are attacked simultaneously (say an area spell perhaps), it will give preference to the topmost entry, so the person would assist the king, not the queen (since the mob can only fight one person at a time). name: block [mob] usage: 'P block <north|south|east|west|down|up>' Much like the old stock bitvectors, this will make a mob prevent someone from moving in a certain direction while the mob is alive. This is mainly used for sentinel guards that are protecting a room or person in a specific room. You can use any combination of the directions listed above separated by a | just like in incompatible_obj above. The mob will prevent travel in those directions as long as it's alive. name: dragon [mob] usage: 'P dragon <fire|frost|acid|gas|lightning|all>' This is a fun one. You can set any mob to be the Dragon race, but this is the heart of being a dragon. This is where breathing, tail whips, and shrieking take place. Currently, you can only have a single-type or the 'all' type, but this will change soon so that you can specify a list of types like you can the incompatible_obj proc above. As you would expect, the type you specify will choose what type of breath they use, and the 'all' choice will make a random choice of all the available types. For perspective on the following 3 procs that comprise this master proc, the dragon proc assigns these 3 on a 10% breathe, then 15% fear, then 10% tailsweep percentage basis. The 'then' means that it checks the breathe proc at 15% success, if that doesn't fire, it checks the fear proc, and likewise the tailsweep proc. name: breathe [mob] usage: 'P breathe <fire|frost|acid|gas|lightning|all> <probability>' This is a fun one. This is the breathing portion of the dragon proc only. So if you want a mob to breathe, but not do the other things, such as tailsweep, or shriek to fear the group, you can use this. The probability percentage represents how often you wish the proc to fire off in combat. If I used 'breath fire 30', for example, the mob would breathe fire 30% of the time. name: fear [mob] usage: 'P fear <probability>' This is the fear portion of the dragon proc only. You can use this by itself for mob's that are able to scare people out of the room by way of a horrible scream. The probability is 1-100, the percentage of the time you wish it to happen. For example, to 'fear' 75% of the time it would be: 'P fear 75'. name: tailsweep [mob] usage: 'P tailsweep <probability>' This is the tailsweep portion of the dragon proc only. You can use this one for lizard type mobs or anything that would have a huge tail to whip around at you. The probability works just like the fear version with the percentage of success time as the probability argument. name: guild [mob] usage: 'P guild <class list>' This controls the ability to train players and their associated skills (if they are in the acceptable level range to learn from a trainer rather than a teacher). The list of classes the mob can train are listed and separated with a '|'. There is an entry for all the classes in the world, but it needs to be all lowercase letters, so a Mage trainer would be: 'P guild mage|elementalist' and the like. You can have as many or as few of the classes as you'd like, but please keep it to a minimum. A mob that trains every class in the world just shouldn't exist. name: clanguard [mob] usage: 'P clanguard <clan number> <north|south|east|west|down|up>' When you create a clanguard, you can get the value of the clan from the Immortals to use in the specification. The mob can block 1 direction or all 6 directions depending on the circumstances, but you should just need the 1 direction leading into the clanhall. The proc is not susceptible to invis people like block() is, so you also don't have to worry about clanhall raids (well, unless they kill the guard all together *nod me*). name: mail [mob] usage: 'P mailer' Well, you can't just be content with your own board, you must be able to communicate with the outside world. Well, put this proc on a mob and you'll be able to send and receive your mail as long as you're in the room with him and have sufficient funds. You'll need 150 coins per stamp to send, but delivery is free, just like the USPS. One added feature in DO2.1 is the 'multi-mail' ability. You can specify multiple names in the mail command and a copy of the mail will be sent to each person. And, yes, you need 150 coins PER stamp. We're a game, but we're not stupid. name: no_kill [mob] usage: 'P no_kill' Adding this proc to a mob will make him unattackable. All offensive attacks will be stopped by the mob. All shop keepers and ship captains will have this proc by default. Be very careful in using this. name: mob_transform [mob] usage: 'P mob_transform' Adding this proc to a mob will cause the mob to load the mob with the next vnum (ie: putting this on mob 1 will load mob 2) when the mob enters combat. This resembles the TRANSFORM field on an object when you wear it, but is used for mobs. name: board [obj] usage: 'P board <read level> <write level> <remove level>' So you want to be able to write nifty messages on a board and have them saved, huh? Well, here's your chance. All entries will be keyed to the vnum of the board object, so no matter how many you load the posts will be the same on each version. The read level is minimum level a person must be in order to decipher the holy words in the text. Write level and remove level function much the same as the read level variable. One note, even if you're above the remove level for the board, if the person that posted the message is of higher level than you, you will not be able to remove their post. You need to contact that person or an Immortal to have that post removed. name: incompatible_obj [obj] usage: 'P incompatible_obj <vnum list>' Certain magical items sometimes conflict with each other out in the world. This proc is a method to make sure that it affects the player rather than having to make certain affect combos on multiple items. In the specification, you can specify 1 or more items that this item is incompatible with. When a character tries to wear this item and is already wearing something in the vnum list, it will give them a message like 'You wear it, and get a shock, forcing you to drop it!' and it will end up back in their inventory. There is no damage incurred from the shock, it just prevents the items from being worn together. Note: this is a 1-way process. Make sure if you have 1 item that is incompatible with another, that the 2nd item is incompatible with the first as well. If you don't they can simply wear the items in the reverse order and be able to get them both on at the same time. name: gateway [obj] usage: 'P gateway ... then several lines of config options' A gateway is like a super portal. Except for a full mobprog, a gateway is the most powerful, and complicated, proc you can assign. It has its own mini-language of "gateway" commands, although this language is declarative like HTML or XML, not imperative like the mob prog "scripting language". Before getting into the details, here is how a gateway is more flexible than a portal, 1. Portals all use "enter", but a gateway can use any command. You could make "touch orb" teleport someone, instead of forcing them to "enter" the orb. 2. Gateways can have more than one keyword, each keyword leading to a different destination. 3. Gateways can be setup to let characters "peek" into a room and see what's there, not always to teleport them. Like #1 above, the command word that does this is configurable. It does not have to be "peek"; you could have "kneel altar" give the character visions of a certain room. 4. The messages for using a gateway are fully customizable, unlike portals which always say "NAME enters OBJECT." Here is an example gateway that exactly fakes the arena portal, P gateway port_cmd enter char_msg You enter $P.#N from_msg $n enters $P.#N to_msg $n steps out of a #Yyellow## portal.#N gate portal 3000 /gate /gateway ~ The first thing to notice is the general structure of the gateway data, P gateway ... stuff ... /gateway ~ Within that structure, there are 2 sets of commands. First, the global commands that define the gateway: which command it uses for "enter", and what messages it sends around when it is used, port_cmd enter char_msg You enter $P.#N from_msg $n enters $P.#N to_msg $n steps out of a #Yyellow## portal.#N After this global data, a gateway has a list of "gates". Our gateway has only one gate, going to room 3000, the entrance of the arena, gate portal 3000 /gate That is about as simple as it gets. "enter portal" will echo the messages to the room, and move the character to room 3000. Now that we have a seen a simple example, we can list the full set of gateway commands, and then follow with a complicated example that uses all of them, - port_cmd: Names the command used to teleport with the gateway. If omitted, the gateway cannot be entered. e.g. port_cmd enter e.g. port_cmd touch - look_cmd: Names the command used to "look through" the gateway to the other side, without teleporting. If omitted, the gateway cannot be looked through. e.g. look_cmd peer e.g. look_cmd gaze - char_msg: 1st person message sent to the user of the gateway when it is "entered". If omitted, no message will be sent. e.g. char_msg You enter $P.#N e.g. char_msg As you reach to pick up a gem, darkness decends over you... - from_msg: 3rd person message sent to the room, when someone "enters" a gateway. If omitted, no message will be sent. e.g. from_msg $n enters $P.#N e.g. from_msg $n reaches to pick up a gem, and is suddenly gone! - to_msg: 3rd person message sent to the destination room, when someone emerges from a gateway. If omitted, no message will be sent. e.g. to_msg $n steps out of a #Yyellow## portal.#N e.g. to_msg The darkness wavers momentarily, and $n appears from within. - look_msg: 1st person message, sent when a user looks through a gateway, at the top of the text before showing the destination room. (There is, currently, no way to specify a 3rd person message to notify the room when a gateway is looked through.) If omitted, no message will be sent. e.g. look_msg You gaze into $P and see...#N e.g. look_msg As you kneel before the altar, images fill your mind...#N - gate: Specifies a "keyword" of the gateway, and the destination it leads to. There may be more than one "gate" command on a gateway. There are also several special "gate commands" below, that can only be specified within a gate, and apply to the single gate, not the entire gateway. If omitted, your gateway is 100% useless. :P e.g. gate portal 3000 /gate e.g. gate orb 1221 /gate - /gate: Necessary to terminate a previous 'gate' command. Cannot be omitted. - alias: used with a 'gate' command to give additional keywords to the gate. this is a convenience so you don't have to cut-and-paste the same gate twice just to give it 2 different names. If omitted, the gate will have only the single keyword given by the 'gate' command. e.g. gate moon 1220 alias lunar /gate Ok, now that we've seen all that, and that it really isn't so complicated ... 2 commands for enter and look-through, 4 messages, and then 1 or more gates... here is a full example that uses everything. It is an immortal tool that we sometimes use to go to hometowns and other main locations, without having to remember all the internal numbers. If we are feeling lazy, we can just use it to "enter targon" and appear in Preacher's Square. #1207 crystal globe~ #Aa globe of crystal##~ #AA globe of crystal floats here, a few inches above a pedestal.##~ ~ 12 ^12|^13|^14 0 0 0 0 0 0 0 3 3 3 0 0 1 1 0 0 E crystal globe~ Although the entire mortal world is visible through the crystal, some locations stand out more sharply than others. The brightest images are those around: Boryied Moraelin Caer Cormac Raschid Dunsane Silvertear IsleDead Targon Kuprek Tintagel Luthnallaine Underkeep One can #Apeer## into the globe to see its images more clearly, and if one has the will and presense of mind, physically #Aenter## into the torrent of images and manifest presently within them. ~ P gateway look_cmd peer port_cmd enter look_msg You gaze into $P and see...#N char_msg #AThe images are so entrancing that you feel drawn inside...###N from_msg $n gazes into $P and disappears! to_msg $n appears amidst a #Aswirl of flickering images.## gate targon 2603 /gate gate dunsane 6101 /gate gate silvertear 8381 /gate gate kuprek 9485 /gate gate caercormac 11868 alias caer alias cormac /gate gate luthnallaine 12300 alias luth /gate gate moraelin 18605 /gate gate isledead 21407 alias mistwoods /gate gate underkeep 24040 /gate gate raschid 24215 /gate gate boryied 26227 /gate gate tintagel 31920 /gate /gateway ~ Most likely, the gateways you create will not have this many features. Probably, all you want is a simple portal to one room, but with custom trigger commands, keywords, and messages. But the rest of the functionality up there exists, to use if you can come up with a neat reason to. One more technical note! Although, as noted above, a gateway is usually put on an object, it is technically possible to put it on a mob. Some of the messages above used $P to insert the gateway object's name in the descriptions. If your gateway is on a mob, $P will not be available, but $N, $M, $E, and $S will instead. In general, we recommend using objs for your gateways, because objs consume less mud resources than mobs. But if a mob gateway is really what you want, go ahead and try, it might be cool. You can also put a gateway on a room... although we don't really recommend this. It is easier on immortals to create an invisible object in the room that does the gateway. That way when an imm is poking around your area, he can see the invisible object, and know there's something special.