# Programming for CoffeeMud 5.9
Overview Building Windows Unix External Components Default Import List Text Target Info Tag Color JavaScripting Writing Your First Javascript Core Topic 1: Message Passing Major Code Bitmask Message Previewing Message Flagging and Modification Message Execution Message Trailers Core Topic 2: State Layers PhyStats fields CharStats codes CharState Core Topic 3: Threading Core Topic 4: Core Libraries Core class purposes Library mappings Common Classes Core Topic 5: Input Core Topic 6: Database Tables Commands MOBs Coding a new MOB Life and Death Items Creation and Destruction Behaviors Character Classes Races Exits Locales Areas Properties Skills Skill Nature Flags Skill Affect Flags Spells, Prayers, and Chants Spells Spell Domains Prayers Chants Songs Common Skills Gathering Skill Crafting Skill Poisons Diseases Traps & Bombs Languages | ## Overview The purpose of this document is to assist those who wish to add custom Items, MOBs, Behaviors, Properties, or other objects to CoffeeMud. The reader should be familiar with Java programming, and should be experienced with writing and compiling Java classes. The object oriented notions of class inheritance and polymorphism, as well as the Java constructs of interfaces should be at least vaguely familiar to you before attempting to build classes for CoffeeMud. Also, it is expected that all of the ideas presented in the Archons Guide and Game Builders Guide are completely familiar. The difference between a GenItem and a StdItem, or a GenMob and a GenPostman will not be explained in this document. It is not expected that someone would wish to dive in and make wholesale changes to the CoffeeMud system right away, but is more likely wanting to fill in a functional gap in the system for their own needs. For this reason, this document is not organized as a comprehensive guide to programming CoffeeMud. Instead, it is designed to be a quick reference for those who wish to create the spot MOB, Behavior, Item, or Property for use on their maps. With this in mind then, let's start out with some brief development instructions, and then and in no particular order, discuss the several essential object types in CoffeeMud are presented. ## Rebuilding CoffeeMud ### In Microsoft Windows Go to your coffeemud directory and edit the make.bat, the first line will be something like: `SET JAVACPATH= C:\Program Files\Java\jdk1.6.0_22\bin\javac` This might be different for you depending on what version of the Java JDK you installed, and where your java development package is installed. Save the bat file. Run the bat file by double clicking on it. This will compile the mud, making all the .class files. ### In Unix Go to your coffeemud directory and edit the makeUNIX.sh, the first line will be something like: `Java_Home=/home/knoppix/jdk1.6.0_22` This might be different for you depending on what version of the Java JDK you installed, and where your java development package is installed. Save the shell script. Issue this command: `chmod 755 makeUNIX.sh` Execute the shell script. This will compile the mud, making all the .class files. ### Introducing External Components If you perused the coffeemud.ini file as mentioned in the Installation Guide, you may have noticed and wondered about the section near the bottom which lists the default load paths for the several CoffeeMud objects. By default, the CoffeeMud engine dynamically loads the vast majority of its object code at boot time by referring to the paths specified in the coffeemud.ini file. The value `%DEFAULT%` is always used as a substitute for the default CoffeeMud object path. For instance, if you installed CoffeeMud at "`C:\CoffeeMud\`", then "`BEHAVIORS=%DEFAULT%`" in the ini file would load "`C:\CoffeeMud\com\planet_ink\coffee_mud\Behaviors\*.class`" into its behavior set. This default object boot paths may be removed or added-to using semicolon delimited paths, or even replaced with your own object boot directories. In fact, when adding objects to your CoffeeMud boot sequence, it is recommended that you place your objects in a separate directory path inside your CoffeeMud folder and add its path to the coffeemud.ini file under the proper setting. The order in which you place multiple paths in a single entry is also significant, as the CoffeeMud ClassLoader will load the files in the order in which they appear listed. For instance:
    MOBS=%DEFAULT%;/resources/examples/MyClass.class;/resources/otherclasses
Will cause the default CoffeeMud versions of the mob classes to be loaded first, followed by MyClass.class, followed by all the class files in the resources/otherclasses folder in your CoffeeMud package. Also notice that the ClassLoader follows the rules of the CMFS described in the Archons Guide, meaning that the forward slash is always the proper path separator, and that no folder outside of your CoffeeMud package may be referenced. Also bear in mind that case is sensitive when naming Java class files, even in these boot paths. When writing these custom classes for your special object boot directory(s), it is important to keep a number of things in mind: Do not mix your object types in the same directory! Never try to boot custom items from the same directory from which you boot your custom mobs. It will only confuse you and CoffeeMud. Java Packaging is irrelevant, you may package your classes or not. Implement or extend a class that implements the proper interfaces. If you are coding mobs, this would mean the MOB interface. If you are coding locales, the Room interface, etc, etc. See the section on the object type you are coding for the proper interface to implement. You may get around this requirement by extending one of the base classes, such as StdItem, StdMOB, StdContainer, StdRoom, StdAbility, GenMob, GenItem, GenContainer, etc. Make sure the `ID()` method in your classes always matches the name of your class. You will understand this better as you reference the object sections below. Try to make the `name()` methods in your classes return name values unique among all objects, especially objects of that type. This is not a hard fast rule, and breaking it will not cause malfunction in the system, but breaking this rule WILL make writing help files impossible. Class files loaded directly in the CoffeeMud classpath can not be reloaded at run-time using the `UNLOAD` and `LOAD` commands. If you plan on making changes to your classes during run-time, place them in their own directories. As a general rule, you may import any "`interfaces.*`" packages in the base CoffeeMud structure, any core Java packages, the CoffeeMud "`core.*`" package, and any single base CoffeeMud class you may be extending. Do not import more than that. Use the CMClass getter methods if you need to create new instances of CoffeeMud classes, and use the CMLib methods to access her code libraries. ### Complete Default Import List
    import com.planet_ink.coffee_mud.core.*;
    import com.planet_ink.coffee_mud.core.collections.*;
    import com.planet_ink.coffee_mud.core.interfaces.*;
    import com.planet_ink.coffee_mud.Abilities.interfaces.*;
    import com.planet_ink.coffee_mud.Areas.interfaces.*;
    import com.planet_ink.coffee_mud.Behaviors.interfaces.*;
    import com.planet_ink.coffee_mud.CharClasses.interfaces.*;
    import com.planet_ink.coffee_mud.Commands.interfaces.*;
    import com.planet_ink.coffee_mud.Common.interfaces.*;
    import com.planet_ink.coffee_mud.Exits.interfaces.*;
    import com.planet_ink.coffee_mud.Items.interfaces.*;
    import com.planet_ink.coffee_mud.Locales.interfaces.*;
    import com.planet_ink.coffee_mud.MOBS.interfaces.*;
    import com.planet_ink.coffee_mud.Races.interfaces.*;
    import com.planet_ink.coffee_mud.Libraries.interfaces.*;
    import java.io.IOException;
    import java.util.*;
## Text Before we get started with objects, needs must the topic of text display be covered. Throughout the system you will see text being sent to the user. Since a mud is a text producing engine, this should be no great surprise. However, within that text you will often see different kinds of codes and tags which affect the output. For instance, consider the following lines:
    msg=CMClass.newMsg(mob,target,this,CMMsg.MSG_OK_ACTION,"<S-NAME> reach(es) for <T-NAMESELF>.");
    mob.location().show(mob,null,CMMsg.MSG_OK_ACTION,"<S-NAME> regain(s) <S-HIS-HER> feet.");
Focusing only on the text for a moment, you will notice that special tags are used to designate a player name, or the name of the target of a spell. You will also notice that (s) and (es) is used to modify the proper form of a verb. These are key features of the CoffeeMud text engine. Here is a more complete list of available tags:
`<S-HIS-HER>` | Outputs 'Your' if Observer=Source, otherwise 'His'/'Her'.
`<S-HIM-HER>` | Outputs 'You' if Observer=Source, otherwise 'Him'/'Her'.
`<S-NAME>` | Outputs 'You' if Observer=Source, otherwise the Name.
`<S-NAMESELF>` | Outputs 'Yourself' if Observer=Source, otherwise the Name
`<S-NAMENOART>` | Outputs 'You' if Observer=Source, otherwise the Name minus any prefix articles (a, an, some, etc..).
`<S-HE-SHE>` | Outputs 'You' if Observer=Source, otherwise 'He'/'She'
`<S-SIRMADAM>` | Outputs 'Sir'/'Madam'
`<S-MRMS>` | Outputs 'Mr.'/'Ms.'
`<S-MISTERMADAM>` | Outputs 'Mister'/'Madam'
`<S-IS-ARE>` | Outputs 'Are' if Observer=Source, otherwise 'Is'.
`<S-HAS-HAVE>` | Outputs 'Have' if Observer=Source, otherwise 'Has'.
`<S-YOUPOSS>` | Outputs 'Your' if Observer=Source, otherwise the Name`s
`<S-HIM-HERSELF>` | Outputs 'Yourself' if Observer=Source, otherwise the 'Himself'/'Herself'
`<S-HIS-HERSELF>` | Outputs 'Yourself' if Observer=Source, otherwise the 'Hisself'/'Herself'
`<T-HIS-HER>` | Outputs 'You' if Observer=Target, otherwise 'His'/'Her'.
`<T-HIM-HER>` | Outputs 'You' if Observer=Target, otherwise 'Him'/'Her'.
`<T-NAME>` | Outputs 'You' if Observer=Target, otherwise the Name.
`<T-NAMESELF>` | Outputs 'Yourself' if Observer=Target, otherwise the Name
`<T-NAMENOART>` | Outputs 'You' if Observer=Target, otherwise the Name minus any prefix articles (a, an, some, etc..).
`<T-HE-SHE>` | Outputs 'You' if Observer=Target, otherwise 'He'/'She'
`<T-SIRMADAM>` | Outputs 'Sir'/'Madam'
`<T-MRMS>` | Outputs 'Mr.'/'Ms.'
`<T-MISTERMADAM>` | Outputs 'Mister'/'Madam'
`<T-IS-ARE>` | Outputs 'Are' if Observer=Target, otherwise 'Is'.
`<T-HAS-HAVE>` | Outputs 'Have' if Observer=Target, otherwise 'Has'.
`<T-YOUPOSS>` | Outputs 'Your' if Observer=Target, otherwise the Name with an '`s'
`<T-HIM-HERSELF>` | Outputs 'Yourself' if Observer=Source, otherwise the 'Himself'/'Herself'
`<T-HIS-HERSELF>` | Outputs 'Yourself' if Observer=Source, otherwise the 'Hisself'/'Herself'
`<S-ACCOUNTNAME>` | Outputs 'You' if Observer=Source, otherwise the Account Name.
Occasionally, you will find color/font codes embedded in system strings. For instance:
    msg.append("^!You are thirsty.^?\n\r");
These codes are as follows:
`^N` | Normal
`^!` | Bold
`^H` | Highlight
`^_` | Underline
`^*` | Blink
`^/` | Italics
`^.` | Reset (turns off reverse)
`^^` | Generates an untranslated "^" character
`^?` | Restores previous color
`^f` | You-Fight
`^e` | Fight-You
`^F` | Fight
`^S` | Spell
`^E` | Emote
`^T` | Talk
`^Q` | Channel Background
`^q` | Channel Foreground
`^x` | Important message 1
`^X` | Important message 2
`^Z` | Important message 3
`^O` | Room Title
`^L` | Room Description
`^J` | Weather
`^D` | Direction
`^d` | Door
`^I` | Item
`^M` | MOB
`^U` | Unexplored Direction
`^u` | Unexplored Door
`^w` | White
`^g` | Green
`^b` | Blue
`^r` | Red
`^y` | Yellow
`^c` | Cyan
`^p` | Purple
`^W` | Dark White
`^G` | Dark Green
`^B` | Dark Blue
`^R` | Dark Red
`^Y` | Dark Yellow
`^C` | Dark Cyan
`^P` | Dark Purple
`^~w` | White Background
`^~g` | Green Background
`^~b` | Blue Background
`^~r` | Red Background
`^~y` | Yellow Background
`^~c` | Cyan Background
`^~p` | Purple Background
`^#xxx` | 256 color foreground x=0-5
`^##xx` | 256 color foreground xx=hex 00-ff
`^|xxx` | 256 color background x=0-5
`^||xx` | 256 color background xx=hex 00-ff
`^<` | < character. Used for MXP tags only.
`^>` | > character. Used for MXP tags only.
`^&` | & character. Used for MXP tags only.
As you might have guessed, it is preferred that the system colors (the last codes) be used sparingly, in favor of the more customizable codes above. Also, be sure to always put foreground color codes before background color codes. Foreground color codes always "reset" the default background color. ## JavaScripting: JavaScript is an interpreted scripting language which is used in various parts of CoffeeMud. The CoffeeMud engine integrates the Rhino Javascript interpretor package from Mozilla in such places as the Scriptable behavior, the JRun command, the ClassLoader, the Quest engine, and the web server. In lieu of a complete write up on the syntax of this language, it is suggested that you read the documentation available from the authors of the interpretor here: http://www.mozilla.org/js/ and http://www.mozilla.org/rhino/. If you are familiar with writing Javascript for web browsers, there are several differences you will need to adjust to when using Javascript in CoffeeMud. A minor difference is that the Rhino interpretor requires that all variables be declared before use. A more important difference is that Javascript Strings are not the same as Java String objects, and that confusing them can lead to errors. To get around this problem, all of the implementations of Javascript in CoffeeMud, with the exception of the ClassLoader, provide a special method to convert Javascript strings into Java Strings before passing them to Java methods or objects which will require them. An example is below:
    var javascriptstring=' this is a javascript string ';
    var javastring=toJavaString(javascriptstring);
    // and now javastring is a real-live Java-compliant and Java-friendly string
When writing Java classes in JavaScript, however, this method is only available through the CMLib object in the core package. This is how you would access the `toJavaString()` method from a class written in JavaScript:
    var javascriptstring=' this is a javascript string ';
    var javastring=Packages.com.planet_ink.coffee_mud.core.CMLib.toJavaString(javascriptstring);
    // and now javastring is a real-live Java-compliant and Java-friendly string
The most important difference between coding Javascript for CoffeeMud and for browsers is that there is no HTML DOM (Document Object Model), and therefore several of the libraries you are used to are probably missing, such as Math. For this reason, it is necessary for you to learn the CoffeeMud object packages in order to get access to useful data and useful libraries. And now you understand why the JavaScripting notes are kept in the Programming guide. :) To access the CoffeeMud object packages, you will need to make use of the Packages object to reference external packages. So long as the imported objects are in your CoffeeMud classpath, they can be accessed and used. For instance, to use the CoffeeMud `pow(x,y)` function in CMath.java:
    var lib=Packages.com.planet_ink.coffee_mud.core.CMLib;
    // the above creates a reference to the CoffeeMud Library as a shortcut
    var value=lib.math().pow(4,2);
    // now we can access the math() library from our shortcut.
Depending upon the context from which your script runs (the Scriptable behavior, JRun command, the Quest engine, or the http/web server), certain other objects are made available to assist scripts in properly interacting with their environment. When writing Java classes in JavaScript for the ClassLoader, however, you must always use the `Packages.com.planet_ink.coffee_mud.core.CMLib` reference to access special methods such as the toJavaString method discussed above. In the Scriptable behavior, several methods are made available to access objects which are related to the event which triggered the scripted code. These methods include `MOB source(), Environmental target(), Environmental host(), Item item1(), Item item2(), String message(),` and `MOB monster()`. The JRun command provides the methods `MOB mob(), int numParms(), String getParm(int i),` and `String getParms()`. The web server makes the `HTTPRequest request()` object available, as well as the method `void write(String s)`. The quest engine makes the current running Quest object available from the method `Quest quest()` and the current state of the quest setup script available in a custom QuestState object referencing method called `QuestState setupState()` The last piece of general information about JavaScript in CoffeeMud concerns writing Java classes for the CoffeeMud ClassLoader. Any JavaScript file *.js included in the ClassLoader boot paths (see the previous section) will be loaded and treated just like any Java compiled *.class file. The JavaScript file would be parsed, compiled, and loaded at boot time. For the most part, writing Java Classes in JavaScript is extremely similar to writing Java Classes in Java. Base classes may be extended (using the special CoffeeMud `//extends` command in your JavaScript), interfaces may be implemented (using the special CoffeeMud `//implements` command in your JavaScript), super class variables and methods may be accessed (using the `this.variableName` and `this.super$methodname()` syntax), and super class methods may be overridden by JavaScript functions of the same name and number of parameters. Class files written in Javascript *.js files may also be loaded and unloaded at runtime using the LOAD and UNLOAD Archon commands, which gives them a step up on native Java classes in the JVM classpath. ### Writing your first JavaScript Below is an example of a Java Class written in JavaScript. Examples of Embedded JavaScript in CoffeeMud Virtual Pages (cmvp) web files can be found in the Web Server Guide. Examples of Embedded JavaScript in a Scriptable MOBPROG script can be found in the Scripting Guide. Our Java Class example is called GenLemming.js. It is a sample MOB class to demonstrate extending the GenMob class to create a type of modifiable mob for your maps. In this example, we add functionality to make all mobs in the world created from the GenLemming base suicidal. To use this class, save the code somewhere in our CoffeeMud folder under the name "GenLemming.js", and add an object path reference to it in the MOBS entry in your coffeemud.ini file, as described in section one.
    //extends com.planet_ink.coffee_mud.MOBS.GenMob

    function ID(){return "GenLemming";}

    var lib=Packages.com.planet_ink.coffee_mud.core.CMLib;
The first lines of our class include the special //extends command which informs the CoffeeMud ClassLoader that this JavaScript class will extend GenMob, thereby inhereting all functionality of the maleable GenMob. The `ID()` method is required in all CoffeeMud classes. It must be the simple name of the class, and must match the name of the JavaScript file containing it. For example, GenLemming.js contains class GenLemming and returns an ID of "GenLemming". They all match exactly. Lastly, we define the variable "lib" to act as a shortcut to the CoffeeMud core Libraries. Now, moving on; since we don't have the ability to write constructors in JavaScript, any initial fields we need to set whenever a new instance of our class is created must be done in the CoffeeMud `newInstance()` method as shown here:
    function newInstance()
    {
     var lemm=this.super$newInstance();
     lemm.setName("a generic lemming");
     lemm.setDisplayText("a generic lemming is waiting to commit suicide");
     return lemm;
    }
There are several interesting points to make here. One is to notice that the function has no explicit return type, which is part of the JavaScript standard of being "weakly typed". Also notice the syntax for calling the SuperClass version of the `newInstance()` method -- `this.super$newInstance()`. This is very different from Java syntax and should be noted. And now we move on to overriding our first GenMob method, tick.
    var countdown = 10;

    function tick( host, tickID )
    {
     if( !this.amDead() )
     {
     countdown--;
     if( countdown <= 0 )
     {
     lib.combat().postDeath( null, this, null );
     countdown = 10;
     }
     }
     return this.super$tick( host, tickID );
    }
The `public boolean tick(Tickable host, int tickID)` method from the standard MOB interface is designed to be called every CoffeeMud tick (about 4 seconds). Now, the tick method in StdMOB, which is extended by GenMob, handles things like recovering hit points, automatic combat rounds, and other important periodic activities. It is explained further in Core Topic 3. For our GenLemming, we create a variable to count down the ticks from 10 to 0. When the countdown variable reaches 0, we call the `postDeath(MOB killer, MOB killed, CMMsg msg)` method, which is part of the CombatLibrary in the core libraries. "lib" is the variable we defined above as a shortcut to our core libraries. The last thing we do is return control to the SuperClass version of the tick method. Now we'll get creative and implement a message previewer (see the Core Topic 1 below for more information on message previewing and handling). This method will be called when any event happens in the same room as the GenLemming mob. We will use this fact to look for, capture, and modify the message string which will inform the room of our impending death. Since it is the previewing method, it will be called BEFORE the activity actually takes place, giving us a chance to make our modifications before anyone actually sees the message strings.
    function okMessage(host,msg)
    {
     if( ( msg.isSource( this ) )
     &&( msg.isOthers( "DEATH" ) )
     &&( msg.othersMessage() != null )
     )
     {
     msg.setOthersMessage("<S-NAME> jumps off a cliff!!!");
     }

     return this.super$okMessage(host,msg);
    }
In our message previewing method, we will check every message that comes our way, acting only if this particular GenLemming is the source of the message, that he appears to be dying to others in the room `( isOthers( "DEATH" ) )` and that the message being given to others in the room is a non-null string. In these conditions, we modify the message which others in the room see. When our condition is not met, we return control to the SuperClass-GenMob version of okMessage. ## Core Topic 1: Getting the Message: CoffeeMud is essentially a distributed message passing and handling system, where the actions and events that occur in the system are represented as messages (Common.interfaces.CMMsg) which are then previewed, modified, cancelled, and/or reacted to by handlers. Understanding this idea is key to fully understanding how CoffeeMud really works, so let's take a second and peruse this concept in more detail. Messages in CoffeeMud, at least as we are talking about them here, always represent Events. Events such as a mob picking up an item, swinging a sword at an opponent, taking damage from a fireball, or getting pricked by a poisonous needle. These events can never actually occur in CoffeeMud unless a proper message is generated for them first. These messages, in the code, implement the interface `Common.interfaces.CMMsg`, and are typically an instance of the class `Common.DefaultMessage`. Messages are created at the moment that the event needs to occur. This moment can be triggered by the player entering a command into their telnet client and pressing Enter. It can also by triggered by the mindless algorithms which animate the mobs. Either way, when the moment has come, a message is created, and it looks like this:
    CMMsg msg = CMClass.getMsg(mob, targetMOB, this,
     CMMsg.MSG_CAST_ATTACK_VERBAL_SPELL,"^S<S-NAME> invoke a spell at <T-NAME>s feet..^?",
     CMMsg.MSG_CAST_ATTACK_VERBAL_SPELL,"^S<S-NAME> invoke(s) a spell at your feet.^?",
     CMMsg.MSG_CAST_ATTACK_VERBAL_SPELL,"^S<S-NAME> invokes a spell at <T-NAME>s feet.^?"
     );
The above message was taken from the code for the Grease spell, which calls the `core.CMClass.getMsg` method to construct a CMMsg object. Constructing the CMMsg object does not actually make anything happen, but it is the vital first step. The message we constructed here, in this case, utilizes every major component of a message. These components are, in order: Source The source of any message must always be a valid reference to an instance of the MOB interface. In short, all events that occur in the system are a direct result of the activity of a MOB. This is on the theory that the universe is controlled and governed by sentience. In the extremely rare instances where a mob is not readily available to provide a message source, one should be instantiated -- even if it is just a blank, new StdMOB. Target The target of a message may be null, or any valid reference to an instance of the Environmental interface, which includes Items, MOBs, Rooms, Exits, etc. The type and context of message you wish to generate will typically tell you intuitively whether the source is doing something to someone or something else, or is acting independently. This is usually another mob or an item, but you will find examples of all kinds of targets in the code. Tool The tool of a message may be null, or any valid reference to an instance of the Environmental interface, which includes Items, Abilities, MOBs, Rooms, Exits, etc. The tool represents something which the source is utilizing to accomplish the task or generate the event. This is typically either an Ability object (like a Spell or Skill being used), or an Item object (like a weapon in an attack event). Source Code This is an encoded integer which represents what the source MOB is actually doing. We'll break down this code below. Source Message This is the string which the source MOB will see should the event occur successfully. Target Code This is an encoded integer which represents what is happening to the target. If there is no target, this number will typically have the value of 0 (CMMsg.NOEFFECT). Target Message This is the string which the target MOB (if it is a MOB) will see should the event occur successfully. If there is no target, this string is null. Others Code This is an encoded integer which represents how any other objects (such as MOBs, Items, Rooms, Exits) other than the source and target, in the same room, perceive the event. If the event is completely imperceptible by anything other than the source, it may be 0 (CMMsg.NOEFFECT) Others Message This is the string which other MOBs in the same room as the source and target MOBs will see should the event occur successfully. If the event is completely imperceptible by other MOBs, it may be null. The Source Code, Target Code, and Others Code is easily the most complicated aspect of a Message. For this reason, numerous pre-configured message codes have been created in the CMMsg interface, all of which begin with the characters MSG_. Although we will not go into the meaning of each of these messages (that will be left to the reader to search the code for instances of messages which use the codes, and learn from the context in which they are used), we can at least break down these codes so that they can be better understood. These coded integers all have two parts, the Major aspect (or the Major Code) and the Minor aspect (or the Minor Code). They may be referenced off of an already constructed CMMsg object using such methods as `sourceMajor()` and `sourceMinor()`. These methods will automaticallyy break down a `sourceCode()` into the components we will discuss. The Major code is a series of significant bits in the integer, each of which gives some new meaning to the message. These bits are as follows:
Bit mask | CMMsg Equate Variable(s) | Meaning
--- | --- | ---
2048 | MASK_HANDS | Message includes small movements.
4096 | MASK_MOVE | Message includes large, full-body movements.
8192 | MASK_EYES | Message includes visual information.
16384 | MASK_MOUTH | Message include mouth movement, or consumption.
32768 | MASK_SOUND, MASK_SOUNDEDAT | Message includes auditory information.
65536 | MASK_ALWAYS | Override mask which flags the message as something which Must occur, regardless of the state of the source or target.
131072 | MASK_MAGIC | Message has a magical nature.
262144 | MASK_DELICATE | Message includes very fine, delicate movements, such as thief skills.
524288 | MASK_MALICIOUS | Message represents an attack of some sort.
1048576 | MASK_CHANNEL | Message is part of public channel conversation.
2097152 | MASK_OPTIMIZE | Message implementation should be optimized for repetition.
4194304 | MASK_CNTRLMSG | Message implementation is entirely internal system message.
8388608 | MASK_INTERMSG | Message denotes an action that is part of a final larger action.
The above masks can be quite confusing. It is best to examine the several MSG_ equates in the CMMsg interface to see how they are properly or improperly used. Remember a MSG_ equate is a completely constructed Code, complete with the appropriate Major and Minor aspects. The Minor Code represents the more specific activity being performed, and is a simple integer ranging from 0 (NO EFFECT) to 2047. The officially recognized Minor codes are exhaustively listed in the CMMsg interface, and all begin with the prefix TYP_. These types cover every sort of major event which occurs in the CoffeeMud engine, including getting items, casting spells, entering or leaving rooms, etc, etc..
    CMMsg msg = CMClass.getMsg(attacker,target,weapon,CMMsg.MSG_WEAPONATTACK,
     "<S-NAME>attack(s) <T-NAME>!");
The core.CMClass has many different getMsg signatures to make message construction quick and painless. The above is an example where only a single Code and a single message text are provided. In constructors where only one Code or message text field are provided, it is assumed that the code and message texts will be the same for source, target (if any) and others. CMMsg objects also have `value()` and `setValue(int)` methods for modifying an integer not found in the constructor. This number is used for several different purposes in message construction, from the amount of damage in a TYP_DAMAGE message, to the amount of experience in a TYP_EXPCHANGE message. This number is also used to determine whether or not a standard saving throw was made. Value defaults to 0, but, after running through a message which contains a savable event, the value will be >0 if the save was made. ### Message Previewing Once a Message has been constructed, it is time to actually put the message out into the system. There is a standard form for the sending of almost all messages. If the source of the message is a MOB called "SourceMOB", this standard form looks like this:
    CMMsg msg = CMClass.getMsg(SourceMOB,TargetMOB,weapon,CMMsg.MSG_WEAPONATTACK, "<S-NAME>attack(s) <T-NAME>!");

    if(SourceMOB.location().okMessage(SourceMOB,msg))
    {
     SourceMOB.location().send(SourceMOB,msg);
    }
The `location()` field on a MOB refers to the Room in which the mob is. Room's are always the top level at which messages are previewed, and then executed or sent. The first line (where the message is constructed) has already been examined. The second line, in which the Room method `okMessage()` is called, is the preview step. In this step, the message is evaluated before it actually happens. The first parameter to `okMessage()` is called the "host" object, and it refers to the object to which the one you are sending the message should refer back to. This parameter is rarely used, except by Behaviors, and it is always safe to use the source of your message as this value. The second parameter to `okMessage()` is the message we constructed. The third line, where the Room `send()` method is called, is the execution step. In the preview step, the room object will examine the message to see if there is anything which it might not like, wish to modify, or wish to flag about the Message it has been handed. If the Room object does not like the message, it will return false. Returning false from `okMessage()` is always an order to cancel, and not execute the message. Under any other circumstances, true may be returned to allow the message to go forward. The Room will also make calls to the `okMessage()` methods on every other MOB in the room, Exit from the room, Item in the room, spell effects which may be on the room, and behaviors of the room. The MOB who receives the `okMessage()` call will, in turn, pass the Message to the `okMessage()` methods in every Item the MOB is carrying or wearing, every spell effect on the MOB, and every behavior of the MOB. Items wills also make `okMessage()` calls on their spell effects. Any of these calls may modify or flag the message they receive. Any of these calls may also return false. If any object which previews a message returns false, the Room `okMessage()` method will also return false, ordering the message to be totally canceled. For this reason, `okMessage()` methods are careful about returning true unless they have a really good reason not to. Inside the `okMessage()` methods of every Item, MOB, Behavior, Ability (spell effect), Exit, and Room the Messages may (as we mentioned) be examined and modified, flagged, or canceled. As we have already covered how Messages are canceled (by returning false). Let us turn now to the manner in which Messages are modified or flagged. ### Message Flagging and Modification Message modification is very rare. When it happens though, it is done by calling one of the several `modify()` methods on the Common.interfaces.CMMsg object. These methods allow the source, target, and all other fields to be updated. Message modification should also happen during the preview step so that any changes made to the message are made before the message is executed. It is also often wise, after making a change to a message, to recursively call the okMessage method on the room again so that the modifications can be previewed, but this is not always necessary. Message flagging is somewhat less rare. Messages may be flagged when a combat strike is successful, or when a saving throw is made against a spell Effect, or for any other reason the Message constructing code may wish. Flagging is done by calling the aforementioned `CMMsg.setValue(int)` method, and using it to change the value to something other than the default of 0. Flagging using the `setValue()` method lets the code which constructed the Message know that something significant with relation to the Message has occurred. The meaning of this value will vary depending upon the type of message being generated, and upon the purpose to which the creator of the message wishes to put it. The value is read using the `int value()` method on CMMsg. ### Message Execution Once the `okMessage()` method on a Room object has returned true, and any code which may need to check or handle modifications to the Message have executed, the Message is sent. The proper way to send a Message is through the Room objects, by calling one of the following Messages: `Room.send(MOB SourceMOB, CMMsg msg)` or `Room.sendOthers(MOB SourceMOB, CMMsg msg)`. The first method handles a standard Execution, while the second allows every relevant object except the SourceMOB to handle Execution. The first method should almost always be called. The `send()` methods will then begin calling other methods in other objects. These other methods are called the `executeMsg()` methods, and are usually of the form `public void executeMsg(Environmental myHost, CMMsg msg);`. These methods are responsible for Executing the contents of the message. The Room method will make `executeMsg()` method calls on itself, and on every Exit, Item, MOB, spell effects (Ability object), and Behavior associated with that Room. As in the `okMessage()` case, the MOBs will in turn call the `executeMsg()` methods on their own Items and spell effects. Items will then call the `executeMsg()` methods on their own spell effects, and so on. Of course, not every object in your game will handle and react to the Execution of every Message sent. Most of the time, a given object will be ignoring the Message altogether. However, each object knows precisely which Messages are important for it, and watch carefully for them in both their `okMessage()` and `executeMsg()` methods. In general, every Message which is previewed in an objects `okMessage()` method is handled in the `executeMsg()` method of the same object, though this is by no means always true. In general, the following object types handle the following types of Messages: MOBs Any Message which has the mob instance as a target is both Previewed and Executed. Any Message which has the mob as a source is typically Previewed, and (lacking a target) may also be Executed. Items Any Message which has the item instance as a target. Exits Any Message which has the exit instance as a target or tool. Rooms Any Message which has the room instance as a target. Ability(spell effects) Any Message pertaining to the MOB or Item which is affected by the spell or skill. Behavior Any Message pertaining to the object instance which has this behavior. Now that you are completely confused, it will make you at least a bit happier to know that Room objects have several short-cut methods for creating, previewing, and executing messages. They include the following:
    public boolean show( MOB source,
     Environmental target,
     int allCode,
     String allMessage
     );

    public boolean show( MOB source,
     Environmental target,
     Environmental tool,
     int allCode,
     String allMessage
     );

    public boolean show( MOB source,
     Environmental target,
     Environmental tool,
     int srcCode,
     int tarCode,
     int othCode,
     String allMessage
     );

    public boolean show( MOB source,
     Environmental target,
     Environmental tool,
     int srcCode,
     String srcMessage,
     int tarCode,
     String tarMessage,
     int othCode,
     String othMessage
     );

    public boolean show( MOB source,
     Environmental target,
     Environmental tool,
     int allCode,
     String srcMessage,
     String tarMessage,
     String othMessage
     );

    public boolean showOthers( MOB source,
     Environmental target,
     int allCode,
     String allMessage
     );

    public boolean showOthers( MOB source,
     Environmental target,
     Environmental tool,
     int allCode,
     String allMessage
     );

    public boolean showSource( MOB source,
     Environmental target,
     int allCode,
     String allMessage
     );

    public boolean showSource( MOB source,
     Environmental target,
     Environmental tool,
     int allCode,
     String allMessage
     );

    public void showHappens(int allCode, String allMessage);

    public void showHappens( int allCode,
     Environmental like,
     String allMessage
     );
The first methods (show) is very commonly used; it constructs a message with the given source and target (no tool), and with the given Code and text message applying to source, target, and others. The `showHappens()` methods will do the same, but will also construct a blank MOB object to act as the source, for those instances where a source MOB is not readily available. The `showOthers()` methods behave like the first, but do not allow the source MOB to preview or execute the message, while the `showSource()` methods ONLY allows the source MOB to preview and execute the message. All four of those methods will construct a CMMsg object, give the Message to the Room object for previewing ("okMessage"), and then, if the Message is not canceled, will call the Room "send" method for execution and return true. If the Message was canceled, false will be returned. ### Message Trailers The final subject we will discuss in the area of Messages and Message handling regards another rare technique called Message Trailer adding. Message Trailers are CMMsg objects which have been added to another CMMsg instance using the `CMMsg.addTrailerMsg(CMMsg msg)` method. The Message passed to this method is constructed in the usual way. This method may be properly called at any point during the Preview or Execution stage of Message handling, by any Previewing or Executing object. When it is performed is not important, because any Messages added using this method are not Previewed or Executed until after the Room object has completely finished sending the host Message to all interested objects. Constructing and adding messages which act as message trailers can serve many purposes, but the most important of which is that the trailer messages only happen IF the host message also happens, and only happen AFTER the host message happens. This can be useful for the timing of subsequent messages which are dependent on others. ## Core Topic 2: The State of Things: In most systems, it is typical for all of the data variables which describe a particular object to be coded directly inside that object. While this is also true in CoffeeMud, many important data fields, along with the appropriate "getter" and "setter" methods, are stored in separate special data-storage, or state objects. These data-storage objects provide access to numerous important properties for those objects. These storage/state objects are routinely copied and then the copies are modified by other objects which have a spacial relationship with them. For instance, a MOB object may copy one or more of its state objects, and then allow the local Room object, or his inventory Item objects, or spell Effect objects to modify the copy, The copied state object modifications are stacked on each other. Confused? Well, keep reading! Each instance of the several Physical objects (MOBs, Items, Exits, Rooms) have a particular storage/state object called their Physical Stats. This object implements the Common.interfaces.PhyStats interface, and is typically an instance of the Common.DefaultPhyStats class. Access to this state object is available through each core.interfaces.Physical objects `PhyStats basePhyStats()` and `PhyStats phyStats()` method calls. Since Rooms, MOBS, Items, Exits, and Areas are all Physical objects, that means that they all have basePhyStats and phyStats methods as well. ### PhyStats state object fields
Field name | Relevant objects | Meaning
--- | --- | ---
level | Item, MOB, Exit | Experience level (see Archon's Guide)
ability | Item, MOB | Magical level (see Archon's Guide)
rejuv | Item, MOB | Rejuvenation rate (see Archon's Guide)
weight | Item, MOB | Weight of the object
height | Armor, MOB | Size of the object
armor | Item, MOB | Protection level (see Archon's Guide)
damage | Item, MOB | Damaging ability
speed | Item, MOB | Attack speed
attackAdjustment | Item, MOB | Attack level
replacementName | Item, MOB, Exit | New displayable name of the object
sensesMask | Item, MOB, Exit, Room | Bit mask of relevant sensory abilities.
disposition | Item, MOB, Exit, Room | Bit mask of relevant disposition state
Although most of these fields are better described in the Archon's Guide, there are two whose nature may not be readily apparent: the sensesMask and the disposition. These two integers are bitmaps. The value of each bit is defined by equates in the Common.interfaces.PhyStats interface. The equates which refer to the bits for sensesMask all begin with "CAN_" for MOBs or "SENSE_" for non-MOBs, while the equates which refer to the bits for disposition all begin with "IS_". Now, as mentioned previously, all Physical objects have two methods for accessing their PhyStats. One is `core.interfaces.Physical.basePhyStats()` and the other is `core.interfaces.Physical.phyStats()`. The difference between these two methods is very significant. The PhyStats state object returned by the "basePhyStats" method refers to the permanent, unmodified, "base" state of the Physical object. The "phyStats" method, however, returns the modified, less permanent, "current" state of the Physical object. The PhyStats object returned by the "phyStats" method is always copied and derived from the "basePhyStats" values, after all relevant modifications have been made to it. How the current state object goes from its base values (basePhyStats) to its current values (phyStats) is our next topic. We must now introduce two other Physical interface methods significant to this topic. One is the `recoverPhyStats()` method, while the other is the `affectPhyStats(Physical affected, PhyStats affectableStats)` method. The "recoverPhyStats" method is also located on every Physical (Item, MOB, Exit, etc) object and is the method which turns the `basePhyStats()` values into their current `phyStats()` values. This method call works by copying the base values into the current values and then allowing certain other objects to have an opportunity to affect the copy. Only after all opportunities to modify the copied values have been exhausted, does the `recoverPhyStats()` method return. In essence, `recoverPhyStats()` allows the Physical objects `basePhyStats()` to be updated, with that updated state object made available through `phyStats()`. The way in which the current PhyStats state object is modified by the `recoverPhyStats()` method call is by making repeated internal calls to the `affectPhyStats(Physical affected, PhyStats affectedStats)` methods on other relevant objects. These methods will then have the opportunity to change the values in the current state object (affectedStats parameter) however they wish. The relevant objects which may change the state of an Physical are as follows: MOBs Room object being occupied, something being Ridden, the MOBs Character Class object, the MOBs Race object, the Items in the MOBs inventory, and finally the Ability objects which are affecting the MOB (spell effects). Items, Exits, Areas Ability objects which are affecting it (spell effects). Rooms Area object which this room is a part of, Ability objects which are affecting it (spell effects), Items in the Room, and MOBs in the Room. Here is an example: Gunker the Thief wears Full Plate Armor (Item), and has the Shield spell cast on him. His base Armor rating is 100. When he puts on the Plate Armor, the "recoverPhyStats" method is called on Gunker's MOB object. That method in turn calls the "affectPhyStats" method on the Plate Armor and the Shield spell Effect. Both of those methods improve the Armor rating on Gunker's MOB's current PhyStats by some number. Thus, Gunker becomes harder to hit in combat. Also, when Gunker picked up the Plate armor, the weight of the armor was added to Gunker's overall carried weight by increasing the weight value in Gunker's PhyStats object. I know, this is probably still confusing. Confusing or not, however, we still have to consider two other state objects, both of which are only available from the MOB object. One of which is the CharStats object, and the other of which is the CharState object. The CharStats objects are most closely analogous to the PhyStats objects. For instance, there are `CharStats baseCharStats()` and `CharStats charStats()` method calls from a MOB object, as well as a `recoverCharStats()` method call. All of these work similarly to the ones described above for PhyStats. The fields on a Common.interfaces.CharStats object are somewhat more straight forward however. Most of the fields of a CharStats object are referenced using the `int getStat(int)` and `setStat(int,int)` methods on a CharStats object. Both of these methods require, as their first parameter, an integer code which corresponds to the specific stat being set or read. These stat parameters are defined as equates within the CharStats interface, and include: STAT_STRENGTH, STAT_INTELLIGENCE, STAT_DEXTERITY, STAT_CONSTITUTION, STAT_CHARISMA, STAT_WISDOM, STAT_GENDER, STAT_SAVE_PARALYSIS, STAT_SAVE_FIRE, STAT_SAVE_COLD, STAT_SAVE_WATER, STAT_SAVE_GAS, STAT_SAVE_MIND, STAT_SAVE_GENERAL, STAT_SAVE_JUSTICE, STAT_SAVE_ACID, STAT_SAVE_ELECTRIC, STAT_SAVE_POISON, STAT_SAVE_UNDEAD, STAT_SAVE_MAGIC, STAT_SAVE_DISEASE, STAT_SAVE_TRAPS, STAT_MAX_STRENGTH_ADJ, STAT_MAX_INTELLIGENCE_ADJ, STAT_MAX_DEXTERITY_ADJ, STAT_MAX_CONSTITUTION_ADJ, STAT_MAX_CHARISMA_ADJ, STAT_MAX_WISDOM_ADJ, STAT_AGE, STAT_SAVE_DETECTION, STAT_SAVE_OVERLOOKING. In addition to these equates defined and read through the `getStat()` and `setStat()` methods, there is also the Race object available through `getMyRace()` and `setMyRace()` methods, as well as Character Class and Character Class level methods. See the Common.interfaces.CharStats java file for more information on those methods and how they work. Like the PhyStats above, those objects listed as able to modify the PhyStats current state object are the same objects which are able to modify the CharStats state objects. Rereading the section on PhyStats will make clear how the CharStats objects are modified in the same analogous manner, using repeated calls to`affectCharStats(MOB affected, CharStats affectedStats)` methods on related objects. The last state object to consider is the Common.interfaces.CharState objects on MOBs. The CharState object represents those fields which are constantly in flux: Hit Points, Mana, Movement, Hunger, Fatigue, and Thirst. Unlike PhyStats and CharStats, there are three CharState objects to consider for MOBs: the base CharState object (available through `CharState baseState()` method, the adjusted base CharState (or max state) object available through the `CharState maxState()` method and modified by `recoverMaxState(MOB affected, CharState affectedState)` methods on related objects, and lastly the current CharState object available through the `CharState curState()` and refreshed or reset to maximums using the MOBs `resetToMaxState()` method. The relationship between the above objects is as follows: The base CharState object represents the maximum values for the state variables BEFORE modification by magical armor or spells. The adjusted base CharState object (Max State) represents the maximum values for the state variables AFTER modification by magical armor or spells. The current CharState object (curState) represents the current hit points, mana points, etc available to the MOB. In the case of the CharState objects, adjustment by relevant objects is initiated by calling the MOBs `recoverMaxState()` method. This method allows the same objects who modify the PhyStats and CharStats above to modify the maximum CharState values as well. Once again, to understand one of them fully is to understand them all. ### Core Topic 3: Tick Tock Our next Core Topic will cover the ability of the mobs, items, exits, abilities, spell effects, behaviors, and other objects to perform tasks on a regular, timed, basis. The tasks to be performed are always located within an method called `boolean tick(Tickable ticking, int tickID)`. All Environmental objects define this method, and Behavior objects do as well. These methods are called on a regular, timed basis whenever the object instance in question has been properly set up to do so, and at a defined frequency and interval. The "ticking" parameter is usually a reference to the object itself, or to the host object in the case of Behaviors. The "tickID" parameter describes what sort of regular timed event is occurring. These events are defined as equates in the core.interfaces.Tickable interface, and include IDs such as TICKID_MOB, TICKID_AREA, TICKID_EXIT_REOPEN and others. See the java file of that interface for more defined tickID values. Before we get into the methods by which an object instance are properly set up for regular calls to its `tick()` method, it may be worthwhile to discuss which regular ticks are setup by the system by default. These tick events cover the most commonly used objects under the most common circumstances, and so may be just the events you already needed! They include: MOBs All MOBs have their `tick()` method called once per CMProps.getTickMillis() (4 seconds), with the "tickID" defined by Tickable.MOB_TICK. MOBs will, in turn, call the `tick()` methods on their own Behaviors, and Ability objects affecting them. If any of these dependent objects return "false" from their own tick methods, then the object will cease to receive any further tick method calls. Exits, Items, Rooms Whenever a Behavior is added to any of these objects, they will begin to have their tick methods called once per CMProps.getTickMillis() (4 seconds), with the tickID defined by Tickable.TICKID_ITEM_BEHAVIOR, TICKID_EXIT_BEHAVIOR, or TICKID_ROOM_BEHAVIOR. Deletion of the last behavior from the host object will stop this tick event from occurring again. Areas All Area objects have their tick methods called once per CMProps.getTickMillis(), with the tickID defined by Tickable.TICKID_AREA. Ability Whenever an Ability object is added as an Effect (using the `addEffect()` Physical method) to a non-MOB object by using the proper Ability invoke procedure (see below), then the Ability object itself will gain it's own regular calls to its tick method. The tickID for this call is also Tickable.TICKID_MOB, so as to make consistant the tickID for all spell and similar effects. To sum up, MOBs have regular tick calls which they use to perform their own periodic tasks, as well as to allow their Behavior and spell effects to perform tasks. The other objects have circumstantial ticks in certain instances. Now, to add a new periodic call to the "tick" method on an Environmental object, one needs only to make a method call like this:
    CMClass.threads().startTickDown(theEnvObject,Tickable.MY_TICK_ID,CMProps.getTickMillis(),NUM_TICKS);
The second parameter is the tickID which will be used when the `tick()` method on the "theEnvObject" object is called. The third parameter is the time interval, in milliseconds, between each event. The fourth parameter is the number of time intervals between each call to the `tick()` method. The total time between each call to the `tick()` method, therefore, will be CMProps.getTickMillis() * NUM_TICKS. Now, the above version of `startTickDown()` can be used to create timed events of any duration. However, all objects in the base distribution of CoffeeMud operate on a single default time interval, usually of 4000 milliseconds, as defined by CMProps.getTickMillis() and ultimately from the coffeemud.ini file. For this reason, a different version of the `startTickDown()` method is called which does not include the time parameter, utilizing the standard delay instead:
    CMClass.ThreadEngine().startTickDown(theEnvObject,Host.MY_TICK_ID,NUM_TICKS);
Stopping any of these tick calls can be done by simply returning "false" from the tick method itself, or manually using the following:
    CMClass.ThreadEngine().deleteTick(theEnvObject,Host.MY_TICK_ID);
You may also stop tick calls to an object by using the Environmental objects `destroy()` method. ## Core Topic 4: Core Libraries The CoffeeMud engine contains numerous Java classes whose purpose is to perform much of the underlying game functionality. Some of these Java classes are Core classes, some are Library classes, and some are Common classes. Core classes are those classes found in the com.planet_ink.coffee_mud.core package. Like the interfaces, they may not be extended or overwritten without risking problems. The core classes, and their general purpose is:
Core Class Name | Purpose
--- | ---
B64Encoder | Encode and decode text<->binary using Base64
CMath | Converting strings to numbers, performing bit-wise and other arithmetic operations
CMClass | Main ClassLoader -- get all your objects from methods here!
CMFile | FileSystem manager, get all your file data from this class
CMLib | The non-core library reference object. * See below for more information.
CMParms | Methods for parsing strings and determining parameter values in many different ways.
CMProps | Properties manager, for reading INI file values from coffeemud.ini and other places.
CMSecurity | The security manager, for evaluating player and system security flags.
CMStrings | Methods to manipulate, pad, and filter strings.
Directions | Methods to handle the different compass directions.
Log | The file and console logging manager.
MiniJSON | A JSON text document parser
Resources | The object-resource manager, usually with lots of StringBuffers keyed by String names.
You should check out the javadocs for those classes for more information on the core classes. * CMLib also refers to some of the sub-core classes, such as the Database access objects, and the Threading engine. While they are considered core, they are accessed through CMLib as if they were non-core libraries. Most core classes can also be accessed through CMLib methods, making it a one-stop shop. Now, non-core libraries, or Libraries proper, are located in the com.planet_ink.coffee_mud.Libraries package, and each one implements a unique interface from the com.planet_ink.coffee_mud.Libraries.interfaces package. This is unique, that each class in the Libraries package implements a unique interface all its own, but that is not the only unique thing about this package. Libraries are also singletons -- there is never more than 1 instance of each Library. Moreover, these singletons are all accessed from a single accessor class, CMLib, which we mentioned earlier. Here is a map of how the classes, interfaces, and CMLib methods are all mapped together:
Library class name `...Libraries.*` | Library interface name `...Libraries.interfaces.*` | CMLib method name `...core.CMLib` | Purpose of the Library
--- | --- | --- | ---
AutoTitles | AutoTitlesLibrary | `titles()` | Automatic player vanity titles
Achievements | AchievementLibrary | `achievements()` | Player achievments system
BeanCounter | MoneyLibrary | `beanCounter()` | Handle money and currency.
CharCreation | CharCreationLibrary | `login()` | Login and create new players.
Clans | ClanManager | `clans()` | Handle all clans.
CMAbleMap | AbilityMapper | `ableMapper()` | Maps CharClasses to Skills/Abilities.
CMAbleComps | AbilityComponents | ableComponents() | Manages Skill Components
CMAbleParms | AbilityParameters | ableParms() | Editors for Ability recipes/parms
CMCatalog | CatalogLibrary | catalog() | Manages cataloged mobs and items
CMChannels | ChannelsLibrary | `channels()` | Handles public channels.
CMColor | ColorLibrary | `color()` | ANSI and color code conversions.
CMEncoder | TextEncoders | `encoder()` | Compression library.
CMJournals | JournalsLibrary | `journals()` | Handles public journal commands.
CMGenEditor | GenericEditor | genEd() | Command Line editing prompts
CMLister | ListingLibrary | `lister()` | Handles listing tables nicely.
CMMap | WorldMap | `map()` | Find areas and rooms.
CMPlayers | PlayerLibrary | `players()` | Manage player lists
CoffeeFilter | TelnetFilter | `coffeeFilter()` | Filters/transforms text going to and from a player.
CoffeeLevels | ExpLevelLibrary | `leveler()` | Leveling and Experience gaining functionality.
CoffeeMaker | GenericBuilder | `coffeeMaker()` | Generic Mob/Item and CoffeeXML generators.
CoffeeUtensils | ProtocolsLibrary | `protocol()` | Special protocol support: MSP, MXP, MSDP, GMCP.
CoffeeShops | ShoppingLibrary | `coffeeShops()` | Handles manipulation of shop inventories.
CoffeeTables | StatisticsLibrary | `coffeeTables()` | Maintains player usage stats.
CoffeeTime | TimeManager | `time()` | Real-life date/time display.
CoffeeUtensils | CMMiscUtils | `utensils()` | Misc stuff-- law, traps, titles, resets.
ColumbiaUniv | ExpertiseLibrary | `expertises()` | Handle ability expertise lists
CommonMsgs | CommonCommands | `commands()` | Methods for getting, talking, common-stuff
Dice | DiceLibrary | `dice()` | Random number generator.
DirtyLanguage | LanguageLibrary | `lang()` | Handle hl translation rules
EnglishParser | EnglishParsing | `english()` | Player command line parsing helpers.
Factions | FactionManager | `factions()` | Handles the factions and faction system.
GroundWired | TechLibrary | tech() | Handles tech and spacy stuff.
MUDLaw | LegalLibrary | law() | Handles legal and property matters.
MUDFight | CombatLibrary | `combat()` | Combat and Death routines.
MUDHelp | HelpLibrary | `help()` | Handling help-file entries.
MUDPercolator | AreaGenerationLibrary | percolator() | Random area generation library.
MUDTracker | TrackingLibrary | `tracking()` | Methods for NPC movement, and for tracking.
MUDZapper | MaskingLibrary | `masking()` | Zapper-mask parsing and evaluation.
Polls | PollManager | `polls()` | Handle the public polls.
Quests | QuestManager | `quests()` | Quest Manager system.
RawCMaterials | MaterialLibrary | materials() | Manipulate/Create raw resource objects
Sense | CMFlagLibrary | `flags()` | Sensory and Disposition bitmap/flag handling.
Sessions | SessionsList | `sessions()` | Container for player connection objects.
SlaveryParser | SlaveryLibrary | `slavery()` | Geas and Slavery order parsing and execution.
SMTPclient | SMTPLibrary | `smtp()` | E-Mail sending routines.
Socials | SocialsList | `socials()` | Socials container and parser.
StdLibrary | NONE | NONE | SuperClass of other libraries.
TimsLibrary | ItemBalanceLibrary | `itemBuilder()` | Methods for normalized item evaluation.
WebMacroCreamer | WebMacroLibrary | `webMacroFilter()` | Web Server extension for cmvp files.
XMLManager | XMLLibrary | `xml()` | General XML parsing.
Libraries are lastly unique in that it is almost useless to write new ones, unless you are doing the most serious additions and enhancements to your system. However, they are designed especially so they they can be extended and overridden. They have their own entry in the coffeemud.ini file called LIBRARY. By writing classes that extend the base CoffeeMud library classes, and overriding their methods, you can make changes to the most basic CoffeeMud algorithms, even at run-time! Libraries also have an entry in the coffeemud.ini file, LIBRARY, so that you can specify your custom extended versions of them after the %DEFAULT% string, thus allowing your changes to be loaded at boot-time. The last set of classes to discuss under this topic are neither Core class or Libraries, but form parts of the cores of other classes, including many of the Libraries. These are the Common classes. They are part of the com.planet_ink.coffee_mud.Common package. Like the Libraries, they each implement their own unique interface from the com.planet_ink.coffee_mud.Common.interfaces package. However, unlike the Libraries, numerous instances of each class will exist in your mud, and they are created from the core CMClass loader, much like MOBs, Items, Rooms, and so forth. The javadocs are also a good place to learn about these classes, but here is a brief list of them to wrap up our last Core Topic.
Common Class | Description
--- | ---
AuctionCoffeeShop | A special derivative of DefaultCoffeeShop for auctioneers
DefaultAbilityComponent | Describes a component needed to use a skill.
DefaultArrestWarrant | An object created every time a law is broken.
DefaultAuction | An object to store the state information about an ongoing auction.
DefaultAuctionPolicy | An object to grab and manipulate auction house policies, pricing, timing, etc
DefaultCharState | Contains a mobs hit points, mana, movement, fatigue, hunger, and thirst.
DefaultCharStats | Contains a mobs class, race, saving throws, and basic stat scores.
DefaultClan | Represents a single Clan.
DefaultClanPosition | A rank within a clan government.
DefaultClanGovernment | A clan government.
DefaultClimate | A single climatary system for a given area.
DefaultCoffeeShop | Represents a single shop store inventory.
DefaultCoffeeTableRow | Represents a days worth of game player usage statistics.
DefaultFaction | Represents a single faction.
DefaultHttpClient | Represents an internal http/web page getter.
DefaultItemCollection | Represents an external collection of standard Items
DefaultJournalEntry | Represents an entry in a journal.
DefaultLawSet | Represents a single set of laws and legal policies.
DefaultManufacturer | Represents a manufacturer of technical/electronic items.
DefaultMessage | A CoffeeMud event message (CMMsg).
DefaultPhyStats | Contains an objects attack bonus, armor bonus, weight, height, rejuv rate.
DefaultPlayerAccount | A characters base account, if the account system is used
DefaultPlayerStats | Represents player-specific fields like prompts, friends, alias, etc.
DefaultPoll | A single poll object.
DefaultQuest | Container for a single timed quest.
DefaultRoomnumberSet | Container for a players area visitation memory.
DefaultScriptingEngine | Engine for executing MOBPROG scripts and maintaining script variables
DefaultSession | Connection object for handling a players telnet session with the mud
DefaultSocial | Object for a single social command.
DefaultTattoo | Object for a named marker/flag with optional tick lifespan.
DefaultTimeClock | Object representing a single calendar/time system that spans areas, possibly the whole world.
FakeSession | A non-user Session, for snooping and user modeling
WeakItemCollection | A collection of items based on Weak java references
### Core Topic 5: Input Almost all user interaction with CoffeeMud begins and ends with the standard command line parser. However, from time to time, it may be important to prompt the player for further information, whether it be a name for their new frog, a confirmation that they really want a frog as a pet, or a set of one-letter options on what to do with the frog once they have it. To accomplish this purpose, there are several standard-issue methods on the Session object accessible from the player MOB to allow you to do this, some are old and bad, and some are new and better. Lets look at the old bad ones first, because it's important to understand them to know why they are bad:
    if(mob.session()!=null)
    {
      String s=mob.session().prompt("Enter a message number (1): ","1");
      if ((s.length()>0)&&(CMath.isInteger(s)))
      {
        if(mob.session().confirm("Are you sure you want to view message #"+s+" (Y/n)?","Y"))
        {
          mob.session().println("Here is message #"+s);
          // .... show them the message
          String choice=mob.session().choose("Would you like to D)elete or K)eep this message (d/K)?","DK","K");
          if(choice.equals("K"))
          {
            // .... delete the message
            mob.session().println("Message #"+s+" deleted.);
          }
        }
      }
    }
In the above example, we check to see if the session() method on the MOB object is non-null. This is important! All NPCs in your game will have a null-session(). Only players, who are also the only ones capable of responding to prompts, have a non-null session(). Next we prompt(..) the user for a message number. The first parameter to this method is the prompt to display, while the second parameter is the default response should the user just hit ENTER by itself. Next we ask the user to confirm(...) that they really want to view that message. The first parameter to confirm(...) is again the message to display, while the second is either "Y" or "N", meaning what the default is should the user just hit ENTER. Last we ask the user to choose(...) from among 2 options for dealing with the message, where the first parameter is again the message to display, the second parameter is a string containing all the one-letter choices available to the user, and the last parameter is the default should the user just hit ENTER. The above example represents the way all prompting has been done in CoffeeMud since 1.0. And it still works! However, it is a bad idea to call those methods, and it's important to know why. The reason has to do with threads. A thread represents your computer's opportunity to execute code in the computer; the more threads a program has, the more things it can do at once. Everything in CoffeeMud runs in threads. However, threads are expensive to have around, and fewer of them is better than more. For this reason, almost everything in CoffeeMud shares threads with everything else, which helps prevent the system from using too many or from running out of them. Sharing is good; once a piece of CoffeeMud is finished running, it hands its thread off to other parts of CoffeeMud. However, the three methods shown above ( prompt(String,String), confirm(String,String), and choose(String, String, String) ) do not share their thread with the rest of CoffeeMud. In fact, what happens when they execute is that the precious thread that is running that piece of code just sits around doing nothing until the user presses ENTER. This is *awful*. For this reason, a new method of prompting the user was added to the session() object to allow your Java to prompt the user without hogging the thread all to itself. So, let's look at a new example:
    final Session session=mob.session();
    if(session != null)
    {
      session.prompt(new InputCallback(InputCallback.Type.PROMPT,"1",0)
      {
        public void showPrompt() { session.printPrompt("Enter a message number (1): ");}
        public void timedOut() { }
        public void callBack()
        {
          if ((this.input.length()>0)&&(CMath.isInteger(this.input)))
          {
            final String messageNumber=this.input;
            session.prompt(new InputCallback(InputCallback.Type.CONFIRM,"Y",0)
            {
              public void showPrompt() { session.printPrompt("Are you sure you want to view message #"+messageNumber+" (Y/n)?");}
              public void timedOut() { }
              public void callBack()
              {
                session.println("Here is message #"+messageNumber);
                // .... show them the message
                session.prompt(new InputCallback(InputCallback.Type.CHOOSE,"K","DK",0)
                {
                  public void showPrompt() { session.printPrompt("Would you like to D)elete or K)eep this message (d/K)?");}
                  public void timedOut() { }
                  public void callBack()
                  {
                    if(this.input.equals("K"))
                    {
                      // .... delete the message
                      session.println("Message #"+messageNumber+" deleted.");
                    }
                  }
                });
              }
            });
          }
        }
      });
    }
The above code does exactly what the first block of code did, but does it without hogging any threads. It does it using a principle called "call backs", which you should look up online to learn more about. In this case, the new session.prompt(InputCallback) method is called with a customized inline java class of the abstract InputCallback class. You'll notice that the InputCallback constructor takes a InputCallback.Type as its first parameter, to tell what type of prompt it is, then it takes a default value, just like the old methods did, and he last parameter is a time, in milliseconds, before the prompt will time-out (we use 0 to prevent timeouts). The InputCallback.Type.CHOOSE constructor also accepted, just before the timeout value, the letters to choose from, just like in the old session().choose(..) method. In every case, the first thing that happens is that the InputCallback.showPrompt() method is called to display any necessary messages to the user. Then, the new session.prompt(...) immediately returns, allowing any code afterwards to immediately execute. However, the user must now enter something as well. After the user enters something valid, the InputCallback.callBack() method is called, and this.input will contain the information the user entered. Two things to bear in mind when working with these asynchronous user input prompts: one, any variables that are local to the surrounding method must either be final, or copied into final variables to be accessible in the callBack() methods below. Another thing is to always bear in mind that session().prompt(InputCallback) displays a message and returns immediately -- it does not block the thread like the other methods did. This last fact will play with your mind and mess up your coding if you aren't careful. ### Core Topic 6: Database Tables If all goes well, you will never ever have to care about this topic. CoffeeMud includes numerous ways to expand the data storage of its numerous objects without careing how or where it is being persisted. However, for the curious or those who enjoy danger, here is a description of the CoffeeMud Database Tables. By way of overview, the CoffeeMud database schema reflects the sharp turns in design that CoffeeMud has taken over the years. Originally, CoffeeMud games were meant to be built by coders writing Java objects. Since all the little details would be "stored" in java class files, that left very little for the actual database to persist. Mobs and Items in rooms would only have needed to persist little details that might differ from instance to instance, such as the simple Java Class name (what we still call the ID()), level, rejuvenation rate, a general numeric value (ability) that each java class can use for its own purposes, as well as a general string value (miscText) that they can use. The exception to this would be the players themselves, which would have lots and lots of database fields, since they would vary much more than mobs and items. Later, CoffeeMud was changed to be built online at runtime. Suddenly all the little details that were stored in Java had to be persisted to the database. This was accomplished by storing all of those details as an XML document in the same place that the general string value (miscText) was. Still, this left the system with relatively few tables with relatively few fields. The fact that all that XML data could not be queried was fairly unimportant. CoffeeMud loaded all of its data at boot-time, so that even the tables and relations, such as they were, were mostly unused after the boot completed. For a long time, things stayed this way. However, the day came when suddenly queries became important. Journals, forums, virtual filesystems, polls, "thin" areas, and backlogs all required the data to be pulled in on demand. The number of tables as well as the fields in existing tables began to modestly expand. Eventually the weight of new features whose data fit nowhere else caused the numer of tables to balloon to the current list. All the while, CoffeeMud tried to maintain compatibility, not only with fakedb, but with every other database, commercial or open source. Every database engine has its own standard table names, special column names, and so forth. Predicting when one column name would conflict with which database engine was a problem from the very start. Therefore, the database tables and colum names were given almost cryptic names in order to help eliminate the possibility of conflict. And that, my friends, is why the CoffeeMud database is the way it is. So, how is it? Let's look:
cmvfs | The Virtual (Database) File System storage. One row per file.
cmchab | Per-character reference for Abilities, and later Scripts, Effects and characterr Behaviors as well. One Char Ability per row.
cmchcl | Per-character reference for Clan membership and Role. One Char Clan Membership per row.
cmstat | Per-time-period (usually 1 day) collection of game statistics, for the STAT command and MUDGrinder game stats. One row per period.
cmpoll | The polls given to users at login. One Poll and their results per row.
cmchar | The main Character table. One row per Character.
cmchfo | Per-character followers table for the mobs following players around. One row per Char Follower.
cmchit | Per-character inventory table for the items mobs carry around and wear. One row per Char Item.
cmroch | Per-room mob table, for the mobs that start in each room. One row per Room MOB.
cmroex | Per-room exit table, for the exit objects from each room. One row per Room Exit.
cmroit | Per-room item object table, for the items sitting in each room. One row per Room Item.
cmroom | The main Room table. One row per Room. Also holds the entire catalog in special room ids.
cmquests | Quests table. One row per quest definition string, which can be a whole quest script or a reference to an external file.
cmarea | The Areas table. One row per Area.
cmjrnl | The Journals table, which is also for Forums, Command Journals, and Email. One row per forum message.
cmclan | Clan table. One row per Clan.
cmpdat | Originally Player Data, with one row per Player Section Key of data. Think bank accounts. Also holds clan data as well.
cmgrac | Generic Race table. One row per Race.
cmccac | Generic Character Class table. One row per Class.
cmgaac | Generic Ability table. One row per Ability.
cmacct | Common Account table, if you use that optional system. One row per player account.
cmbklg | Channels Backlog table. One row per Channel message.
cmclit | Clan Item table, for each clan item deposited in various areas. One row per room clan item.
CMCHAB
CMUSERID | Character name | CMABID | Ability ID / Behavior ID / Effect ID
CMABPF | Proficiency (MIN=script/behavior, MAX=effect) | CMABTX | Misc Text
CMCHAR
CMCHID | MOB class ID | CMUSERID | Character name
CMPASS | Password (encoded / hash) | CMCLAS | Char Class(es), ; delimited
CMSTRE | Base Strength | CMRACE | Race ID
CMDEXT | Base Dexterity | CMCONS | Base Constitution
CMGEND | Gender | CMWISD | Base Wisdom
CMINTE | Base Intelligence | CMCHAR | Base Charisma
CMHITP | Base Hit Points | CMLEVL | Class Level(s), ; delimited
CMMANA | Base Mana | CMMOVE | Base Movement
CMDESC | Description | CMALIG | (Unused -- replaced with Faction system)
CMEXPE | Experience Points | CMEXLV | Experience to next level
CMWORS | Deity name | CMPRAC | Practice Points
CMTRAI | Training Points | CMAGEH | Age in Hours
CMGOLD | Money, deprecated for Coin items | CMWIMP | Wimp Hit Point Level
CMQUES | Quest Points | CMROID | Current Room ID || Starting Room ID
CMDATE | Last login Date/Time | CMCHAN | Channels on/off bitmask
CMATTA | Base Attack | CMAMOR | Base Armor
CMDAMG | Base Damage | CMBTMP | MOB Attributes Bitmap (ansi, mxp, etc..)
CMLEIG | Leige/Lord Name | CMHEIT | Height
CMWEIT | Base Weight | CMPRPT | Prompt String (if custom)
CMCOLR | Custom Color strings | CMLSIP | Last login IP address
CMEMAL | Email Address | CMPFIL | All Player Stats as XML document
CMSAVE | Saving Throws stats ; delimited | CMMXML | All Factions and their values as XML document
CMCHFO
CMUSERID | Character name | CMFONM | Follower key (unique per char follower id)
CMFOID | MOB class ID for the follower | CMFOTX | Misc Text / GenMob XML
CMFOLV | Level | CMFOAB | Misc number / Ability
CMCHCL
CMUSERID | Character name | CMCLAN | Clan name
CMCLRO | Characters Role in the Clan | CMCLSTS | Character Clan Stats (kills, pvps, etc)
CMCHIT
CMUSERID | Character name | CMITNM | Character item key (unique per char item)
CMITID | Item class ID | CMITTX | Misc Text / GenItem XML
CMITLO | Container item key (matches CMITNM) | CMITWO | Worn code (if the item is being worn)
CMITUR | Uses remaining / Item condition | CMITLV | Level
CMITAB | Misc number / Ability | CMHEIT | Height (armor "size")
CMROCH
CMROID | Room ID | CMCHNM | Room mob key (unique per room mob)
CMCHID | MOB class ID | CMCHTX | Misc Text / GenMOB XML
CMCHLV | Level | CMCHAB | Misc number / Ability
CMCHRE | Rejuvenation (Rejuv) ticks | CMCHRI | Riding key (matched CMITNM or CMCHNM)
CMROEX
CMROID | Room ID | CMDIRE | Direction code
CMEXID | Exit class ID | CMEXTX | Misc Text / GenExit XML
CMNRID | Next Room ID (the one that this exit travels to from CMROID)
CMROIT
CMROID | Room ID | CMITNM | Character item key (unique per room item)
CMITID | Item class ID | CMITLO | Container item key (matches CMITNM)
CMITTX | Misc Text / GenItem XML | CMITRE | Rejuvenation (Rejuv) ticks
CMITUR | Uses remaining / Item condition | CMITLV | Level
CMITAB | Misc number / Ability | CMHEIT | Height (armor "size")
CMROOM
CMROID | Room ID | CMLOID | Room class ID
CMAREA | Area name | CMDESC1 | Room title
CMDESC2 | Room long description text | CMROTX | Room properties (behaviors, effects, etc) in XML
CMAREA
CMAREA | Area name | CMTYPE | Area class ID
CMCLIM | Climate code | CMSUBS | SubOp character names, semicolon delimited
CMDESC | Long description | CMROTX | Area properties (behaviors, effects, etc) in XML
CMTECH | Area theme code
CMJRNL
CMJKEY | Journal Message Key (unique per message) | CMJRNL | Journal name
CMFROM | Message sender | CMDATE | Message post date / time
CMTONM | Message receiver / ALL | CMSUBJ | Subject
CMPART | Parent message (if this is a reply / child message) | CMATTR | Attributes (protected, etc..)
CMDATA | Usually the journal name, not sure | CMUPTM | Last updated date / time
CMIMGP | Message image path | CMVIEW | Number of message views
CMREPL | Number of message replies / children | CMMSGT | Message text
CMCLAN
CMCLID | Clan name | CMTYPE | Unused, clan "type" code
CMDESC | Clan Description / Premise | CMACPT | Acceptance settings for application (Zapper Mask)
CMPOLI | Clan details (govt, relations, etc) as XML doc | CMRCLL | Clan recall room ID
CMDNAT | Clan donation room ID | CMSTAT | Clan status code (active or not, etc)
CMMORG | Clan morgue room ID | CMTROP | Clan trophies bitmask
CMCLIT
CMCLID | Clan name | CMITNM | Character item key (unique per char item)
CMITID | Item class ID | CMITTX | Misc Text / GenItem XML
CMITLO | Container item key (matches CMITNM) | CMITWO | Worn code (if the item is being worn)
CMITUR | Uses remaining / Item condition | CMITLV | Level
CMITAB | Misc number / Ability | CMHEIT | Height (armor "size")
CMQUESTS
CMQUESID | Quest name (unique) | CMQUTYPE | Quest class ID
CMQFLAGS | Quest statue flags (suspended, etc) | CMQSCRPT | Quest script, or load command
CMQWINNS | List of Character name quest winners (semicolon delimited)
CMPDAT
CMPLID | Character name (or Clan name) | CMSECT | Data "Section" (bank chain, for example)
CMPKEY | Data row key (unique per row) | CMPDAT | Data as an XML document (usually)
CMGRAC
CMRCID | Race ID | CMRDAT | Race definition data XML
CMCCAC
CMCCID | Character Class ID | CMCDAT | Character Class definition data XML
CMGAAC
CMGAID | Ability ID | CMGAAT | Ability definition data XML
CMGACL | Generic Ability Class ID
CMSTAT
CMSTRT | Start of data date/time | CMENDT | End of data date/time
CMDATA | All the data stats for this period as an XML document
CMPOLL
CMNAME | Poll name (unique) | CMBYNM | Poll creator / owner character name
CMSUBJ | Subject | CMDESC | Poll description / introduction
CMOPTN | Options / selections as XML doc | CMFLAG | Poll flags / status bitmask
CMQUAL | Participant qualification zapper mask | CMRESL | Results / Answers XML document
CMEXPI | Poll expiration / end date time
CMVFS
CMFNAM | File path and name, unique per row | CMDTYP | File attributes bitmap (hidden, etc)
CMMODD | File modified date/time | CMWHOM | Owner character name
CMDATA | File data, B64 encoded
CMACCT
CMANAM | Account name (unique) | CMPASS | Account password (encrypted / hash)
CMCHRS | Account characters list, semicolon delimited | CMAXML | Account details as XML document
CMBKLG
CMNAME | Channel name | CMINDX | Backlog message index number
CMDATE | Backlog message date/time | CMDATA | CMMsg data, comma delimited
## Commands Commands are exactly what they sound like: LOOK, QUIT, KILL, GET, and all the other things you type into the mud are handled by CoffeeMud Commands. A Custom Command may or may not belong to any particular package, though it is important that the `ID()` of the Command be unique in the system. A custom Command imports the same packages mentioned in the first section of this document under Complete Default Import List as well as com.planet_ink.coffee_mud.Commands.StdCommand.
    public class DoNothing extends com.planet_ink.coffee_mud.Commands.StdCommand
    {
     public DoNothing(){}

     private final String[] access={ "DONOTHING" };
     public String[] getAccessWords(){ return access; }
All Commands should extend StdCommand for conformity's sake, though it is not required so long as your class implements the com.planet_ink.coffee_mud.core.interfaces.Command interface. In our example above, we have an empty constructor, but we do define some access words. Access words are what you think they are: the words which, when typed, allow the users to activate the command. We define a string array containing one such access word in this case, and then define our Command interface method getAccessWords() to return that array. Our String array may contain as many strings as you would need to provide sufficient words to activate this command.
    public double actionsCost(MOB mob, List<String> cmds){ return 1.0; }
    public double combatActionsCost(MOB mob, List<String> cmds){ return 1.0; }

    public boolean canBeOrdered(){ return true; }
The next two methods, `actionsCost()` and `combatActionsCost()`, designate how LONG it takes to execute this command. A value of 0 means that the command always happens instantly. A value greater than 0 will always take that many free actions to complete. A standard player may perform 1 action in a given Tick ( 4 second period), or 2 actions during combat in the default combat system -- they retain their 1 action per tick in other combat systems). Action costs may be partial as well, costing 0.5 (1/2 action) or other values. The `canBeOrdered()` method designates whether this command represents an action which a creature or player might reasonably be ordered to do by another player. Archons and those with the "ORDER" security code are exempt from this flag.
     public boolean securityCheck( MOB mob )
     {
       return CMSecurity.isAllowed( mob, mob.location(), CMSecurity.SecFlag.IMMORT);
     }
And speaking of security, this method returns whether or not the given mob may even have access to this command. If the `securityCheck()` method returns false, the command and its access words will behave as if they do not even exist, returning "Huh?" should a player attempt to use it. Returning true, however, means only that the execute method below may be accessed. Any further security would have to be implemented during execution of the command. In the above example, we call the `isAllowed()` method in CMSecurity with the mob reference, the room in which the mob is located, and the security code CMSecurity.SecFlag.IMMORT. This asks the Security module whether this mob, at this location, is authorized to perform functions designated by the "IMMORT" security code.
     public boolean preExecute(MOB mob, List<String> commands, int metaFlags, int secondsElapsed, double actionsRemaining)
     throws java.io.IOException;
     {
       if( secondsElapsed == 0 )
       {
         mob.tell( "You are preparing to do nothing." );
       }

       if( secondsElapsed == 3 )
       {
         mob.tell( "You almost ready to do nothing." );
       }
     }
The `preExecute()` method is very rarely implemented, but it is important to mention in light of the `actionsCost()` and `combatActionsCost()` values above. The purpose of the method is to give the player or the room status messages when the player does not yet have enough actions to execute the command. The method will be called immediately if a player does not have enough actions to execute the command, and will present a secondsElapsed value of 0. It will then be called again every second or so with updated values until the player has enough actions to proceed.
     public boolean execute( MOB mob, List<String> commands, int metaFlags )
     throws java.io.IOException
     {
       String parameters = CMParms.combine( commands, 1 );
       if( parameters.length() == 0 )
       {
         mob.tell( "Nothing done." );
       }
       else
       {
         mob.tell( "Nothing, not even '" + parameters + "', done." );
       }
       return false;
     }
Our last method is where the command actually does its work. The mob given would be the MOB object trying to execute this command, while commands is a List of parameters. The parameter commands is never null, and by convention is a List of strings starting with the access word used to execute the command. For instance, if the user entered:
    donothing never "and always" never
The commands List would be size 4, and contain "donothing", "never", "and always", and "never" respectively. In the case of this command, we use one of the String utilities to recombine the last 3 parameters back into one string "never and always never", and then issue a message to the mob depending upon whether there were any parameters at all. Since this command requires a command word to access it, it is reasonable to assume that the 0th element in the commands List is the word "donothing", which means we can safely ignore it. ## MOBs MOBs, or "Moveable OBjects", are the creatures and characters which the players fight. In CoffeeMud, they are among the simpler objects to code. This is not because they are uncomplex. In fact, they are MOST complex. However, this complexity comes due to the myriad of Items, Behaviors, Properties, and Abilities that are added to them. Short of these numerous additions, a MOB by himself is rather simple! This simplicity is important however, and should be carefully considered before you run off to create new MOBs. If you are creating a new MOB because you want a creature to have some new kind of ability, then are you sure it is not a new Ability you want to write? If the new MOBs behavior is complex and unique, are you sure it's not a new Behavior you wish to code? Otherwise, the best reasons to be coding MOBs are actually three: because you have a particular kind of monster that is used prolifically in your world, and you want to save memory by coding him as a special mob that extends StdMOB, or because you want to code special player capabilities by creating your own class that both extends StdMOB and has an `ID()` of "StdMOB", or because you want to add special NPC monster capabilities by creating your own class that extends GenMob and has an `ID()` of "GenMob". So, if you are sure this is what you want to do, carry on! The directory for your custom coded MOB objects should be specified using the "MOBS" entry in the coffeemud.ini file. See the section above on Rebuilding CoffeeMud for more information on this feature. ### Coding a new MOB A Custom MOB may or may not belong to any particular package, though it is important that the ID() of the MOB be unique in the system. A custom MOB imports the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.MOBS.StdMOB because our sample mob extends it. A MOB class must extend either StdMOB or GenMob, StdShopKeeper or GenShopKeeper, StdRideable or GenRideable depending on the basic capabilities, and customizability you would like. Although Generic objects are more customizable at run-time, they also take a long time for the system to load and build, and take up a lot of database disk space, and more memory. For this reason, using Standard instead of Generic wherever possible is always good. Another reason for extending StdMOB is because all players in the game use the "StdMOB" class as a basis, which means that special player fields and capabilities can be coded by both extending the StdMOB class, and also giving your custom class an `ID()` of "StdMOB". If you do this, however, make sure your class is loaded after the %DEFAULT% list in your coffeemud.ini file. As was stated, each unique MOB must also have a custom `ID()` method as shown below. Notice that the `ID()` is the same as the name of the class. This is no accident -- this is required!
    public class MyNewMOB extends com.planet_ink.coffee_mud.MOBS.StdMOB
    {
      public String ID(){ return "MyNewMOB";}
All of your customizing will be done inside the constructor: name, displayText, description, etc, etc.
      public MyNewMOB()
      {
         super();

         setName( "a new mob" );
         setDescription( "It`s furry with 2 legs" );
         setDisplayText( "My new mob is standing here." );

         CMLib.factions().setAlignment( this, Faction.Align.NEUTRAL );
         setMoney( 0 );
         setWimpHitPoint( 2 );
         basePhyStats().setDamage( 4 );

         basePhyStats().setAbility( 0 );
         basePhyStats().setLevel( 1 );
         basePhyStats().setArmor( 30 );
         basePhyStats().setSpeed( 1.0 );
         basePhyStats().setAttackAdjustment( 30 );
         basePhyStats().setWeight( 85 );
         basePhyStats().setSensesMask( PhyStats.CAN_SEE_DARK|PhyStats.CAN_SEE_INFRARED );
         basePhyStats().setDisposition( PhyStats.IS_FLYING );
         baseCharStats().setCurrentClass( CMClass.getCharClass( "Fighter" ) );

         baseCharStats().setMyRace( CMClass.getRace( "Dog" ) );
         baseCharStats().getMyRace().startRacing( this, false );
         baseCharStats().setStat( CharStats.STAT_GENDER, (int)'F' );
         baseCharStats().setStat( CharStats.STAT_STRENGTH, 18 );
         baseCharStats().setStat( CharStats.STAT_INTELLIGENCE, 14 );
         baseCharStats().setStat( CharStats.STAT_WISDOM, 13 );
         baseCharStats().setStat( CharStats.STAT_DEXTERITY, 15 );
         baseCharStats().setStat( CharStats.STAT_CONSTITUTION, 12 );
         baseCharStats().setStat( CharStats.STAT_CHARISMA, 13 );
         baseCharStats().setStat( CharStats.STAT_SAVE_COLD, 50 );

         baseState.setHitPoints( CMLib.dice().roll( basePhyStats().level(), 20, 20 ) );
         baseState.setMana( CMLib.dice().roll( basePhyStats().level(), 50, 100 ) );

         recoverMaxState();
         resetToMaxState();
         recoverPhyStats();
         recoverCharStats();
      }
You can see here that the basic stats have been filled out, from level to attack speed, alignment and weight. For numeric values, higher is always better, except for Armor, which is always best low, and comes down from 100. You'll notice above that two commands are required to set the Race of the creature. Also, you should realize that the numerous saving throws, and senses as well as dispositions (sneaking, hiding) are not represented above, but can easily be added using the format shown. It is very important to note the last four commands. These commands "reset" the MOB, and "implement" the scores which are given in the several areas. `recoverPhyStats()`, for instance, must be called whenever a change is made to the `basePhyStats()` object. Ditto for "CharStats" and "MaxState". Now, suppose we wanted to add an Effect or Behavior or Ability to your MOB. The proper place for such a statement would be in the same above constructor, among the other commands. Preferably before the several "recover" commands, but after the several stat definitions. Of course, all of this is unnecessary for a new GenMOB object.
      addNonUninvokableEffect( CMClass.getAbility( "Fighter_Berzerk" ) );

      Ability A = CMClass.getAbility( "Prop_Resistance" );
      if( A != null )
      {
         A.setMiscText( "Fire 200%" );
         addNonUninvokableEffect( A );
      }

      addAbility( CMClass.getAbility( "Poison" ) );

      addBehavior( CMClass.getBehavior( "MudChat" ) );
      addBehavior( CMClass.getBehavior( "Mobile" ) );
      addBehavior( CMClass.getBehavior( "CombatAbilities" ) );
The commands above will make the MOB permanently Berzerk, gives it the ability to Poison folks while in combat, allows the MOB to Chat with other players, and to walk around in its area. The last behavior gives the MOB the wisdom to use its Poison ability while in combat. If your MOB extends StdShopKeeper, you will need to add your inventory manually through the `getShop()` object access method as shown below. The `getShop()` method returns an instance of the com.planet_ink.coffee_mud.Common.interfaces.CoffeeShop interface, which stores inventory for the shopkeepers. In creating the shopkeepers, you will also need to specify the type of ShopKeeper.
      setWhatIsSold( ShopKeeper.ONLYBASEINVENTORY );

      Weapon sword = (Weapon)CMClass.getWeapon( "Longsword" );
      getShop().addStoreInventory( sword, 35, -1, this );
      Armor mail = (Armor)CMClass.getArmor( "FullPlate" );
      getShop().addStoreInventory( mail, 35, -1, this );
      Item waterskin = CMClass.getItem( "Waterskin" );
      getShop().addStoreInventory( waterskin, 35, -1, this );
You'll recall from the Archon's Guide that there are many different types of ShopKeepers, including trainers, pet sellers, weaponsmiths, and others. StdRideable MOBs will require a few other settings as well!
      setRideBasis( Rideable.RIDEABLE_LAND );
      setMobCapacity( 2 );
The last thing is to give the MOB equipment, armor, and weapons. The following commands will do the trick!
      Weapon sword = (Weapon)CMClass.getWeapon( "Longsword" );
      addItem( sword );
      sword.wearIfPossible( this );

      Armor mail = (Armor)CMClass.getArmor( "FullPlate" );
      addItem( mail );
      mail.wearIfPossible( this );

      Item sack = (Item)CMClass.getItem( "StdContainer" );
      addItem( sack );

      Item waterskin = (Item)CMClass.getItem( "Waterskin" );
      addItem( waterskin );
      waterskin.setContainer( sack );
And that's all there is to creating a new standard MOB. Easy, huh? Well, obviously, the real complexity of MOBs comes when the Behaviors and Abilities are programmed, but that is not covered here, of course. There is also the advanced topic of extending the capabilities of the existing MOB classes. As mentioned previously, this consists in creating your own java classes with the same class name and `ID()` string methods as the base CoffeeMud MOB classes, and the adding the reference to your custom class to the coffeemud.ini file's MOBS enter after the %DEFAULT% entry. Now, adding or extending the capabilities of these classes typically means both adding your own methods, and extending the importing existing methods in those classes. The most important of those existing methods are discussed above in the Core Topics, namely okMessage, executeMsg, and tick. However, there are many other methods which might be extended to the end of altering or enhancing basic aspects of the mud. Those are numerated both in the classes you are extending, and in com.planet_ink.coffee_mud.MOBS.interfaces.MOB.java. Consult the CoffeeMud java docs for more information. ### Bringing MOBs to Life, and Taking That Life Away The following instructions are supplemental, and unnecessary. Once you have created your new MOB, modified your INI file, and rebooted your CoffeeMud server, you need only use the CREATE and other Archon commands to make use of him. If, for some reason, you want to know HOW these commands do their work, however, here it is. To bring a MOB into existence, a MOB must have somewhere to exist! Presumably, this is some room on your map. Rooms on the map are classes which implement the interface com.planet_ink.coffee_mud.Locales.interfaces.Room. If a MOB is to have a permanent existence, it must also have a starting room, or a place to rejuvenate into when necessary. If a MOB does not have a starting room, then its death, when that death comes, will be forever.
    MOB mob = CMClass.getMOB( "MyNewMOB" );
    Room room = CMLib.map().getRoom( "Midgaard#3504" );

    mob.setStartRoom( room ); // this mob will rejuvenate into this room.
    mob.basePhyStats().setRejuv( 500 ); // 30 minutes rejuvenation time
    mob.recoverPhyStats(); // remember this command?!

    mob.bringToLife( room, true ); // tadah!
And THAT's all there is to bring a standard mob to life. Now, generic items require an additional step:
    Item item = CMClass.getItem( "GenItem" );
    Room room = CMLib.map().getRoom( "Midgaard#3504" );

    item.text();
    item.recoverPhyStats();
    room.addItem( item );
    room.recoverRoomStats();
The call to the `text()` method and the seemingly redundant call to `Item.recoverPhyStats()` (which we know is already in the item constructor), ensures that some of the internal structures of the Generic MOB are properly set. Of course, you may want to save this room to the database to make the situation permanent, but all of this is usually done from inside CoffeeMud using the CREATE, MODIFY, and DESTROY commands anyway. Speaking of destroy, destroying a mob for good is even easier than creating one:
    Room room = CMLib.map().getRoom( "Midgaard#3504" );
    for( int i = 0; i < room.numInhabitants(); i++ )
    {
      MOB mob = room.fetchInhabitant( i );
      mob.destroy();
    }
## Items: A Custom Item may or may not belong to any particular package, though it is important that the `ID()` of the Item be unique in the system. A custom Item imports the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Items.Weapons.StdWeapon because our first sample item extends it. An Item class must extend either StdItem or GenItem, StdWeapon or GenWeapon, StdRideable or GenRideable, StdArmor or GenArmor depending on the basic capabilities, and customizability you would like. Although Generic objects are more customizable at run-time, they also take a long time for the system to load and build, and take up a lot of database disk space. For this reason, using Standard instead of Generic wherever possible is always good. There are generally two good reasons to be coding your own Items: because you have a particular kind of item that is used prolifically in your world, and you want to save memory by coding it as a special item that extends StdItem or StdWand, or because you want to code special item capabilities by creating your own class that both extends one of the base item classes and has the same `ID()` string of that class. The directory for your custom coded Item objects should be specified using the "ITEMS", "WEAPONS", "ARMOR", "CLANITEMS", or "MISCMAGIC" entries in the coffeemud.ini file. See the section above on Rebuilding CoffeeMud for more information on this feature. Each Item must also have a custom `ID()` method as shown below. Notice that the `ID()` is the same as the name of the class. This is no accident -- this is required!
    public class MyNewSword extends com.planet_ink.coffee_mud.Items.Weapons.StdWeapon
    {
      public String ID(){ return "MyNewSword"; }

      public MyNewSword()
      {
         super();
      }
    }
All of your customizing will be done inside the constructor: name, displayText, description, etc, etc.
     public MyNewSword()
     {
       super();

       setName( "a super sword" );
       setDescription( "A long super duper sword!" );
       setDisplayText( "Someone left their super sword here." );
       setSecretIdentity( "" );
       setMaterial( RawMaterial.RESOURCE_STEEL );
       setWeaponDamageType( Weapon.TYPE_SLASHING );
       setWeaponClassification( Weapon.CLASS_SWORD );

       setBaseValue( 500 );
       basePhyStats().setDisposition( PhyStats.IS_GLOWING );
       basePhyStats.setWeight( 25 );
       basePhyStats.setAttackAdjustment( 10 );
       basePhyStats.setDamage( 15 );
       recoverPhyStats();
     }
What is shown above is entirely sufficient for the creation of a normal StdWeapon . The material, weight, attack and damage describe it completely. You'll even notice that by setting a disposition flag, we have made the sword glow! Now, what if we wanted a missile weapon?
     public MyNewBow()
     {
       super();

       setName( "a super bow" );
       setDescription( "A long super duper bow!" );
       setDisplayText( "Someone left their super bow here." );
       setSecretIdentity( "" );

       setMaterial( RawMaterial.RESOURCE_OAK );
       setBaseValue( 5000 );
       basePhyStats.setWeight( 15 );
       basePhyStats.setAttackAdjustment( 20 );
       basePhyStats.setDamage( 5 );
       setWeaponDamageType( Weapon.TYPE_PIERCING );
       setWeaponClassification( Weapon.CLASS_RANGED );
       setRanges( 1, 5 );
       setAmmunitionType( "arrows" );
       recoverPhyStats();
     }

     public void recoverPhyStats()
     {
       basePhyStats().setDamage(1 * basePhyStats().level());
       basePhyStats().setAttackAdjustment(basePhyStats().level()*2);
       super.recoverPhyStats();
     }
You'll notice we added two new methods, `setRanges()`, and `setAmmunitionType()`. With the former, we specify that this is a ranged-only weapon, usable from range 1 (0=melee) to range 5. The ammunition type specifies that it uses arrows. We also added the method `recoverPhyStats()` in order to have the attack and damage for the weapon always reflect the level of the item. So those are weapons. Other classes, however, have different requirements altogether. For instance, if class extends com.planet_ink.coffee_mud.Items.Armor.StdArmor:
     public MyNewArmor()
     {
       super();

       setName( "a super bracer" );
       setDescription( "A super duper bracer" );
       setDisplayText( "Someone left their super bracer here." );
       setSecretIdentity( "" );

       setMaterial( RawMaterial.RESOURCE_STEEL );
       setBaseValue( 100 );
       basePhyStats.setWeight( 5 );
       basePhyStats.setArmor( 5 );
       setRawProperLocationBitmap( Wearable.WORN_LEFT_WRIST|Wearable.WORN_RIGHT_WRIST );
       setRawLogicalAnd( false );
       recoverPhyStats();
     }

     public void recoverPhyStats()
     {
       basePhyStats().setArmor(2+(basePhyStats().level()/2));
       super.recoverPhyStats();
     }
In this case, we made a bracer wearable on both left and right wrists. If it were something that could only be worn on both wrists at the same time (like handcuffs), then the RawLogicalAnd value would have been true. Now, a class extending com.planet_ink.coffee_mud.Items.Basic.StdContainer:
     public MyNewBag()
     {
       super();

       setName( "a super bag" );
       setDescription( "A super duper bag" );
       setDisplayText( "Someone left their super bag here." );
       setSecretIdentity( "" );

       setBaseValue( 50 );
       setDoorsNLocks( false, true, false, false, false, false );
       setKeyName( "" );
       setMaterial( RawMaterial.RESOURCE_LEATHER );
       basePhyStats.setWeight( 1 );
       setCapacity( 100 );
       recoverPhyStats();
     }
When setting the capacity of a container, remember that it must also be able to hold its own weight! Also, note the lids and locks flags have made this container lidless and lockless and always open. Of course, without a lock, setting a key would be silly! Now, a class extending com.planet_ink.coffee_mud.Items.Basic.StdDrink will create a drinkable container:
     public MyNewCup()
     {
       super();

       setName( "a super cup" );
       setDescription( "A super duper cup" );
       setDisplayText( "Someone left their super cup here." );
       setSecretIdentity( "" );

       setMaterial( RawMaterial.RESOURCE_LEATHER );
       setBaseValue( 5 );
       setLiquidHeld( 2000 );
       setLiquidRemaining( 2000 );
       setThirstQuenched( 500 );
       setLiquidType( RawMaterial.RESOURCE_MILK );
       basePhyStats.setWeight( 1 );
       setCapacity( 0 );
       recoverPhyStats();
     }
The StdDrink created above is an enormous cup of milk! You'll notice the capacity is 0, meaning that mundane objects cannot be stored in it. Now, a class extending com.planet_ink.coffee_mud.Items.Basic.StdFood:
     public MyNewFood()
     {
       super();

       setName( "a super crumb" );
       setDescription( "A super duper crumb" );
       setDisplayText( "Someone left their super crumbs." );
       setSecretIdentity( "" );

       setBaseValue( 1 );
       setMaterial( RawMaterial.RESOURCE_MEAT );
       setNourishment( 500 );
       basePhyStats.setWeight( 1 );
       recoverPhyStats();
     }
Now, the items extending com.planet_ink.coffee_mud.Items.Basic.StdRideable resemble the MOB of the same name, and thus, have identical modifications.
     public MyNewBed()
     {
       super();

       setName( "a bed" );
       setDescription( "A bed" );
       setDisplayText( "A bed is here" );
       setSecretIdentity( "" );

       setBaseValue( 100 );
       setMobCapacity( 2 );
       setRideBasis( Rideable.RIDEABLE_SLEEP );
       basePhyStats.setWeight( 100 );
       recoverPhyStats();
     }
A pile of money extends class com.planet_ink.coffee_mud.Items.Basic.StdCoins, and is simplest of all:
     public MyNewMoney()
     {
       super();

       setName( "a pile of coins" );
       setDescription( "A pile of coins" );
       setDisplayText( "Someone left their money here." );
       setSecretIdentity( "" );

       setBaseValue( 0 );
       setMaterial( RawMaterial.RESOURCE_GOLD );
       setNumberOfCoins( 1000 ); // 1000 coins!
       setDenomination( 1.0 ); // each coin worth 1.0 basic gold
       basePhyStats.setWeight( 1 );
       recoverPhyStats();
     }
Notice that the base value of the coins is 0, it's the other methods that truly determine its value. Now, to make a magical pill, our class should extend com.planet_ink.coffee_mud.Items.MiscMagic.StdPill:
     public MyNewPill()
     {
       super();

       setName( "a super pill" );
       setDescription( "A super duper pill" );
       setDisplayText( "Someone left their super pill." );
       setSecretIdentity( "" );

       setBaseValue( 1 );
       setMaterial( RawMaterial.RESOURCE_MEAT );
       setNourishment( 500 );
       basePhyStats.setWeight( 1 );
       setSpellList( "Spell_Sleep;Prayer_CureLightWounds" );
       recoverPhyStats();
     }
The spells cast on the eater are listed by their Class names, separated by semicolons. The secret identity is also trimmed out, since the system will handle that automaticallyy. Also notice that the StdPill resembles StdFood except for the addition of the setSpellList method. In the exact same way, the com.planet_ink.coffee_mud.Items.MiscMagic.StdPotion class resembles the StdDrink class except that it has an identical setSpellList method added to IT. So, in the interests of saving a little sand for future generations, I would enumerate the StdPotion. We can, however, show off another class which extends com.planet_ink.coffee_mud.Items.MiscMagic.StdScroll:
     public MyNewScroll()
     {
       super();

       setName( "a super scroll" );
       setDescription( "A super duper scroll" );
       setDisplayText( "Someone left their super scroll." );
       setSecretIdentity( "" );
       setBaseValue( 100 );

       setMaterial( RawMaterial.RESOURCE_PAPER );
       setUsesRemaining( 50 );
       basePhyStats.setWeight( 1 );
       setScrollSpells( "Spell_Sleep;Prayer_CureLightWounds" );
       recoverPhyStats();
     }
Not too difficult, right? Looks like the other two, but the spell setting method has a different name. Now, let's look at a sample of a class extending com.planet_ink.coffee_mud.Items.MiscMagic.StdWand:
     public MyNewWand()
     {
       super();

       setName( "a wand" );
       setDescription( "A magic wand" );
       setDisplayText( "Someone left their magic wand." );
       setSecretIdentity( "" );

       setBaseValue( 1000 );
       setMaterial( RawMaterial.RESOURCE_OAK );
       basePhyStats.setWeight( 1 );
       setSpell( CMClass.getAbility( "Spell_Fireball" ) );
       setUsesRemaining( 50 );
       recoverPhyStats();
     }
In this case, we made use of the "uses remaining" field to set the number of charges for the wand. The way the spell is set is also different. A wand may only have one spell, and the actual Ability object for the spell must be passed in, instead of just the class name as we did before. You will find that this is also how the classes extending com.planet_ink.coffee_mud.Items.MiscMagic.StdStaff work. The StdStaff resembles the StdWeapon we did above, except that the additional setSpell and setUsesRemaining calls become appropriate to the constructor. The next thing we will look at is adding effects and behaviors to Items. Behavior addition (despite the fact that there is really only one behavior that works with Items) will look familiar. The only difference between this and the MOB example above is the fact that we are setting a parameter on the Behavior before adding it.
    Behavior B = CMClass.getBehavior( "Emoter" );
    B.setParms( "min=1 max=20 chance=75;makes strange sounds" );
    addBehavior( B );
Adding normal effects as properties is also similar to mobs...
    Ability A = CMClass.getAbility( "Prop_HaveResister" );
    A.setMiscText( "fire acid 50%" );
    A.addNonUninvokableEffect( A );
The above Effect will allow anyone who owns the item to resist fire and acid at 50%! And again, as with mobs, these commands are best put in the constructor of the item before the recoverPhyStats() call. There is also the advanced topic of extending the capabilities of the existing Item classes. As mentioned previously, this consists in creating your own java classes with the same class name and ID() string methods as the base CoffeeMud Item classes, and the adding the reference to your custom class to the relevant coffeemud.ini file's entries after the %DEFAULT% string. Now, adding or extending the capabilities of these classes typically means both adding your own methods, and extending the importing existing methods in those classes. The most important of those existing methods are discussed above in the Core Topics, namely okMessage and executeMsg. However, there are many other methods which might be extended to the end of altering or enhancing basic aspects of the mud. Those are numerated both in the classes you are extending, in com.planet_ink.coffee_mud.Items.interfaces.Item.java, and in other interface files in that directory. Consult the CoffeeMud java docs for more information. ### Creating and Destroying Items As with mobs, the following instructions are supplemental, and unnecessary. Once you have created your new Item, modified your INI file, and rebooted your CoffeeMud server, you need only use the CREATE and other Archon commands to make use of it. If, for some reason, you want to know HOW these commands do their work, however, here it is. To bring an Item into existence, an item must have somewhere to exist! Items can belong to either Rooms, as mobs are, or they can belong to mobs themselves. This means that Items actually have two different creation mechanisms. Here is an example of each, starting with the creation of an Item in a Room:
    Item item = CMClass.getItem( "MyNewItem" );
    Room room = CMLib.map().getRoom( "Midgaard#3504" );

    room.addItem( item );
    room.recoverRoomStats();
A room is grabbed off the map, and the item is added to the room using the `addItem()` method. Then the room recover is called to make the room react to the addition of the item. Now, generic items require an additional step:
    Item item = CMClass.getItem( "GenItem" );
    Room room = CMLib.map().getRoom( "Midgaard#3504" );

    item.text();
    item.recoverPhyStats();
    room.addItem( item );
    room.recoverRoomStats();
The call to the `text()` method and the seemingly redundant call to `Item.recoverPhyStats()` (which we know is already in the item constructor), ensures that some of the internal structures of the Generic Item are properly set. Of course, these items are one-shot items, meaning that they are not generated to exist on the map forever and ever.
    Item item = CMClass.getItem( "MyNewItem" );
    Room room = CMLib.map().getRoom( "Midgaard#3504" );

    item.basePhyStats().setRejuv( 500 ); // 30 minutes rejuvenation time
    item.recoverPhyStats();
    room.addItem( item );
    room.recoverRoomStats();
    room.startItemRejuv();
In this case, we wanted the item to be rejuvenating. That means that, when the item is removed from the room by a player, the item will reset at some point in the future. If the rejuv ticks count is set to 0, the item will not reset. In the example above, the count is set to 500 so that the item will reset. However, the rejuvenation is not actually activated until the room item rejuvs are set. This is done with the last method call to `startItemRejuv()`, which handles the rejuv resets on all items in the room. In the previous section, we saw how items are given to mobs by simply calling the `addItem()` method, so this will not be repeated. Regardless of where or how the item is created, however, it is destroyed the same way. With a simple call to the `destroy()` method on the item. Here is an example of destroying all the items in a room.
    Room room = CMLib.map().getRoom( "Midgaard#3504" );

    for( int i = room.numItems() - 1; i >= 0; i-- )
    {
      Item item = room.fetchItem( i );
      item.destroy();
    }
## Behaviors A Behavior is defined as a property of an item, mob, exit, or room which takes proactive (as opposed to REactive) steps on behalf of its host. Examples of Behaviors include aggressiveness, mobility, auto-emoting, and scripting. Behaviors import the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Behaviors.StdBehavior because our sample behavior extends it. Custom behaviors are loaded at boot-time by adding references to them to the BEHAVIORS entry in your coffeemud.ini file. Let's take a look at a sample Behavior and see how they are put together:
    public class Ravenous extends com.planet_ink.coffee_mud.Behaviors.StdBehavior
    {
      public String ID(){ return "Ravenous"; }
      public String name(){ return "Ravenous Eater"; }
Our first step, as seen above, is to make sure we define an `ID()` method with the classes name, just as we do in other CoffeeMud objects. Notice that the `ID()` is the same as the name of the class. This is no accident -- this is required! The next step is to give the Behavior a name, which is entirely unimportant to players, but helpful for Archons.
      protected int canImproveCode(){ return Behavior.CAN_MOBS; }
      public long flags(){ return 0; }
      public boolean grantsAggressivenessTo( MOB M ){ return false; }
Next are some important flags that tell the CoffeeMud system some important things about your behavior. The first method (`canImproveCode()`) tells the behavior whether it is properly used on Mobs, or Items, Rooms, Exits, or all of these. In this case, our behavior only affects mobs. The next method (`flags()`) tells the system certain things about the behavior by returning values such as Behavior.FLAG_MOBILITY, or Behavior.FLAG_TROUBLEMAKING. The last method (`grantsAggressivenessTo()`) says whether or not this method would necessary cause the host mob to attack the mob (M) in the parameter.
      public void startBehavior( PhysicalAgent forMe )
      {}
The next method, seldom used, is still quite important. startBehavior receives as its parameter the brand new host of this behavior. If the behavior instance needs to do any variable or other preparation to either the behaving object host (forMe) or itself, it should do so here.
      public String getParms(){ return super.getParms(); }
      public void setParms( String parameters )
      {
        super.setParms( parameters );
      }
These methods, part of the StdBehavior and Behavior interface, are shown here just to make you aware of how parameter strings passed to behaviors are accessed. Sometimes prepatory code is also executed inside a setParms method, for instance. Normally these methods would not appear in your own instance of a Behavior.
      public boolean tick( Tickable ticking, int tickID )
      {
        MOB mob = getBehaversMOB( ticking ); // returns mob, if ticking is a mob. Returns mob owner, if ticking is an item
        Room room = getBehaversRoom( ticking ); // whatever the ticking object is, this will return its location
        if( ( mob == null ) || ( room == null ) || ( tickID != Host.MOB_TICK ) )
        {
          return super.tick( ticking, tickID );
        }
Now we get to the nitty gritty of the Behaviors work. A behavior gets all or almost all of its work done in a tick method. If you have not read the Core Topic above about the tick method, you should definitely do so! In this example, we call two internal StdBehavior methods to get some important starting information about the behaving object host of the behavior. In this example, our behaving object host will be a mob. However, these methods may still intelligently return Item owners, or Exit rooms if the host is other than a mob. The ticking parameter will always be the behaving object host. The next line checks to see if our host mob exists, and is in a room. We also check to see if the tickID is the valid mob ticking id. If our host had been an Item, Exit, or Room, this tickID would no longer be Tickable.TICKID_MOB, but would be Tickable.TICKID_ITEM_BEHAVIOR, Tickable.TICKID_ROOM_BEHAVIOR, or Tickable.TICKID_EXIT_BEHAVIOR. Since our host, in this case, is a Mob, we check for Tickable.TICKID_MOB.
        if( ( !canActAtAll( mob ) ) || ( !canFreelyBehaveNormal( mob ) ))
        {
          return super.tick( ticking, tickID );
        }
Our next step is to call a couple more internal StdBehavior methods. The first (`canActAtAll()`) returns true if the mob is alive, awake, and mobile. The second method (`canFreelyBehaveNormal()`) returns true if the mob is not currently in combat, not charmed or following anyone, and is not severely injured. We want our ravenous mob to follow this behavior only in the best of health and mood.
        Item eatible = null;
        for( int i = 0; i < mob.numItems(); i++ )
        {
          Item I = mob.getItem( i );
          if( ( I != null ) && ( I instanceof Food ) )
          {
            eatible=I;
          }
        }
Next, we iterate through the mob's inventory to find the last instance of a piece of food.
        if( eatible != null)
        {
          room.show( mob, eatible, null, "<S-NAME> gobble(s) up <T-NAMESELF>." );
          return true;
        }
If some food was found, the mob will eat it. Now, practically speaking, the mob will quickly devour and use up any and all food which it may have had to begin with. What we decide to do when the mob does NOT have food, therefore, is just as important.
        MOB mobToHitUp = room.fetchRandomInhabitant();
        if( ( mobToHitUp == null )
        ||( mobToHitUp == mob )
        ||( CMLib.dice().rollPercentage() > 75 ))
        {
          return true;
        }
Since our mob is hungry, and another mob is the most likely source of food, we will pick a random inhabitant of the room, which is not ourselves, 25% of the time. Otherwise, we just return true, and try again on the next tick.
        Item I = mobToHitUp.getRandomItem();
        if( ( I != null ) && ( I instanceof Food ) )
        {
          eatible = I;
        }

        if( eatible == null )
        {
          return true;
        }
Next we will pick a random piece of inventory from that mob, and see if it is food. If not, we return true and try again on the next tick.
        CMLib.commands().postSay( mob, mobToHitUp, "May I have some of your " + eatible.name() + "?" , false, false );

        return true;
      }
And lastly, since we have picked a random mob in the room, and seen that he has food, we will ask him for it! If it's a player, then perhaps he might even give us some. If we are given food, we will eat it on the next tick for sure!
      public void executeMsg( Environmental affecting, CMMsg msg )
      {}

      public boolean okMessage( Environmental oking, CMMsg msg )
      {
        return true;
      }
    }
The above two methods are shown here just to remind you that, although a behavior's PRIMARY purpose is to be proactive in a tick method, a behavior also has the ability to preview and respond to messages affecting the host behaving object. That object will always be identified in the affecting and oking parameters respectively. If these two methods mean nothing to you, you should definitely go back and read the Core Topic on message passing. ## Character Classes A Character Class, in CoffeeMud, is the carreer being followed by the player. Armor and weapon choices, skill and spell access, as well as score advancements all depend on the Character Class chosen by the player. Thankfully, despite all this weighty responsibility, Character Classes are not difficult to code. CharClasses import the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.CharClasses.StdCharClass because our sample class extends it. Your custom classes need to be listed in your coffeemud.ini file under the CHARCLASSES entry. Aside from making custom classes, you can also extend an existing class, return an identical `ID()` string, and then list it at the end of the aforementioned entry in the coffeemud.ini file. Now, let's take a look at a simple one here:
    public class NormalGuy extends com.planet_ink.coffee_mud.CharClasses.StdCharClass
    {
Our Normal Guy character class will define all of the basic elements of a filled-out character class.
      public String ID()
      {
        return "NormalGuy";
      }

      public String baseClass()
      {
        return ID();
      }
The first methods above are the unique Character Class ID and the Base Class ID of the class. The Class ID must be a unique identifier. The `baseClass()` method takes a bit of explaining. If your CoffeeMud system is using the default SubClassing system, the baseClass will define which classes may be switched between by a player, as well as which classes are available to choose from when a new player is created. Fighter, Monk, Paladin, Ranger, and Barbarian, for instance, all have a baseClass of "Fighter". This means that the Fighter class is one of the classes which may be chosen by a new player (since it's `ID()` and `baseClass()` are the same), and that any of the baseClass() "Fighter" classes may switch amongst each other. If your CoffeeMud system is using the multi-class or single classing system, this method is irrelevant.
      public String name()
      {
        return "Normal Guy";
      }

      public String name( int classLevel )
      {
        return name();
      }
Our next method, `name()`, is the default displayable name of your class. The next method `name( int classLevel )` is, in this case, simply returning the default name again. However, if you like, your character classes may have different names at different class levels. Simply check the classLevel and return a different string! As standard practice, however, class level 0 should always return the default name. Remember that Class Levels are different from Player Levels. A Player may, in a multi-classing system, have numerous levels in numerous classes. The Class Level represents how many levels the player has gained in this character class ONLY!
      protected String[] names = null;

      public String[] nameSet()
      {
        if( names != null )
        {
          return names;
        }

        names = new String[1];
        names[0] = name();
        return names;
      }
The `nameSet()` method really only needs to be extended and re-implemented when there are more than 1 available names for your class. Its purpose is to return a string list of all the names that this class may go by. As you can see from the above code, by default, the StdCharClass will nicely handle classes with just one name. However, the code above will need to be altered in your own character class if you choose to make one with multiple names.
      public String getHitPointsFormula()
      {
        return "((@x6<@x7)/3)+(2*(1?6))";
      }
Next come the hit point ranges. When a player with this class gains a level,these values will determine hit points gained based on class and stats. See the Archon help on Math Formulas (or just Formulas) for information on how to write formulas. The variables that can be included are: @x1: Players current class level, @x2: Players adjusted Strength, @x3: Players Max adjusted Strength, @x4: Players adjusted Dexterity, @x5: Players Max adjusted Dexterity, @x6: Players adjusted Constitution, @x7: Players Max adjusted Constitution, @x8: Players adjusted Wisdom, @x9: Players adjusted Intelligence
      public int getPracsFirstLevel()
      {
        return 3;
      }

      public int getTrainsFirstLevel()
      {
        return 1;
      }

      public int getBonusPracLevel()
      {
        return 0;
      }
The next two methods define the starting Training and Practice points for this Character Class. The BonusPracLevel method tells us how many bonus practices (above the number determined the WISDOM/4 formula) which the player will receive every level.
      public int getAttackAttribute()
      {
        return CharStats.STAT_STRENGTH;
      }

      public int getBonusAttackLevel()
      {
        return 1;
      }
And here is an method defining which of the 6 primary Character Attributes (Strength, Intelligence, Wisdom, Dexterity, Constitution, or Charisma) are used to determine any attack bonuses whenever the player gains a level. Usually this is Strength. The number of bonus attack points received by a player when a level is gained is determined by dividing the players score in this attribute by 6, and then adding the value returned by `getBonusAttackLevel()`.
      public String getManaFormula()
      {
        return "((@x4<@x5)/3)+(1*(1?4))";
      }
This method determines how much mana a player receives when they gain a level in this class. See the Archon help on Math Formulas (or just Formulas) for information on how to write formulas. The variables that can be included are: @x2: Players adjusted Wisdom, @x3: Players Max adjusted Wisdom, @x4: Players adjusted Intelligence, @x5: Players Max adjusted Intelligence, @x6: Players adjusted Attack Attr @x7: Players Max adjusted Attack Attr, @x8: Players adjusted Charisma, @x9: Players adjusted Constitution
      public int getLevelsPerBonusDamage()
      {
        return 25;
      }
This score determines how many levels a player must make, in this class, before they will gain a bonus point of damage to all damage rolls.
      public String getMovementFormula()
      {
        return "10*((@x2<@x3)/18)";
      }
And lastly for our scores, this method will determine how many movement points a player receives when they gain a level. See the Archon help on Math Formulas (or just Formulas) for information on how to write formulas. The variables that can be included are: @x1: Players current class level, @x2: Players adjusted Strength, @x3: Players Max adjusted Strength, @x4: Players adjusted Dexterity, @x5: Players Max adjusted Dexterity, @x6: Players adjusted Constitution, @x7: Players Max adjusted Constitution, @x8: Players adjusted Wisdom, @x9: Players adjusted Intelligence
      public int allowedArmorLevel()
      {
        return CharClass.ARMOR_CLOTH;
      }
The CharClass interface defines a method called "armorCheck" which returns true if the player is in compliance with armor requirements. This method does its work by checking the `allowedArmorLevel()` method. This method returns an equate defined in the CharClass interface which may specify ANY armor, CLOTH level, armor, LEATHER (or worse) armor, or NON-METAL armor. You should check the CharClass interface for any other ARMOR_* definitions which may be added from time to time.
      public int allowedArmorLevel()
      {
        return CharClass.ARMOR_CLOTH;
      }

      protected int requiredArmorSourceMinor()
      {
        return -1;
      }

      protected String armorFailMessage()
      {
        return "<s-name> fumble(s) <s-his-her> <skill> due to <s-his-her> armor!";
      }
The The StdCharClass will automaticallyy enforce armor requirements whenever a class skill is used, provided these methods are defined. The `allowedArmorLevel()` method returns an equate defined in the CharClass interface which may specify ANY armor, CLOTH level, armor, LEATHER (or worse) armor, METAL-ONLY, or NON-METAL armor. You should check the CharClass interface for any other ARMOR_* definitions which may be added from time to time. While the `armorFailMessage()` method is pretty self explanatory, the requiredArmorSourceMinor may not be. The later method returns the MINOR code of the SOURCE code of the message generating the skill use. Typically this method will either return -1 for non spell casters, or CMMsg.TYP_CAST_SPELL for spell casters. See the Core Topics for more information on what the heck a source code of a message might be.
      public int allowedWeaponLevel()
      {
        return CharClass.WEAPONS_THIEFLIKE;
      }

      private Set<Integer> disallowedWeapons = buildDisallowedWeaponClasses();
      public Set<Integer> disallowedWeaponClasses( MOB mob )
      {
        return disallowedWeapons;
      }

      private Set<Integer> requiredWeaponMaterials = buildRequiredWeaponMaterials();
      public Set<Integer> requiredWeaponMaterials()
      {
        return requiredWeaponMaterials;
      }
The StdCharClass will automaticallyy enforce weapon restrictions whenever a weapon attack is made, provided these methods are defined. The `allowedWeaponLevel()` method returns an equate defined in the CharClass interface which may specify ANY weapons, DAGGER only, THIEF-like weapons, WOODEN weapons, and several others. You should check the CharClass interface for other WEAPONS_* definitions which may be added from time to time. The `disallowedWeaponClasses( MOB mob )` and `requiredWeaponMaterials()` methods return HashSet objects which, due to the method calls in StdCharClass seen above, are totally derivative of the value you already put in `allowedWeaponLevel()`. In other words, so long as you include the `allowedWeaponLevel()` method, you should also include those next four methods, exactly as you see them.
      public int getLevelCap() {return -1;}
Although not often used, you can set a level cap for the character class by returning some number above -1 from the getLevelCap method. The engine will take care of the rest.
      public int availabilityCode()
      {
        return Area.THEME_FANTASY;
      }
The method `availabilityCode()` defines how players can access this race. Possible values for this constant include: 'Area.THEME_FANTASY' (makes the class available for players to choose when creating fantasy characters), 'Area.THEME_FANTASY|Area.THEME_SKILLONLYMASK' (makes the class available to spells or Skills, but not for player creation), or '0' (the class is not available to spells or for player creation.)
      public NormalGuy()
      {
        super();
        maxStat[CharStats.STAT_CHARISMA] = 10;
      }

      public void initializeClass()
      {
        CMLib.ableMapper().addCharAbilityMapping( ID(), 1,  "Skill_Write",  50,
                                                  "", true, false, new Vector(), "" );
        CMLib.ableMapper().addCharAbilityMapping( ID(), 1,  "Skill_Recall",  0,
                                                  "", true, false, new Vector(), "" );
        CMLib.ableMapper().addCharAbilityMapping( ID(), 1,  "Skill_Climb",  0,
                                                  "", true, false, new Vector(), "" );
        CMLib.ableMapper().addCharAbilityMapping(ID(), // class/race to assign the skill to
                                                 1, // level the skill is qualified for
                                                 "Skill_Swim", // the java ID of the ability to qualify for
                                                 0, // default proficiency to give after gaining
                                                 "", // any misc parameters to pass to the Skill_Swim skill
                                                 false, // true for the class to gain automatically, false to qualify
                                                 false, // whether this skill is unlisted for this class
                                                 CMParms.parseSemicolons("Skill_Climb;Skill_Write", true ), // list of skills required to gain this one
                                                 "-LOCALE +UNDERWATER" // mask to apply to class members wanting this skill
                                               );
      }
    }
And now, after a few methods to flag our construction, work, we come to our constructor! The Constructor for every character class defines any special maximums for the primary attributes. This is done by setting the appropriate value in the `maxStat[]` array for the class. By default, 18 is the maximum score for all primary attributes. The second method is found in all CMObject, and is the initializeClass() method. This method is called after all classes have been loaded, but before the map is loaded. The method is called once on every class, but only during initialization. In Character classes, it establishes the qualifying and bonus skills for the class. This is done through repeated calls to one of the several `CMLib.ableMapper().addCharAbilityMapping()` methods. The first parameter of the method is the `ID()` value of the Character Class itself, followed by the level at which this class gains or qualifies for the skill. Next is the `ID()` value of the Ability to allow this class to qualify for, followed by the default proficiency which this class displays in the skill (typically 0). The next parameter are any special parameters that affects the way this class uses the skill, followed by a boolean which establishes whether the player will receive this skill automaticallyy when he or she gains the appropriate level, or whether they merely qualify for the skill. The next parameter, almost always false, determines whether the skill is "secret" for this class. Secret skills are qualified for (or gained), but do not appear on Qualify lists, Class information, or Help files. Secret skills are never taught by Guildmasters (MOBTeachers) unless specifically told to. The next parameter is a List of Strings, representing a list of skills which must be known by this class before he can learn the skill in question. The last parameter is a String representing a mask which must be passed by the person who wants to gain this skill.
      public CMSecurity.SecGroup getSecurityFlags( int classLevel )
      {
        if( classLevel > 1000 )
        {
          CMSecurity.SecFlag[] flags = new CMSecurity.SecFlag[] {
          CMSecurity.SecFlag.ABOVELAW,
          CMSecurity.SecFlag.LISTADMIN
          }
          return new CMSecurity.SecGroup(flags);
        }
        else
        {
          return new CMSecurity.SecGroup(new CMSecurity.SecFlag[0]);
        }
      }
The purpose of this method is to allow you to assign CoffeeMud Security Flags or CoffeeMud Security Groups to your players based on their Character Class and Character Class Level. This is a rather obscure feature that is really only meant for special Character Classes you may design for your admins and builders. Your player `getSecurityGroups()` methods will normally just return an empty List regardless of classLevel. In this case, however, we are demonstrating how a player who gains 1001 levels in our NormalGuy Class will become immune to the CoffeeMud legal system (ABOVELAW flag) and gain access to the Archon LIST command (LISTADMIN flag). See the Archon's Guide for more information on the CoffeeMud security system.
      public boolean qualifiesForThisClass( MOB mob, boolean quiet )
      {
        if( !CMLib.flags().canBreathe( mob ) )
        {
          if( !quiet )
          {
            mob.tell( "You need to be breathing to be a normal guy." );
          }
          return false;
        }
        return super.qualifiesForThisClass( mob, quiet );
     }
The `qualifiesForThisClass()` method would actually check and enforce the qualifications described by `statQualifications()`. In our example above, there is only a check to see if the idiot is still breathing. Also note that a quiet boolean exists to allow qualifications to be checked without sending any messages to the player in question.
      private final String[] raceRequiredList=new String[] {
        "Human","Humanoid","Troll-kin","Elf"
      };
      public String[] getRequiredRaceList(){ return raceRequiredList; }
The next method, like qualifiesForThisClass`` method above is for checking qualifications. It contains an exhaustive list of all races, race IDs, or racial categories required to become this class. A list with the word "All" would let any race become the class.
      private final Pair<String,Integer>[] minimumStatRequirements=new Pair[]{
        new Pair<String,Integer>("Strength",Integer.valueOf(9)),
        new Pair<String,Integer>("Intelligence",Integer.valueOf(9))
      };
      public Pair<String,Integer>[] getMinimumStatRequirements() { return minimumStatRequirements; }
The next method, like qualifiesForThisClass`` method above is for checking qualifications. It contains an exhaustive list character stat names, and minimum values required to become this class. An empty list, of course, means no stat requirements.
      public String otherBonuses()
      {
        return "Receives a mortgage, but no home.";
      }
The next method, like `statQualifications above()`, is for the benefit of the web macros. It describes any special bonuses received due to being this class.
      public List<Item> outfit( MOB myChar )
      {
        if( outfitChoices == null )
        {
          outfitChoices = new Vector();
          Weapon w = (Weapon)CMClass.getWeapon( "a mortgage" );
          outfitChoices.add( w );
        }
        return outfitChoices;
      }
The outfit method should return a List of any Class-Specific Item object equipment they may need. Clothing and so forth is actually covered by Races.
      public void grantAbilities( MOB mob, boolean isBorrowedClass )
      {
        super.grantAbilities( mob, isBorrowedClass );
        if( mob.isMonster() )
        {
          List<AbilityMapper.AbilityMapping> V=CMLib.ableMapper().getUpToLevelListings(ID(), mob.charStats().getClassLevel(ID()), false, false );

          for(final AbilityMapper.AbilityMapping able : V)
          {
            final Ability A=CMClass.getAbility(able.abilityID());
            if( ( A != null )
            && ( ( A.classificationCode()&Ability.ALL_ACODES) != Ability.ACODE_COMMON_SKILL )
            && ( !CMLib.ableMapper().getDefaultGain( ID(), true, A.ID() ) ))
            {
              giveMobAbility( mob, A, CMLib.ableMapper().getDefaultproficiency( ID(), true, A.ID() ),
                            CMLib.ableMapper().getDefaultParm( ID(), true, A.ID() ), isBorrowedClass );
            }
          }
        }
      }
This important method is called whenever a player gains a level in this class, or when an NPC mob is being "outfitted" with this class via one of the following Behaviors: CombatAbilities, Fighterness, Druidness, Bardness, Clericness, Thiefness, Mageness. The `grantAbilities()` method has the important job of making sure that players receive their autogained skills or any other options skills when they level. The StdCharClass version of grantAbilities (called by `super.grantAbilities(...)`) takes care of any autogained skills up to the player or mobs current level in the class. Each char class which extends this, however, needs to take care of any skills or abilities for NPC mobs which are not automaticallyy gained. This is to make up for the fact that npc mobs will not be lining up at your guildmasters to spend their trains on skills they merely qualify for. In the sample code above, we give the mobs every skill the class qualifies for up to the mobs level in the class, except for any common skills. Those would still need to be given by hand to each mob.
      public boolean okMessage( Environmental myHost, CMMsg msg )
      {
        if( !( myHost instanceof MOB ) )
        {
          return super.okMessage( myHost, msg );
        }

        MOB myChar = (MOB)myHost;

        if( ( msg.amITarget( myChar ) )
        &&( msg.targetMinor() == CMMsg.TYP_DAMAGE )
        &&( ( msg.sourceMinor() == CMMsg.TYP_COLD )
        ||( msg.sourceMinor() == CMMsg.TYP_WATER )))
        {
          int recovery = myChar.charStats().getClassLevel( this );
          msg.setValue( msg.value() - recovery );
        }
        else
        if( ( msg.amITarget( myChar ) )
        &&( msg.targetMinor() == CMMsg.TYP_DAMAGE )
        &&( msg.sourceMinor() == CMMsg.TYP_FIRE ))
        {
          int recovery = msg.value();
          msg.setValue( msg.value() + recovery );
        }

        return super.okMessage( myChar, msg );
      }
    }
And lastly, just as I'm sure you were wondering how useful those three Core Topics above would really be, we see them in active use. Some classes contain methods such as these to enforce some of the benefits for the class. In the `okMessage()` method, which we discussed in the first Core Topic, we see messages messages containing the type of damage taken by the player being intercepted. TYP_DAMAGE messages always have their damage amounts stored in the `.value()` method of a message, so it is these values which are modified, based on the type of damage taken. And not least, although we won't go into it in detail here, there are two other methods which may be of use for the advanced Character Class programmer. They are the level and unLevel methods. These methods are called when a player gains or loses (respectively) a level in the class. If there are any extra skills or bonus scores the player may wish to gain and lose with levels, that would be the place for such code. Also, in some cases (Mages and Clerics come to mind), the gaining of qualifying skills may be somewhat complex. In those cases, overriding the gainAbilities method may be in order. Check the Mage and Cleric classes for more information. ## Races A Race, in CoffeeMud, contributes very little to functionality, but quite a bit to the role playing and other "soft" aspects of the game.. For this reason, everyone is encouraged to code as many races as humanly possible. The more, the better! Races import the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Races.StdRace because our sample class extends it. Your custom races need to be listed in your coffeemud.ini file under the RACES entry. Aside from making custom race classes, you can also extend an existing race class, return an identical ID() string, and then list it at the end of the aforementioned entry in the coffeemud.ini file. Now, let's take a look at a simple one here:
    public class Grumbler extends com.planet_ink.coffee_mud.Races.StdRace
    {
Our Grumbler race will define all of the basic elements of a filled-out race.
      public String ID()
      {
        return "Grumbler";
      }

      public String name()
      {
        return "Grumbler";
      }

      public String racialCategory()
      {
        return "Grumbler";
      }

      protected static Vector<RawMaterial> resources = new Vector<RawMaterial>();

      public int availabilityCode()
      {
        return Area.THEME_FANTASY;
      }
The first methods return the unique ID of the Race (which must always match the java/class file name) and the `name()` method is the displayable name of the Race. The third method is very important, as it defines the category into which this race falls. There is no hard rule to determine when a new category should be created versus using an old one. Some of the uses of racial categories include the Ranger Favored Enemy skill, as well as most of the race-based restrictions on doors and with shopkeepers. In many ways, the racial category is more important than the name of the race itself, if functionality is considered. The last method list above, availabilityCode, defines how players can access this race. Possible values for this constant include: 'Area.THEME_FANTASY' (makes the race available for players to choose when creating fantasy characters), 'Area.THEME_FANTASY|Area.THEME_SKILLONLYMASK' (makes the race available to spells such as Polymorph or Wish, but not for player creation), or '0' (the race is not available to spells or for player creation.) public int[] getBreathables() { return new int[]{ RawMaterial.RESOURCE_AIR }; } This method returns either an empty array, or an array of integers, each of which is a RawMaterial code representing something like AIR, or FRESHWATER, or OXYGEN, etc. It tells the system what kind of atmospheres this race can breathe without dying. There are several pre-defined built-in static arrays in StdRace.java that you can use for common cases, such as breatheAirArray, breatheWaterArray, breatheAirWaterArray, or breatheAnythingArray (which is empty). You can define your own also, of course. Remember that the RawMaterial codes you return will be the ONLY atmospheres the race can breathe. Returning an empty integer array int[0] will denote that the race can breathe anything.
      public int shortestMale()
      {
        return 84;
      }

      public int shortestFemale()
      {
        return 78;
      }

      public int heightVariance()
      {
        return 80;
      }

      public int lightestWeight()
      {
        return 2000;
      }

      public int weightVariance()
      {
        return 500;
      }
These methods, as you might have guessed, establish parameters for the base height and weight of a typical monster of this type. A random number from 0-`heightVariance()` will be added to the `shortedMale()`/`shortestFemale()` value to determine height, while a random number from 0-`weightVariance()` will be added to `lightestWeight()` to determine that.
      public long forbiddenWornBits()
      {
        return Wearable.WORN_WIELD
              |Wearable.WORN_WAIST
              |Wearable.WORN_ABOUT_BODY
              |Wearable.WORN_FEET
              |Wearable.WORN_HANDS;
      }
This method establishes where a creature of this type may NOT wear something. In this case, we forbid any wielded items, or anything worn around the waist, on hands or feet, or about the body. Anywhere else is fine. Return 0 if you do not wish any restrictions on wearing.
      private static final int[] parts = {0,2,2,1,1,0,0,1,4,4,1,0,1,1,1,2};

      public int[] bodyMask()
      {
        return parts;
      }
The `bodyMask()` method defines and returns an array of integers which defines the types and number of particular body parts normally retained by the race. Each position in the array is defined by the equates BODY_ in the Race interface. These equates are (starting from 0): BODY_ANTENNEA, BODY_EYE, BODY_EAR, BODY_HEAD, BODY_NECK, BODY_ARM, BODY_HAND, BODY_TORSO, BODY_LEG, BODY_FOOT, BODY_NOSE, BODY_GILL, BODY_MOUTH, BODY_WAIST, BODY_TAIL, BODY_WING. Remember that these can be found in the Race interface for you to reference. In the above example, we find no antennea, 2 eyes, 2 ears, a head, neck, no arms or hands, a torso, 4 legs, 4 feet, a nose, but no gill, and then a mouth, waist, tail, and 2 wings.
      private String[] racialAbilityNames = { "Skill_Trip", "Fighter_Whomp" };
      private int[] racialAbilityLevels = { 1, 3 };
      private int[] racialAbilityProficiencies = { 75, 50 };
      private boolean[] racialAbilityQuals = { false, false };

      protected String[] racialAbilityNames()
      {
        return null;
      }

      protected int[] racialAbilityLevels()
      {
        return null;
      }

      protected int[] racialAbilityProficiencies()
      {
        return null;
      }

      protected boolean[] racialAbilityQuals()
      {
        return null;
      }

      public List<Ability> racialAbilities( MOB mob )
      {
        List V = super.racialAbilities( mob );
        return V;
      }
Our next section here deals with Racial Abilities, which are defined as follows: A racial ability is a skill that has a command word, and is not autoinvoked. A racial ability may be qualified for or automaticallyy gained. If the skill is qualified for, then upon reaching the designated player level, the player may GAIN the skill, and will have a default proficiency as designated. If the skill is not qualified for, then it is automaticallyy gained. This means that all mobs or players of this race, who have obtained the necessary player level, will have access to the use of the skill as if they had learned it, and at the proficiency designated. Racial Abilities are available to any mob or player of this race, even those affected by Shape Shift, Polymorph, or similar skills. The first four methods define these skills. The data in all four variables are ordered with relative to each other. The `racialAbilityNames` is a list of the Ability class ID. The `racialAbilityLevels` is the level at which the skill is qualified for or gained. The `racialAbilityProficiencies()` is the proficiency of skills automaticallyy gained. The `racialAbilityQuals()` tells whether or not the skill is automaticallyy gained (false) or is only qualified for (true). The method above (`racialAbilities()`) will return a List of Ability objects, with proficiency already set, appropriate to the mob passed in. This list should consist only of automaticallyy gained abilities appropriate to the level of the mob. If the four variables are set properly, the programmer will not need to override the method from StdRace unless there other gender-based or other special qualifications for skills not defined by those four variables.
      public List<Item> outfit( MOB myChar )
      {
        if( outfitChoices == null )
        {
          outfitChoices = new Vector();
          Weapon w = (Weapon)CMClass.getItem( "GenPants" );
          outfitChoices.add( w );
        }
        return outfitChoices;
      }
The outfit method should return a List of any Race-Specific Item object equipment they may need.
      private String[] culturalAbilityNames = { "Dwarven", "Mining" };
      private int[] culturalAbilityProficiencies = { 100, 50 };

      public String[] culturalAbilityNames()
      {
        return culturalAbilityNames;
      }

      public int[] culturalAbilityProficiencies()
      {
        return culturalAbilityProficiencies;
      }
Cultural Abilities are defined as those skills which a mob or player of this race would know through upbringing in the culture of that race, such as language. Players Shape Shifted or Polymorphed into the race, since they did not grow up in the culture, would not have automatic access to these skills per se. These two methods are defined similarly to the Racial Abilities above.
      public void affectPhyStats( Physical affected, PhyStats affectableStats )
      {
        super.affectPhyStats( affected, affectableStats );

        affectableStats.setSensesMask(affectableStats.sensesMask() | PhyStats.CAN_SEE_INFRARED);
      }
This sample of the `affectPhyStats()` method we discussed in the Core Topics above makes sure that all creatures of this race can see in the infrared spectrum.
      public void affectCharStats( MOB affectedMOB, CharStats affectableStats )
      {
        super.affectCharStats( affectedMOB, affectableStats );
        affectableStats.setStat( CharStats.STAT_STRENGTH, 15 );
        affectableStats.setStat( CharStats.STAT_DEXTERITY, 25 );
        affectableStats.setStat( CharStats.STAT_INTELLIGENCE, 5 );
      }
This sample of the affectCharStats method we discussed in the Core Topics above establishes a base strength, dexterity, and intelligence for all creatures of this race. As this is the ONLY way to modify a MOBs stats short of magical equipment, it should be used with care!
      public void startRacing( MOB mob, boolean verifyOnly )
      {
        super.startRacing( mob, verifyOnly );
      }
startRacing is called whenever a player of this race logs on, or a mob of this race is created. If there are any special properties of the mob or player which must be set due to their being this race, this would be the appropriate method in which to do so. This method is not called for Polymorph, Shape Shift, or similar changes in race, but only for those whose permanent race is this one.
      public Weapon myNaturalWeapon()
      {
        if( naturalWeapon == null )
        {
          naturalWeapon = CMClass.getWeapon( "StdWeapon" );
          naturalWeapon.setName( "huge claws" );
          naturalWeapon.setMaterial(RawMaterial.RESOURCE_BONE);
          naturalWeapon.setUsesRemaining(1000);
          naturalWeapon.setWeaponDamageType( Weapon.TYPE_PIERCING );
        }
        return naturalWeapon;
      }
This method allows you to create (see item creation above) a special weapon to serve the creature whenever they are not wielding something. Since our Grumbler cannot wield weapons anyway, it is important to give them some big piercing claws.
      public String healthText( MOB viewer, MOB mob )
      {
        double pct = ( CMath.div( mob.curState().getHitPoints(), mob.maxState().getHitPoints() ) );
        if( pct < .10 )
        {
          return "^r" + mob.displayName(viewer) + "^ris raging in bloody pain!^N";
        }
        else
        if( pct < .20 )
        {
          return "^r" + mob.displayName(viewer) + "^ris covered in blood.^N";
        }
        else if( pct < .30 )
        {
          return "^r" + mob.displayName(viewer) + "^r is bleeding badly from lots of wounds.^N";
        }
        else if( pct < .50 )
        {
          return "^y" + mob.displayName(viewer) + "^y has some bloody wounds and gashed scales.^N";
        }
        else if( pct < .60 )
        {
          return "^p" + mob.displayName(viewer) + "^p has a few bloody wounds.^N";
        }
        else if( pct < .70 )
        {
          return "^p" + mob.displayName(viewer) + "^p is cut and bruised heavily.^N";
        }
        else if( pct < .90 )
        {
          return "^g" + mob.displayName(viewer) + "^g has a few bruises and scratched scales.^N";
        }
        else if( pct < .99 )
        {
          return "^g" + mob.displayName(viewer) + "^g has a few small bruises.^N";
        }
        else
        {
          return "^c" + mob.displayName(viewer) + "^c is in perfect health.^N";\
        }
      }
Although the programmer is welcome to skip the above method and use the defaults from the StdRace class, this allows you to set special health messages for creatures of this type.
      public List<RawMaterial> myResources()
      {
        synchronized( resources )
        {
          if( resources.size() == 0 )
          {
            resources.addElement( makeResource( "a " + name().toLowerCase() + "claw",  RawMaterial.RESOURCE_BONE ) );

            for( int i = 0; i < 10; i++ )
            {
              resources.addElement( makeResource( "a strip of " + name().toLowerCase() + " hide", RawMaterial.RESOURCE_SCALES) );
            }

            for( int i = 0; i < 10; i++ )
            {
              resources.addElement( makeResource( "a pound of " + name().toLowerCase() + " meat", RawMaterial.RESOURCE_MEAT ));
            }

            resources.addElement( makeResource( "some " + name().toLowerCase() + " blood", RawMaterial.RESOURCE_BLOOD));
          }
        }
        return resources;
      }
    }
The above method allows you to determine what sorts of materials are gotten from this creature whenever the dead corpse is Butchered. Now, in addition to the methods above which are good to include in your custom races, there are also several methods which are not normally extended or overridden, but which is may be good to do so in special cases. These methods include `public void level( MOB mob )`, which is called whenever a player of that race gains a level, public void `agingAffects( MOB mob, CharStats baseStats, CharStats charStats )` , which is called to enforce how aging effects this race, and `public DeadBody getCorpseContainer( MOB mob, Room room )`, which is called to create a corpse for members of this race. ## Exits Exits are the connecting points between two rooms, and tend to be rather simple. If two rooms, A & B, are connected to each other, there are always two exits associated with that connection. One from room A to room B, and the other from room B to room A. Exits import the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Exits.StdExit because our sample class extends it. Here is an example exit:
    public class SlidingDoor extends com.planet_ink.coffee_mud.Exits.StdExit
    {
      public String ID()
      {
        return "SlidingDoor";
      }

      public SlidingDoor()
      {
        super();
        Ability A = CMClass.getAbility( "Prop_ReqHeight" );
        A.setMiscText( "30" );
        addNonUninvokableEffect( A );
      }

      public String name()
      {
        return "a sliding door";
      }

      public String displayText()
      {
        return "";
      }

      public String closedText()
      {
        return "a closed sliding door";
      }

      public String doorName()
      {
        return "door";
      }

      public String openName()
      {
        return "slide";
      }

      public String closeName()
      {
        return "slide";
      }

      public boolean hasADoor()
      {
        return true;
      }

      public boolean hasALock()
      {
        return false;
      }

      public boolean defaultsLocked()
      {
        return false;
      }

      public boolean defaultsClosed()
      {
        return true;
      }

      public int openDelayTicks()
      {
        return 45;
      }
    }
As you can see, exits are very simple. A set of variables and parameters are sufficient to establish every function of an exit, and these are already well defined in the Archon's Guide. This is due primarily to the fact that several Properties and Behaviors give an exit most of its color and complexity. Exits, like all other Environmental objects, get to preview and execute messages. They will only tend to listen for messages dealing with OPENING or CLOSING where the exit is the target, or ENTERING and LEAVING where the exit is the tool. If a player is going from room A to room B. The player message will note that he or she is ENTERING the exit in room A and LEAVING the exit in room B. Although this makes perfect sense to me, it may sound a little backwards from the intuitive way. Since Room objects (Locales) are almost always the target of ENTER and LEAVE messages, exits are subordinated to being the tools of such messages. Exits will never tick, by and large, unless they have a door that defaults closed and the door is opened, or they gain some sort of Behavior (such as Emoter). ## Locales Locales are the stuff rooms are made of, and so they implement the interface Room. There are actually four different general types of locales: the standard room, the standard grid, the "thin" grid, and the standard maze. Each of those respectively is a functional superset of the former respectively. Rooms import the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Rooms.StdGrid, com.planet_ink.coffee_mud.Rooms.StdRoom, or com.planet_ink.coffee_mud.Rooms.StdMaze, because our sample classes extends them. Let's looks at an example of a standard grid room, which has much of the functionality we are interested in:
    public class RoadGrid extends com.planet_ink.coffee_mud.Locales.StdGrid
    {
      public String ID()
      {
        return "RoadGrid";
      }

      public RoadGrid()
      {
        super();
        name = "a road";
        basePhyStats.setWeight( 1 );
        recoverPhyStats();
      }

      public String getGridChildLocaleID()
      {
        return "Road";
      }

      public List<Integer> resourceChoices()
      {
        return Road.roomResources;
      }

      public int domainType()
      {
        return Room.DOMAIN_OUTDOORS_PLAINS;
      }
    }
Here we see the standard RoadGrid. It's effects, behaviors, displaytext, description, and (since it is a grid type) size in the x and y are all defined by the builder. The features (and they aren't many) which are available to the coder can be seen here. We see the base weight being set to "1" here. This is the default number of movement points consumed by crossing this room. For Grids, we see the Locale ID of the child-rooms inside the grid. We also see the standard room settings methods for the domain type (the type of locale it is) and the domain conditions (the quality of the weather, or the air, wetness, dryness, etc). The Resource choices for this room are borrowed from the Road itself, though this will never be used. Players will never actually be inside the Grid room itself, but will always occupy one of the child rooms, each of which will take direction from the parent Grid. If you wish to define resources, however, be aware that the resourceChoices list returned may not be null, and must only contain Integer objects representing the Resource (see the Items.interfaces.RawMaterial.java interface) available there. Use the RESOURCE_* static integer values from RawMaterial interface. Here are another set of useful methods:
     public String displayText(MOB mob)
     public String description(MOB mob)
These methods return the title and description of the room respectively. These methods are responsible for making the title and description into a proper displayable format. They draw on the values of the room object `displayText()` and `description()` methods respectively, then parse that data for any special display codes, though often that data is simply passed through. The `executeMsg()`, and `okMessage()` methods on rooms are also available, as they are in all Environmental objects, for customized message handling as described in the Core Topics above. ## Areas The Area objects, which represent areas in the game, are the most difficult to advise about regarding programming. However, an attempt must be made. Therefore, we will go over some of the methods and features available on the Area object, which might be overridden for some other use. Areas import the same packages mentioned in the first section of this document under Complete Default Import List.
    public class StdArea implements Area
    {
      public String ID()
      {
        return "StdArea";
      }

     [...]

      public Climate getClimateObj(){...}
      public int climateType(){...}
      public void setClimateType( int newClimateType ){...}
Of course, like every Environmental object, the Area must define an `ID()`. Notice that the `ID()` is the same as the name of the class. This is no accident -- this is required! The name, display text, description, and others are all handled by the builder, or Properties or behaviors, and aren't pertinent to this discussion of Areas. The weather, however, is a relative function of each area. Each area knows its current weather object (see the Climate interface) as well as the next weather change "in the que". These can be read and set by the methods in the Climate object. Each area also knows it climatic "tendencies", and this also can be set and read from the area itself. Lastly, a method exists on the Climate object to force the area to cycle through its weather, which will force the "next" weather code to become current, and establish a new "next" weather code.
      public int getTheme()
      public void setTheme( int level )
These will return the technical level allowed in the area, whether it be magic, technology, or both.
      public String getArchivePath()
      public void setArchivePath( String pathFile )
The Archive name of the area is set and read from the area, though it's more properly set by the builder.
      public TimeClock getTimeObj()
Similar to Climate above, each area has a reference to a TimeClock object which contains information about local time. Unlike the Climate, however, StdAreas all share the same Time object, meaning that time is global. However, the object exists here in case you want local time areas.
      public void toggleMobility( boolean onoff )
      public boolean getMobility()
These methods define whether Mobile mobs will move around. By toggling mobility off, no mob or player in the whole area will move from room to room for any reason, allowing a good base state for builders to work from.
      public StringBuffer getAreaStats()
If the data, appearance, or format of the HELP provided for areas needs to be changed, the `getAreaStats()` method is where to generate a new one.
      public Enumeration<Room> getMetroMap()
      public int metroSize()
      public Room getRandomMetroRoom()
These methods provide access to all of the rooms in the given area, plus all of the rooms in any child areas, plus any rooms in their children areas and so forth.
      public void fillInAreaRooms()
      public void fillInAreaRoom( Room R )

      public Enumeration<Room> getProperMap()
      public int properSize()
      public Room getRandomProperRoom()
      public void clearMetroCache()
The first two methods are called in order to perform finalizing clean-up or resetting of room structures. The remaining methods provide access to the set of rooms which are directly a part of this area. The last method is one which should be called if any proper rooms are ever added, since it clears and "re-calculates" the metro rooms list.
      public void addSubOp( String username )
      public void delSubOp( String username )
      public boolean amISubOp( String username )
      public String getSubOpList()
      public void setSubOpList( String list )
And lastly, the list of staff (Area Archons they are also sometimes called), can be managed from here. Changing these methods would modify how staff are handled by Areas. ## Properties Properties are the simplest of the objects which implement the Ability interface, and are defined as effects which can be permanently tacked-on to items, mobs, and other Physical objects. Properties are Abilities, but they are never qualified for by classes, never gained as skills, and never wear off or disappear when a mob dies. They are always added to a mob, item, room, etc using the Physical interface method `addNonUninvokableEffect( Ability )` method either inside a custom coded Physical object, or at run-time to a GenMob, GenItem, Room, or similar type object. Properties and Behaviors are often the basic building blocks of the customized GenMob and GenItem in CoffeeMud, and differ from each other in this basic respect: Properties tend to have a smaller memory footprint and tend to react to events affecting their hosts rather than cause their hosts to take proactive actions. Properties make heavy use of the message handlers and stat affecting methods. If you have not read the Core Topics above already, you should do so now. A Custom property may or may not belong to any particular package, though it is important that the ID() of the property be unique in the system. Properties import the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Properties.Property because our sample class extends it. A customized property class must extend the Property class implemented in the aforementioned package. This Property class already implements the Ability interface, and already has dummy methods for most of the Ability interface methods which are unnecessary or are unused in a Property. Each property must also have custom `ID()`, and `name()` methods as shown below. Notice that the `ID()` is the same as the name of the class. This is no accident -- this is required!
    public class Prop_AstralSpirit extends com.planet_ink.coffee_mud.Abilities.Properties.Property
    {
      public String ID()
      {
        return "Prop_AstralSpirit";
      }

      public String name()
      {
        return "Astral Spirit";
      }
Above we see the aforementioned methods defined. The Property does not differ from other Abilities, or indeed other Physical objects in this respect. A unique `ID()`, and `name()` method must be defined for each new class.
      protected int canAffectCode()
      {
        return Ability.CAN_MOBS;
      }

      public String accountForYourself()
      {
        return "an astral spirit";
      }
Here are two important support methods you will also find in Skills and the other more standard Abilities. The first method tells what type of objects (Areas, MOBs, Items, Rooms, or Exits) can be affected by this property. In this case, this property only affects MOBS. A value like Ability.CAN_MOBS|Ability.CAN_ITEMS would denote one that affects MOBs or Items. The second method is a string which is returned whenever this property appears on an Item which is Identified. This string would appear in addition to any secretIdentity defined for the item.
      /** this method defines how this thing responds
      * to environmental changes. It may handle any
      * and every msg listed in the CMMsg class
      * from the given Environmental source */
      public boolean okMessage( Environmental myHost, CMMsg msg )
      {
        if( ( affected == null ) || ( !( affected instanceof MOB ) ) )
        {
          return true;
        }

        MOB mob = (MOB)affected;

        if( ( msg.amISource( mob ) )
        && ( !CMath.bset( msg.sourceMajor(), CMMsg.MASK_ALWAYS ) ))
        {
          if( ( msg.tool() != null )
          &&( msg.tool().ID().equalsIgnoreCase( "Skill_Revoke" ) ))
          {
            return super.okMessage( myHost, msg );
          }
          else if( msg.targetMinor() == CMMsg.TYP_WEAPONATTACK )
          {
            mob.tell( "You are unable to attack in this incorporeal form." );
            peaceAt( mob );
            return false;
          }
          else if( ( CMath.bset( msg.sourceMajor(), CMMsg.MASK_HANDS ) )
          || ( CMath.bset( msg.sourceMajor(), CMMsg.MASK_MOUTH ) ))
          {
            if( CMath.bset( msg.sourceMajor(), CMMsg.MASK_SOUND ) )
            {
              mob.tell( "You are unable to make sounds in this incorporeal form." );
            }
            else
            {
              mob.tell( "You are unable to do that this incorporeal form." );
            }

            peaceAt( mob );
            return false;
          }
        }
        else
        if( ( msg.amITarget( mob ) )
        &&( !msg.amISource( mob ) )
        &&( !CMath.bset( msg.targetMajor(), CMMsg.MASK_ALWAYS ) ))
        {
          mob.tell( mob.name() + " doesn't seem to be here." );
          return false;
        }

        return true;
      }
As discussed in the Core Topics above, here is an example of an okMessage method. In this case, we intercept attack and other vocal or hand movement messages where the source of the action is the mob whose property this is. We then return false, effectively canceling those messages, after telling the poor bloke why we are doing it. The rest of the method prevents any messages from targeting the mob with this property. This saves him from being attacked by aggressives, or arrested by cityguards -- since technically he isn't even there.
      public void affectPhyStats( Physical affected, PhyStats affectableStats )
      {
        super.affectPhyStats( affected, affectableStats );
        // when this spell is on a MOBs Affected list,
        // it should consistantly put the mob into
        // a sleeping state, so that nothing they do
        // can get them out of it.

        affectableStats.setWeight( 0 );
        affectableStats.setHeight( -1 );

        affectableStats.setDisposition(
        affectableStats.disposition()|PhyStats.IS_GOLEM);

        affectableStats.setDisposition(affectableStats.disposition()|PhyStats.IS_INVISIBLE);

        affectableStats.setDisposition(affectableStats.disposition()|PhyStats.IS_NOT_SEEN);

        affectableStats.setSensesMask(affectableStats.sensesMask()|PhyStats.CAN_NOT_SPEAK);
      }
    }
Last but not least, here is another example from the Core Topics, an `affectPhyStats()` method. This method will always have the host mob passed in the "affected" parameter, and a copy of his current PhyStats objects in the affectableStats parameter. This method then sets the mob as being both invisible, and totally unseen. It makes him unviewable to infrared, and prevents him from speaking. The two methods above then combine to produce our desired results, an Astral Spirit. ## Introduction to Skill Abilities Abilities are easily the most complicated and varied of all the objects in CoffeeMud. They encompass everything from invoked skills and spell, like TRIP or MAGIC MISSILE, to natural abilities, like NONDETECTION. A Skill Ability then is an object which implements the Ability interface fully, unlike the Property above, which implements only certain parts. An Ability is known in the mud as any of the following: A Spell, Song, Dance, Skill, Common Skill, Thief Skill, Poison, Disease, Prayer, Chant, or Trap. They all implement the Ability interface, which in turn extends the Environmental interface discussed throughout the rest of this document. Abilities make extensive use of the okMessage and executeMsg, tick, and stat affecting methods discussed above in the Core Topics. If you have not read the Core Topics, you should do so now. Abilities will all tend to extend the basic StdAbility class found in the Abilities package, and sometimes they will further extend a class more specific to their type, such as Spell, StdSkill, Song, BardSkill, Prayer, FighterSkill, ThiefSkill, Chant, or some other basic types found in the standard CoffeeMud distribution packages. Abilities are added to mob objects using the addAbility method on MOBs. From there, through casting or by autoInvocation (discussed below), they may end up in the effects list of a mob, item, room, area, or exit via the addEffect method. A Custom ability may or may not belong to any particular package, though it is important that the `ID()` of the ability be unique in the system. A custom ability imports the same packages mentioned in the first section of this document under Complete Default Import List as well as (in this case) com.planet_ink.coffee_mud.Abilities.StdAbility because our sample class extends it. A customized ability class usually extends the StdAbility class implemented in the aforementioned package. This StdAbility class already implements the Ability interface, and already has numerous support methods which aid in the creation of custom abilities. Each ability must also have custom `ID()` and `name()` methods as shown below. Notice that the `ID()` is the same as the name of the class. This is no accident -- this is required!
    public class Skill_Trip extends com.planet_ink.coffee_mud.Abilities.StdAbility
    {
      public String ID()
      {
        return "Skill_Trip";
      }

      public String name()
      {
        return "Trip";
      }
Above we see the aforementioned methods defined. This skill does not differ from other Abilities, or indeed other Environmental objects in this respect. A unique `ID()` and `name()` method must be defined for each new class.
      public String displayText()
      {
        return "(Tripped)";
      }
The display text on an Ability always refers to the text shown in the "You are affected by" section shown by the SCORE and AFFECTS commands in the MUD. In this case, someone affected by trip will see (Tripped). If this method does not leave any information for those affected by it, it should return "".
      protected int canAffectCode()
      {
        return CAN_MOBS;
      }

      protected int canTargetCode()
      {
        return CAN_MOBS;
      }
These two methods assist the MUDGrinder, and the HELP files in classifying the several skills and spells. The first method, `canAffectCode()`, returns what type of objects, if any, this ability class may find itself in the effects list of. Since our Trip skill effects the tripped mob, we list mobs. Other possible values include any combination of CAN_ROOMS, CAN_EXITS, CAN_ITEMS, or CAN_AREAS. If a skill may Effect more than one, they can be combined using the | operator. An example skill that affects both mobs and items might return CAN_MOBS|CAN_ITEMS, for instance. The second method, `canTargetCode()`, above tells the system what type of objects can be targeted by this skill. Some skills will target items (like the Enchant Weapon spell), or rooms (like the Darkness spell), or exits (like the Knock spell). In a similar fashion to canAffectCode, this method can return any combination of valid objects to notify the system of proper targets.
      public int abstractQuality()
      {
        return Ability.QUALITY_MALICIOUS;
      }
This MOST important method tells the system quite a bit about the nature of the skill, as well as how mobs with behaviors like CombatAbilities should use it. In this case, we return Ability.QUALITY_MALICIOUS, which tells the system that the skill is always malicious to others, and that it will most likely anger the target. It tells mobs to target this skill at enemies in combat Other possible values include:
Ability.QUALITY_BENEFICIAL_SELF | always helpful to oneself when used
Ability.QUALITY_BENEFICIAL_OTHERS | can be targeted to other people, and is always beneficial
Ability.QUALITY_OK_SELF | targets oneself, but is only useful in certain circumstances, or it has complicated parameters that mobs won't find useful
Ability.QUALITY_OK_OTHERS | targets other people, but is only useful under certain circumstances, or it also has complicated parameters
Ability.QUALITY_INDIFFERENT | targets items, or rooms, and is only useful in certain circumstances
Only skills marked as Ability.QUALITY_BENEFICIAL_* or Ability.QUALITY_MALICIOUS will be used in combat or by most behaviors.
      public int castingQuality( MOB invoker, Physical target )
      {
        return super.castingQuality( invoker, target );
      }
This second most important method is similar to the `abstractQuality()` method above, but it tells the system what the quality of the skills or spell is if it is specifically used by the given invoker against the given target at this given time. If your skill is only useful in water or against elves, it might be good to check to see if the invoker is in water or the target is an elf before returning a value. The same kinds of values may be returned from this method as are returned by abstractQuality, except for QUALITY_OK_OTHERS and Ability.QUALITY_OK_SELF, which are meaningless in this context.
      public boolean isAutoInvoked()
      {
        return false;
      }
All skills are either autoInvoking, or they must be invoked by a player or mob. The value returned by this method determines which sort this ability is. If it is autoinvoking, it will not have an invoke( method as described below, nor will it have trigger strings, nor will it return anything other than "" from it's `displayText()` method. An example of an autoInvoking ability would be Blind Fighting or Two Weapon Fighting. In our case, however, Trip is not autoinvoking, but requires a player to invoke it.
      private static final String[] triggerStrings = { "TRIP" };
      public String[] triggerStrings()
      {
        return triggerStrings;
      }

      public double castingTime(MOB mob, List<String> cmds)
      {
        return 0.25;
      }

      public double combatCastingTime(MOB mob, List<String> cmds)
      {
        return 1.0;
      }
For skills which are not autoinvoking, like this one, we must define an array of strings which constitute the command words to use this skill. Each entry in the array must be only one word. If more than one skill is found with the same trigger words (such as the spells, which all share the trigger word "CAST"), then the name of the specific ability will be the required next parameter. Trip, however, has a unique trigger word, which is defined by this method. Skills can also define how many actions they take to execute when the caster or user of the skill is in combat, or not in combat. The next two methods define this. A value of 0 means that the skill or spell is always instantaneous. A higher value means that the skill requires a full action to perform. Typical players have 1 action per tick (4 second period) to use.
      public int classificationCode()
      {
        return Ability.ACODE_SKILL;
      }
This important method defines which category an ability falls into. Possible values include: SKILL, PRAYER, SONG, TRAP, SPELL, THIEF_SKILL, LANGUAGE, CHANT, COMMON_SKILL, DISEASE, or POISON.
      public long flags()
      {
        return Ability.FLAG_MOVING;
      }
This method returns a value consisting of one or more flags, separated by | symbols in the same way that canAffectCode does above. Each flag has a specific meaning and imparts information to the engine about the ability. Possible values, which may be used alone or together in any combination, include:
FLAG_BINDING | Binds and or limits movement and the use of hands.
FLAG_MOVING | Changes the position of the target or affected one.
FLAG_TRANSPORTING | Changes the room of the target, requires that the performer of the skill be present.
FLAG_WEATHERAFFECTING | Changes the weather.
FLAG_SUMMONING | Changes the room of the target, where the performer of the skill is not present. May also bring new creatures into existence.
FLAG_CHARMING | Charms the target.
FLAG_TRACKING | Results in the target tracking something.
FLAG_HEATING | Makes the target hot.
FLAG_BURNING | Makes the target on fire.
FLAG_HOLY | Means that the skill is GOOD aligned, unless FLAG_UNHOLY is also set, in which case it makes the skill NEUTRAL.
FLAG_UNHOLY | Means that the skill is EVIL aligned, unless FLAG_UNHOLY is also set, in which case it makes the skill NEUTRAL.
FLAG_PARALYZING | Makes the target or affected one unable to move their muscles.
      public void affectPhyStats( Physical affected, PhyStats affectableStats )
      {
        super.affectPhyStats( affected, affectableStats );
        if( !doneTicking )
        {
          affectableStats.setDisposition( affectableStats.disposition() | PhyStats.IS_SITTING);
        }
      }
This is an example of the `affectPhyStats()` method described in the Core Topics. In the case of our Trip skill, it forces the affected target into a sitting position.
      public boolean okMessage( Environmental myHost, CMMsg msg )
      {
        if( ( affected == null ) || ( !( affected instanceof MOB ) ) )
        {
          return true;
        }

        MOB mob = (MOB)affected;
        if( doneTicking && msg.amISource( mob ) )
        {
          unInvoke();
        }
        else
        if( msg.amISource( mob )
        && ( msg.sourceMinor() == CMMsg.TYP_STAND ))
        {
          return false;
        }
        return true;
      }
This is an example of the `okMessage()` method described in the Core Topics. In this case, it intercepts messages where the affected mob is trying to stand and cancels the message, without comment, by returning false.
      public void unInvoke()
      {
        if( ( affected == null ) || ( !( affected instanceof MOB ) ) )
        {
          return;
        }

        MOB mob = (MOB)affected;
        if( canBeUninvoked() )
        {
          doneTicking = true;
        }

        super.unInvoke();

        if( !mob.amDead() )
        {
          if( mob.location() != null )
          {
            CMMsg msg = CMClass.getMsg( mob, null, CMMsg.MSG_NOISYMOVEMENT, "<S-NAME> regain(s) <S-HIS-HER> feet.");
            if( mob.location().okMessage( mob, msg ) )
            {
              mob.location().send( mob, msg );
              CMLib.commands().postStand( mob, true );
            }
          }
          else
          {
            mob.tell( "You regain your feet." );
          }
        }
      }
All standard abilities include an `unInvoke()` method, which is called when the Effect caused by the ability is dispelled, or the duration of the ability expires. The `super.unInvoke()` method, which is located in StdAbility.java, actually does the work of removing the Effect from the affected object (stored in the variable affected), and then setting affected to null. In this particular `unInvoke()` method, we also see the code trying to force the mob back to his feet.
      public boolean preInvoke( MOB mob, List<String> commands, Physical givenTarget, boolean auto,
                                int asLevel, int secondsElapsed, double actionsRemaining )
      {
        return true;
      }
The `preInvoke()` method is an optional method that normally just returns true. Unless you have reason to do so, you do not need to override the standard preInvoke method in StdAbility.java. The preInvoke method must return true before the `invoke()` method (below) is executed. The difference between the two is that the preInvoke method is called at the moment the skill command words are entered, even if the skill is coded, via the `castingTime()` or `combatCastingTime()` methods, to invoke at some later time. If your skill does invoke at a later time, it is generally useful to use the preInvoke method to scan the commands Vector, which contains the command parameter strings minus any trigger words, for errors. You may also give the user a message that their skill will invoke later on. The preInvoke method will continue to be called, at 1 second intervals, until the player is able to invoke the command.
      public boolean invoke( MOB mob, List<String> commands, Physical givenTarget, boolean auto, int asLevel )
      {
If an ability is not autoinvoked, it will always have a functional invoke method. This invoke method includes the following parameters: the mob invoking the ability and a vector of command parameter strings (which does not include any trigger words). The givenTarget parameter, which is null on normal ability invocations, will have the value of a target to the skill if one is available. Calls to the invoke method where the givenTarget is not null are typically from potions, wands, traps, or other automatic invocations. Which brings us to the last parameter, auto. Auto is false on normal invocations of the skill, and true whenever the skill should always invoke no matter what. Setting auto to true not only changes the output string for the skill, but overrides proficiency checks as well.
        MOB target = this.getTarget( mob, commands, givenTarget );
        if( target == null )
        {
          return false;
        }
Our first step in Trip is to get our target. There are several `getTarget()` methods built into StdAbility for determining a target object based on the command parameters passed in, as well as the `abstractQuality()` value for the ability. The StdAbility method call to `getTarget()` is smart enough to know that if a target name is not specified by givenTarget, and also one is not specified in the commands Vector passed in, that it should choose whoever the mob is fighting, since the ability isAbility.QUALITY_MALICIOUS. Non-malicious skills would not follow this reasoning, but would choose the caster himself as default. All of the several `getTarget()` methods will generate their own error messages to the user if a target is not specified, or found, or cannot be determined. For this reason, we need only to check to see if a target has been returned. If not, we can return false from `invoke()`, telling the system that the ability failed to invoke.
        if( CMLib.flags().isSitting( target )
        || CMLib.flags().isSleeping( target ))
        {
          mob.tell( target, null, null, "<S-NAME> is already on the floor!" );
          return false;
        }

        if( !CMLib.flags().isAliveAwakeMobile( mob, true )
        ||( CMLib.flags().isSitting( mob ) ))
        {
          mob.tell( "You need to stand up!" );
          return false;
        }

        if( mob.isInCombat() && ( mob.rangeToTarget() > 0 ) )
        {
          mob.tell( "You are too far away to trip!" );
          return false;
        }

        if( target.riding() != null )
        {
          mob.tell( "You can't trip someone " + target.riding().stateString( target ) + " " + target.riding().name() + "!");
          return false;
        }

        if( CMLib.flags().isFlying( target ) )
        {
          mob.tell( target.name(mob) + " is flying and can't be tripped!" );
          return false;
        }
Here are numerous checks to see if the invoking mob is able to trip, and the target is able to be tripped.
        if( !super.invoke( mob, commands, givenTarget, auto ) )
        {
          return false;
        }
The `invoke()` method back up in StdAbility is called now. This method will check mana requirements, and subtract mana if necessary. It should be called AFTER all other preliminary checks have been made.
        int levelDiff = target.phyStats().level() - mob.phyStats().level();
        if( levelDiff > 0 )
        {
          levelDiff = levelDiff * 5;
        }
        else
        {
          levelDiff = 0;
        }

        Double temp = Integer.valueOf(target.charStats().getStat(CharStats.STAT_DEXTERITY)).doubleValue() - 9.0;

        int adjustment = (-levelDiff) + (-( 35 + ( (int)Math.round( temp * 3.0 ) ) ) );

        boolean success = proficiencyCheck( mob, adjustment, auto );
The `proficiencyCheck()` method called at the end here will determine of the user of the skill has passed their proficiency check. The first parameter of this method is the invoking mob, followed by either a positive (or helpful) adjustment, or a negative (not helpful) adjustment. The second parameter is the auto flag mentioned above, to allow overrides of the normal proficiency. In the case of Trip, we calculate an adjustment based both on level and the dexterity of the target. We store whether or not the proficiency check failed or passed into the variable success.
        success = success && ( target.charStats().getBodyPart( Race.BODY_LEG ) > 0 );

        if( success )
        {
          CMMsg msg = CMClass.getMsg( mob, target, this,
                                      CMMsg.MSK_MALICIOUS_MOVE|CMMsg.TYP_JUSTICE|( auto ? CMMsg.MASK_ALWAYS : 0 ),
                                      auto ? "<T-NAME> trip(s)!" : "^F<S-NAME> trip(s) <T-NAMESELF>!^?"
          );

          if( mob.location().okMessage( mob, msg ) )
          {
            mob.location().send( mob, msg );
            int durationTicks = ( msg.value() > 0 ) ? 1 : 2;
            maliciousAffect( mob, target, asLevel, durationTicks, -1 );
            target.tell( "You hit the floor!" );
          }
        }
        else
        {
          return maliciousFizzle( mob, target, "<S-NAME> attempt(s) to trip <T-NAMESELF>, but fail(s).");
        }

        return success;
      }
    }
The rest of the `invoke()` method actually does the work of sending the trip message and affecting the target if necessary, or sending the "fizzle" message if the proficiency check failed (success was false). Of special note are some of the other StdAbility method calls in this section of code. You'll notice that the message constructed (as per the Core Topics discussion in a previous section) in this case uses a TYP_JUSTICE message (meaning an attack on dignity), with the malicious and movement flags set. If this message gets sent, a call to `maliciousAffect()` is made. The first parameter is the invoker, and the second parameter is the one its being invoked upon. The third parameter is the level of the affect, or 0 for default values. The forth parameter is the duration of the Effect in ticks, which you can see is dependent in this case upon whether the message came back with a `value() > 0` (meaning the saving throw was made). If the forth parameter is 0, then the default duration formula will be used. All other positive values, such as in this case, denote a number of ticks of duration. The last parameter, normally -1, asks `maliciousAffect()` to give the target one more saving throw, against any of the valid saving throw type messages, such as TYP_FIRE, TYP_ACID, TYP_GAS, etc. The value of -1 means not to make any further saving throw attempts before affecting the target. If this skill had not been malicious, we could have made a call to the `beneficialAffect()` method instead. That method has the same parameters as `maliciousAffect()`, though it lacks the final parameter for a further saving throw, since beneficial affects require no saving throw. Now, if the success variable had been false, then we made a call to the `maliciousFizzle()` method. In addition to a display in the room, this method will make sure the target knows that the invoking mob was trying to do something bad to him or her, so that the target will get angry and start fighting. Had this not been a malicious ability, we would have made calls instead to either the `beneficialWordsFizzle()` method, or the `beneficialVisualFizzle()` method, depending upon whether the skill is verbal or somantic based. Most spells are verbal based, for instance, while most skills are somantic. Finally, we return the results of the success variable from the `invoke()` method, to let the system know whether or not the ability succeeded. If it did, the target will now be affected by this ability, and will have to stay on the ground for a few ticks while the source mob pounds on him or her. ## Spells, Prayers, and Chants Spells, Prayers, and Chants are all special forms of Abilities. For this reason, it is required that you go back and read the previous section on Skill Abilities before proceeding. You will also be required to poke through the Core Topics elsewhere in this document as well. ### Spells Spells will follow all the rules mentioned above in the Skill Abilities section, with a few differences:
    public class Spell_ResistFire extends com.planet_ink.coffee_mud.Abilities.Spells.Spell
    {
      public String ID()
      {
        return "Spell_ResistFire";
      }

      public String name()
      {
        return "Resist Fire";
      }

      public String displayText()
      {
        return "(Resist Fire)";
      }

      public int abstractQuality()
      {
        return Ability.QUALITY_BENEFICIAL_OTHERS;
      }

      protected int canAffectCode()
      {
        return CAN_MOBS;
      }

      public int classificationCode()
      {
        return Ability.ACODE_SPELL|Ability.DOMAIN_ABJURATION;
      }
The first difference you will notice above is that spells extend the base class Spell.java found in the Abilities/Spells directory instead of StdAbility. Spell.java also extends StdAbility as well. The second difference is in the `classificationCode()` method. You will notice that the domain of the spell is also specified. In addition to the normal classification code of Ability.ACODE_SPELL, the domain may be added using the | symbol. Possible domains include:
DOMAIN_DIVINATION | Spells that grant knowledge.
DOMAIN_ABJURATION | Spells that protect.
DOMAIN_ILLUSION | Spells that fool the senses.
DOMAIN_EVOCATION | Spells that bring forth the elements.
DOMAIN_ALTERATION | Spells that change things.
DOMAIN_TRANSMUTATION | Spells that change people.
DOMAIN_ENCHANTMENT | Spells that enchant items or the mind.
DOMAIN_CONJURATION | Spells that transport people or items.
      public boolean invoke( MOB mob,List<String> commands, Physical givenTarget, boolean auto, int asLevel)
      {
        MOB target = getTarget( mob, commands, givenTarget );
        if( target == null )
        {
          return false;
        }

        if( !super.invoke( mob, commands, givenTarget, auto ) )
        {
          return false;
        }

        boolean success = proficiencyCheck( mob, 0, auto );
        if( success )
        {
          CMMsg msg = CMClass.getMsg( mob, target, this, affectType( auto ), auto ?
                                      "<T-NAME> feel(s) cooly protected."
                                    : "^S<S-NAME> invoke(s) a cool field of protection around <T-NAMESELF>.^?"
          );

          if( mob.location().okMessage( mob, msg ) )
          {
            mob.location().send( mob, msg );
            beneficialAffect( mob, target, asLevel, 0 );
          }
        }
        else
        {
           beneficialWordsFizzle( mob, target, "<S-NAME> attempt(s) to invoke fire protection, but fail(s).");
        }

        return success;
      }
    }
The `invoke()` method above follows the one in Skill_Abilities very closely. You will see that no adjustment is made to the proficiency check, and that, since this is not aAbility.QUALITY_MALICIOUS ability, calls are made to `beneficialAffect()` and `beneficialWordsFizzle()` instead of `maliciousAffect()` and `maliciousFizzle()`. The main difference to notice here, however, is the line constructing the evoking message. You will notice that where the message code should be specified, a method call to `affectType()`, which is a method located in Spell.java, is made. This call will automaticallyy construct the proper message type for a spell, taking into accountAbility.QUALITY_MALICIOUSness, and whether the auto flag is set. You will also notice that different message strings are constructed depending upon whether the auto flag is set. ### Prayers Prayers will follow all the rules mentioned above in the Skill Abilities section, with a few differences:
    public class Prayer_Anger extends com.planet_ink.coffee_mud.Abilities.Prayers.Prayer
    {
      public String ID()
      {
        return "Prayer_Anger";
      }

      public String name()
      {
        return "Anger";
      }

      public int abstractQuality()
      {
        return Ability.QUALITY_MALICIOUS;
      }

      public long flags()
      {
        return Ability.FLAG_UNHOLY;
      }

      public boolean invoke( MOB mob, List<String> commands, Physical givenTarget, boolean auto, int asLevel )
      {
        if( !super.invoke( mob, commands, givenTarget, auto ) )
        {
          return false;
        }

        boolean success = proficiencyCheck( mob, 0, auto );

        boolean someoneIsFighting = false;
        for( int i = 0; i < mob.location().numInhabitants(); i++ )
        {
          MOB inhab = mob.location().fetchInhabitant( i );
          if( ( inhab != null ) && ( inhab.isInCombat() ) )
          {
            someoneIsFighting = true;
          }
        }

        if( success
        &&( !someoneIsFighting )
        &&( mob.location().numInhabitants() > 3 ))
        {
          // it worked, so build a copy of this ability,
          // and add it to the effects list of the
          // affected MOB. Then tell everyone else
          // what happened.
           CMMsg msg = CMClass.getMsg( mob, null, this, affectType(auto), auto?"A feeling of anger descends": "^S<S-NAME> rage(s) for anger.^?" );

           if( mob.location().okMessage( mob, msg ) )
           {
             mob.location().send( mob, msg );

             [.......]
    }
The first difference you may notice between this and the Skill Ability discussed in the previous section is that this skill extends the Prayer.java class instead of StdAbility. Prayer.java will make sure that the `classificationCode()` method returns the proper value. You should also take note of the `flags()` method. All Prayers must return a value from `flags()` where either the FLAG_UNHOLY is set (meaning the Prayer is EVIL aligned), FLAG_HOLY is set (meaning the Prayer is GOOD aligned), or BOTH are set, in which case the Prayer is NEUTRAL. The last special note is down in the message construction in the `invoke()` method. The `invoke()` method above follows the one in Skill_Abilities very closely. You will see that no adjustment is made to the proficiency check, for instance. The main difference to notice here, however, is the line constructing the evoking message. You will notice that where the message code should be specified, a method call to `affectType()`, which is a method located in Prayer.java, is made. This call will automaticallyy construct the proper message type for a prayer, taking into accountAbility.QUALITY_MALICIOUSness, and whether the auto flag is set. You will also notice that different message strings are constructed depending upon whether the auto flag is set. ### Chants Chants will follow all the rules mentioned above in the Skill Abilities section, with a few differences:
    public class Chant_AlterTime extends com.planet_ink.coffee_mud.Abilities.Druid.Chant
    {
      public String ID()
      {
        return "Chant_AlterTime";
      }

      public String name()
      {
        return "Alter Time";
      }

      public String displayText()
      {
        return "";
      }

      public int overrideMana()
      {
        return 100;
      }

      public int abstractQuality()
      {
        return Ability.QUALITY_INDIFFERENT;
      }

      protected int canAffectCode()
      {
        return 0;
      }

      protected int canTargetCode()
      {
        return 0;
      }

      public boolean invoke( MOB mob, List<String> commands, Physical givenTarget, boolean auto, int asLevel )
      {
        if( !super.invoke( mob, commands, givenTarget, auto ) )
        {
          return false;
        }

        boolean success = proficiencyCheck( mob, 0, auto );
        if( success )
        {
          // it worked, so build a copy of this ability,
          // and add it to the effects list of the
          // affected MOB. Then tell everyone else
          // what happened.
          CMMsg msg = CMClass.getMsg( mob, null, this, affectType( auto ), auto ? "" : "^S<S-NAME> chant(s), and reality seems to start blurring.^?" );

          if( mob.location().okMessage( mob, msg ) )
          {
            mob.location().send( mob, msg );
            int x = CMath.s_int( text() );
            while( x == 0 )
            {
              x = CMLib.dice().roll( 1, 3, -2 );
            }

            if( x > 0 )
            {
              mob.location().showHappens( CMMsg.MSG_OK_VISUAL, "Time moves forwards!" );
            }
            else
            {
              mob.location().showHappens( CMMsg.MSG_OK_VISUAL, "Time moves backwards!" );
            }

            if( CMLib.map().numAreas() > 0 )
            {
              CMLib.map().getFirstArea().tickTock( x );
            }
          }
        }
        else
        {
          return beneficialWordsFizzle( mob, null, "<S-NAME> chant(s), but the magic fades" );
        }

        // return whether it worked
        return success;
      }
    }
The first difference you may notice between this and the Skill Ability discussed in the previous section is that this skill extends the Chant.java class instead of StdAbility. Chant.java will make sure that the `classificationCode()` method returns the proper value. You should also take note that the `overrideMana()` method is actually returning a value here of 100. This method allows your ability to always cost the same amount of mana, regardless of the invokers level. This method may be used in any ability, not just chants. Also, this is not a method that is normally found in chants. This particular chant, being deemed to be especially powerful, happens to return a value for it. Normally this method would not be found. The last special note is down in the message construction in the `invoke()` method. The `invoke()` method above follows the one in Skill_Abilities very closely. You will see that no adjustment is made to the proficiency check, for instance. The main difference to notice here, however, is the line constructing the evoking message. You will notice that where the message code should be specified, a method call to `affectType()`, which is a method located in Chant.java, is made. This call will automaticallyy construct the proper message type for a chant, taking into accountAbility.QUALITY_MALICIOUSness, and whether the auto flag is set. You will also notice that different message strings are constructed depending upon whether the auto flag is set. ## Songs Although Songs also follow the Skill Abilities rules above, they are the most unique of skills. More than any other skill, they rely very heavily on basic functionality provide by their appropriate superclasses. For your sanity, I recommend that ALL of your coded songs extend either com.planet_ink.coffee_mud.Abilities.Songs.Song, com.planet_ink.coffee_mud.Abilities.Songs.Dance, or com.planet_ink.coffee_mud.Abilities.Songs.Play. This is because those classes provide very important basic functionality unique to songs, and save you as the coder from having to worry about coding that unique functionality yourself. By unique functionality, I am referring to the way songs behave when invoked in particular. They are always invoked upon groups, and always require the invoker to remain in the room for the song to remain in effect.
    public class Song_Protection extends com.planet_ink.coffee_mud.Abilities.Songs.Song
    {
      public String ID()
      {
        return "Song_Protection";
      }

      public String name()
      {
        return "Protection";
      }
Like the skill abilities above, `ID()` and `name()` are implemented. The `name()` will get intermingled into the invocation text, so name your songs carefully, so they sound right when invoked!
      public int abstractQuality()
      {
        return Ability.QUALITY_BENEFICIAL_OTHERS;
      }
This method, discussed above for skill abilities, is absolutely vital for Songs, as it tells the Song superclass whether to invoke the song upon all your enemies, or upon all your group members. Make sure you implement this method!
      public void affectPhyStats( Physical affected, PhyStats affectableStats )
      {
        super.affectPhyStats( affected, affectableStats );
        if( invoker == null )
        {
          return;
        }

        affectableStats.setAttackAdjustment( affectableStats.attackAdjustment() - 5 );
      }
This particular song uses affectPhyStats to lower the attack rating of everyone that hears the song. Although this is not a malicious song, it is the price of using it.
      public void affectCharStats( MOB affected, CharStats affectableStats )
      {
        super.affectCharStats( affected, affectableStats );
        if( invoker == null )
        {
          return;
        }

        affectableStats.setStat( CharStats.STAT_DEXTERITY,
        affectableStats.getStat( CharStats.STAT_DEXTERITY ) - 1 );

        affectableStats.setStat( CharStats.STAT_SAVE_ACID,
                                 affectableStats.getStat( CharStats.STAT_SAVE_ACID )
                                 + (invoker.charStats().getStat( CharStats.STAT_CHARISMA ) * 4)
                               );

        affectableStats.setStat( CharStats.STAT_SAVE_COLD,
                                 affectableStats.getStat( CharStats.STAT_SAVE_COLD )
                                 + (invoker.charStats().getStat(CharStats.STAT_CHARISMA) * 4)
                               );

        affectableStats.setStat( CharStats.STAT_SAVE_ELECTRIC,
                                 affectableStats.getStat( CharStats.STAT_SAVE_ELECTRIC )
                                 + ( invoker.charStats().getStat( CharStats.STAT_CHARISMA ) * 4 )
                               );

        affectableStats.setStat( CharStats.STAT_SAVE_FIRE,
                                 affectableStats.getStat( CharStats.STAT_SAVE_FIRE )
                                 + ( invoker.charStats().getStat( CharStats.STAT_CHARISMA ) * 4 )
                               );

        affectableStats.setStat( CharStats.STAT_SAVE_GAS,
                                 affectableStats.getStat( CharStats.STAT_SAVE_GAS )
                                 + ( invoker.charStats().getStat( CharStats.STAT_CHARISMA ) * 4 )
                               );
      }
    }
The most important thing our sample song does is improve the saving throws of everyone who hears it. The `affectCharStats()` method makes that happen by modifying the appropriate saving throws in affectableStats. ## Common Skills There are actually 3 unique kinds of common skills. One type is simply a normal skill, just like the ones shown above. Another type is the gathering skill, which is used to collect resources, and extends com.planet_ink.coffee_mud.Abilities.Common.GatheringSkill. The last type is the crafting skill, which extends com.planet_ink.coffee_mud.Abilities.Common.CraftingSkill. In general, common skills have this in common: they invoke immediately, but take a long time to complete. They give messages of progress to the user, and they immediately unInvoke themselves if the user leaves the room, enters combat, or some other canceling condition arises. Let's look at a Gathering skill. Although Crafting skills are much more involved, especially in the way they select the items they create, and in the way they fill-in the variables for what they are creating, you will find them remarkably similar to gathering skills.
    public class Fishing extends com.planet_ink.coffee_mud.Abilities.Common.GatheringSkill
    {
      public String ID()
      {
        return "Fishing";
      }

      public String name()
      {
        return "Fishing";
      }
If you've read the Skill Abilities section above, you will recognize these methods and their importance. As always, the `ID()` must match the class name, while the `name()` can be whatever you want to call the skill.
      private static final String[] triggerStrings = { "FISH" };
      public String[] triggerStrings()
      {
        return triggerStrings;
      }
And again, like a normal skill, the common skills create and return their invocation words (or "trigger strings" as they are called in skills).
      public long flags()
      {
        return FLAG_GATHERING;
      }

      public String supportedResourceString()
      {
        return "FLESH";
      }
The `flags()` method you will also recognize from the Skill Abilities section. However, we've provided the system at large with a flag to let it know that this skill is for gathering resources, and not for crafting. The `supportedResourceString()` is a great supplementary method that is unique to Common Skills. It's purpose is to inform the system what kinds of MATERIALS and RESOURCES are utilized by this skill. Fishing is for catching fish, so we'll notify the system that we deal in meat (flesh). Appropriate strings to return from this method are listed in com.planet_ink.coffee_mud.Items.interfaces.RawMaterial.java. If there is more than one resource or material type, they are separated with the pipe | character.
      protected Item found = null;
      protected String foundShortName = "";
Almost all the common skills create the item that they will generate in the invoke method, store it in the skill, and then provide it when the skill is unInvoked. For this reason, we'll need some variables to store the object we will create, and a string for its name.
      public Fishing()
      {
        super();
        displayText = "You are fishing...";
        verb = "fishing";
      }
Our constructor sets the variable "verb", which is part of the CommonSkill superclass. It is used when constructing sentences which let the user and others around them know what they are doing. displayText serves the same purpose described by the Skill Abilities section above.
      public boolean tick( Tickable ticking, int tickID )
      {
        if( ( affected != null )
        && ( affected instanceof MOB )
        && ( tickID == Tickable.TICKID_MOB ))
        {
          MOB mob = (MOB)affected;
          if( tickUp == 6 )
          {
            if( found != null )
            {
              commonTell( mob, "You got a tug on the line!" );
            }
            else
            {
              StringBuffer str = new StringBuffer( "Nothing is biting around here.\n\r" );
              commonTell( mob, str.toString() );
              unInvoke();
            }
          }
        }
        return super.tick( ticking, tickID );
      }
Although our common skill super classes do most of the hard work of maintaining the task being performed, you will still find that they are often extended by individual common skills in other to give more appropriate messages to the user. If you don't know what a tick method is fore, read the Core Topic on the subject first. In this case, before calling the superclasses tick method and letting it do most of our work, we take a moment to check the tickUp integer maintained by CommonSkill.java. That variable is incremented every 4 seconds after the skill is invoked. in this case, after 24 seconds (6*4), we let the user know whether or not an item was generated by the invoke method. If an an item was invoked, we tell them they have hooked a fish. If an item was not generated, we tell them that nothing is biting and immediately `unInvoke()` the skill. The `commonTell()` method is another feature unique to common skills. Since common skills are often found on hireling mobs, we wanted a special method which would tell players who invoke the skill about the progress of our task, even if it is a follower that is actually DOING the task. For instance, `commonTell()` would tell a player who is fishing "You got a tug on the line!". However, commonTell would force an NPC follower of a player to SAY "I got a tug on the line!".
      public void unInvoke()
      {
        if( canBeUninvoked() )
        {
          if( ( affected != null ) && ( affected instanceof MOB ) )
          {
            MOB mob = (MOB)affected;
            if( ( found != null )
            && ( !aborted )
            &&( !helping ))
            {
              int amount = CMLib.dice().roll( 1, 5, 0 ) * ( abilityCode() );
              String s = "s";
              if( amount == 1 )
              {
                s = "";
              }

              mob.location().show( mob, null, CMMsg.MSG_NOISYMOVEMENT, "<S-NAME> manage(s) to catch " + amount + " pound"
                                   + s + " of " + foundShortName + "." );

              for( int i = 0; i < amount; i++ )
              {
                Item newFound = (Item)found.copyOf();
                mob.location().addItem( newFound, ItemPossessor.ItemExpiration.Player_Drop );

                if( ( mob.riding() != null )
                && ( mob.riding() instanceof Container ))
                {
                  newFound.setContainer( (Container)mob.riding() );
                }
                CMLib.commands().postGet( mob, null, newFound, true );
              }
            }
          }
        }
        super.unInvoke();
      }
As mentioned above, the `unInvoke()` method is where the final work is done. So long as the skill has not been aborted (the aborted variable), or the skill was invoked only to help ANOTHER player (the helping variable), we go ahead and create several copies of our target item, put them in the room using addItem, and force the player to get them into their inventory (if they can).
      public boolean invoke( MOB mob, List<String> commands, Physical givenTarget, boolean auto, int asLevel )
      {
        bundling = false;
        if( (!auto)
        && ( commands.size() > 0 )
        && ( ( (String)commands.firstElement() ).equalsIgnoreCase( "bundle" ) ))
        {
          bundling = true;
          if( super.invoke( mob, commands, givenTarget, auto, asLevel ) )
          {
            return super.bundle( mob, commands );
          }
          return false;
        }
The `invoke()` method is where common skills do 99% of their work, namely determining what the user wants to do and whether they have the resources and are in the right place to do it, and then actually generating the target item and filling it out. Then the invoke method actually places the filled-out common skill on the player as an "effect", allowing it to receive "tick" calls until it completes. In this case, right off the bat we check to see if the user is trying to use the Fishing skill to bundle up a pile of fish. If so, we call a superclass helper method to do the bundling for us. The bundle method which will happily use the `supportedResourceString()` method above to determine what the player is allowed to bundle.
        int foundFish = -1;
        boolean maybeFish = false;
        if( mob.location() != null )
        {
          for( int i = 0; i < RawMaterial.FISHES.length; i++ )
          {
            if( mob.location().myResource() == RawMaterial.FISHES[i] )
            {
              foundFish = RawMaterial.FISHES[i];
              maybeFish = true;
            }
            else
            if( ( mob.location().resourceChoices() != null )
            && ( mob.location().resourceChoices().contains(Integer.valueOf( RawMaterial.FISHES[i] ) ) ) )
            {
              maybeFish = true;
            }
          }
        }
Our next step is to initialize a variable for the com.planet_ink.coffee_mud.Items.interfaces.RawMaterial.java (resource) code which will represent the type of fish we have caught here. We also set a variable saying whether or not ANY fish are even POSSIBLY available here.
        if( !maybeFish )
        {
          commonTell( mob, "The fishing doesn't look too good around here." );
          return false;
        }
If maybeFish is false, we are in a location where no fish are even possibly available (such as a Desert room).
        verb = "fishing";
        found = null;
        playSound = "fishreel.wav";
Otherwise, we re-initialize the "verb" and "found" variables we mentioned above, and set a CommonSkill string called "playSound" which will be used to give our skill a little sound effect while it is working.
        if( !super.invoke( mob, commands, givenTarget, auto, asLevel ) )
        {
          return false;
        }
Next we call the GatherSkill superclass invoke method. It is important to note that several qualifying checks are made in that method, such as whether the player is able to perform the skill. It also subtracts the necessary mana or movement points for using the skill.
        if( ( proficiencyCheck( mob, 0, auto ) )
        && ( foundFish > 0 ))
        {
          found = (Item)CMLib.materials().makeResource( foundFish, mob.location().domainType(), false, null );
          foundShortName = "nothing";
          if( found != null )
          {
            foundShortName = RawMaterial.CODES.NAME( found.material()).toLowerCase();
          }
        }
Now we check to see if two important conditions have occurred; the first being whether the player has passed his or her proficiency check, and the second being whether the foundFish variable was assigned. Remember that the foundFish variable represents the material & resource code for the type of fish we will catch. If both of those are true, we make use of a very useful method in the `utensils()` library called makeResource to generate our item for us. We also properly set the name of what we have caught based on the material type of the foundFish.
        int duration = 35 - mob.phyStats().level();
        if( duration < 10 )
        {
          duration=10;
        }

        CMMsg msg = CMClass.getMsg( mob, found, this, CMMsg.MSG_NOISYMOVEMENT, "<S-NAME> start(s) fishing." );

        if( mob.location().okMessage( mob, msg ) )
        {
          mob.location().send( mob, msg );
          found = (Item)msg.target();
          beneficialAffect( mob, mob, asLevel, duration );
        }
        return true;
      }
    }
Our last step is to calculate the amount of time (duration) that it will take to catch the fish, create a coffeemud message to declare the start of our finishing adventure, and send the message out. After doing so, notice that we re-set the found variable to `msg.target()`. This may seem strange, since, in the getMsg method, we already declared found to be our message target. So isn't that like saying that A=A? Actually no! Remember that the okMessage method may preview or *modify* a message. Re-setting the found variable to `msg.target()` is done to support code which may have modified our target to something else. Now we'll take a look at a proper crafting skill. They are more complicated than gathering skills, but you'll be able to apply almost all you learned by reviewing the gathering skill to build a good picture of the way crafting skills work. The first difference is that the crafting skills extend com.planet_ink.coffee_mud.Abilities.Common.CraftingSkill. Many of them also implement the com.planet_ink.coffee_mud.Abilities.interfaces.ItemCrafter interface, which allows them to provide items to other parts of coffeemud instantly!
    public class GlassBlowing extends CraftingSkill implements ItemCraftor
    {
      public String ID()
      {
        return "GlassBlowing";
      }

      public String name()
      {
        return "Glass Blowing";
      }
If you've read the Skill Abilities section above, you will recognize these methods and their importance. As always, the `ID()` must match the class name, while the `name()` can be whatever you want to call the skill.
      private static final String[] triggerStrings = { "GLASSBLOW", "GLASSBLOWING" };
      public String[] triggerStrings()
      {
        return triggerStrings;
      }
And again, like a normal skill, the common skills create and return their invocation words (or "trigger strings" as they are called in skills).
      public String supportedResourceString()
      {
        return "GLASS|SAND";
      }
The `supportedResourceString()` is a great supplementary method that is unique to Common Skills. It's purpose is to inform the system what kinds of MATERIALS and RESOURCES are utilized by this skill. GlassBlowing is for turning sand into glass, so we'll notify the system that we deal in sand and glass resources. Appropriate strings to return from this method are listed in com.planet_ink.coffee_mud.Items.interfaces.RawMaterial.java. If there is more than one resource or material type, they are separated with the pipe | character.
      protected static final int RCP_FINALNAME = 0;
      protected static final int RCP_LEVEL = 1;
      protected static final int RCP_TICKS = 2;
      protected static final int RCP_WOOD = 3;
      protected static final int RCP_VALUE = 4;
      protected static final int RCP_CLASSTYPE = 5;
      protected static final int RCP_MISCTYPE = 6;
      protected static final int RCP_CAPACITY = 7;
      protected static final int RCP_SPELL = 8;
This list is at the core of the crafting skills It represents the name and function of each column of the crafting skill's text file. Later on, we will use these constants to index into a Vector that represents the particular row from the crafting skill's text file that the player is building.
      public String parametersFormat()
      {
        return
        "ITEM_NAME\tITEM_LEVEL\tBUILD_TIME_TICKS\tMATERIALS_REQUIRED\tITEM_BASE_VALUE\t"
        +"ITEM_CLASS_ID\tLID_LOCK\tCONTAINER_CAPACITY||LIQUID_CAPACITY\tCODED_SPELL_LIST";
      }
The `parametersFormat()` method supports the recipe editors, both online and command line, but giving the engine a coded representation of the meaning of each column as specified above. Each column is tab-delimited, and each entry is one of the specific value codes. If a column can have multiple meanings, usually based on class, it is separated by || characters. Value codes include: OPTIONAL_RESOURCE_OR_MATERIAL, AMMO_TYPE, BASE_ARMOR_AMOUNT, WEAPON_TYPE, REQUIRED_COMMON_SKILL_ID, AMMO_CAPACITY, MATERIALS_REQUIRED, SPELL_ID, CONTAINER_TYPE_OR_LIDLOCK, ITEM_BASE_VALUE, ITEM_NAME, AMOUNT_MATERIAL_REQUIRED, N_A, POSE_DESCRIPTION, RESOURCE_NAME, ATTACK_MODIFICATION, STATUE, WEAPON_CLASS, LIQUID_CAPACITY, OPTIONAL_RACE_ID, RESOURCE_OR_MATERIAL, CODED_WEAR_LOCATION, CONTAINER_TYPE, INSTRUMENT_TYPE, CLAN_ITEM_CODENUMBER, MAXIMUM_RANGE, RESOURCE_OR_KEYWORD, LID_LOCK, OPTIONAL_AMOUNT_REQUIRED, SMELL_LIST, LIGHT_DURATION, READABLE_TEXT, CODED_SPELL_LIST, BUILD_TIME_TICKS, POSE_NAME, METAL_OR_WOOD, RESOURCE_NAME_AMOUNT_MATERIAL_REQUIRED, CLAN_EXPERIENCE_COST_AMOUNT, CLAN_AREA_FLAG, RESOURCE_NAME_OR_HERB_NAME, CONTAINER_CAPACITY, ITEM_LEVEL, BASE_DAMAGE, ITEM_CLASS_ID, RIDE_CAPACITY, FOOD_DRINK, WOOD_METAL_CLOTH, WEAPON_HANDS_REQUIRED, RIDE_BASIS, HERB_NAME, SMOKE_FLAG, STONE_FLAG
      protected Item building = null;
      protected Item fire = null;
      protected boolean messedUp = false;
As in the gathering skill, we need to set up our global variables to remember the object we are crafting, since it will be constructed below in our invoke method, but not sent out into the world until the unInvoke method. We also need a reference to the fire object we are using, so we can watch and see if it goes out.
      public boolean tick( Tickable ticking, int tickID )
      {
        if( ( affected != null )
        && ( affected instanceof MOB )
        && ( tickID == Tickable.TICKID_MOB ))
        {
          MOB mob = (MOB)affected;
          if( ( building == null )
          || ( fire == null )
          || ( !CMLib.flags().isOnFire( fire ) )
          || ( !mob.location().isContent( fire ) )
          || ( mob.isMine( fire ) ) )
          {
            messedUp = true;
            unInvoke();
          }
        }
        return super.tick( ticking, tickID );
      }
Unlike the gathering skill, we will let the superclass tick method do all the talking to the player. The only job being done here is to make sure the fire didn't go out. If it did, we declare the project messed up, and immediately unInvoke it.
      protected List<List<String>> loadRecipes()
      {
        return super.loadRecipes( "glassblowing.txt" );
      }
Overriding the `loadRecipes()` method is absolutely necessary for any crafting skill, as it specifies the recipes list. A recipes list is a comma-delimited file where each row is linefeed delimited. Each columns meaning is defined by the constants above. The loadRecipes(String) method will automaticallyy look in $coffeemud-install-path/resources/skills for the file specified.
      public void unInvoke()
      {
        if( canBeUninvoked() )
        {
          if( ( affected != null ) && ( affected instanceof MOB ) )
          {
            MOB mob = (MOB)affected;

            if( ( building != null ) && ( !aborted ) )
            {
              if( messedUp )
              {
                commonTell( mob, CMStrings.capitalizeAndLower( building.name()) + " explodes!" );
              }
              else
              {
                mob.location().addItem( building, ItemPossessor.ItemExpiration.Player_Drop );
              }
            }
            building = null;
          }
        }
        super.unInvoke();
      }
Just like in the gathering skill, the `unInvoke()` method is where we actually give our product to the world. Its been saved in the 'building' variable reference, so its just a matter of checking whether everything went ok and adding it to the room if things did. Since common skills work by adding themselves as affects on the player/mobs performing the skill, we need only check the StdAbility.affected reference variable to find our craftor.
      @Override
      public boolean invoke(MOB mob, List<String> commands, Physical givenTarget, boolean auto, int asLevel)
      {
        // same invoke method as in all other Abilities, but we are redirecting to a special
        // method only for Crafting Skills.
        return autoGenInvoke(mob,commands,givenTarget,auto,asLevel,0,false,new Vector<Item>(0));
      }

      @Override
      protected boolean autoGenInvoke(final MOB mob, List<String> commands, Physical givenTarget, final boolean auto,
                                      final int asLevel, int autoGenerate, boolean forceLevels, List<Item> crafted)
Crafting skills are all outfitted with the ability to allow the rest of the system to use the skill class as an automatic item generator. By convention, this is done by overriding the autoGenInvoke interface, and then redirecting the normal invoke interface at it. Then, by sending in the extra parameters, such as autoGenerate, which represents the material out of which the item should be made, and maps back to one of the RawMaterial.RESOURCE_* constants, it tells the rest of the code to behave differently.
      randomRecipeFix( mob, addRecipes( mob, loadRecipes() ), commands, autoGenerate );
This complex line does the most important work related to the autoGenerate flag we set above, and also to handle the case where mobs are initiating this skill on their own. Embedded are three method calls: one to get a vector of vectors representing the skill row matrix (`loadRecipes()`), another to append to this vector any recipe Items in the mobs inventory (`addRecipes(..)`), and lastly, to randomly select a recipe based on the autoGenerate flag or if the invoker is an NPC (`randomRecipeFix()`). `randomRecipeFix()` can handle things like modifying the parameter list (commands) so that it has the name of the random recipe selected.
      if( commands.size() == 0 )
      {
        commonTell( mob, "Make what? Enter \"glassblow list\" for a list." );
        return false;
      }

      if( ( !auto )
      && ( commands.size() > 0 )
      &&( ( (String)commands.firstElement() ).equalsIgnoreCase( "bundle" ) ))
      {
        bundling = true;
        if( super.invoke( mob, commands, givenTarget, auto, asLevel ) )
        {
          return super.bundle( mob, commands );
        }
        return false;
      }
Now we can finally start dealing the parameter list typed by the player, or generated by the system. The parameter list (minus the command invoking word) is in the "commands" vector as a set of strings. The first thing we do is check the parameters to see if they want to generate a bundle of raw resources. If they do, we call a superclass helper method to do so and exit -- this is identical to the way it was done in the gathering skill above.
      List<List<String>> recipes = addRecipes( mob, loadRecipes() );
We're going to need that final recipes list so we can search for the one the player entered into the command line. Therefore we call `loadRecipes()` to get the list from our text file, and then addRecipes to tack on any Recipe Items in the mobs inventory. What comes back is our vector of vectors, representing the rows and columns in the text file. Each vector in the 'recipes' vector can be index by the RCP_* constants above.
      String str = (String)commands.elementAt( 0 );
      String startStr = null;
      bundling = false;
      int completion = 4;
Next we initialize a few important variables, such as setting a variable for the first word in the parameters (str), setting a default completion ticks (4), and initializing a bundling flag to false. Even if the player did not explicitly use the word bundle in the parameters, they may still have selected a bundle item from the recipes list, so we need that flag to notify the rest of the code of that fact.
      if( str.equalsIgnoreCase( "list" ) )
      {
        StringBuffer buf = new StringBuffer( CMStrings.padRight( "Item", 16 ) + " Lvl Sand required\n\r" );

        for( int r = 0; r < recipes.size(); r++ )
        {
          List<String> V = recipes.elementAt( r );
          if( V.size() > 0 )
          {
            String item = replacePercent( V.elementAt( RCP_FINALNAME ), "" );
            int level = CMath.s_int( V.elementAt( RCP_LEVEL ) );
            int wood = CMath.s_int( V.elementAt( RCP_WOOD ) );
            if( level <= mob.phyStats().level() )
            {
              buf.append( CMStrings.padRight( item, 16 ) + " " + CMStrings.padRight( "" + level, 3 ) + " " + wood + "\n\r" );
            }
          }
        }

        commonTell( mob, buf.toString() );
        return true;
      }
If the player entered "list" as the first word in the parameters, we display the recipes to them.
      fire = getRequiredFire( mob,autoGenerate );
      if( fire == null )
      {
        return false;
      }

      building = null;
      messedUp = false;
Now we know we are definitely building something, so we can initialize some more variables, such as the global messedUp flag and the global building reference item. The global fire reference item is also set here by calling a superclass helper method `getRequiredFire(..)` which also has the benefit of giving the user an error message if it fails to find a fire to use. The autoGenerate flag is sent in to tell the method to skip the check if we are simply using the invoke method to automaticallyy generate an item.
      int amount = -1;
      if( ( commands.size() > 1 )
      && ( CMath.isNumber( (String)commands.lastElement() ) ))
      {
        amount = CMath.s_int( (String)commands.lastElement() );
        commands.removeElementAt( commands.size() - 1 );
      }
Our next step is to check the parameters list to see if the player is specifying how much raw material they want to use in the construction of this item. The recipe list mentions the minimum amount of material, but the user is allowed to specify more if they like. We'll save this override amount and confirm its validity later.
      String recipeName = CMParms.combine( commands, 0 );
      List<String> foundRecipe = null;
      List<List<String>> matches = matchingRecipeNames( recipes, recipeName, true );
      for( int r = 0; r < matches.size(); r++ )
      {
        List<String> V = matches.get( r );
        if( V.size() > 0 )
        {
          int level = CMath.s_int( (String)V.elementAt( RCP_LEVEL ) );
          if( ( autoGenerate > 0 ) || ( level <= mob.phyStats().level() ) )
          {
            foundRecipe = V;
            break;
          }
        }
      }
Now we can actually get to the important part of making sure that the recipe name entered by the players into the command line is actually a valid recipe. We do that by combining the remaining strings on the command line into a single variable "recipeName", and then calling a superclass helper method called "matchingRecipeNames" to generate a subset of the master recipe list which matches that name. Once we have this list of matching recipes, we can select the winner based on level (unless we are performing an auto-generation, in which case level doesn't matter). Our winning recipe is stored in a single vector of strings called foundRecipe, which we can index by the RCP_* constants.
      if( foundRecipe == null )
      {
        commonTell( mob, "You don't know how to make a '" + recipeName + "'. Try \"glassblow list\" for a list." );
        return false;
      }
Of course, if no recipe matched, or none met the level requirements, our matched row vector will be null, in which case we error out.
      int woodRequired = CMath.s_int( (String)foundRecipe.elementAt( RCP_WOOD ) );
      if( amount > woodRequired )
      {
        woodRequired = amount;
      }

      String misctype = (String)foundRecipe.elementAt( RCP_MISCTYPE );
      bundling = misctype.equalsIgnoreCase( "BUNDLE" );
      int[] pm = { RawMaterial.RESOURCE_SAND, RawMaterial.RESOURCE_CRYSTAL, RawMaterial.RESOURCE_GLASS };

      int[][] data = fetchFoundResourceData( mob, woodRequired, "sand", pm, 0, null, null, bundling, autoGenerate );
      if( data == null )
      {
        return false;
      }

      woodRequired = data[0][FOUND_AMT];
However, if we did find a matching row, its time to start pulling information out of that row and start using it. The first thing we check is the minimum required raw materials (woodRequired) which can be modified by a larger "amount" variable by the player if they entered one. We also draw out the general modifier string "misctype", which can be used to specify parameters on the item being generated. For instance, is the misctype column says "bundle", we know that we are bundling raw resources and can set our bundling flag to true. The next step is a bit more complicated. The pm array is constructed of RawMaterial.RESOURCE_* constants which represent those material or resource types valid for making the items in this common skill. Next we call the powerful superclass method fetchFoundResourceData which will return to us the amount and specific type of valid resources found, and give an error if none are found. Of course it doesn't really matter with the autoGenerate flag, so it will take that into account as well. The returned array "data" has two dimensions, 0 for the primary resource, and 1 for a secondary resource if applicable (its not applicable here). Each dimension can be dereferenced using superclass FOUND_* constants. For instance, we can get a final "woodRequired" value from the data integer array.
      if( !super.invoke( mob, commands, givenTarget, auto, asLevel ) )
      {
        return false;
      }
Just like for gathering skills, the superclass invoke method is called to take care of mana consumption, and to make sure the person trying to do the crafting is not asleep or dead.
      int lostValue = destroyResources( mob.location(), woodRequired, data[0][FOUND_CODE], 0, null );

      if(autoGenerate>0)
        lostValue = 0;
      building = CMClass.getItem( (String)foundRecipe.elementAt( RCP_CLASSTYPE ) );

      if( building == null )
      {
        commonTell( mob, "There's no such thing as a " + foundRecipe.elementAt( RCP_CLASSTYPE ) + "!!!" );
        return false;
      }
Our next step is to call another superclass method `destroyResources()` which will remove the resources from the room which are used to construct the item. After that, we can actually initialize the building item reference so we can begin to fill it out. The building variable will remain referenced only by the common skill class until the `unInvoke()` method is called, when it will be given to the craftor.
      completion = CMath.s_int( (String)foundRecipe.elementAt( RCP_TICKS ) )
                   - ( ( mob.phyStats().level() - CMath.s_int( (String)foundRecipe.elementAt( RCP_LEVEL ) ) ) * 2 );

      String itemName = replacePercent(
      (String)foundRecipe.elementAt( RCP_FINALNAME ),
      RawMaterial.CODES.NAME( data[0][FOUND_CODE] ] ).toLowerCase();

      if( bundling )
      {
        itemName = "a " + woodRequired + "# " + itemName;
      }
      else
      {
        itemName = CMStrings.startWithAorAn( itemName );
      }

      building.setName( itemName );
      startStr = "<S-NAME> start(s) blowing " + building.name() + ".";
      displayText = "You are blowing " + building.name();
      verb = "blowing " + building.name();
      playSound = "fire.wav";
      building.setDisplayText( itemName + " is here" );
      building.setDescription( itemName + ". " );
      building.basePhyStats().setWeight( woodRequired );
      building.setBaseValue( CMath.s_int( (String)foundRecipe.elementAt( RCP_VALUE ) ) );
Now that we have a reference to the item object we are building, we can start filling in some fields, such as its name, display text, weight, and base value, usually from columns in our recipe text file. We can also derive the final completion variable, representing the number of ticks it will take to complete the item.
      if( data[0][FOUND_CODE] == RawMaterial.RESOURCE_SAND )
      {
        building.setMaterial( RawMaterial.RESOURCE_GLASS );
      }
      else
      {
        building.setMaterial( data[0][FOUND_CODE] );
      }

      building.basePhyStats().setLevel( CMath.s_int( (String)foundRecipe.elementAt( RCP_LEVEL ) ) );

      building.setSecretIdentity( "This is the work of " + mob.Name() + "." );
      int capacity = CMath.s_int( (String)foundRecipe.elementAt( RCP_CAPACITY ) );
      String spell = ( foundRecipe.size() > RCP_SPELL ) ? ( (String)foundRecipe.elementAt( RCP_SPELL ) ).trim() : "";

      addSpells( building, spell );
Continuing with our mission of filling out the building object, we set the material type, level, and secret identity. We also add any properties to it that are listed in the recipe text file by calling the superclass helper method `addSpells()`. There is also a column in the recipe file for the capacity of the item if it is a container.
      if( building instanceof Container )
      {
        if( capacity > 0 )
        {
          ((Container)building ).setCapacity( capacity + woodRequired );
        }

        if( misctype.equalsIgnoreCase( "LID" ) )
        {
          ((Container)building ).setDoorsNLocks( true, false, true, false, false, false );
        }
        else if( misctype.equalsIgnoreCase( "LOCK" ) )
        {
          ((Container)building ).setDoorsNLocks( true, false, true, false );
          ((Container)building ).setKeyName( Double.valueOf( Math.random() ).toString() );
        }
        ((Container)building ).setContainTypes( Container.CONTAIN_ANYTHING );
      }
If, in fact, the item we are building is a container, we'll set the capacity of the container, and use our general purpose "misctype" column from the table to determine whether a lit or lock needs to be made.
      if( building instanceof Drink )
      {
        if( CMLib.flags().isGettable( building ) )
        {
          ((Drink)building ).setLiquidRemaining( 0 );
          ((Drink)building ).setLiquidHeld( capacity * 50 );
          ((Drink)building ).setThirstQuenched( 250 );

          if( ( capacity * 50 ) < 250 )
          {
            ((Drink)building ).setThirstQuenched( capacity * 50 );
          }
        }
      }

      if( bundling )
      {
        building.setBaseValue( lostValue );
      }
If the item is a Drinkable, then we have a few more fields to fill out, based on the capacity column. The last line makes sure that the gold value of the item reflects the sum of the materials used, in case we are bundling.
      building.recoverPhyStats();
      building.text();
      building.recoverPhyStats();
The filling out of the item is complete, so we call `recoverPhyStats()`, populate the miscText field if the item is Generic, and then recover the env stats again in case that changed anything.
      messedUp =! proficiencyCheck( mob, 0, auto );
      if( completion < 4 )
      {
        completion = 4;
      }

      if( bundling )
      {
        messedUp = false;
        completion = 1;
        verb = "bundling " + RawMaterial.CODES.NAME( building.material() ).toLowerCase();

        startStr = "<S-NAME> start(s) " + verb + ".";
        displayText = "You are " + verb;
      }
Now we can set our messedUp flag based on a proficiency check, and change our common skill player-message strings based on whether we are bundling.
      if( autoGenerate > 0 )
      {
        crafted.add( building );
        return true;
      }
If the autoGenInvoke method was called simply to generate the item, we are done -- we can add the item to the crafted list (where it will be expected), and return.
      CMMsg msg = CMClass.getMsg( mob, building, this, CMMsg.MSG_NOISYMOVEMENT, startStr );

      if( mob.location().okMessage( mob, msg ) )
      {
        mob.location().send( mob, msg );
        building = (Item)msg.target();
        beneficialAffect( mob, mob, asLevel, completion );
      }
      else if( bundling )
      {
        messedUp = false;
        aborted = false;
        unInvoke();
      }
      return true;
    }
    }
Last but not least, we do exactly what we did in our gathering skill, namely generate a message for this event, and add the common skill as an effect to the invoker of it. The completion time is used to determine how long it will take to generate the item. ## Poisons
    public class Poison_BeeSting extends com.planet_ink.coffee_mud.Abilities.Poisons.Poison
    {
      public String ID()
      {
        return "Poison_BeeSting";
      }

      public String name()
      {
        return "Bee Sting";
      }
The Poison base class in the Poisons package provides a tidy template upon which your more common, mundane poisons can be based. The first three methods are those required by any Environmental class. The fact that none of the other preliminary methods normally found in skill abilities are present is a testimony to the homogeneous nature of Poisons.
      private static final String[] triggerStrings = { "POISONSTING" };
      public String[] triggerStrings()
      {
        return triggerStrings;
      }
Poisons have the feature of having their own trigger commands, meaning they can be added as attack abilities to monsters (like a Bee in this case).
      protected String POISON_DONE()
      {
        return "The stinging poison runs its course.";
      }

      protected String POISON_START()
      {
        return "^G<S-NAME> turn(s) green.^?";
      }

      protected String POISON_CAST()
      {
        return "^F<S-NAME> sting(s) <T-NAMESELF>!^?";
      }

      protected String POISON_FAIL()
      {
        return "<S-NAME> attempt(s) to sting <T-NAMESELF>, but fail(s).";
      }
In this set of methods, strings are defined for the invocation of the poison, all the way through its recovery string.
      protected int POISON_TICKS()
      {
        return 10; // 0 means no adjustment!
      }
Poisons can have a variable duration dependent upon level (by returning 0) or can have a set duration on the poisoned creature.
      protected int POISON_DELAY()
      {
        return 2;
      }

      protected int POISON_DAMAGE()
      {
        return ( invoker != null ) ? 2 : 0;
      }

      protected String POISON_AFFECT()
      {
        return "<S-NAME> cringe(s) from the poisonous itch.";
      }
Poisons can also be set to cause the poisoned creature to emote on a regular basis, and to take damage as well. Here you can see three methods being used to designate how often the emote/damage cycle occurs (in ticks) as well as the amount of damage, and the text of the emote.
      public void affectCharStats( MOB affected, CharStats affectableStats )
      {
        affectableStats.setStat( CharStats.STAT_CONSTITUTION, affectableStats.getStat( CharStats.STAT_CONSTITUTION ) - 1 );

        affectableStats.setStat( CharStats.STAT_STRENGTH, affectableStats.getStat( CharStats.STAT_STRENGTH ) - 1 );

        if( affectableStats.getStat( CharStats.STAT_CONSTITUTION ) <= 0 )
        {
          affectableStats.setStat( CharStats.STAT_CONSTITUTION, 1 );
        }

        if( affectableStats.getStat( CharStats.STAT_STRENGTH ) <= 0 )
        {
          affectableStats.setStat( CharStats.STAT_STRENGTH, 1 );
        }
      }
    }
And lastly, as described under the Core Topic on state affects, we have the code which lowers the poisoned creatures constitution and strength while the poison is in effect. We even have a few lines to make sure the values don't fall below 0. ## Diseases Like Poison, the Disease base class in the Diseases package provides a tidy template upon which your more common, mundane diseases can be based.
    public class Disease_Cold extends com.planet_ink.coffee_mud.Abilities.Diseases.Disease
    {
      public String ID()
      {
        return "Disease_Cold";
      }

      public String name()
      {
        return "Cold";
      }

      public String displayText()
      {
        return "(Cold Virus)";
      }

      protected int canAffectCode()
      {
        return CAN_MOBS;
      }

      protected int canTargetCode()
      {
        return CAN_MOBS;
      }

      public int abstractQuality()
      {
        return Ability.QUALITY_MALICIOUS;
      }

      public boolean putInCommandlist()
      {
        return false;
      }
The Disease base class provides many important base services that allows CoffeeMud to interact properly with your disease. For this reason, making a disease that extends the Disease base class is highly recommended. In the first half dozen methods, we see the important values of a standard skill being defined. See the introduction to Skill Abilities if you need more details on these methods.
      protected String DISEASE_DONE()
      {
        return "Your cold clears up.";
      }

      protected String DISEASE_START()
      {
        return "^G<S-NAME> come(s) down with a cold.^?";
      }
In this set of methods, strings are defined for the invocation of the disease as well as its recovery string.
      protected int DISEASE_TICKS()
      {
        return 24;
      }
Diseases can have a variable duration dependent upon level (by returning 0) or can have a set duration on the diseased creature.
      protected int DISEASE_DELAY()
      {
        return 5;
      }

      protected String DISEASE_AFFECT()
      {
        return "<S-NAME> sneeze(s). AAAAAAAAAAAAAACHOOO!!!!";
      }
Diseases can also be set to cause the poisoned creature to emote on a regular basis. Here you can see a pair of methods being used to designate how often the emote/damage cycle occurs (in ticks) as well as the text of the emote. Any damage or other consequences of the disease are defined later.
      public int spreadBitmap()
      {
        return DiseaseAffect.SPREAD_CONSUMPTION |DiseaseAffect.SPREAD_PROXIMITY |DiseaseAffect.SPREAD_CONTACT |DiseaseAffect.SPREAD_STD;
      }
This important method is used to define how the disease is spread. Some aspects of disease catching must be coded by the programmer of the disease. Some aspects are handled by the engine, while most are handled by the Disease base class. This method is used to coordinate the efforts on behalf of the disease by the CoffeeMud engine as a whole. Different bit values are defined by the DiseaseAffect interface.
      public boolean tick( Tickable ticking, int tickID )
      {
        if( !super.tick( ticking,tickID ) )
        {
          return false;
        }

        if( affected == null )
        {
          return false;
        }

        if( !( affected instanceof MOB ) )
        {
          return true;
        }

        MOB mob = (MOB)affected;
        MOB diseaser = invoker;
        if( diseaser == null )
        {
          diseaser = mob;
        }
If a disease does anything during its delay cycle (defined above by `DISEASE_DELAY()`), then the programmer must implement a tick method to take care of this functionality. These first few lines of the method are error and state checking, as well as defining some useful variables, such as who caused the disease (diseaser), and who has the disease (mob)
        if( ( getTickDownRemaining() == 1 )
        &&( CMLib.dice().rollPercentage() > mob.charStats().getSave( CharStats.STAT_SAVE_COLD ) )
        &&( CMLib.dice().rollPercentage() < 25 - mob.charStats().getStat( CharStats.STAT_CONSTITUTION ) )
        &&( !mob.amDead() )
        &&( !mob.isMonster() ))
        {
          mob.delEffect( this );
          Ability A = CMClass.getAbility( "Disease_Pneumonia" );
          A.invoke( diseaser, mob, true );
        }
One of the things we have decided to do in the disease Cold is to make it so that, if the creature does not cure the disease before it expires naturally, they will almost certainly catch Pneumonia. By checking `getTickDownRemaining()`, we check out counter which runs downwards from `DISEASE_TICKS()` to 0. At a value of 1, we make a saving throw check for the creature with the cold, and potentially give them another disease to enjoy when the Cold expires 1 tick later.
        else if( ( !mob.amDead() ) && ( ( --diseaseTick ) <= 0 ) )
        {
          diseaseTick = DISEASE_DELAY();
          mob.location().show( mob, null, CMMsg.MSG_NOISE, DISEASE_AFFECT() );
          if( mob.curState().getHitPoints() > ( ( 2 * diseaser.phyStats().level() ) + 1 ) )
          {
            int damage = CMLib.dice().roll( 2, diseaser.phyStats().level(), 1 );
            CMLib.combat().postDamage( diseaser, mob, this, damage, CMMsg.MASK_ALWAYS|CMMsg.TYP_DISEASE, -1, null );
          }

          catchIt( mob );
          return true;
        }
        return true;
      }
The last thing we do in this method is, every `DISEASE_DELAY()` ticks, we emote our DISEASE_AFFECT string, and then allow the creature to take a few points of disease damage by calling the `MUDFight.postDamage()` method. After this, we also call the `catchIt(MOB mob)` method up in the Disease base class. This important method spreads the disease among those in the same room as the creature, thereby handling any diseases spread by proximity as defined in `abilityCode()` above.
      public void affectCharStats( MOB affected, CharStats affectableStats )
      {
        if( affected == null )
        {
          return;
        }

        affectableStats.setStat( CharStats.STAT_CONSTITUTION, affectableStats.getStat( CharStats.STAT_CONSTITUTION ) - 2 );

        affectableStats.setStat( CharStats.STAT_STRENGTH, affectableStats.getStat( CharStats.STAT_STRENGTH ) - 3 );

        if( affectableStats.getStat( CharStats.STAT_CONSTITUTION ) <= 0 )
        {
          affectableStats.setStat( CharStats.STAT_CONSTITUTION, 1 );
        }

        if( affectableStats.getStat( CharStats.STAT_STRENGTH ) <= 0 )
        {
          affectableStats.setStat( CharStats.STAT_STRENGTH, 1 );
        }
      }
    }
And lastly, as described under the Core Topic on state affects, we have the code which lowers the diseased creatures constitution and strength while the disease is in effect. We even have a few lines to make sure the values don't fall below 0. ## Traps Traps and Bombs are so similar, that the differences are not worth mentioning. However, although they are classified as skill abilities, they are different from normal Skill Abilities mentioned above in that they rely very heavily on their superclass bases, which are com.planet_ink.coffee_mud.Abilities.Traps.StdTrap, and com.planet_ink.coffee_mud.Abilities.Traps.StdBomb respectively. Making a proper and compliant trap is helped considerably by following that advice. Otherwise, so long as your trap implements the com.planet_ink.coffee_mud.Abilities.interfaces.Trap interface, it will be ok.
    public class Trap_ElectricShock extends com.planet_ink.coffee_mud.Abilities.Traps.StdTrap
    {
      public String ID()
      {
        return "Trap_ElectricShock";
      }

      public String name()
      {
        return "electric shock";
      }
If you've read the Skill Abilities section above, you will recognize these methods and their importance. As always, the `ID()` must match the class name, while the `name()` can be whatever you want to call the skill.
      protected int canAffectCode()
      {
        return Ability.CAN_ITEMS|Ability.CAN_EXITS;
      }

      protected int canTargetCode()
      {
        return 0;
      }
It is very important, even more so than normal skills, to make sure that your StdAbility `canAffectCode()` method returns a proper value. Some traps can be placed on rooms (floors), and some on items, and others on exits. Make sure your method informs StdAbility what your trap will do.
      protected int trapLevel()
      {
        return 19;
      }
The `trapLevel()` is the class level of your trap. In general, a player needs this many levels in their trap-laying class before they can create this trap.
      public String requiresToSet()
      {
        return "10 pounds of metal";
      }
This is another trap-specific method which is used by the Set Traps skill to inform the user of what kinds of extra-materials are required by the user before they can lay this particular trap. It will be enforced below in the canSetTrap and setTrap methods.
      public Trap setTrap( MOB mob, Physical E, int trapBonus, int qualifyingClassLevel, boolean permanent )
      {
        if( E == null )
        {
          return null;
        }

        if( mob != null )
        {
          Item I = findMostOfMaterial( mob.location(), RawMaterial.MATERIAL_METAL );
          if( I != null )
          {
            super.destroyResources( mob.location(), I.material(), 10 );
          }
        }
        return super.setTrap( mob, E, trapBonus, qualifyingClassLevel, permanent );
      }
This method is used to actually set the trap, well before the trap is sprung. Springing is handled by the StdTrap superclass system, and is based on what is returned by the `canAffectCode()` method. The setTrap method received the mob/player setting the trap, the item onto which the trap is being set (E -- I know, very descriptive; sue me), the trapBonus of the trap setter, if any, and at what level they first qualified for this trap. In this particular method, we use some helper methods from StdTrap to find all of the metal in the room, and then use another StdTrap superclass method to remove the found metal from the room. `findMostOfMaterial()` will look for any raw material Metals in the room, and return an example Item representing the specific type (bronze, iron, gold) of metal that is most numerous in the room. The `destroyResources()` method then will remove 10 of those from the room.
      public boolean canSetTrapOn( MOB mob, Physical E )
      {
        if( !super.canSetTrapOn( mob, E ) )
        {
          return false;
        }

        if( mob != null )
        {
          Item I = findMostOfMaterial( mob.location(), RawMaterial.MATERIAL_METAL );
          if( ( I == null )
          || ( super.findNumberOfResource( mob.location(), I.material() ) < 10 ))
          {
            mob.tell( "You'll need to set down at least 10 pounds of metal first." );
            return false;
          }
        }
        return true;
      }
This method is called before the `setTrap()` method to determine whether the given player/mob is allowed or able to set the trap on the given object (E). Just as we did in setTrap above, we use `findMostOfMaterial()` to determine what the most numerous metal resource on the room is, then call another StdTrap superclass method, `findNumberOfResource()`, to make sure there is enough of this particular metal resource to do the job. If not, we inform the user and return false from the method. If everything is fine, we return true. Notice that we were careful to call the superclass version of this method -- it does important things for us also, so it should definitely be called!
      public List<Item> getTrapComponents()
      {
        Vector V = new Vector();
        for( int i = 0 ; i < 10 ; i++ )
           V.addElement( CMLib.materials().makeItemResource( RawMaterial.RESOURCE_IRON ) );
        return V;
      }
This method is not a terribly important one, but helps serve skills that allow traps to be disassembled. It fills a Vector with something that at least resembles as closely as possible the items that were required to create the trap. In this case, we are calling the makeItemResource method on the materials library to construct 10 pieces of raw iron, which at least resembles our 10 pounds of metal requirement.
      public void spring( MOB target )
      {
        if( ( target != invoker() ) && ( target.location() != null ) )
        {
          if( ( !invoker().mayIFight( target ) )
          || ( CMLib.dice().rollPercentage() <= target.charStats().getSave( CharStats.STAT_SAVE_TRAPS) ))
          {
            target.location().show( target, null, null, CMMsg.MASK_ALWAYS|CMMsg.MSG_NOISE, "<S-NAME> avoid(s) setting off a shocking trap!" );
          }
          else if( target.location().show( target, target, this, CMMsg.MASK_ALWAYS|CMMsg.MSG_NOISE, "<S-NAME> set(s) off an shocking trap!" ) )
          {
            super.spring( target );
            CMLib.combat().postDamage( invoker(), target, null, CMLib.dice().roll( trapLevel(), 8, 1 ), CMMsg.MASK_ALWAYS|CMMsg.TYP_ELECTRIC,
                                       Weapon.TYPE_STRIKING, "The shock <DAMAGE> <T-NAME>!" + CMLib.protocol().msp( "shock.wav",30 ) );

            if( ( canBeUninvoked() ) && ( affected instanceof Item ) )
            {
              disable();
            }
          }
        }
      }
    }
The spring method is where the action is at. If the code in StdTrap determines that the trap has been sprung, then this method will be called with only one parameter, namely the mob who sprung it. After making sure we aren't springing the trap on the thief who set it, we make sure that the thief who set the trap is not breaking PK rules by hurting the player. We do this using the `invoker()` method from StdAbility, which will return a reference to the thief MOB who set the trap. We also give the poor bloke who sprung the trap a saving throw. If both checks fail, we let the room know that the trap has gone off. Notice that it is inside this condition that we call `super.spring()`. This is because, normally, the spring method is only supposed to hurt people. Since we have lots of conditions by which the mob can get out of being hurt, we need to wrap our call to `super.spring()`. Anyway, since the trap has gone off, we make a library call to the `combat()` engine's `postDamage()` method. That method has lots of very complicated parameters, so you'll have to read up on the Library section for more information on it, but suffice to say that it posts the damage message that takes hit points away from the player. Lastly, if the trap is allowed to be uninvoked, we call the special StdTrap `disable()` method, which makes the trap unviable FOREVER. It effectively destroys the trap. ## Languages Of all skills, you will find that Languages are the easiest to code. Although they fall into the category of Ability, and are a far derivative of StdAbility, you will need very little of that extended knowledge if you follow the K.I.S.S. principle and use the simple template provided by the StdLanguage base class in the Languages package, which implements the Language interface.
    public class Elvish extends com.planet_ink.coffee_mud.Abilities.Languages.StdLanguage
    {
      public String ID()
      {
        return "Elvish";
      }

      public String name()
      {
        return "Elvish";
      }
Like all Abilities, the Language requires an ID which is the same as its class name, and a readable name. In the case of Elvish, they are identical.
      private static boolean mapped = false;
      public Elvish()
      {
        super();
        if( !mapped )
        {
          mapped = true;
          CMLib.ableMapper().addCharAbilityMapping( "All", 1, ID(), false );
        }
      }
The constructor of this language is worth noting. Under the section on Character Classes, we learned how to make classes qualify for skills. Languages, like Common Skills, are available to ALL classes. For this reason, we save ourselves the trouble by having the language declare its qualifications itself by accessing the same CMLib.ableMapper() method we saw up in Character Class creation.
      public static List<String[]> wordLists = null;
      public List<String[]> translationVector(String language)
      {
        if(wordLists==null)
        {
          String[] one = { "a", "e", "i", "o", "�", "�", "�", "�" };

          String[] two = { "os", "vi", "ne", "vo", "li", "eh", "no", "ai", "by", "et", "ce", "un", "il" };

          String[] three = { "�na", "cil", "sar", "tan", "hel", "loa", "sir", "hep", "yur", "nol", "hol", "qua", "�th" };

          String[] four = { "s�ya", "qual", "quel", "lara", "uqua", "sana", "yava", "masse", "yanna", "quettaparma", "manna", "manan",
                            "merme", "carma", "harno", "harne", "varno", "essar", "saira", "cilta", "veuma", "norta", "turme", "saita" };

          String[] five = { "cuiva", "cuina", "nonwa", "imire", "nauta", "cilta", "entuc", "norta", "latin", "l�tea", "veuya", "veuro",
                            "apama", "hampa", "nurta", "firta", "saira", "holle", "herwa", "uquen", "arcoa", "calte", "cemma", "hanta",
                            "tanen"};

          String[] six = { "mahtale", "porisalque", "hairie", "tararan", "ambarwa", "latina", "ol�tie", "amawil", "apacen",
                           "yavinqua", "apalume", "linquilea", "menelwa", "alassea", "nurmea", "parmasse", "ceniril", "heldasse",
                           "imirin", "earina", "calatengew", "lapselunga", "rianna", "eneques" };

          wordLists=new Vector();
          wordLists.add( one );
          wordLists.add( two );
          wordLists.add( three );
          wordLists.add( four );
          wordLists.add( five );
          wordLists.add( six );
        }
        return wordLists;
      }
The first, often only, and certainly most important Language method is `translationVector(String language)`, which returns a Vector object containing a set of String arrays for the given language id. The parameter is needed only if your language class performs services for more than one spoken language, so usually the parameter will be ignored. Each String array that is returned by this method is designated by the size of the Common language words which will be used by the array for translation. That is to say, whenever a Common word of three letters is being translated into Elvish, the String array three will have a word randomly chosen from it. The words which are placed into these string arrays is arbitrary, and may actually contain as many or few letters as you like. Keeping the number of letters close or the same as the Common word equivalent provides a certain symmetry, however, and makes it fun for the players who don't speak a language to try and guess what is being said by counting letters.
      private static final Map<String,String> hashwords = new Hashtable();
      public Map<String,String> translationHash(String language)
      {
        if( ( hashwords != null ) && ( hashwords.size() > 0 ) )
        {
          return hashwords;
        }

        hashwords.put( "ABANDON", "avarta" );
        hashwords.put( "ABLE", "pol" );
        hashwords.put( "ACCOMMODATE", "camta" );
        hashwords.put( "ACT", "car" );

     ...

        hashwords.put( "WRONG", "raic�" );
        hashwords.put( "YES", "y�" );
        hashwords.put( "YESTERDAY", "tellaur�" );
        return hashwords;
      }
    }
The last Language method is `translationHash(String language)`. Like translationVector, it has a language parameter that can safely be ignored. For that matter, this method is entirely optional and may be left out of a language definition. In fact, it usually IS left out. However, when it is not, it provides a hashtable which can be used to translate exact english matches back to the fantasy language. The First word in each hashtable entry is the English word (and it MUST MUST MUST be in UPPERCASE) as the key, and the translation word as the entry value. Correct casing is taken care of by the Language base class.