<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Programming for CoffeeMud 5.2</title>
<link rel="StyleSheet" href="style.css" type="text/css" media="screen" />
<!-- Modified by Josh Mueller, 2006-5-6, fix validation problems, reformat, fix spelling errors -->
</head>
<body>
<center>
<table border="1" bordercolor="gray" cellpadding="10" cellspacing="0" width="90%">
<tbody>
<tr>
<td colspan="2" align="left" bgcolor="#dfdfdf" width="100%">
<h1> Programming for CoffeeMud 5.2 </h1>
</td>
</tr>
<tr>
<td align="left" valign="top" width="20%">
<ul>
<li> <a href="#overview">Overview</a>
</li>
<li> <a href="#BUILD">Building</a>
<ul>
<li> <a href="#buildwin">Windows</a>
</li>
<li> <a href="#buildunix">Unix</a>
</li>
<li> <a href="#external">External Components</a>
</li>
<li> <a href="#IMPORTS">Default Import
List</a> </li>
</ul>
</li>
<li> <a href="#TEXT">Text</a>
<ul>
<li> <a href="#nametag">Target Info Tag</a>
</li>
<li> <a href="#textcolor">Color</a>
</li>
</ul>
</li>
<li> <a href="#javascript">JavaScripting</a>
<ul>
<li> <a href="#writingjavascript">Writing
Your First Javascript</a> </li>
</ul>
</li>
<li> <a href="#DIG1">Core Topic 1: Message Passing</a>
<ul>
<li><a href="#majorcode">Major Code Bitmask</a></li>
<li><a href="#messagepreview">Message Previewing</a></li>
<li><a href="#messageflagging">Message Flagging and Modification</a></li>
<li><a href="#messageexecution">Message Execution</a></li>
<li><a href="#messagetrailers">Message Trailers</a></li>
</ul>
</li>
<li> <a href="#DIG2">Core Topic 2: State Layers</a>
<ul>
<li><a href="#envstats">EnvStats fields</a></li>
<li><a href="#charstats">CharStats codes</a></li>
<li><a href="#charstate">CharState</a></li>
</ul>
</li>
<li> <a href="#DIG3">Core Topic 3: Threading</a>
</li>
<li> <a href="#DIG4">Core Topic 4: Core Libraries</a>
<ul>
<li><a href="#corepurpose">Core class purposes</a></li>
<li><a href="#corelibrarymap">Library mappings</a></li>
<li><a href="#corecommon">Common Classes</a></li>
</ul>
</li>
<li><a href="#DIG5">Core Topic 5: Adding Data</a><br />
</li>
<li><a href="#CMDS">Commands</a> </li>
<li> <a href="#MOBS">MOBs</a>
<ul>
<li><a href="#mobcoding">Coding a new MOB</a></li>
<li><a href="#moblife">Life and Death</a></li>
</ul>
</li>
<li> <a href="#ITEMS">Items</a>
<ul>
<li><a href="#itemlife">Creation and Destruction</a></li>
</ul>
</li>
<li> <a href="#BEHAVS">Behaviors</a>
</li>
<li> <a href="#CLASSES">Character Classes</a>
</li>
<li> <a href="#RACES">Races</a> </li>
<li> <a href="#EXITS">Exits</a> </li>
<li> <a href="#LOCALES">Locales</a>
</li>
<li> <a href="#AREAS">Areas</a> </li>
<li> <a href="#PROPS">Properties</a>
</li>
<li> <a href="#SKILLS">Skills</a>
<ul>
<li><a href="#skillquality">Skill Nature Flags</a></li>
<li><a href="#skillflags">Skill Affect Flags</a></li>
</ul>
</li>
<li> <a href="#SPC">Spells, Prayers, and Chants</a>
<ul>
<li><a href="#spells">Spells</a></li>
<li><a href="#spelldomain">Spell Domains</a></li>
<li><a href="#prayers">Prayers</a></li>
<li><a href="#chants">Chants</a></li>
</ul>
</li>
<li> <a href="#SONGS">Songs</a> </li>
<li> <a href="#COMMON">Common Skills</a>
<ul>
<li><a href="#skillgathering">Gathering Skill</a></li>
<li><a href="#skillcrafting">Crafting Skill</a></li>
</ul>
</li>
<li> <a href="#POISON">Poisons</a>
</li>
<li> <a href="#DISEASE">Diseases</a>
</li>
<li> <a href="#TRAPS">Traps & Bombs</a>
</li>
<li> <a href="#LANGS">Languages</a>
</li>
</ul>
</td>
<td align="left" valign="top"> <img src="images/mug.jpg" alt="CoffeeMud logo" />
<h2> <a name="overview" id="overview">Overview</a>
</h2>
<p> 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 <a href="ArchonGuide.html">Archons Guide</a>
and <a href="GameBuildersGuide.html">Game Builders Guide</a> are completely familiar.
The difference between a GenItem and a StdItem, or a GenMob and
a GenPostman will not be explained in this document. </p>
<p> 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.
</p>
<p> 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.
</p>
<img src="images/sprockets.jpg" alt="Recompiling" />
<h2> <a name="BUILD" id="BUILD">Rebuilding CoffeeMud</a>
</h2>
<h3> <a name="buildwin" id="buildwin">In Microsoft Windows</a>
</h3>
<ul>
<li>
<p> Go to your coffeemud directory and edit the make.bat,
the first line will be something like: <code>SET JAVACPATH=
C:\jdk1.5.0_05\bin\javac</code> This might be different for
you depending on where your java development package is installed.
</p>
</li>
<li>
<p> Save the bat file. </p>
</li>
<li>
<p> Run the bat file by double clicking on it. This
will compile the mud, making all the .class files.
</p>
</li>
</ul>
<h3> <a name="buildunix" id="buildunix">In Unix</a>
</h3>
<ul>
<li>
<p> Go to your coffeemud directory and edit the makeUNIX.sh,
the first line will be something like: <code>Java_Home=/home/knoppix/j2sdk1.4.2</code>
This might be different for you depending on where your java
development package is installed. </p>
</li>
<li>
<p> Save the shell script. </p>
</li>
<li>
<p> Issue this command: <code>chmod 755 makeUNIX.sh</code>
</p>
</li>
<li>
<p> Execute the shell script. This will compile the
mud, making all the .class files. </p>
</li>
</ul>
<h3> <a name="external" id="external">Introducing External
Components</a> </h3>
<p> If you perused the coffeemud.ini file as mentioned in
the Installation Guide, you may have noticed and wondered about
the section at the end which lists the default load paths for
the several CoffeeMud objects. </p>
<p> 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
<code>%DEFAULT%</code> is always used as a substitute for the
default CoffeeMud object path. For instance, if you installed
CoffeeMud at "<code>C:\CoffeeMud\</code>", then "<code>BEHAVIORS=%DEFAULT%</code>"
in the ini file would load "<code>C:\CoffeeMud\com\planet_ink\coffee_mud\Behaviors\*.class</code>"
into its behavior set. </p>
<p> 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:
</p>
<pre>MOBS=%DEFAULT%;/resources/examples/MyClass.class;/resources/otherclasses<br /></pre>
<p> 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. </p>
<p> When writing these custom classes for your special object
boot directory(s), it is important to keep a number of things
in mind: </p>
<ul>
<li>
<p> 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. </p>
</li>
<li>
<p> Java Packaging is irrelevant, you may package
your classes or not. </p>
</li>
<li>
<p> 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. </p>
</li>
<li>
<p> Make sure the <code>ID()</code> method in your
classes always matches the name of your class. You will understand
this better as you reference the object sections below.
</p>
</li>
<li>
<p> Try to make the <code>name()</code> 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.
</p>
</li>
<li>
<p> Class files loaded directly in the CoffeeMud
classpath can not be reloaded at run-time using the <code>UNLOAD</code>
and <code>LOAD</code> commands. If you plan on making changes
to your classes during run-time, place them in their own
directories. </p>
</li>
<li>
<p> As a general rule, you may import any
"<code>interfaces.*</code>" packages in the base CoffeeMud
structure, any core Java packages, the CoffeeMud "<code>core.*</code>"
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.
</p>
</li>
</ul>
<h3> <a name="IMPORTS" id="IMPORTS">Complete Default Import
List</a> </h3>
<pre>import com.planet_ink.coffee_mud.core.*;<br />import com.planet_ink.coffee_mud.core.interfaces.*;<br />import com.planet_ink.coffee_mud.Abilities.interfaces.*;<br />import com.planet_ink.coffee_mud.Areas.interfaces.*;<br />import com.planet_ink.coffee_mud.Behaviors.interfaces.*;<br />import com.planet_ink.coffee_mud.CharClasses.interfaces.*;<br />import com.planet_ink.coffee_mud.Commands.interfaces.*;<br />import com.planet_ink.coffee_mud.Common.interfaces.*;<br />import com.planet_ink.coffee_mud.Exits.interfaces.*;<br />import com.planet_ink.coffee_mud.Items.interfaces.*;<br />import com.planet_ink.coffee_mud.Locales.interfaces.*;<br />import com.planet_ink.coffee_mud.MOBS.interfaces.*;<br />import com.planet_ink.coffee_mud.Races.interfaces.*;<br />import com.planet_ink.coffee_mud.Libraries.interfaces.*;<br />import java.io.IOException;<br />import java.util.*;<br /></pre>
<img src="images/rainbow.jpg" alt="Text" />
<h2> <a name="TEXT" id="TEXT">Text</a> </h2>
<p> 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:
</p>
<pre>msg=CMClass.newMsg(mob,target,this,affectType,"<S-NAME> reach(es) for <T-NAMESELF>.");<br />mob.location().show(mob,null,CMMsg.MSG_OK_ACTION,"<S-NAME> regain(s) <S-HIS-HER> feet.");<br /><br /></pre>
<p> 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: </p>
<a name="nametag" id="nametag"> </a>
<table bgcolor="#ffffcc" border="1">
<tbody>
<tr>
<td> <code><S-HIS-HER></code>
</td>
<td> Outputs 'Your' if Observer=Source,
otherwise 'His'/'Her'. </td>
</tr>
<tr>
<td> <code><S-HIM-HER></code>
</td>
<td> Outputs 'You' if Observer=Source,
otherwise 'Him'/'Her'. </td>
</tr>
<tr>
<td> <code><S-NAME></code>
</td>
<td> Outputs 'You' if Observer=Source,
otherwise the Name. </td>
</tr>
<tr>
<td> <code><S-NAMESELF></code>
</td>
<td> Outputs 'Yourself' if Observer=Source,
otherwise the Name </td>
</tr>
<tr>
<td> <code><S-NAMENOART></code>
</td>
<td> Outputs 'You' if Observer=Source,
otherwise the Name minus any prefix articles (a, an, some,
etc..). </td>
</tr>
<tr>
<td> <code><S-HE-SHE></code>
</td>
<td> Outputs 'You' if Observer=Source,
otherwise 'He'/'She' </td>
</tr>
<tr>
<td> <code><S-SIRMADAM></code>
</td>
<td> Outputs 'Sir'/'Madam'
</td>
</tr>
<tr>
<td> <code><S-IS-ARE></code>
</td>
<td> Outputs 'Are' if Observer=Source,
otherwise 'Is'. </td>
</tr>
<tr>
<td> <code><S-HAS-HAVE></code>
</td>
<td> Outputs 'Have' if Observer=Source,
otherwise 'Has'. </td>
</tr>
<tr>
<td> <code><S-YOUPOSS></code>
</td>
<td> Outputs 'Your' if Observer=Source,
otherwise the Name`s </td>
</tr>
<tr>
<td> <code><S-HIM-HERSELF></code>
</td>
<td> Outputs 'Yourself' if Observer=Source,
otherwise the 'Himself'/'Herself' </td>
</tr>
<tr>
<td> <code><S-HIS-HERSELF></code>
</td>
<td> Outputs 'Yourself' if Observer=Source,
otherwise the 'Hisself'/'Herself' </td>
</tr>
<tr>
<td> <code><T-HIS-HER></code>
</td>
<td> Outputs 'You' if Observer=Target,
otherwise 'His'/'Her'. </td>
</tr>
<tr>
<td> <code><T-HIM-HER></code>
</td>
<td> Outputs 'You' if Observer=Target,
otherwise 'Him'/'Her'. </td>
</tr>
<tr>
<td> <code><T-NAME></code>
</td>
<td> Outputs 'You' if Observer=Target,
otherwise the Name. </td>
</tr>
<tr>
<td> <code><T-NAMESELF></code>
</td>
<td> Outputs 'Yourself' if Observer=Target,
otherwise the Name </td>
</tr>
<tr>
<td> <code><T-NAMENOART></code>
</td>
<td> Outputs 'You' if Observer=Target,
otherwise the Name minus any prefix articles (a, an, some,
etc..). </td>
</tr>
<tr>
<td> <code><T-HE-SHE></code>
</td>
<td> Outputs 'You' if Observer=Target,
otherwise 'He'/'She' </td>
</tr>
<tr>
<td> <code><T-SIRMADAM></code>
</td>
<td> Outputs 'Sir'/'Madam'
</td>
</tr>
<tr>
<td> <code><T-IS-ARE></code>
</td>
<td> Outputs 'Are' if Observer=Target,
otherwise 'Is'. </td>
</tr>
<tr>
<td> <code><T-HAS-HAVE></code>
</td>
<td> Outputs 'Have' if Observer=Target,
otherwise 'Has'. </td>
</tr>
<tr>
<td> <code><T-YOUPOSS></code>
</td>
<td> Outputs 'Your' if Observer=Target,
otherwise the Name with an '`s' </td>
</tr>
<tr>
<td> <code><T-HIM-HERSELF></code>
</td>
<td> Outputs 'Yourself' if Observer=Source,
otherwise the 'Himself'/'Herself' </td>
</tr>
<tr>
<td> <code><T-HIS-HERSELF></code>
</td>
<td> Outputs 'Yourself' if Observer=Source,
otherwise the 'Hisself'/'Herself' </td>
</tr>
</tbody>
</table>
<p> Occasionally, you will find color/font codes embedded
in system strings. For instance: </p>
<pre>msg.append("^!You are thirsty.^?\n\r");<br /></pre>
<p> These codes are as follows: </p>
<a name="textcolor" id="textcolor"> </a>
<table bgcolor="#ccffff" border="1">
<tbody>
<tr>
<td> <code>^N</code> </td>
<td> Normal </td>
</tr>
<tr>
<td> <code>^!</code> </td>
<td> Bold </td>
</tr>
<tr>
<td> <code>^H</code> </td>
<td> Highlight </td>
</tr>
<tr>
<td> <code>^_</code> </td>
<td> Underline </td>
</tr>
<tr>
<td> <code>^*</code> </td>
<td> Blink </td>
</tr>
<tr>
<td> <code>^/</code> </td>
<td> Italics </td>
</tr>
<tr>
<td> <code>^.</code> </td>
<td> Reset (turns off reverse)
</td>
</tr>
<tr>
<td> <code>^^</code> </td>
<td> Generates an untranslated "^" character
</td>
</tr>
<tr>
<td> <code>^?</code> </td>
<td> Restores previous color
</td>
</tr>
<tr>
<td> <code>^f</code> </td>
<td> You-Fight </td>
</tr>
<tr>
<td> <code>^e</code> </td>
<td> Fight-You </td>
</tr>
<tr>
<td> <code>^F</code> </td>
<td> Fight </td>
</tr>
<tr>
<td> <code>^S</code> </td>
<td> Spell </td>
</tr>
<tr>
<td> <code>^E</code> </td>
<td> Emote </td>
</tr>
<tr>
<td> <code>^T</code> </td>
<td> Talk </td>
</tr>
<tr>
<td> <code>^Q</code> </td>
<td> Channel Background
</td>
</tr>
<tr>
<td> <code>^q</code> </td>
<td> Channel Foreground
</td>
</tr>
<tr>
<td> <code>^x</code> </td>
<td> Important message 1
</td>
</tr>
<tr>
<td> <code>^X</code> </td>
<td> Important message 2
</td>
</tr>
<tr>
<td> <code>^Z</code> </td>
<td> Important message 3
</td>
</tr>
<tr>
<td> <code>^O</code> </td>
<td> Room Title </td>
</tr>
<tr>
<td> <code>^L</code> </td>
<td> Room Description </td>
</tr>
<tr>
<td> <code>^J</code> </td>
<td> Weather </td>
</tr>
<tr>
<td> <code>^D</code> </td>
<td> Direction </td>
</tr>
<tr>
<td> <code>^d</code> </td>
<td> Door </td>
</tr>
<tr>
<td> <code>^I</code> </td>
<td> Item </td>
</tr>
<tr>
<td> <code>^M</code> </td>
<td> MOB </td>
</tr>
<tr>
<td> <code>^U</code> </td>
<td> Unexplored Direction
</td>
</tr>
<tr>
<td> <code>^u</code> </td>
<td> Unexplored Door </td>
</tr>
<tr>
<td> <code>^w</code> </td>
<td> White </td>
</tr>
<tr>
<td> <code>^g</code> </td>
<td> Green </td>
</tr>
<tr>
<td> <code>^b</code> </td>
<td> Blue </td>
</tr>
<tr>
<td> <code>^r</code> </td>
<td> Red </td>
</tr>
<tr>
<td> <code>^y</code> </td>
<td> Yellow </td>
</tr>
<tr>
<td> <code>^c</code> </td>
<td> Cyan </td>
</tr>
<tr>
<td> <code>^p</code> </td>
<td> Purple </td>
</tr>
<tr>
<td> <code>^W</code> </td>
<td> Dark White </td>
</tr>
<tr>
<td> <code>^G</code> </td>
<td> Dark Green </td>
</tr>
<tr>
<td> <code>^B</code> </td>
<td> Dark Blue </td>
</tr>
<tr>
<td> <code>^R</code> </td>
<td> Dark Red </td>
</tr>
<tr>
<td> <code>^Y</code> </td>
<td> Dark Yellow </td>
</tr>
<tr>
<td> <code>^C</code> </td>
<td> Dark Cyan </td>
</tr>
<tr>
<td> <code>^P</code> </td>
<td> Dark Purple </td>
</tr>
<tr>
<td> <code>^<</code>
</td>
<td> < character. Used for MXP tags
only. </td>
</tr>
<tr>
<td> <code>^></code>
</td>
<td> > character. Used for MXP tags
only. </td>
</tr>
<tr>
<td> <code>^&</code>
</td>
<td> & character. Used for MXP tags
only. </td>
</tr>
</tbody>
</table>
<p> As you might have guessed, it is preferred that the system
colors (the last 16 codes) be used sparingly, in favor of the
more customizable codes above. </p>
<img src="images/mozilla.jpg" alt="Mozilla Javascript" />
<h2> <a name="javascript" id="javascript">JavaScripting:</a>
</h2>
<p> 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. </p>
<p> 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: <a href="http://www.mozilla.org/js/">http://www.mozilla.org/js/</a> and
<a href="http://www.mozilla.org/rhino/">http://www.mozilla.org/rhino/</a>.
</p>
<p> 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,
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: </p>
<pre>var javascriptstring=' this is a javascript string ';<br />var javastring=toJavaString(javascriptstring);<br />// and now javastring is a real-live Java-compliant and Java-friendly string<br /></pre>
<p> 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 <code>toJavaString()</code>
method from a class written in JavaScript: </p>
<pre>var javascriptstring=' this is a javascript string ';<br />var javastring=Packages.com.planet_ink.coffee_mud.core.CMLib.toJavaString(javascriptstring);<br />// and now javastring is a real-live Java-compliant and Java-friendly string<br /></pre>
<p> 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. :) </p>
<p> 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
<code>pow(x,y)</code> function in CMParms.java: </p>
<pre>var lib=Packages.com.planet_ink.coffee_mud.core.CMLib;<br />// the above creates a reference to the CoffeeMud Library as a shortcut<br />var value=lib.math().pow(4,2);<br />// now we can access the math() library from our shortcut.<br /></pre>
<p> 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 <code>Packages.com.planet_ink.coffee_mud.core.CMLib</code>
reference to access special methods such as the toJavaString method
discussed above. </p>
<p> 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 <code>MOB source(),
Environmental target(), Environmental host(), Item item1(), Item
item2(), String message(),</code> and <code>MOB monster()</code>.
The JRun command provides the methods <code>MOB mob(), int
numParms(), String getParm(int i),</code> and <code>String
getParms()</code>. The web server makes the <code>ExternalHTTPRequests
request()</code> object available, as well as the method <code>void
write(String s)</code>. The quest engine makes the current running
Quest object available from the method <code>Quest quest()</code>
and the current state of the quest setup script available in a
custom QuestState object referencing method called <code>QuestState
setupState()</code> </p>
<p> 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
<code>//extends</code> command in your JavaScript), interfaces
may be implemented (using the special CoffeeMud <code>//implements</code>
command in your JavaScript), super class variables and methods
may be accessed (using the <code>this.variableName</code> and
<code>this.super$methodname()</code> 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. </p>
<h3> <a name="writingjavascript" id="writingjavascript">Writing
your first JavaScript</a> </h3>
<p> 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. </p>
<p> 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. </p>
<pre>//extends com.planet_ink.coffee_mud.MOBS.GenMob<br /><br />function ID(){return "GenLemming";}<br /><br />var lib=Packages.com.planet_ink.coffee_mud.core.CMLib;<br /></pre>
<p> 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. </p>
<p> The <code>ID()</code> 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. </p>
<p> Lastly, we define the variable "lib" to act as a shortcut
to the CoffeeMud core Libraries. </p>
<p> 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 <code>newInstance()</code> method as shown here:
</p>
<pre>function newInstance()<br />{<br /> var lemm=this.super$newInstance();<br /> lemm.setName("a generic lemming");<br /> lemm.setDisplayText("a generic lemming is waiting to commit suicide");<br /> return lemm;<br />}<br /></pre>
<p> 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
<code>newInstance()</code> method -- <code>this.super$newInstance()</code>.
This is very different from Java syntax and should be noted.
</p>
<p> And now we move on to overriding our first GenMob method,
tick. </p>
<pre>var countdown = 10;<br /><br />function tick( host, tickID )<br />{<br /> if( !this.amDead() )<br /> {<br /> countdown--;<br /> if( countdown <= 0 )<br /> {<br /> lib.combat().postDeath( null, this, null );<br /> countdown = 10;<br /> }<br /> }<br /> return this.super$tick( host, tickID );<br />}<br /> </pre>
<p> The <code>public boolean tick(Tickable host, int tickID)</code>
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. </p>
<p> 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 <code>postDeath(MOB killer, MOB killed, CMMsg msg)</code>
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. </p>
<p> 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. </p>
<pre>function okMessage(host,msg)<br />{<br /> if( ( msg.isSource( this ) )<br /> &&( msg.isOthers( "DEATH" ) )<br /> &&( msg.othersMessage() != null )<br /> )<br /> {<br /> msg.setOthersMessage("<S-NAME> jumps off a cliff!!!");<br /> }<br /><br /> return this.super$okMessage(host,msg);<br />}<br /></pre>
<p> 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 <code>( isOthers( "DEATH" ) )</code> 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. </p>
<img src="images/kiss.jpg" alt="Getting the Message" />
<h2> <a name="DIG1" id="DIG1">Core Topic 1: Getting the Message:</a>
</h2>
<p> 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. </p>
<p> 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 <code>Common.interfaces.CMMsg</code>, and are typically
an instance of the class <code>Common.DefaultMessage</code>.
</p>
<p> 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: </p>
<pre>CMMsg msg = CMClass.getMsg(mob, targetMOB, this,<br /> CMMsg.MSG_CAST_ATTACK_VERBAL_SPELL,"^S<S-NAME> invoke a spell at <T-NAME>s feet..^?",<br /> CMMsg.MSG_CAST_ATTACK_VERBAL_SPELL,"^S<S-NAME> invoke(s) a spell at your feet.^?",<br /> CMMsg.MSG_CAST_ATTACK_VERBAL_SPELL,"^S<S-NAME> invokes a spell at <T-NAME>s feet.^?"<br /> );<br /><br /></pre>
<p> The above message was taken from the code for the Grease
spell, which calls the <code>core.CMClass.getMsg</code> 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:
</p>
<ul>
<li>Source
<p> 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. </p>
</li>
<li>Target
<p> 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. </p>
</li>
<li>Tool
<p> 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).
</p>
</li>
<li>Source Code
<p> This is an encoded integer which represents what
the source MOB is actually doing. We'll break down this code
below. </p>
</li>
<li>Source Message
<p> This is the string which the source MOB will
see should the event occur successfully. </p>
</li>
<li>Target Code
<p> 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).
</p>
</li>
<li>Target Message
<p> 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. </p>
</li>
<li>Others Code
<p> 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)
</p>
</li>
<li>Others Message
<p> 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. </p>
</li>
</ul>
<p> 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. </p>
<p> 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 <code>sourceMajor()</code> and
<code>sourceMinor()</code>. These methods will automaticallyy break
down a <code>sourceCode()</code> into the components we will
discuss. </p>
<p> 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: </p>
<a name="majorcode" id="majorcode"> </a>
<table bgcolor="#ffccff" border="1">
<thead> <tr>
<th width="15%"> Bit mask
</th>
<th width="30%"> CMMsg Equate Variable(s)
</th>
<th> Meaning </th>
</tr>
</thead> <tbody>
<tr>
<td> 2048 </td>
<td>
<p> MASK_HANDS </p>
</td>
<td> Message includes small movements.
</td>
</tr>
<tr>
<td> 4096 </td>
<td>
<p> MASK_MOVE </p>
</td>
<td> Message includes large, full-body
movements. </td>
</tr>
<tr>
<td> 8192 </td>
<td> MASK_EYES </td>
<td> Message includes visual information.
</td>
</tr>
<tr>
<td> 16384 </td>
<td> MASK_MOUTH </td>
<td> Message include mouth movement,
or consumption. </td>
</tr>
<tr>
<td> 32768 </td>
<td> MASK_SOUND,<br />
MASK_SOUNDEDAT </td>
<td> Message includes auditory information.
</td>
</tr>
<tr>
<td> 65536 </td>
<td> MASK_ALWAYS </td>
<td> Override mask which flags the message
as something which Must occur, regardless of the state of
the source or target. </td>
</tr>
<tr>
<td> 131072 </td>
<td> MASK_MAGIC </td>
<td> Message has a magical nature.
</td>
</tr>
<tr>
<td> 262144 </td>
<td> MASK_DELICATE </td>
<td> Message includes very fine, delicate
movements, such as thief skills. </td>
</tr>
<tr>
<td>524288</td>
<td>MASK_MALICIOUS</td>
<td>Message represents an attack of some sort.</td>
</tr>
<tr>
<td> 1048576 </td>
<td> MASK_CHANNEL </td>
<td> Message is part of public channel
conversation. </td>
</tr>
<tr>
<td> 2097152 </td>
<td> MASK_OPTIMIZE </td>
<td> Message implementation should be
optimized for repetition. </td>
</tr>
</tbody>
</table>
<p> 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. </p>
<p> 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.. </p>
<pre>CMMsg msg = CMClass.getMsg(attacker,target,weapon,CMMsg.MSG_WEAPONATTACK,<br /> "<S-NAME>attack(s) <T-NAME>!");<br /></pre>
<p> 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.
</p>
<p> CMMsg objects also have <code>value()</code> and <code>setValue(int)</code>
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. </p>
<h3><a name="messagepreview" id="messagepreview">Message Previewing</a></h3>
<p> 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: </p>
<pre>CMMsg msg = CMClass.getMsg(SourceMOB,TargetMOB,weapon,CMMsg.MSG_WEAPONATTACK,<br /> "<S-NAME>attack(s) <T-NAME>!");<br /><br />if(SourceMOB.location().okMessage(SourceMOB,msg))<br />{<br /> SourceMOB.location().send(SourceMOB,msg);<br />}<br /></pre>
<p> The <code>location()</code> 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 <code>okMessage()</code>
is called, is the preview step. In this step, the message is evaluated
before it actually happens. The first parameter to <code>okMessage()</code>
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 <code>okMessage()</code> is the message we constructed.
The third line, where the Room <code>send()</code> method is called,
is the execution step. </p>
<p> 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 <code>okMessage()</code> 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 <code>okMessage()</code> 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 <code>okMessage()</code> call will, in
turn, pass the Message to the <code>okMessage()</code> 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
<code>okMessage()</code> 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 <code>okMessage()</code> method will also
return false, ordering the message to be totally canceled. For
this reason, <code>okMessage()</code> methods are careful
about returning true unless they have a really good reason not
to. </p>
<p> Inside the <code>okMessage()</code> 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. </p>
<h3><a name="messageflagging" id="messageflagging">Message Flagging
and Modification</a></h3>
<p> Message modification is very rare. When it happens though,
it is done by calling one of the several <code>modify()</code>
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.
</p>
<p> 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 <code>CMMsg.setValue(int)</code> method, and
using it to change the value to something other than the default
of 0. Flagging using the <code>setValue()</code> 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 <code>int value()</code>
method on CMMsg. </p>
<h3><a name="messageexecution" id="messageexecution">Message Execution</a></h3>
<p> Once the <code>okMessage()</code> 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: <code>Room.send(MOB
SourceMOB, CMMsg msg)</code> or <code>Room.sendOthers(MOB
SourceMOB, CMMsg msg)</code>. 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. </p>
<p> The <code>send()</code> methods will then begin calling
other methods in other objects. These other methods are called
the <code>executeMsg()</code> methods, and are usually of the form
<code>public void executeMsg(Environmental myHost,
CMMsg msg);</code>. These methods are responsible for Executing
the contents of the message. The Room method will make <code>executeMsg()</code>
method calls on itself, and on every Exit, Item, MOB, spell effects
(Ability object), and Behavior associated with that Room. As in
the <code>okMessage()</code> case, the MOBs will in turn call the
<code>executeMsg()</code> methods on their own Items and spell effects.
Items will then call the <code>executeMsg()</code> methods on
their own spell effects, and so on. </p>
<p> 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 <code>okMessage()</code>
and <code>executeMsg()</code> methods. In general, every Message
which is previewed in an objects <code>okMessage()</code> method
is handled in the <code>executeMsg()</code> 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: </p>
<ul>
<li>MOBs
<p> 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. </p>
</li>
<li>Items
<p> Any Message which has the item instance as a target.
</p>
</li>
<li>Exits
<p> Any Message which has the exit instance as a target
or tool. </p>
</li>
<li>Rooms
<p> Any Message which has the room instance as a target.
</p>
</li>
<li>Ability(spell effects)
<p> Any Message pertaining to the MOB or Item
which is affected by the spell or skill. </p>
</li>
<li>Behavior
<p> Any Message pertaining to the object instance which
has this behavior. </p>
</li>
</ul>
<p> 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: </p>
<pre>public boolean show( MOB source,<br /> Environmental target,<br /> int allCode,<br /> String allMessage<br /> );<br /><br />public boolean show( MOB source,<br /> Environmental target,<br /> Environmental tool,<br /> int allCode,<br /> String allMessage<br /> );<br /><br />public boolean show( MOB source,<br /> Environmental target,<br /> Environmental tool,<br /> int srcCode,<br /> int tarCode,<br /> int othCode,<br /> String allMessage<br /> );<br /><br />public boolean show( MOB source,<br /> Environmental target,<br /> Environmental tool,<br /> int srcCode,<br /> String srcMessage,<br /> int tarCode,<br /> String tarMessage,<br /> int othCode,<br /> String othMessage<br /> );<br /><br />public boolean show( MOB source,<br /> Environmental target,<br /> Environmental tool,<br /> int allCode,<br /> String srcMessage,<br /> String tarMessage,<br /> String othMessage<br /> );<br /><br />public boolean showOthers( MOB source,<br /> Environmental target,<br /> int allCode,<br /> String allMessage<br /> );<br /><br />public boolean showOthers( MOB source,<br /> Environmental target,<br /> Environmental tool,<br /> int allCode,<br /> String allMessage<br /> );<br /><br />public boolean showSource( MOB source,<br /> Environmental target,<br /> int allCode,<br /> String allMessage<br /> );<br /><br />public boolean showSource( MOB source,<br /> Environmental target,<br /> Environmental tool,<br /> int allCode,<br /> String allMessage<br /> );<br /><br />public void showHappens(int allCode, String allMessage);<br /><br />public void showHappens( int allCode,<br /> Environmental like,<br /> String allMessage<br /> );<br /></pre>
<p> 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 <code>showHappens()</code> 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 <code>showOthers()</code> methods behave like the first, but
do not allow the source MOB to preview or execute the message,
while the <code>showSource()</code> methods ONLY allows the source
MOB to preview and execute the message. </p>
<p> 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. </p>
<h3><a name="messagetrailers">Message Trailers</a></h3>
<p> 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
<code>CMMsg.addTrailerMsg(CMMsg msg)</code> 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. </p>
<p> 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. </p>
<img src="images/temple.jpg" alt="The State of Things" />
<h2><a name="DIG2" id="DIG2">Core Topic 2: The State of Things:</a></h2>
<p> 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! </p>
<p> Each instance of the several Environmental
objects (MOBs, Items, Exits, Rooms) have a particular storage/state
object called their Environmental Stats. This object implements the
Common.interfaces.EnvStats interface, and is typically an instance
of the Common.DefaultEnvStats class. Access to this state object
is available through each core.interfaces.Environmental objects
<code>EnvStats baseEnvStats()</code> and <code>EnvStats
envStats()</code> method calls. Since Rooms, MOBS, Items, Exits,
and Areas are all Environmental objects, that means that they
all have baseEnvStats and envStats methods as well. </p>
<h3><a name="envstats" id="envstats">EnvStats state object fields</a></h3>
<table bgcolor="#ccccff" border="1">
<thead> <tr>
<th> Field name </th>
<th> Relevant objects </th>
<th> Meaning </th>
</tr>
</thead> <tbody>
<tr>
<td> level </td>
<td> Item, MOB, Exit </td>
<td> Experience level (see Archon's
Guide) </td>
</tr>
<tr>
<td> ability </td>
<td> Item, MOB </td>
<td> Magical level (see Archon's Guide)
</td>
</tr>
<tr>
<td> rejuv </td>
<td> Item, MOB </td>
<td> Rejuvenation rate (see Archon's
Guide) </td>
</tr>
<tr>
<td> weight </td>
<td> Item, MOB </td>
<td> Weight of the object
</td>
</tr>
<tr>
<td> height </td>
<td> Armor, MOB </td>
<td> Size of the object
</td>
</tr>
<tr>
<td> armor </td>
<td> Item, MOB </td>
<td> Protection level (see Archon's
Guide) </td>
</tr>
<tr>
<td> damage </td>
<td> Item, MOB </td>
<td> Damaging ability
</td>
</tr>
<tr>
<td> speed </td>
<td> Item, MOB </td>
<td> Attack speed </td>
</tr>
<tr>
<td> attackAdjustment </td>
<td> Item, MOB </td>
<td> Attack level </td>
</tr>
<tr>
<td> replacementName </td>
<td> Item, MOB, Exit </td>
<td> New displayable name of the object
</td>
</tr>
<tr>
<td> sensesMask </td>
<td> Item, MOB, Exit, Room
</td>
<td> Bit mask of relevant sensory abilities.
</td>
</tr>
<tr>
<td> disposition </td>
<td> Item, MOB, Exit, Room
</td>
<td> Bit mask of relevant disposition
state </td>
</tr>
</tbody>
</table>
<p> 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.EnvStats interface. The equates which refer to
the bits for sensesMask all begin with "CAN_", while the equates
which refer to the bits for disposition all begin with "IS_".
</p>
<p> Now, as mentioned previously, all Environmental
objects have two methods for accessing their EnvStats. One
is <code>core.interfaces.Environmental.baseEnvStats()</code>
and the other is <code>core.interfaces.Environmental.envStats()</code>.
The difference between these two methods is very significant.
The EnvStats state object returned by the "baseEnvStats" method
refers to the permanent, unmodified, "base" state of the Environmental
object. The "envStats" method, however, returns the modified,
less permanent, "current" state of the Environmental object. The
EnvStats object returned by the "envStats" method is always copied
and derived from the "baseEnvStats" values, after all relevant
modifications have been made to it. How the current state object
goes from its base values (baseEnvStats) to its current values
(envStats) is our next topic. </p>
<p> We must now introduce two other Environmental
interface methods significant to this topic. One is the <code>recoverEnvStats()</code>
method, while the other is the <code>affectEnvStats(Environmental
affected, EnvStats affectableStats)</code> method. The "recoverEnvStats"
method is also located on every Environmental (Item, MOB, Exit,
etc) object and is the method which turns the <code>baseEnvStats()</code>
values into their current <code>envStats()</code> 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 <code>recoverEnvStats()</code>
method return. In essence, <code>recoverEnvStats()</code> allows
the Environmental objects <code>baseEnvStats()</code> to be updated,
with that updated state object made available through <code>envStats()</code>.
</p>
<p> The way in which the current EnvStats state
object is modified by the <code>recoverEnvStats()</code> method call is
by making repeated internal calls to the <code>affectEnvStats(Environmental
affected, EnvStats affectedStats)</code> 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 Environmental are as follows: </p>
<ul>
<li>MOBs
<p> 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). </p>
</li>
<li>Items, Exits, Areas
<p> Ability objects which are affecting it (spell
effects). </p>
</li>
<li>Rooms
<p> 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. </p>
</li>
</ul>
<p> Here is an example: </p>
<p> 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 "recoverEnvStats" method is
called on Gunker's MOB object. That method in turn calls the
"affectEnvStats" method on the Plate Armor and the Shield spell
Effect. Both of those methods improve the Armor rating on Gunker's
MOB's current EnvStats 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 EnvStats
object. </p>
<p> I know, this is probably still confusing. </p>
<p> 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. </p>
<p> The CharStats objects are most closely analogous
to the EnvStats objects. For instance, there are <code>CharStats
baseCharStats()</code> and <code>CharStats charStats()</code>
method calls from a MOB object, as well as a <code>recoverCharStats()</code>
method call. All of these work similarly to the ones described
above for EnvStats. 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
<code>int getStat(int)</code> and <code>setStat(int,int)</code>
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:
</p>
<p><a name="charstats" id="charstats"> </a> 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.
</p>
<p> In addition to these equates defined and read
through the <code>getStat()</code> and <code>setStat()</code> methods,
there is also the Race object available through <code>getMyRace()</code>
and <code>setMyRace()</code> 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.
</p>
<p> Like the EnvStats above, those objects listed as
able to modify the EnvStats current state object are the same
objects which are able to modify the CharStats state objects.
Rereading the section on EnvStats will make clear how the CharStats
objects are modified in the same analogous manner, using repeated
calls to<code>affectCharStats(MOB affected, CharStats
affectedStats)</code> methods on related objects. </p>
<p><a name="charstate" id="charstate"> </a> 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. </p>
<p> Unlike EnvStats and CharStats, there are three
CharState objects to consider for MOBs: the base CharState object
(available through<code>CharState baseState()</code> method,
the adjusted base CharState (or max state) object available through
the <code>CharState maxState()</code> method and modified
by <code>recoverMaxState(MOB affected, CharState affectedState)</code>
methods on related objects, and lastly the current CharState object
available through the <code>CharState curState()</code>
and refreshed or reset to maximums using the MOBs <code>resetToMaxState()</code>
method. </p>
<p> 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.
</p>
<p> In the case of the CharState objects, adjustment
by relevant objects is initiated by calling the MOBs <code>recoverMaxState()</code>
method. This method allows the same objects who modify the EnvStats
and CharStats above to modify the maximum CharState values as
well. </p>
<p> Once again, to understand one of them fully is to understand
them all. </p>
<img src="images/time.jpg" alt="Tick Tock" />
<h3><a name="DIG3" id="DIG3">Core Topic 3: Tick Tock</a></h3>
<p> Our last 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
<code>boolean tick(Tickable ticking, int tickID)</code>.
All Environmental objects define this method, and Behavior objects
do as well. </p>
<p> 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. </p>
<p> Before we get into the methods by which an object instance
are properly set up for regular calls to its <code>tick()</code>
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:
</p>
<ul>
<li>MOBs
<p> All MOBs have their <code>tick()</code> method called
once per core.interfaces.MudHost.TIME_TICK (4 seconds), with the
"tickID" defined by Host.MOB_TICK. MOBs will, in turn, call the
<code>tick()</code> 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. </p>
</li>
<li>Exits, Items, Rooms
<p> Whenever a Behavior is added to any of
these objects, they will begin to have their tick methods called
once per MudHost.TIME_TICK (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. </p>
</li>
<li>Areas
<p> All Area objects have their tick methods
called once per core.interfaces.MudHost.TIME_TICK, with the tickID
defined by Tickable.TICKID_AREA. </p>
</li>
<li>Ability
<p> Whenever an Ability object is added as an Effect
(using the <code>addEffect()</code> Environmental 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. </p>
</li>
</ul>
<p> 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. </p>
<p> 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: </p>
<pre>CMClass.threads().startTickDown(theEnvObject,Tickable.MY_TICK_ID,TIME_TICK,NUM_TICKS);<br /></pre>
<p> The second parameter is the tickID which will be used
when the <code>tick()</code> 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 <code>tick()</code> method.
The total time between each call to the <code>tick()</code> method,
therefore, will be TIME_TICK * NUM_TICKS. </p>
<p> Now, the above version of <code>startTickDown()</code>
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 of 4000 milliseconds as defined by Tickable.TIME_TICK.
For this reason, a different version of the <code>startTickDown()</code>
method is called which does not include the TIME_TICK parameter,
utilizing the standard 4 second delay instead: </p>
<pre>CMClass.ThreadEngine().startTickDown(theEnvObject,Host.MY_TICK_ID,NUM_TICKS);<br /></pre>
<p> Stopping any of these tick calls can be done by simply
returning "false" from the tick method itself, or manually using
the following: </p>
<pre>CMClass.ThreadEngine().deleteTick(theEnvObject,Host.MY_TICK_ID);<br /></pre>
<p> You may also stop tick calls to an object by
using the Environmental objects <code>destroy()</code> method.
</p>
<img src="images/books.jpg" alt="Core Libraries" />
<h2><a name="DIG4" id="DIG4">Core Topic 4: Core Libraries</a></h2>
<p> 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. </p>
<p> 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:<br />
</p>
<a name="corepurpose" id="corepurpose"> </a>
<table bgcolor="#ffffcc" border="1">
<thead> <tr>
<th> Core Class Name </th>
<th> Purpose </th>
</tr>
</thead> <tbody>
<tr>
<td> B64Encoder </td>
<td> Encode and decode text<->binary
using Base64 </td>
</tr>
<tr>
<td> CMath </td>
<td> Converting strings to numbers, performing
bit-wise and other arithmetic operations </td>
</tr>
<tr>
<td> CMClass </td>
<td> Main ClassLoader -- get all your
objects from methods here! </td>
</tr>
<tr>
<td> CMFile </td>
<td>FileSystem manager, get all your file data from this
class </td>
</tr>
<tr>
<td> CMLib </td>
<td> The non-core library reference object.
* See below for more information.
</td>
</tr>
<tr>
<td> CMParms </td>
<td> Methods for parsing strings and
determining parameter values in many different ways.
</td>
</tr>
<tr>
<td> CMProps </td>
<td> Properties manager, for reading
INI file values from coffeemud.ini and other places.
</td>
</tr>
<tr>
<td> CMSecurity </td>
<td> The security manager, for evaluating
player and system security flags. </td>
</tr>
<tr>
<td> CMStrings </td>
<td> Methods to manipulate, pad, and
filter strings. </td>
</tr>
<tr>
<td> Directions </td>
<td> Methods to handle the different
compass directions. </td>
</tr>
<tr>
<td> DVector </td>
<td> A multi-dimensional version of java.util.Vector
</td>
</tr>
<tr>
<td> Log </td>
<td> The file and console logging manager.
</td>
</tr>
<tr>
<td> Resources </td>
<td> The object-resource manager, usually
with lots of StringBuffers keyed by String names.
</td>
</tr>
<tr>
<td> Scripts </td>
<td> The human-language readable strings
loader. </td>
</tr>
</tbody>
</table>
<p> You should check out the javadocs for those classes for
more information on the core classes. </p>
<p> * 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.
</p>
<p> 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. </p>
<p> Here is a map of how the classes, interfaces, and CMLib
methods are all mapped together: </p>
<a name="corelibrarymap" id="corelibrarymap"> </a>
<table bgcolor="#99ff99" border="1">
<thead> <tr>
<th> Library class name<br />
<code>...Libraries.*</code> </th>
<th> Library interface name<br />
<code>...Libraries.interfaces.*</code>
</th>
<th> CMLib method name<br />
<code>...core.CMLib</code> </th>
<th> Purpose of the Library
</th>
</tr>
</thead> <tbody>
<tr>
<td> BeanCounter </td>
<td> MoneyLibrary </td>
<td> <code>beanCounter()</code>
</td>
<td> Handle money and currency.
</td>
</tr>
<tr>
<td> CharCreation </td>
<td> CharCreationLibrary
</td>
<td> <code>login()</code>
</td>
<td> Login and create new players.
</td>
</tr>
<tr>
<td> Clans </td>
<td> ClanManager </td>
<td> <code>clans()</code>
</td>
<td> Handle all clans.
</td>
</tr>
<tr>
<td> CMAble </td>
<td> AbilityMapper </td>
<td> <code>ableMapper()</code>
</td>
<td> Maps CharClasses to Skills/Abilities.
</td>
</tr>
<tr>
<td> CMChannels </td>
<td> ChannelsLibrary </td>
<td> <code>channels()</code>
</td>
<td> Handles public channels.
</td>
</tr>
<tr>
<td> CMColor </td>
<td> ColorLibrary </td>
<td> <code>color()</code>
</td>
<td> ANSI and color code conversions.
</td>
</tr>
<tr>
<td> CMEncoder </td>
<td> TextEncoders </td>
<td> <code>encoder()</code>
</td>
<td> Compression library.
</td>
</tr>
<tr>
<td> CMJournals </td>
<td> JournalsLibrary </td>
<td> <code>journals()</code>
</td>
<td> Handles public journal commands.
</td>
</tr>
<tr>
<td> CMLister </td>
<td> ListingLibrary </td>
<td> <code>lister()</code>
</td>
<td> Handles listing tables nicely.
</td>
</tr>
<tr>
<td> CMMap </td>
<td> WorldMap </td>
<td> <code>map()</code>
</td>
<td> Find areas and rooms.
</td>
</tr>
<tr>
<td> CoffeeFilter </td>
<td> TelnetFilter </td>
<td> <code>coffeeFilter()</code>
</td>
<td> Filters/transforms text going to
and from a player. </td>
</tr>
<tr>
<td> CoffeeLevels </td>
<td> ExpLevelLibrary </td>
<td> <code>leveler()</code>
</td>
<td> Leveling and Experience gaining
functionality. </td>
</tr>
<tr>
<td> CoffeeMaker </td>
<td> CMObjectBuilder </td>
<td> <code>coffeeMaker()</code>
</td>
<td> Generic Mob/Item and CoffeeXML generators.
</td>
</tr>
<tr>
<td> CoffeeShops </td>
<td> ShoppingLibrary </td>
<td> <code>coffeeShops()</code>
</td>
<td> Handles manipulation of shop inventories.
</td>
</tr>
<tr>
<td> CoffeeTables </td>
<td> StatisticsLibrary
</td>
<td> <code>coffeeTables()</code>
</td>
<td> Maintains player usage stats.
</td>
</tr>
<tr>
<td> CoffeeTime </td>
<td> TimeManager </td>
<td> <code>time()</code>
</td>
<td> Real-life data/time display.
</td>
</tr>
<tr>
<td> CoffeeUtensils </td>
<td> CMMiscUtils </td>
<td> <code>utensils()</code>
</td>
<td> Misc stuff-- law, traps, titles,
resets. </td>
</tr>
<tr>
<td> CommonMsgs </td>
<td> CommonCommands </td>
<td> <code>commands()</code>
</td>
<td> Methods for getting, talking, common-stuff
</td>
</tr>
<tr>
<td> Dice </td>
<td> DiceLibrary </td>
<td> <code>dice()</code>
</td>
<td> Random number generator.
</td>
</tr>
<tr>
<td> EnglishParser </td>
<td> EnglishParsing </td>
<td> <code>english()</code>
</td>
<td> Player command line parsing helpers.
</td>
</tr>
<tr>
<td>ColumbiaUniv</td>
<td>ExpertiseLibrary</td>
<td><span style="font-family: monospace;">expertise()</span></td>
<td>Maintains expertise skill flags</td>
</tr>
<tr>
<td> Factions </td>
<td> FactionManager </td>
<td> <code>factions()</code>
</td>
<td> Handles the factions and faction
system. </td>
</tr>
<tr>
<td>MUDLaw</td>
<td>LegalLibrary</td>
<td>l<span style="font-family: monospace;">aw()</span></td>
<td>Handles legal and property matters.</td>
</tr>
<tr>
<td> MUDFight </td>
<td> CombatLibrary </td>
<td> <code>combat()</code>
</td>
<td> Combat and Death routines.
</td>
</tr>
<tr>
<td> MUDHelp </td>
<td> HelpLibrary </td>
<td> <code>help()</code>
</td>
<td> Handling help-file entries.
</td>
</tr>
<tr>
<td> MUDTracker </td>
<td> TrackingLibrary </td>
<td> <code>tracking()</code>
</td>
<td> Methods for NPC movement, and for
tracking. </td>
</tr>
<tr>
<td> MUDZapper </td>
<td> MaskingLibrary </td>
<td> <code>masking()</code>
</td>
<td> Zapper-mask parsing and evaluation.
</td>
</tr>
<tr>
<td> Polls </td>
<td> PollManager </td>
<td> <code>polls()</code>
</td>
<td> Handle the public polls.
</td>
</tr>
<tr>
<td> Quests </td>
<td> QuestManager </td>
<td> <code>quests()</code>
</td>
<td> Quest Manager system.
</td>
</tr>
<tr>
<td>RawCMaterials</td>
<td>MaterialLibrary</td>
<td><span style="font-family: monospace;">materials()</span></td>
<td>Manipulate/Create raw resource objects</td>
</tr>
<tr>
<td> Sense </td>
<td> CMFlagLibrary </td>
<td> <code>flags()</code>
</td>
<td> Sensory and Disposition bitmap/flag
handling. </td>
</tr>
<tr>
<td> Sessions </td>
<td> SessionsList </td>
<td> <code>sessions()</code>
</td>
<td> Container for player connection
objects. </td>
</tr>
<tr>
<td> SlaveryParser </td>
<td> SlaveryLibrary </td>
<td> <code>slavery()</code>
</td>
<td> Geas and Slavery order parsing
and execution. </td>
</tr>
<tr>
<td> SMTPclient </td>
<td> SMTPLibrary </td>
<td> <code>smtp()</code>
</td>
<td> E-Mail sending routines.
</td>
</tr>
<tr>
<td> Socials </td>
<td> SocialsList </td>
<td> <code>socials()</code>
</td>
<td> Socials container and parser.
</td>
</tr>
<tr>
<td> StdLibrary </td>
<td> NONE </td>
<td> NONE </td>
<td> SuperClass of other libraries.
</td>
</tr>
<tr>
<td> TimsLibrary </td>
<td> ItemBuilderLibrary
</td>
<td> <code>itemBuilder()</code>
</td>
<td> Methods for normalized item evaluation.
</td>
</tr>
<tr>
<td> XMLManager </td>
<td> XMLLibrary </td>
<td> <code>xml()</code>
</td>
<td> General XML parsing.
</td>
</tr>
</tbody>
</table>
<p> 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. </p>
<p> 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.
</p>
<a name="corecommon" id="corecommon"> </a>
<table bgcolor="#ccccff" border="1">
<thead> <tr>
<th> Common Class </th>
<th> Description </th>
</tr>
</thead> <tbody>
<tr>
<td> DefaultArrestWarrant
</td>
<td> An object created every time a law
is broken. </td>
</tr>
<tr>
<td> DefaultCharState
</td>
<td> Contains a mobs hit points, mana,
movement, fatigue, hunger, and thirst. </td>
</tr>
<tr>
<td> DefaultCharStats
</td>
<td> Contains a mobs class, race, saving
throws, and basic stat scores. </td>
</tr>
<tr>
<td> DefaultClan </td>
<td> Represents a single Clan.
</td>
</tr>
<tr>
<td> DefaultClimate </td>
<td> A single climatary system for a
given area. </td>
</tr>
<tr>
<td> DefaultCMIntegerGrouper
</td>
<td> An object for maintaining a players
room visitation memory. </td>
</tr>
<tr>
<td> DefaultCoffeeShop
</td>
<td> Represents a single shop store inventory.
</td>
</tr>
<tr>
<td> DefaultCoffeeTableRow
</td>
<td> Represents a days worth of game
player usage statistics. </td>
</tr>
<tr>
<td> DefaultEnvStats </td>
<td> Contains an objects attack bonus,
armor bonus, weight, height, rejuv rate. </td>
</tr>
<tr>
<td> DefaultFaction </td>
<td> Represents a single faction.
</td>
</tr>
<tr>
<td> DefaultLawSet </td>
<td> Represents a single set of laws
and legal policies. </td>
</tr>
<tr>
<td> DefaultMessage </td>
<td> A CoffeeMud event message (CMMsg).
</td>
</tr>
<tr>
<td> DefaultPlayerStats
</td>
<td> Represents player-specific fields
like prompts, friends, alias, etc. </td>
</tr>
<tr>
<td> DefaultPoll </td>
<td> A single poll object.
</td>
</tr>
<tr>
<td> DefaultQuest </td>
<td> Container for a single timed quest.
</td>
</tr>
<tr>
<td> DefaultRoomnumberSet
</td>
<td> Container for a players area visitation
memory. </td>
</tr>
<tr>
<td> DefaultSession </td>
<td> Connection object for handling a
players telnet session with the mud </td>
</tr>
<tr>
<td> DefaultSocial </td>
<td> Object for a single social command.
</td>
</tr>
<tr>
<td> DefaultTimeClock
</td>
<td> Object representing a single calendar/time
system that spans areas, possibly the whole world.
</td>
</tr>
</tbody>
</table>
<br />
<br />
<img src="images/stat.jpg" alt="Core Libraries" height="70" width="87" />
<h2><a name="DIG5" id="DIG4">Core Topic 5: Stat</a></h2>
<p>In the uncoming sections, you will learn about the layout and design
of each of the several major CoffeeMud class types. Sometimes, however,
you may want to expand or extend the classes to include new or extraneous
data. If so, this last core topic is for you.<br />
</p>
<p>All of the classes which implement the Environmental interface (including
Abilities, Exits, Areas, Rooms, MOBs, and Items) or the PlayerStats interface
(Player MOBs) or several others, will include the following methods for accessing
and modifying certain internal data fields:<br />
</p>
<p><tt> public String[] getStatCodes();<br />
public int getSaveStatIndex();<br />
public String getStat(String code);<br />
public void setStat(String code, String val);</tt><br />
</p>
<p>The<tt> getStatCodes() </tt>method returns a string array of the
"names" of the internal data fields which this class makes available to the
outside world. These names can then be used in the <tt>getStat(String)</tt>
method to retreive the string-rendered values of those data fields, and the
<tt>setStat(String,String)</tt> method can be used to change them. This
is a very versitile way of reading and writing the particular aspects of
a data object, especially when you don't know for sure what kind of object
it is (or you don't care).<br />
</p>
<p>However, the reason this might interest you is because of the method
we havn't mentioned yet: <tt>getSaveStatIndex()</tt>. The purpose of
this method is quite simple: It returns the number of stat code names (from
<tt>getStatCodes()</tt> ) that are already handled by the existing database
code. This means that, for a stock CoffeeMud system, this method will
return the same number as <tt>getStatCodes().length</tt> would. However,
should you decide to add to the stat name strings defined by getStatCodes()
and then extend getStat and setStat methods to manage your own internal variables,
you have only to make sure your new name is at the end, and that getSaveStatIndex()
stops short of that number, to make sure that CoffeeMud will go ahead and
save your new data to the database (and restore it, of course). Exporting
to cmare files and other features are also included this way.<br />
</p>
<p>Here is an example:<br />
</p>
<p><tt>public class MySpecialGenMob extends GenMOB<br />
{<br />
public String ID(){return "</tt><tt>MySpecialGenMob</tt><tt>";}<br />
<br />
private String myvariable="";<br />
<br />
public String[] getStatCodes()<br />
{<br />
List L=java.util.Arrays.asList(super.getStatCodes());<br />
L.add("MYVALUE"); <br />
return (String[])L.toArray();<br />
} <br />
public String getStat(String code)<br />
{<br />
if(code.equalsIgnoreCase("MYVALUE"))<br />
return
myvariable;<br />
return super.getStat(code);<br />
}<br />
public void setStat(String code, String value)<br />
{<br />
if(code.equalsIgnoreCase("MYVALUE"))<br />
myvariable=value;<br />
else<br />
super.setStat(code,value);<br />
}<br />
public int getSaveStatIndex(){return super.getStatCodes().length;}</tt></p>
<p><br />
You'll notice above that the getStatCodes() method is extended to add
a new stat code name "MYVALUE" which will appear at the end of the string
list. The getStat and setStat methods are adjusted accordingly to support
the new code. Lastly, the getSaveStatIndex method is overridden to return
the length of the base classes codes instead of mine, that way the getSaveStatIndex
for <tt>MySpecialGenMob </tt>will return one less than the getSaveStatIndex
for GenMOB, the super class.</p>
<p>And just by doing those simple things, we now have a new variable
which the CoffeeMud engine will ensure is written to the database. However,
this capability is limited to the following types of objects: generic mobs,
generic items, playerstats, or any exits, rooms, or area classes. Since
players are technically implemented as StdMOB objects, you will need to modify
the appropriate methods in the DefaultPlayerStats object to achieve the same
effect for players.</p>
<br />
<img src="images/pencil.jpg" alt="commands" />
<h2><a name="CMDS" id="CMDS">Commands</a></h2>
<p> 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. </p>
<p> A Custom Command may or may not belong to any particular
package, though it is important that the <code>ID()</code> 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.
</p>
<pre>public class DoNothing extends com.planet_ink.coffee_mud.Commands.StdCommand<br />{<br /> public DoNothing(){}<br /><br /> private String[] access={ "DONOTHING" };<br /> public String[] getAccessWords(){ return access; }<br /></pre>
<p> 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. </p>
<p> 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. </p>
<pre>public double actionsCost(){ return 1.0; }<br />public double combatActionsCost(){ return 1.0; }<br /><br />public boolean canBeOrdered(){ return true; }<br /></pre>
<p> The next two methods, <code>actionsCost()</code> and
<code>combatActionsCost()</code>, 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 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. </p>
<p> The <code>canBeOrdered()</code> 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.
</p>
<pre> public boolean securityCheck( MOB mob )<br /> {<br /> return CMSecurity.isAllowed( mob, mob.location(), "IMMORT");<br /> }<br /></pre>
<p> And speaking of security, this method returns whether
or not the given mob may even have access to this command. If
the <code>securityCheck()</code> 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 there.
</p>
<p> In the above example, we call the <code>isAllowed()</code>
method in CMSecurity with the mob reference, the room in which
the mob is located, and the security code "IMMORT". This asks the
Security module whether this mob, at this location, is authorized
to perform functions designated by the "IMMORT" security code.
</p>
<pre> public boolean preExecute(MOB mob, Vector commands, int secondsElapsed, double actionsRemaining)<br /> throws java.io.IOException;<br /> {<br /> if( secondsElapsed == 0 )<br /> {<br /> mob.tell( "You are preparing to do nothing." );<br /> }<br /><br /> if( secondsElapsed == 3 )<br /> {<br /> mob.tell( "You almost ready to do nothing." );<br /> }<br /> }<br /></pre>
<p> The <code>preExecute()</code> method is very rarely implemented,
but it is important to mention in light of the <code>actionsCost()</code>
and <code>combatActionsCost()</code> 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. </p>
<pre> public boolean execute( MOB mob, Vector commands )<br /> throws java.io.IOException<br /> {<br /> String parameters = CMParms.combine( commands, 1 );<br /> if( parameters.length() == 0 )<br /> {<br /> mob.tell( "Nothing done." );<br /> }<br /> else<br /> {<br /> mob.tell( "Nothing, not even '" + parameters + "', done." );<br /> }<br /> return false;<br /><br /> }<br /> </pre>
<p> 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 Vector of parameters.
</p>
<p> The parameter commands is never null, and by convention
is a Vector of strings starting with the access word used to execute
the command. For instance, if the user entered: </p>
<pre>donothing never "and always" never<br /> </pre>
<p> The commands Vector 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 vector is the word "donothing", which means we
can safely ignore it. </p>
<img src="images/smurf.jpg" alt="MOBs" />
<h2><a name="MOBS" id="MOBS">MOBs</a></h2>
<p> 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! </p>
<p> 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 <code>ID()</code> of "StdMOB", or because you want to
add special NPC monster capabilities by creating your own class
that extends GenMob and has an <code>ID()</code> of "GenMob".
</p>
<p> 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. </p>
<h3><a name="mobcoding" id="mobcoding">Coding a new MOB</a></h3>
<p> 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. </p>
<p> 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
<code>ID()</code> of "StdMOB". If you do this, however, make
sure your class is loaded after the %DEFAULT% list in your coffeemud.ini
file. </p>
<p> As was stated, each unique MOB must also have a custom
<code>ID()</code> method as shown below. Notice that the
<code>ID()</code> is the same as the name of the class. This
is no accident -- this is required! </p>
<pre>public class MyNewMOB extends com.planet_ink.coffee_mud.MOBS.StdMOB<br />{<br /> public String ID(){ return "MyNewMOB";}<br /></pre>
<p> All of your customizing will be done inside the
constructor: name, displayText, description, etc, etc. </p>
<pre> public MyNewMOB()<br /> {<br /> super();<br /><br /> setName( "a new mob" );<br /> setDescription( "It`s furry with 2 legs" );<br /> setDisplayText( "My new mob is standing here." );<br /><br /> Factions.setAlignment( this, Faction.ALIGN_NEUTRAL );<br /> setMoney( 0 );<br /> setWimpHitPoint( 2 );<br /> baseEnvStats().setDamage( 4 );<br /><br /> baseEnvStats().setAbility( 0 );<br /> baseEnvStats().setLevel( 1 );<br /> baseEnvStats().setArmor( 30 );<br /> baseEnvStats().setSpeed( 1.0 );<br /> baseEnvStats().setAttackAdjustment( 30 );<br /> baseEnvStats().setWeight( 85 );<br /> baseEnvStats().setSensesMask( EnvStats.CAN_SEE_DARK|EnvStats.CAN_SEE_INFRARED );<br /> baseEnvStats().setDisposition( EnvStats.IS_FLYING );<br /> baseCharStats().setCurrentClass( CMClass.getCharClass( "Fighter" ) );<br /><br /> baseCharStats().setMyRace( CMClass.getRace( "Dog" ) );<br /> baseCharStats().getMyRace().startRacing( this, false );<br /> baseCharStats().setStat( CharStats.STAT_GENDER, (int)'F' );<br /> baseCharStats().setStat( CharStats.STAT_STRENGTH, 18 );<br /> baseCharStats().setStat( CharStats.STAT_INTELLIGENCE, 14 );<br /> baseCharStats().setStat( CharStats.STAT_WISDOM, 13 );<br /> baseCharStats().setStat( CharStats.STAT_DEXTERITY, 15 );<br /> baseCharStats().setStat( CharStats.STAT_CONSTITUTION, 12 );<br /> baseCharStats().setStat( CharStats.STAT_CHARISMA, 13 );<br /> baseCharStats().setStat( CharStats.STAT_SAVE_COLD, 50 );<br /><br /> baseState.setHitPoints( CMLib.dice().roll( baseEnvStats().level(), 20, 20 ) );<br /> baseState.setMana( CMLib.dice().roll( baseEnvStats().level(), 50, 100 ) );<br /><br /> recoverMaxState();<br /> resetToMaxState();<br /> recoverEnvStats();<br /> recoverCharStats();<br /> }<br /></pre>
<p> 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. </p>
<p> 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. <code>recoverEnvStats()</code>,
for instance, must be called whenever a change is made to the <code>baseEnvStats()</code>
object. Ditto for "CharStats" and "MaxState". </p>
<p> 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. </p>
<pre> addNonUninvokableEffect( CMClass.getAbility( "Fighter_Berzerk" ) );<br /><br /> Ability A = CMClass.getAbility( "Prop_Resistance" );<br /> if( A != null )<br /> {<br /> A.setMiscText( "Fire 200%" );<br /> addNonUninvokableEffect( A );<br /> }<br /><br /> addAbility( CMClass.getAbility( "Poison" ) );<br /><br /> addBehavior( CMClass.getBehavior( "MudChat" ) );<br /> addBehavior( CMClass.getBehavior( "Mobile" ) );<br /> addBehavior( CMClass.getBehavior( "CombatAbilities" ) );<br /></pre>
<p> 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. </p>
<p> If your MOB extends StdShopKeeper, you will need
to add your inventory manually through the <code>getShop()</code> object
access method as shown below. The <code>getShop()</code> 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. </p>
<pre> setWhatIsSold( ShopKeeper.ONLYBASEINVENTORY );<br /><br /> Weapon sword = (Weapon)CMClass.getWeapon( "Longsword" );<br /> getShop().addStoreInventory( sword, 35, -1, this );<br /> Armor mail = (Armor)CMClass.getArmor( "FullPlate" );<br /> getShop().addStoreInventory( mail, 35, -1, this );<br /> Item waterskin = CMClass.getItem( "Waterskin" );<br /> getShop().addStoreInventory( waterskin, 35, -1, this );<br /></pre>
<p> You'll recall from the Archon's Guide that there are
many different types of ShopKeepers, including trainers, pet sellers,
weaponsmiths, and others. </p>
<p> StdRideable MOBs will require a few other settings
as well! </p>
<pre> setRideBasis( Rideable.RIDEABLE_LAND );<br /> setMobCapacity( 2 );<br /></pre>
<p> The last thing is to give the MOB equipment, armor, and
weapons. The following commands will do the trick! </p>
<pre> Weapon sword = (Weapon)CMClass.getWeapon( "Longsword" );<br /> addInventory( sword );<br /> sword.wearIfPossible( this );<br /><br /> Armor mail = (Armor)CMClass.getArmor( "FullPlate" );<br /> addInventory( mail );<br /> mail.wearIfPossible( this );<br /><br /> Item sack = (Item)CMClass.getItem( "StdContainer" );<br /> addInventory( sack );<br /><br /> Item waterskin = (Item)CMClass.getItem( "Waterskin" );<br /> addInventory( waterskin );<br /> waterskin.setContainer( sack );<br /></pre>
<p> 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. </p>
<p> 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
<code>ID()</code> 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. </p>
<h3><a name="moblife" id="moblife">Bringing MOBs to Life, and Taking
That Life Away</a></h3>
<p> 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. </p>
<p> 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. </p>
<pre>MOB mob = CMClass.getMOB( "MyNewMOB" );<br />Room room = CMLib.map().getRoom( "Midgaard#3504" );<br /><br />mob.setStartRoom( room ); // this mob will rejuvenate into this room.<br />mob.baseEnvStats().setRejuv( 500 ); // 30 minutes rejuvenation time<br />mob.recoverEnvStats(); // remember this command?!<br /><br />mob.bringToLife( room, true ); // tadah!<br /></pre>
<p> And THAT's all there is to bring a standard mob to life.
Now, generic items require an additional step: </p>
<pre>Item item = CMClass.getItem( "GenItem" );<br />Room room = CMLib.map().getRoom( "Midgaard#3504" );<br /><br />item.text();<br />item.recoverEnvStats();<br />room.addItem( item );<br />room.recoverRoomStats();<br /></pre>
<p> The call to the <code>text()</code> method and the seemingly
redundant call to <code>Item.recoverEnvStats()</code> (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: </p>
<pre>Room room = CMLib.map().getRoom( "Midgaard#3504" );<br />for( int i = 0; i < room.numInhabitants(); i++ )<br />{<br /> MOB mob = room.fetchInhabitant( i );<br /> mob.destroy();<br />}<br /></pre>
<img src="images/sword.jpg" alt="Items" />
<h2><a name="ITEMS" id="ITEMS">Items:</a></h2>
<p> A Custom Item may or may not belong to any
particular package, though it is important that the <code>ID()</code> 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. </p>
<p> 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 <code>ID()</code> 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.
</p>
<p> Each Item must also have a custom <code>ID()</code> method
as shown below. Notice that the <code>ID()</code> is the same
as the name of the class. This is no accident -- this is required!
</p>
<pre>public class MyNewSword extends com.planet_ink.coffee_mud.Items.Weapons.StdWeapon<br />{<br /> public String ID(){ return "MyNewSword"; }<br /><br /> public MyNewSword()<br /> {<br /> super();<br /> }<br />}<br /></pre>
<p> All of your customizing will be done inside the constructor:
name, displayText, description, etc, etc. </p>
<pre> public MyNewSword()<br /> {<br /> super();<br /><br /> setName( "a super sword" );<br /> setDescription( "A long super duper sword!" );<br /> setDisplayText( "Someone left their super sword here." );<br /> setSecretIdentity( "" );<br /> setMaterial( RawMaterial.RESOURCE_STEEL );<br /> setWeaponType( Weapon.TYPE_SLASHING );<br /> setWeaponClassification( Weapon.CLASS_SWORD );<br /><br /> setBaseValue( 500 );<br /> baseEnvStats().setDisposition( EnvStats.IS_GLOWING );<br /> baseEnvStats.setWeight( 25 );<br /> baseEnvStats.setAttackAdjustment( 10 );<br /> baseEnvStats.setDamage( 15 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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? </p>
<pre> public MyNewBow()<br /> {<br /> super();<br /><br /> setName( "a super bow" );<br /> setDescription( "A long super duper bow!" );<br /> setDisplayText( "Someone left their super bow here." );<br /> setSecretIdentity( "" );<br /><br /> setMaterial( RawMaterial.RESOURCE_OAK );<br /> setBaseValue( 5000 );<br /> baseEnvStats.setWeight( 15 );<br /> baseEnvStats.setAttackAdjustment( 20 );<br /> baseEnvStats.setDamage( 5 );<br /> setWeaponType( Weapon.TYPE_PIERCING );<br /> setWeaponClassification( Weapon.CLASS_RANGED );<br /> setRanges( 1, 5 );<br /> setAmmunitionType( "arrows" );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> You'll notice we added two new methods, <code>setRanges()</code>,
and <code>setAmmunitionType()</code>. 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.
Other classes, however, have different requirements altogether.
For instance, if class extends com.planet_ink.coffee_mud.Items.Armor.StdArmor:
</p>
<pre> public MyNewArmor()<br /> {<br /> super();<br /><br /> setName( "a super bracer" );<br /> setDescription( "A super duper bracer" );<br /> setDisplayText( "Someone left their super bracer here." );<br /> setSecretIdentity( "" );<br /><br /> setMaterial( RawMaterial.RESOURCE_STEEL );<br /> setBaseValue( 100 );<br /> baseEnvStats.setWeight( 5 );<br /> baseEnvStats.setArmor( 5 );<br /> setRawProperLocationBitmap( Item.WORN_LEFT_WRIST|Item.WORN_RIGHT_WRIST );<br /> setRawLogicalAnd( false );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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:
</p>
<pre> public MyNewBag()<br /> {<br /> super();<br /><br /> setName( "a super bag" );<br /> setDescription( "A super duper bag" );<br /> setDisplayText( "Someone left their super bag here." );<br /> setSecretIdentity( "" );<br /><br /> setBaseValue( 50 );<br /> setLidsNLocks( false, true, false, false );<br /> setKeyName( "" );<br /> setMaterial( RawMaterial.RESOURCE_LEATHER );<br /> baseEnvStats.setWeight( 1 );<br /> setCapacity( 100 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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: </p>
<pre> public MyNewCup()<br /> {<br /> super();<br /><br /> setName( "a super cup" );<br /> setDescription( "A super duper cup" );<br /> setDisplayText( "Someone left their super cup here." );<br /> setSecretIdentity( "" );<br /><br /> setMaterial( RawMaterial.RESOURCE_LEATHER );<br /> setBaseValue( 5 );<br /> setLiquidHeld( 2000 );<br /> setLiquidRemaining( 2000 );<br /> setThirstQuenched( 500 );<br /> setLiquidType( RawMaterial.RESOURCE_MILK );<br /> baseEnvStats.setWeight( 1 );<br /> setCapacity( 0 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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: </p>
<pre> public MyNewFood()<br /> {<br /> super();<br /><br /> setName( "a super crumb" );<br /> setDescription( "A super duper crumb" );<br /> setDisplayText( "Someone left their super crumbs." );<br /> setSecretIdentity( "" );<br /><br /> setBaseValue( 1 );<br /> setMaterial( RawMaterial.RESOURCE_MEAT );<br /> setNourishment( 500 );<br /> baseEnvStats.setWeight( 1 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> Now, the items extending com.planet_ink.coffee_mud.Items.Basic.StdRideable
resemble the MOB of the same name, and thus, have identical
modifications. </p>
<pre> public MyNewBed()<br /> {<br /> super();<br /><br /> setName( "a bed" );<br /> setDescription( "A bed" );<br /> setDisplayText( "A bed is here" );<br /> setSecretIdentity( "" );<br /><br /> setBaseValue( 100 );<br /> setMobCapacity( 2 );<br /> setRideBasis( Rideable.RIDEABLE_SLEEP );<br /> baseEnvStats.setWeight( 100 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> A pile of money extends class com.planet_ink.coffee_mud.Items.Basic.StdCoins,
and is simplest of all: </p>
<pre> public MyNewMoney()<br /> {<br /> super();<br /><br /> setName( "a pile of coins" );<br /> setDescription( "A pile of coins" );<br /> setDisplayText( "Someone left their money here." );<br /> setSecretIdentity( "" );<br /><br /> setBaseValue( 0 );<br /> setMaterial( RawMaterial.RESOURCE_GOLD );<br /> setNumberOfCoins( 1000 ); // 1000 coins!<br /> setDenomination( 1.0 ); // each coin worth 1.0 basic gold<br /> baseEnvStats.setWeight( 1 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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:
</p>
<pre> public MyNewPill()<br /> {<br /> super();<br /><br /> setName( "a super pill" );<br /> setDescription( "A super duper pill" );<br /> setDisplayText( "Someone left their super pill." );<br /> setSecretIdentity( "" );<br /><br /> setBaseValue( 1 );<br /> setMaterial( RawMaterial.RESOURCE_MEAT );<br /> setNourishment( 500 );<br /> baseEnvStats.setWeight( 1 );<br /> setSpellList( "Spell_Sleep;Prayer_CureLightWounds" );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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: </p>
<pre> public MyNewScroll()<br /> {<br /> super();<br /><br /> setName( "a super scroll" );<br /> setDescription( "A super duper scroll" );<br /> setDisplayText( "Someone left their super scroll." );<br /> setSecretIdentity( "" );<br /> setBaseValue( 100 );<br /><br /> setMaterial( RawMaterial.RESOURCE_PAPER );<br /> setUsesRemaining( 50 );<br /> baseEnvStats.setWeight( 1 );<br /> setScrollSpells( "Spell_Sleep;Prayer_CureLightWounds" );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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:
</p>
<pre> public MyNewWand()<br /> {<br /> super();<br /><br /> setName( "a wand" );<br /> setDescription( "A magic wand" );<br /> setDisplayText( "Someone left their magic wand." );<br /> setSecretIdentity( "" );<br /><br /> setBaseValue( 1000 );<br /> setMaterial( RawMaterial.RESOURCE_OAK );<br /> baseEnvStats.setWeight( 1 );<br /> setSpell( CMClass.getAbility( "Spell_Fireball" ) );<br /> setUsesRemaining( 50 );<br /> recoverEnvStats();<br /> }<br /></pre>
<p> 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. </p>
<p> 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. </p>
<pre>Behavior B = CMClass.getBehavior( "Emoter" );<br />B.setParms( "min=1 max=20 chance=75;makes strange sounds" );<br />addBehavior( B );<br /></pre>
<p> Adding normal effects as properties is also similar to
mobs... </p>
<pre>Ability A = CMClass.getAbility( "Prop_HaveResister" );<br />A.setMiscText( "fire acid 50%" );<br />A.addNonUninvokableEffect( A );<br /></pre>
<p> 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
recoverEnvStats() call. </p>
<p> 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. </p>
<h3><a name="itemlife" id="itemlife">Creating and Destroying Items</a></h3>
<p> 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. </p>
<p> 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:
</p>
<pre>Item item = CMClass.getItem( "MyNewItem" );<br />Room room = CMLib.map().getRoom( "Midgaard#3504" );<br /><br />room.addItem( item );<br />room.recoverRoomStats();<br /></pre>
<p> A room is grabbed off the map, and the item is added
to the room using the <code>addItem()</code> 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: </p>
<pre>Item item = CMClass.getItem( "GenItem" );<br />Room room = CMLib.map().getRoom( "Midgaard#3504" );<br /><br />item.text();<br />item.recoverEnvStats();<br />room.addItem( item );<br />room.recoverRoomStats();<br /></pre>
<p> The call to the <code>text()</code> method and the seemingly
redundant call to <code>Item.recoverEnvStats()</code> (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. </p>
<pre>Item item = CMClass.getItem( "MyNewItem" );<br />Room room = CMLib.map().getRoom( "Midgaard#3504" );<br /><br />item.baseEnvStats().setRejuv( 500 ); // 30 minutes rejuvenation time<br />item.recoverEnvStats();<br />room.addItem( item );<br />room.recoverRoomStats();<br />room.startItemRejuv();<br /></pre>
<p> 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
<code>startItemRejuv()</code>, which handles the rejuv resets on all
items in the room. </p>
<p> In the previous section, we saw how items are given to
mobs by simply calling the <code>addInventory()</code> 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 <code>destroy()</code> method on the item. Here is
an example of destroying all the items in a room. </p>
<pre>Room room = CMLib.map().getRoom( "Midgaard#3504" );<br /><br />for( int i = room.numItems() - 1; i >= 0; i-- )<br />{<br /> Item item = room.fetchItem( i );<br /> item.destroy();<br />}<br /></pre>
<img src="images/clown.jpg" alt="Behaviors" />
<h2><a name="BEHAVS" id="BEHAVS">Behaviors</a></h2>
<p> 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: </p>
<pre>public class Ravenous extends com.planet_ink.coffee_mud.Behaviors.StdBehavior<br />{<br /> public String ID(){ return "Ravenous"; }<br /> public String name(){ return "Ravenous Eater"; }<br /></pre>
<p> Our first step, as seen above, is to make sure we define
an <code>ID()</code> method with the classes name, just as we
do in other CoffeeMud objects. Notice that the <code>ID()</code>
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.
</p>
<pre> protected int canImproveCode(){ return Behavior.CAN_MOBS; }<br /> public long flags(){ return 0; }<br /> public boolean grantsAggressivenessTo( MOB M ){ return false; }<br /></pre>
<p> Next are some important flags that tell the CoffeeMud
system some important things about your behavior. The first method
(<code>canImproveCode()</code>) 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
(<code>flags()</code>) tells the system certain things about the
behavior by returning values such as Behavior.FLAG_MOBILITY, or
Behavior.FLAG_TROUBLEMAKING. The last method (<code>grantsAggressivenessTo()</code>)
says whether or not this method would necessary cause the host
mob to attack the mob (M) in the parameter. </p>
<pre> public void startBehavior( Environmental forMe )<br /> {}<br /></pre>
<p> 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. </p>
<pre> public String getParms(){ return super.getParms(); }<br /> public void setParms( String parameters )<br /> {<br /> super.setParms( parameters );<br /> }<br /></pre>
<p> 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. </p>
<pre> public boolean tick( Tickable ticking, int tickID )<br /> {<br /> MOB mob = getBehaversMOB( ticking ); // returns mob, if ticking is a mob. Returns mob owner, if ticking is an item<br /> Room room = getBehaversRoom( ticking ); // whatever the ticking object is, this will return its location<br /> if( ( mob == null ) || ( room == null ) || ( tickID != Host.MOB_TICK ) )<br /> {<br /> return super.tick( ticking, tickID );<br /> }<br /></pre>
<p> 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. </p>
<p> 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. </p>
<pre> if( ( !canActAtAll( mob ) )<br /> ||( !canFreelyBehaveNormal( mob ) )<br /> )<br /> {<br /> return super.tick( ticking, tickID );<br /> }<br /></pre>
<p> Our next step is to call a couple more internal StdBehavior
methods. The first (<code>canActAtAll()</code>) returns true if
the mob is alive, awake, and mobile. The second method (<code>canFreelyBehaveNormal()</code>)
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. </p>
<pre> Item eatible = null;<br /> for( int i = 0; i < mob.inventorySize(); i++ )<br /> {<br /> Item I = mob.fetchInventory( i );<br /> if( ( I != null ) && ( I instanceof Food ) )<br /> {<br /> eatible=I;<br /> }<br /> }<br /></pre>
<p> Next, we iterate through the mob's inventory to find
the last instance of a piece of food. </p>
<pre> if( eatible != null)<br /> {<br /> room.show( mob, eatible, null, "<S-NAME> gobble(s) up <T-NAMESELF>." );<br /> return true;<br /> }<br /></pre>
<p> 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.
</p>
<pre> int randMob = CMLib.dice().roll( 1, room.numInhabitants(), -1 );<br /> MOB mobToHitUp = room.fetchInhabitant( randMob );<br /> if( ( mobToHitUp == null )<br /> ||( mobToHitUp == mob )<br /> ||( CMLib.dice().rollPercentage() > 75 )<br /> )<br /> {<br /> return true;<br /> }<br /></pre>
<p> 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. </p>
<pre> int randItem = CMLib.dice().roll( 1, mobToHitUp.inventorySize(), -1 );<br /> Item I = mobToHitUp.fetchInventory( randItem );<br /> if( ( I != null ) && ( I instanceof Food ) )<br /> {<br /> eatible = I;<br /> }<br /><br /> if( eatible == null )<br /> {<br /> return true;<br /> }<br /> </pre>
<p> 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. </p>
<pre> CMLib.commands().postSay( mob, mobToHitUp, "May I have some of your " + eatible.name() + "?" , false, false );<br /><br /> return true;<br /> }<br /></pre>
<p> 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! </p>
<pre> public void executeMsg( Environmental affecting, CMMsg msg )<br /> {}<br /><br /> public boolean okMessage( Environmental oking, CMMsg msg )<br /> {<br /> return true;<br /> }<br />}<br /></pre>
<p> 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.
</p>
<img src="images/cloak.jpg" alt="Character Classes" />
<h2><a name="CLASSES" id="CLASSES">Character Classes</a></h2>
<p> 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 <code>ID()</code> 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:
</p>
<pre>public class NormalGuy extends com.planet_ink.coffee_mud.CharClasses.StdCharClass<br />{<br /></pre>
<p> Our Normal Guy character class will define all of the
basic elements of a filled-out character class. </p>
<pre> public String ID()<br /> {<br /> return "NormalGuy";<br /> }<br /><br /> public String baseClass()<br /> {<br /> return ID();<br /> }<br /></pre>
<p> 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 <code>baseClass()</code> 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
<code>ID()</code> and <code>baseClass()</code> 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. </p>
<pre> public String name()<br /> {<br /> return "Normal Guy";<br /> }<br /><br /> public String name( int classLevel )<br /> {<br /> return name();<br /> }<br /></pre>
<p> Our next method, <code>name()</code>, is the default
displayable name of your class. The next method <code>name( int
classLevel )</code> 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! </p>
<pre> protected String[] names = null;<br /><br /> public String[] nameSet()<br /> {<br /> if( names != null )<br /> {<br /> return names;<br /> }<br /><br /> names = new String[1];<br /> names[0] = name();<br /> return names;<br /> }<br /></pre>
<p> The <code>nameSet()</code> 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. </p>
<pre> public int getHPDivisor()<br /> {<br /> return 3;<br /> }<br /><br /> public int getHPDice()<br /> {<br /> return 1;<br /> }<br /><br /> public int getHPDie()<br /> {<br /> return 6;<br /> }<br /></pre>
<p> 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 constitution. </p>
<pre> public int getPracsFirstLevel()<br /> {<br /> return 3;<br /> }<br /><br /> public int getTrainsFirstLevel()<br /> {<br /> return 1;<br /> }<br /><br /> public int getBonusPracLevel()<br /> {<br /> return 0;<br /> }<br /></pre>
<p> 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.
</p>
<pre> public int getAttackAttribute()<br /> {<br /> return CharStats.STAT_STRENGTH;<br /> }<br /><br /> public int getBonusAttackLevel()<br /> {<br /> return 1;<br /> }<br /></pre>
<p> 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
<code>getBonusAttackLevel()</code>. </p>
<pre> public int getManaDivisor()<br /> {<br /> return 3;<br /> }<br /><br /> public int getManaDice()<br /> {<br /> return 1;<br /> }<br /><br /> public int getManaDie()<br /> {<br /> return 6;<br /> }<br /></pre>
<p> These methods determines how much mana a player receives
when they gain a level in this class. </p>
<pre> public int getLevelsPerBonusDamage()<br /> {<br /> return 25;<br /> }<br /></pre>
<p> 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. </p>
<pre> public int getMovementMultiplier()<br /> {<br /> return 2;<br /> }<br /></pre>
<p> And lastly for our scores, this method will determine
how many movement points a player receives when they gain a level.
The formula is determined by dividing the player's strength score
by 9, and multiplying the result by this value. </p>
<pre> public int allowedArmorLevel()<br /> {<br /> return CharClass.ARMOR_CLOTH;<br /> }<br /></pre>
<p> 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
<code>allowedArmorLevel()</code> 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. </p>
<pre> public int allowedArmorLevel()<br /> {<br /> return CharClass.ARMOR_CLOTH;<br /> }<br /><br /> protected int requiredArmorSourceMinor()<br /> {<br /> return -1;<br /> }<br /><br /> protected String armorFailMessage()<br /> {<br /> return "<s-name> fumble(s) <s-his-her> <skill> due to <s-his-her> armor!";<br /> }<br /></pre>
<p> The The StdCharClass will automaticallyy enforce armor
requirements whenever a class skill is used, provided these methods
are defined. The <code>allowedArmorLevel()</code> 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. </p>
<p> While the <code>armorFailMessage()</code> 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. </p>
<pre> public int allowedWeaponLevel()<br /> {<br /> return CharClass.WEAPONS_THIEFLIKE;<br /> }<br /><br /> private HashSet disallowedWeapons = buildDisallowedWeaponClasses();<br /> public HashSet disallowedWeaponClasses( MOB mob )<br /> {<br /> return disallowedWeapons;<br /> }<br /><br /> private HashSet requiredWeaponMaterials = buildRequiredWeaponMaterials();<br /> public HashSet requiredWeaponMaterials()<br /> {<br /> return requiredWeaponMaterials;<br /> }<br /></pre>
<p> The StdCharClass will automaticallyy enforce weapon restrictions
whenever a weapon attack is made, provided these methods are
defined. The <code>allowedWeaponLevel()</code> 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.
</p>
<p> The <code>disallowedWeaponClasses( MOB mob )</code> and
<code>requiredWeaponMaterials()</code> methods return HashSet
objects which, due to the method calls in StdCharClass seen above,
are totally derivative of the value you already put in <code>allowedWeaponLevel()</code>.
In other words, so long as you include the <code>allowedWeaponLevel()</code>
method, you should also include those next four methods, exactly
as you see them. </p>
<pre> public int availabilityCode()<br /> {<br /> return Area.THEME_FANTASY;<br /> }<br /></pre>
<p> The method <code>availabilityCode()</code> 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.) </p>
<pre> public NormalGuy()<br /> {<br /> super();<br /> maxStat[CharStats.STAT_CHARISMA] = 10;<br /> }<br /><br /> public void initializeClass()<br /> {<br /> CMLib.ableMapper().addCharAbilityMapping( ID(),<br /> 1,<br /> "Skill_Write",<br /> 50,<br /> "",<br /> true,<br /> false,<br /> new Vector(),<br /> ""<br /> );<br /><br /> CMLib.ableMapper().addCharAbilityMapping( ID(),<br /> 1,<br /> "Skill_Recall",<br /> 0,<br /> "",<br /> true,<br /> false,<br /> new Vector(),<br /> ""<br /> );<br /><br /> CMLib.ableMapper().addCharAbilityMapping( ID(),<br /> 1,<br /> "Skill_Climb",<br /> 0,<br /> "",<br /> true,<br /> false,<br /> new Vector(),<br /> ""<br /> );<br /><br /> CMLib.ableMapper().addCharAbilityMapping(<br /> ID(), // class/race to assign the skill to<br /> 1, // level the skill is qualified for<br /> "Skill_Swim", // the java ID of the ability to qualify for<br /> 0, // default proficiency to give after gaining<br /> "", // any misc parameters to pass to the Skill_Swim skill<br /> false, // true for the class to gain automatically, false to qualify<br /> false, // whether this skill is unlisted for this class<br /> CMParms.parseSemicolons(<br /> "Skill_Climb;Skill_Write",<br /> true<br /> ), // list of skills required to gain this one<br /> "-LOCALE +UNDERWATER" // mask to apply to class members wanting this skill<br /> );<br /> }<br /> }<br /> </pre>
<p> 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 <code>maxStat[]</code>
array for the class. By default, 18 is the maximum score for all
primary attributes. </p>
<p> 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
<code>CMLib.ableMapper().addCharAbilityMapping()</code> methods. The
first parameter of the method is the <code>ID()</code> value of
the Character Class itself, followed by the level at which this
class gains or qualifies for the skill. Next is the <code>ID()</code>
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 Vector 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. </p>
<pre> public Vector getSecurityGroups( int classLevel )<br /> {<br /> if( classLevel > 1000 )<br /> {<br /> Vector V = new Vector();<br /> V.addElement( "ABOVELAW" );<br /> V.addElement( "LISTADMIN" );<br /> return V;<br /> }<br /> else<br /> {<br /> return new Vector();<br /> }<br /> }<br /></pre>
<p> 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 <code>getSecurityGroups()</code> methods will normally
just return an empty Vector 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. </p>
<pre> public String statQualifications()<br /> {<br /> return "Warm body, breathe.";<br /> }<br /><br /> public boolean qualifiesForThisClass( MOB mob, boolean quiet )<br /> {<br /> if( !CMLib.flags().canBreathe( mob ) )<br /> {<br /> if( !quiet )<br /> {<br /> mob.tell( "You need to be breathing to be a normal guy." );<br /> }<br /><br /> return false;<br /> }<br /><br /> return super.qualifiesForThisClass( mob, quiet );<br /> }<br /></pre>
<p> The next method is a display string, for the benefit
of some of the web macros, which describes in plain english any
attribute, or other numeric qualifications to become this class.
The <code>qualifiesForThisClass()</code> method would actually
check and enforce the qualifications described by <code>statQualifications()</code>.
In our example above, there are no stat qualifications, 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. </p>
<pre> public String otherBonuses()<br /> {<br /> return "Receives a mortgage, but no home.";<br /> }<br /></pre>
<p> The next method, like <code>statQualifications above()</code>,
is for the benefit of the web macros. It describes any special
bonuses received due to being this class. </p>
<pre> public Vector outfit( MOB myChar )<br /> {<br /> if( outfitChoices == null )<br /> {<br /> outfitChoices = new Vector();<br /> Weapon w = (Weapon)CMClass.getWeapon( "a mortgage" );<br /> outfitChoices.addElement( w );<br /> }<br /> return outfitChoices;<br /> }<br /></pre>
<p> The outfit method should return a Vector of any Class-Specific
Item object equipment they may need. Clothing and so forth is
actually covered by Races. </p>
<pre> public void grantAbilities( MOB mob, boolean isBorrowedClass )<br /> {<br /> super.grantAbilities( mob, isBorrowedClass );<br /> if( mob.isMonster() )<br /> {<br /> Vector V = CMLib.abilityMapping().getUpToLevelListings( ID(),<br /> mob.charStats().getClassLevel( ID() ),<br /> false,<br /> false<br /> );<br /><br /> for( Enumeration a = V.elements(); a.hasMoreElements(); )<br /> {<br /> Ability A = CMClass.getAbility( (String)a.nextElement() );<br /> if( ( A != null )<br /> && ( ( A.classificationCode()&Ability.ALL_ACODES) != Ability.ACODE_COMMON_SKILL )<br /> && ( !CMLib.abilityMapping().getDefaultGain( ID(), true, A.ID() ) )<br /> )<br /> {<br /> giveMobAbility( mob,<br /> A,<br /> CMLib.abilityMapping().getDefaultproficiency( ID(), true, A.ID() ),<br /> CMLib.abilityMapping().getDefaultParm( ID(), true, A.ID() ),<br /> isBorrowedClass<br /> );<br /> }<br /> }<br /> }<br /> }<br /></pre>
<p> 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.
</p>
<p> The <code>grantAbilities()</code> 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 <code>super.grantAbilities(...)</code>)
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. </p>
<pre> public boolean okMessage( Environmental myHost, CMMsg msg )<br /> {<br /> if( !( myHost instanceof MOB ) )<br /> {<br /> return super.okMessage( myHost, msg );<br /> }<br /><br /> MOB myChar = (MOB)myHost;<br /><br /> if( ( msg.amITarget( myChar ) )<br /> &&( msg.targetMinor() == CMMsg.TYP_DAMAGE )<br /> &&( ( msg.sourceMinor() == CMMsg.TYP_COLD )<br /> || ( msg.sourceMinor() == CMMsg.TYP_WATER )<br /> )<br /> )<br /> {<br /> int recovery = myChar.charStats().getClassLevel( this );<br /> msg.setValue( msg.value() - recovery );<br /> }<br /> else if( ( msg.amITarget( myChar ) )<br /> &&( msg.targetMinor() == CMMsg.TYP_DAMAGE )<br /> &&( msg.sourceMinor() == CMMsg.TYP_FIRE )<br /> )<br /> {<br /> int recovery = msg.value();<br /> msg.setValue( msg.value() + recovery );<br /> }<br /><br /> return super.okMessage( myChar, msg );<br /> }<br />}<br /></pre>
<p> 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 <code>okMessage()</code>
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 <code>.value()</code> method of a message, so it
is these values which are modified, based on the type of damage
taken. </p>
<p> 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. </p>
<img src="images/dragon.jpg" alt="Races" />
<h2><a name="RACES" id="RACES">Races</a></h2>
<p> 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: </p>
<pre>public class Grumbler extends com.planet_ink.coffee_mud.Races.StdRace<br />{<br /></pre>
<p> Our Grumbler race will define all of the basic elements
of a filled-out race. </p>
<pre> public String ID()<br /> {<br /> return "Grumbler";<br /> }<br /><br /> public String name()<br /> {<br /> return "Grumbler";<br /> }<br /><br /> public String racialCategory()<br /> {<br /> return "Grumbler";<br /> }<br /><br /> protected static Vector resources = new Vector();<br /><br /> public int availabilityCode()<br /> {<br /> return Area.THEME_FANTASY;<br /> }<br /></pre>
<p> The first methods return the unique ID of the Race (which
must always match the java/class file name) and the <code>name()</code>
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. </p>
<p> 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.) </p>
<pre> protected int shortestMale()<br /> {<br /> return 84;<br /> }<br /><br /> protected int shortestFemale()<br /> {<br /> return 78;<br /> }<br /><br /> protected int heightVariance()<br /> {<br /> return 80;<br /> }<br /><br /> protected int lightestWeight()<br /> {<br /> return 2000;<br /> }<br /><br /> protected int weightVariance()<br /> {<br /> return 500;<br /> }<br /></pre>
<p> 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-<code>heightVariance()</code> will be added
to the <code>shortedMale()</code>/<code>shortestFemale()</code>
value to determine height, while a random number from 0-<code>weightVariance()</code>
will be added to <code>lightestWeight()</code> to determine that.
</p>
<pre> protected long forbiddenWornBits()<br /> {<br /> return Item.WORN_WIELD<br /> |Item.WORN_WAIST<br /> |Item.WORN_ABOUT_BODY<br /> |Item.WORN_FEET<br /> |Item.WORN_HANDS;<br /> }<br /></pre>
<p> 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. </p>
<pre> private static final int[] parts = {0,2,2,1,1,0,0,1,4,4,1,0,1,1,1,2};<br /> public int[] bodyMask()<br /> {<br /> return parts;<br /> }<br /></pre>
<p> The <code>bodyMask()</code> 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_ANTENEA, 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
antenea, 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. </p>
<pre> private String[] racialAbilityNames = { "Skill_Trip", "Fighter_Whomp" };<br /> private int[] racialAbilityLevels = { 1, 3 };<br /> private int[] racialAbilityProficiencies = { 75, 50 };<br /> private boolean[] racialAbilityQuals = { false, false };<br /><br /> protected String[] racialAbilityNames()<br /> {<br /> return null;<br /> }<br /><br /> protected int[] racialAbilityLevels()<br /> {<br /> return null;<br /> }<br /><br /> protected int[] racialAbilityProficiencies()<br /> {<br /> return null;<br /> }<br /><br /> protected boolean[] racialAbilityQuals()<br /> {<br /> return null;<br /> }<br /><br /> public Vector racialAbilities( MOB mob )<br /> {<br /> Vector V = super.racialAbilities( mob );<br /> return V;<br /> }<br /></pre>
<p> 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.
</p>
<p> The first four methods define these skills. The data
in all four variables are ordered with relative to each other.
The <code>racialAbilityNames</code> is a list of the Ability class
ID. The <code>racialAbilityLevels</code> is the level at which
the skill is qualified for or gained. The <code>racialAbilityProficiencies()</code>
is the proficiency of skills automaticallyy gained. The <code>racialAbilityQuals()</code>
tells whether or not the skill is automaticallyy gained (false)
or is only qualified for (true). </p>
<p> The method above (<code>racialAbilities()</code>) will
return a Vector of Ability objects, with proficiency already set,
appropriate to the mob passed in. This vector 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. </p>
<pre> public Vector outfit( MOB myChar )<br /> {<br /> if( outfitChoices == null )<br /> {<br /> outfitChoices = new Vector();<br /> Weapon w = (Weapon)CMClass.getItem( "GenPants" );<br /> outfitChoices.addElement( w );<br /> }<br /><br /> return outfitChoices;<br /> }<br /></pre>
<p> The outfit method should return a Vector of any Race-Specific
Item object equipment they may need. </p>
<pre> private String[] culturalAbilityNames = { "Dwarven", "Mining" };<br /> private int[] culturalAbilityProficiencies = { 100, 50 };<br /><br /> public String[] culturalAbilityNames()<br /> {<br /> return culturalAbilityNames;<br /> }<br /><br /> public int[] culturalAbilityProficiencies()<br /> {<br /> return culturalAbilityProficiencies;<br /> }<br /></pre>
<p> 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. </p>
<pre> public void affectEnvStats( Environmental affected, EnvStats affectableStats )<br /> {<br /> super.affectEnvStats( affected, affectableStats );<br /><br /> affectableStats.setSensesMask(<br /> affectableStats.sensesMask() | EnvStats.CAN_SEE_INFRARED<br /> );<br /> }<br /></pre>
<p> This sample of the <code>affectEnvStats()</code> method
we discussed in the Core Topics above makes sure that all creatures
of this race can see in the infrared spectrum. </p>
<pre> public void affectCharStats( MOB affectedMOB, CharStats affectableStats )<br /> {<br /> super.affectCharStats( affectedMOB, affectableStats );<br /> affectableStats.setStat( CharStats.STAT_STRENGTH, 15 );<br /> affectableStats.setStat( CharStats.STAT_DEXTERITY, 25 );<br /> affectableStats.setStat( CharStats.STAT_INTELLIGENCE, 5 );<br /> }<br /></pre>
<p> 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! </p>
<pre> public void startRacing( MOB mob, boolean verifyOnly )<br /> {<br /> super.startRacing( mob, verifyOnly );<br /> }<br /></pre>
<p> 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. </p>
<pre> public Weapon myNaturalWeapon()<br /> {<br /> if( naturalWeapon == null )<br /> {<br /> naturalWeapon = CMClass.getWeapon( "StdWeapon" );<br /> naturalWeapon.setName( "huge claws" );<br /> naturalWeapon.setWeaponType( Weapon.TYPE_PIERCING );<br /> }<br /><br /> return naturalWeapon;<br /> }<br /></pre>
<p> 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. </p>
<pre> public String healthText( MOB viewer, MOB mob )<br /> {<br /> double pct = ( CMath.div( mob.curState().getHitPoints(),<br /> mob.maxState().getHitPoints()<br /> )<br /> );<br /><br /> if( pct < .10 )<br /> {<br /> return "^r" + mob.displayName(viewer) + "^ris raging in bloody pain!^N";<br /> }<br /> else if( pct < .20 )<br /> {<br /> return "^r" + mob.displayName(viewer) + "^ris covered in blood.^N";<br /> }<br /> else if( pct < .30 )<br /> {<br /> return "^r" + mob.displayName(viewer) + "^r is bleeding badly from lots of wounds.^N";<br /> }<br /> else if( pct < .50 )<br /> {<br /> return "^y" + mob.displayName(viewer) + "^y has some bloody wounds and gashed scales.^N";<br /> }<br /> else if( pct < .60 )<br /> {<br /> return "^p" + mob.displayName(viewer) + "^p has a few bloody wounds.^N";<br /> }<br /> else if( pct < .70 )<br /> {<br /> return "^p" + mob.displayName(viewer) + "^p is cut and bruised heavily.^N";<br /> }<br /> else if( pct < .90 )<br /> {<br /> return "^g" + mob.displayName(viewer) + "^g has a few bruises and scratched scales.^N";<br /> }<br /> else if( pct < .99 )<br /> {<br /> return "^g" + mob.displayName(viewer) + "^g has a few small bruises.^N";<br /> }<br /> else<br /> {<br /> return "^c" + mob.displayName(viewer) + "^c is in perfect health.^N";\<br /> }<br /> }<br /></pre>
<p> 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.
</p>
<pre> public Vector myResources()<br /> {<br /> synchronized( resources )<br /> {<br /> if( resources.size() == 0 )<br /> {<br /> resources.addElement( makeResource( "a " + name().toLowerCase() + "claw",<br /> RawMaterial.RESOURCE_BONE<br /> )<br /> );<br /><br /> for( int i = 0; i < 10; i++ )<br /> {<br /> resources.addElement( makeResource( "a strip of " + name().toLowerCase() + " hide",<br /> RawMaterial.RESOURCE_SCALES<br /> )<br /> );<br /> }<br /><br /> for( int i = 0; i < 10; i++ )<br /> {<br /> resources.addElement( makeResource( "a pound of " + name().toLowerCase() + " meat",<br /> RawMaterial.RESOURCE_MEAT<br /> )<br /> );<br /> }<br /><br /> resources.addElement( makeResource( "some " + name().toLowerCase() + " blood",<br /> RawMaterial.RESOURCE_BLOOD<br /> )<br /> );<br /> }<br /> }<br /><br /> return resources;<br /> }<br />}<br /></pre>
<p> The above method allows you to determine what sorts of
materials are gotten from this creature whenever the dead corpse
is Butchered. </p>
<p> 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
<code>public void level( MOB mob )</code>, which is called
whenever a player of that race gains a level, public void <code>agingAffects(
MOB mob, CharStats baseStats, CharStats charStats )</code> , which
is called to enforce how aging effects this race, and <code>public
DeadBody getCorpseContainer( MOB mob, Room room )</code>, which
is called to create a corpse for members of this race.
</p>
<img src="images/chomper.jpg" alt="Exits" />
<h2><a name="EXITS" id="EXITS">Exits</a></h2>
<p> 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. </p>
<p> 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: </p>
<pre>public class SlidingDoor extends com.planet_ink.coffee_mud.Exits.StdExit<br />{<br /> public String ID()<br /> {<br /> return "SlidingDoor";<br /> }<br /><br /> public SlidingDoor()<br /> {<br /> super();<br /> Ability A = CMClass.getAbility( "Prop_ReqHeight" );<br /> A.setMiscText( "30" );<br /> addNonUninvokableEffect( A );<br /> }<br /><br /> public String name()<br /> {<br /> return "a sliding door";<br /> }<br /><br /> public String displayText()<br /> {<br /> return "";<br /> }<br /><br /> public String closedText()<br /> {<br /> return "a closed sliding door";<br /> }<br /><br /> public String doorName()<br /> {<br /> return "door";<br /> }<br /><br /> public String openName()<br /> {<br /> return "slide";<br /> }<br /><br /> public String closeName()<br /> {<br /> return "slide";<br /> }<br /><br /> public boolean hasADoor()<br /> {<br /> return true;<br /> }<br /><br /> public boolean hasALock()<br /> {<br /> return false;<br /> }<br /><br /> public boolean defaultsLocked()<br /> {<br /> return false;<br /> }<br /><br /> public boolean defaultsClosed()<br /> {<br /> return true;<br /> }<br /><br /> public int openDelayTicks()<br /> {<br /> return 45;<br /> }<br />}<br /></pre>
<p> 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.
</p>
<p> 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.
</p>
<p> 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). </p>
<img src="images/scenery.jpg" alt="Locales" />
<h2><a name="LOCALES" id="LOCALES">Locales</a></h2>
<p> 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. </p>
<p> Let's looks at an example of a standard grid room, which
has much of the functionality we are interested in: </p>
<pre>public class RoadGrid extends com.planet_ink.coffee_mud.Locales.StdGrid<br />{<br /> public String ID()<br /> {<br /> return "RoadGrid";<br /> }<br /><br /> public RoadGrid()<br /> {<br /> super();<br /> name = "a road";<br /> baseEnvStats.setWeight( 1 );<br /> recoverEnvStats();<br /> }<br /><br /> public String getGridChildLocaleID()<br /> {<br /> return "Road";<br /> }<br /><br /> public Vector resourceChoices()<br /> {<br /> return Road.roomResources;<br /> }<br /><br /> public int domainType()<br /> {<br /> return Room.DOMAIN_OUTDOORS_PLAINS;<br /> }<br /><br /> public int domainConditions()<br /> {<br /> return Room.CONDITION_NORMAL;<br /> }<br />}<br /></pre>
<p> 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).
</p>
<p> 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 vector 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.
</p>
<p> Here are another set of useful methods: </p>
<pre> public String roomTitle()<br /> public String roomDescription()<br /></pre>
<p> 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 <code>displayText()</code>
and <code>description()</code> methods respectively, then parse
that data for any special display codes, though often that data is
simply passed through. </p>
<p> The <code>executeMsg()</code>, and <code>okMessage()</code>
methods on rooms are also available, as they are in all Environmental
objects, for customized message handling as described in the Core
Topics above. </p>
<img src="images/area.jpg" alt="Areas" />
<h2><a name="AREAS" id="AREAS">Areas</a></h2>
<p> The Area objects, which represent areas in the game,
are the most difficult to advise about regarding programming.
</p>
<p> 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. </p>
<pre>public class StdArea implements Area<br />{<br /> public String ID()<br /> {<br /> return "StdArea";<br /> }<br /><br /> [...]<br /><br /> public Climate getClimateObj(){...}<br /> public int climateType(){...}<br /> public void setClimateType( int newClimateType ){...}<br /></pre>
<p> Of course, like every Environmental object, the Area
must define an <code>ID()</code>. Notice that the <code>ID()</code>
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. </p>
<p> 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. </p>
<pre> public int getTechLevel()<br /> public void setTechLevel( int level )<br /></pre>
<p> These will return the technical level allowed in the
area, whether it be magic, technology, or both. </p>
<pre> public String getArchivePath()<br /> public void setArchivePath( String pathFile )<br /></pre>
<p> The Archive name of the area is set and read from
the area, though it's more properly set by the builder.
</p>
<pre> public TimeClock getTimeObj()<br /></pre>
<p> 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. </p>
<pre> public void toggleMobility( boolean onoff )<br /> public boolean getMobility()<br /></pre>
<p> 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. </p>
<pre> public StringBuffer getAreaStats()<br /></pre>
<p> If the data, appearance, or format of the HELP provided
for areas needs to be changed, the <code>getAreaStats()</code>
method is where to generate a new one. </p>
<pre> public Enumeration getMetroMap()<br /> public int metroSize()<br /> public Room getRandomMetroRoom()<br /></pre>
<p> 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. </p>
<pre> public void fillInAreaRooms()<br /> public void fillInAreaRoom( Room R )<br /><br /> public Enumeration getProperMap()<br /> public int properSize()<br /> public Room getRandomProperRoom()<br /> public void clearMetroCache()<br /></pre>
<p> 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. </p>
<pre> public void addSubOp( String username )<br /> public void delSubOp( String username )<br /> public boolean amISubOp( String username )<br /> public String getSubOpList()<br /> public void setSubOpList( String list )<br /> public Vector getSubOpVectorList()<br /></pre>
<p> 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. </p>
<img src="images/house.jpg" alt="Properties" />
<h2><a name="PROPS" id="PROPS">Properties</a></h2>
<p> 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 Environmental
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 Environmental interface method <code>addNonUninvokableEffect(
Ability )</code> method either inside a custom coded Environmental
object, or at run-time to a GenMob, GenItem, Room, or similar
type object. </p>
<p> 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. </p>
<p> 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. </p>
<p> 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. </p>
<p> Each property must also have custom <code>ID()</code>,
and <code>name()</code> methods as shown below. Notice that the
<code>ID()</code> is the same as the name of the class.
This is no accident -- this is required! </p>
<pre>public class Prop_AstralSpirit extends com.planet_ink.coffee_mud.Abilities.Properties.Property<br />{<br /> public String ID()<br /> {<br /> return "Prop_AstralSpirit";<br /> }<br /><br /> public String name()<br /> {<br /> return "Astral Spirit";<br /> }<br /></pre>
<p> Above we see the aforementioned methods defined. The
Property does not differ from other Abilities, or indeed other
Environmental objects in this respect. A unique <code>ID()</code>,
and <code>name()</code> method must be defined for each new class.
</p>
<pre> protected int canAffectCode()<br /> {<br /> return Ability.CAN_MOBS;<br /> }<br /><br /> public String accountForYourself()<br /> {<br /> return "an astral spirit";<br /> }<br /></pre>
<p> 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. </p>
<p> 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. </p>
<pre> /** this method defines how this thing responds<br /> * to environmental changes. It may handle any<br /> * and every msg listed in the CMMsg class<br /> * from the given Environmental source */<br /> public boolean okMessage( Environmental myHost, CMMsg msg )<br /> {<br /> if( ( affected == null ) || ( !( affected instanceof MOB ) ) )<br /> {<br /> return true;<br /> }<br /><br /> MOB mob = (MOB)affected;<br /><br /> if( ( msg.amISource( mob ) )<br /> && ( !CMath.bset( msg.sourceMajor(), CMMsg.MASK_ALWAYS ) )<br /> )<br /> {<br /> if( ( msg.tool() != null )<br /> &&( msg.tool().ID().equalsIgnoreCase( "Skill_Revoke" ) )<br /> )<br /> {<br /> return super.okMessage( myHost, msg );<br /> }<br /> else if( msg.targetMinor() == CMMsg.TYP_WEAPONATTACK )<br /> {<br /> mob.tell( "You are unable to attack in this incorporeal form." );<br /> peaceAt( mob );<br /> return false;<br /> }<br /> else if( ( CMath.bset( msg.sourceMajor(), CMMsg.MASK_HANDS ) )<br /> || ( CMath.bset( msg.sourceMajor(), CMMsg.MASK_MOUTH ) )<br /> )<br /> {<br /> if( CMath.bset( msg.sourceMajor(), CMMsg.MASK_SOUND ) )<br /> {<br /> mob.tell( "You are unable to make sounds in this incorporeal form." );<br /> }<br /> else<br /> {<br /> mob.tell( "You are unable to do that this incorporeal form." );<br /> }<br /><br /> peaceAt( mob );<br /> return false;<br /> }<br /> }<br /> else if( ( msg.amITarget( mob ) )<br /> &&( !msg.amISource( mob ) )<br /> &&( !CMath.bset( msg.targetMajor(), CMMsg.MASK_ALWAYS ) )<br /> )<br /> {<br /> mob.tell( mob.name() + " doesn't seem to be here." );<br /> return false;<br /> }<br /><br /> return true;<br /> }<br /></pre>
<p> 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. </p>
<pre> public void affectEnvStats( Environmental affected, EnvStats affectableStats )<br /> {<br /> super.affectEnvStats( affected, affectableStats );<br /> // when this spell is on a MOBs Affected list,<br /> // it should consistantly put the mob into<br /> // a sleeping state, so that nothing they do<br /> // can get them out of it.<br /><br /> affectableStats.setWeight( 0 );<br /> affectableStats.setHeight( -1 );<br /><br /> affectableStats.setDisposition(<br /> affectableStats.disposition()|EnvStats.IS_GOLEM<br /> );<br /><br /> affectableStats.setDisposition(<br /> affectableStats.disposition()|EnvStats.IS_INVISIBLE<br /> );<br /><br /> affectableStats.setDisposition(<br /> affectableStats.disposition()|EnvStats.IS_NOT_SEEN<br /> );<br /><br /> affectableStats.setSensesMask(<br /> affectableStats.sensesMask()|EnvStats.CAN_NOT_SPEAK<br /> );<br /> }<br />}<br /></pre>
<p> Last but not least, here is another example from the
Core Topics, an <code>affectEnvStats()</code> method. This method
will always have the host mob passed in the "affected" parameter,
and a copy of his current EnvStats 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. </p>
<img src="images/monk.jpg" alt="Skills" />
<h2><a name="SKILLS" id="SKILLS">Introduction to Skill Abilities</a></h2>
<p> 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. </p>
<p> 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. </p>
<p> 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. </p>
<p> 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. </p>
<p> A Custom ability may or may not belong to any
particular package, though it is important that the <code>ID()</code>
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. </p>
<p> 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.
</p>
<p> Each ability must also have custom <code>ID()</code>
and <code>name()</code> methods as shown below. Notice that
the <code>ID()</code> is the same as the name of the class.
This is no accident -- this is required! </p>
<pre>public class Skill_Trip extends com.planet_ink.coffee_mud.Abilities.StdAbility<br />{<br /> public String ID()<br /> {<br /> return "Skill_Trip";<br /> }<br /><br /> public String name()<br /> {<br /> return "Trip";<br /> }<br /></pre>
<p> 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 <code>ID()</code> and <code>name()</code>
method must be defined for each new class. </p>
<pre> public String displayText()<br /> {<br /> return "(Tripped)";<br /> }<br /></pre>
<p> 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 "". </p>
<pre> protected int canAffectCode()<br /> {<br /> return CAN_MOBS;<br /> }<br /><br /> protected int canTargetCode()<br /> {<br /> return CAN_MOBS;<br /> }<br /></pre>
<p> These two methods assist the MUDGrinder, and the HELP
files in classifying the several skills and spells. </p>
<p> The first method, <code>canAffectCode()</code>, 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. </p>
<p> The second method, <code>canTargetCode()</code>, 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. </p>
<pre> public int abstractQuality()<br /> {<br /> return Ability.QUALITY_MALICIOUS;<br /> }<br /></pre>
<p> 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
</p>
<p> Other possible values include: </p>
<a name="skillquality" id="skillquality"> </a>
<table border="1">
<tbody>
<tr>
<td> Ability.QUALITY_BENEFICIAL_SELF
</td>
<td> always helpful to oneself when used
</td>
</tr>
<tr>
<td> Ability.QUALITY_BENEFICIAL_OTHERS
</td>
<td> can be targeted to other people,
and is always beneficial </td>
</tr>
<tr>
<td> Ability.QUALITY_OK_SELF
</td>
<td> targets oneself, but is only useful
in certain circumstances, or it has complicated parameters
that mobs won't find useful </td>
</tr>
<tr>
<td> Ability.QUALITY_OK_OTHERS
</td>
<td> targets other people, but is only
useful under certain circumstances, or it also has complicated
parameters </td>
</tr>
<tr>
<td> Ability.QUALITY_INDIFFERENT
</td>
<td> targets items, or rooms, and is
only useful in certain circumstances </td>
</tr>
</tbody>
</table>
<p> Only skills marked as Ability.QUALITY_BENEFICIAL_*
orAbility.QUALITY_MALICIOUS will be used in combat or by most
behaviors. </p>
<pre> public int castingQuality( MOB invoker, Environmental target )<br /> {<br /> return super.castingQuality( invoker, target );<br /> }<br /></pre>
<p> This second most important method is similar to the
<code>abstractQuality()</code> 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. </p>
<pre> public boolean isAutoInvoked()<br /> {<br /> return false;<br /> }<br /></pre>
<p> 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
<code>displayText()</code> 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. </p>
<pre> private static final String[] triggerStrings = { "TRIP" };<br /> public String[] triggerStrings()<br /> {<br /> return triggerStrings;<br /> }<br /><br /> public double castingTime()<br /> {<br /> return 0.25;<br /> }<br /><br /> public double combatCastingTime()<br /> {<br /> return 1.0;<br /> }<br /></pre>
<p> 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. </p>
<p> 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.
</p>
<pre> public int classificationCode()<br /> {<br /> return Ability.ACODE_SKILL;<br /> }<br /></pre>
<p> 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. </p>
<pre> public long flags()<br /> {<br /> return Ability.FLAG_MOVING;<br /> }<br /></pre>
<p> 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: </p>
<a name="skillflags" id="skillflags"> </a>
<table border="1" cellpadding="1" cellspacing="1" width="75%">
<tbody>
<tr>
<td> FLAG_BINDING </td>
<td> Binds and or limits movement and
the use of hands. </td>
</tr>
<tr>
<td> FLAG_MOVING </td>
<td> Changes the position of the target
or affected one. </td>
</tr>
<tr>
<td> FLAG_TRANSPORTING
</td>
<td> Changes the room of the target,
requires that the performer of the skill be present.
</td>
</tr>
<tr>
<td> FLAG_WEATHERAFFECTING
</td>
<td> Changes the weather.
</td>
</tr>
<tr>
<td> FLAG_SUMMONING </td>
<td> Changes the room of the target,
where the performer of the skill is not present. May also
bring new creatures into existence. </td>
</tr>
<tr>
<td> FLAG_CHARMING </td>
<td> Charms the target.
</td>
</tr>
<tr>
<td> FLAG_TRACKING </td>
<td> Results in the target tracking something.
</td>
</tr>
<tr>
<td> FLAG_HEATING </td>
<td> Makes the target hot.
</td>
</tr>
<tr>
<td> FLAG_BURNING </td>
<td> Makes the target on fire.
</td>
</tr>
<tr>
<td> FLAG_HOLY </td>
<td> Means that the skill is GOOD aligned,
unless FLAG_UNHOLY is also set, in which case it makes the
skill NEUTRAL. </td>
</tr>
<tr>
<td> FLAG_UNHOLY </td>
<td> Means that the skill is EVIL aligned,
unless FLAG_UNHOLY is also set, in which case it makes the
skill NEUTRAL. </td>
</tr>
<tr>
<td> FLAG_PARALYZING </td>
<td> Makes the target or affected one
unable to move their muscles. </td>
</tr>
</tbody>
</table>
<pre> public void affectEnvStats( Environmental affected, EnvStats affectableStats )<br /> {<br /> super.affectEnvStats( affected, affectableStats );<br /> if( !doneTicking )<br /> {<br /> affectableStats.setDisposition( affectableStats.disposition()<br /> | EnvStats.IS_SITTING<br /> );<br /> }<br /> }<br /></pre>
<p> This is an example of the <code>affectEnvStats()</code>
method described in the Core Topics. In the case of our Trip skill,
it forces the affected target into a sitting position.
</p>
<pre> public boolean okMessage( Environmental myHost, CMMsg msg )<br /> {<br /> if( ( affected == null ) || ( !( affected instanceof MOB ) ) )<br /> {<br /> return true;<br /> }<br /><br /> MOB mob = (MOB)affected;<br /> if( doneTicking && msg.amISource( mob ) )<br /> {<br /> unInvoke();<br /> }<br /> else if( msg.amISource( mob )<br /> && ( msg.sourceMinor() == CMMsg.TYP_STAND )<br /> )<br /> {<br /> return false;<br /> }<br /><br /> return true;<br /> }<br /></pre>
<p> This is an example of the <code>okMessage()</code> 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. </p>
<pre> public void unInvoke()<br /> {<br /> if( ( affected == null ) || ( !( affected instanceof MOB ) ) )<br /> {<br /> return;<br /> }<br /><br /> MOB mob = (MOB)affected;<br /> if( canBeUninvoked() )<br /> {<br /> doneTicking = true;<br /> }<br /><br /> super.unInvoke();<br /><br /> if( !mob.amDead() )<br /> {<br /> if( mob.location() != null )<br /> {<br /> CMMsg msg = CMClass.getMsg( mob,<br /> null,<br /> CMMsg.MSG_NOISYMOVEMENT,<br /> "<S-NAME> regain(s) <S-HIS-HER> feet."<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /> CMLib.commands().postStand( mob, true );<br /> }<br /> }<br /> else<br /> {<br /> mob.tell( "You regain your feet." );<br /> }<br /> }<br /> }<br /></pre>
<p> All standard abilities include an <code>unInvoke()</code>
method, which is called when the Effect caused by the ability
is dispelled, or the duration of the ability expires. The <code>super.unInvoke()</code>
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 <code>unInvoke()</code> method, we also see the code
trying to force the mob back to his feet. </p>
<pre> public boolean preInvoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel,<br /> int secondsElapsed,<br /> double actionsRemaining<br /> )<br /> {<br /> return true;<br /> }<br /></pre>
<p> The <code>preInvoke()</code> 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 <code>invoke()</code> 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 <code>castingTime()</code> or <code>combatCastingTime()</code>
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. </p>
<pre> public boolean invoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel<br /> )<br /> {<br /></pre>
<p> 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. </p>
<pre> MOB target = this.getTarget( mob, commands, givenTarget );<br /> if( target == null )<br /> {<br /> return false;<br /> }<br /></pre>
<p> Our first step in Trip is to get our target. There are
several <code>getTarget()</code> methods built into StdAbility
for determining a target object based on the command parameters
passed in, as well as the <code>abstractQuality()</code> value
for the ability. The StdAbility method call to <code>getTarget()</code>
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. </p>
<p> All of the several <code>getTarget()</code> 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 <code>invoke()</code>, telling the
system that the ability failed to invoke. </p>
<pre> if( CMLib.flags().isSitting( target )<br /> || CMLib.flags().isSleeping( target )<br /> )<br /> {<br /> mob.tell( target,<br /> null,<br /> null,<br /> "<S-NAME> is already on the floor!"<br /> );<br /><br /> return false;<br /> }<br /><br /> if( !CMLib.flags().aliveAwakeMobile( mob, true )<br /> ||( CMLib.flags().isSitting( mob ) )<br /> )<br /> {<br /> mob.tell( "You need to stand up!" );<br /> return false;<br /> }<br /><br /> if( mob.isInCombat() && ( mob.rangeToTarget() > 0 ) )<br /> {<br /> mob.tell( "You are too far away to trip!" );<br /> return false;<br /> }<br /><br /> if( target.riding() != null )<br /> {<br /> mob.tell( "You can't trip someone "<br /> + target.riding().stateString( target )<br /> + " "<br /> + target.riding().name()<br /> + "!"<br /> );<br /><br /> return false;<br /> }<br /><br /> if( CMLib.flags().isFlying( target ) )<br /> {<br /> mob.tell( target.name() + " is flying and can't be tripped!" );<br /> return false;<br /> }<br /></pre>
<p> Here are numerous checks to see if the invoking mob is
able to trip, and the target is able to be tripped. </p>
<pre> if( !super.invoke( mob, commands, givenTarget, auto ) )<br /> {<br /> return false;<br /> }<br /></pre>
<p> The <code>invoke()</code> 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. </p>
<pre> int levelDiff = target.envStats().level() - mob.envStats().level();<br /> if( levelDiff > 0 )<br /> {<br /> levelDiff = levelDiff * 5;<br /> }<br /> else<br /> {<br /> levelDiff = 0;<br /> }<br /><br /> Double temp = new Integer(<br /> target.charStats().getStat(<br /> CharStats.STAT_DEXTERITY<br /> )<br /> ).doubleValue()<br /> - 9.0;<br /><br /> int adjustment =<br /> (-levelDiff) + (-( 35 + ( (int)Math.round( temp * 3.0 ) ) ) );<br /><br /> boolean success = proficiencyCheck( mob, adjustment, auto );<br /></pre>
<p> The <code>proficiencyCheck()</code> 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. </p>
<pre> success = success && ( target.charStats().getBodyPart( Race.BODY_LEG ) > 0 );<br /><br /> if( success )<br /> {<br /> CMMsg msg = CMClass.getMsg( mob,<br /> target,<br /> this,<br /> CMMsg.MSK_MALICIOUS_MOVE|CMMsg.TYP_JUSTICE|( auto ? CMMsg.MASK_ALWAYS : 0 ),<br /> auto ? "<T-NAME> trip(s)!" : "^F<S-NAME> trip(s) <T-NAMESELF>!^?"<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /> int durationTicks = ( msg.value() > 0 ) ? 1 : 2;<br /> maliciousAffect( mob, target, asLevel, durationTicks, -1 );<br /> target.tell( "You hit the floor!" );<br /> }<br /> }<br /> else<br /> {<br /> return maliciousFizzle( mob,<br /> target,<br /> "<S-NAME> attempt(s) to trip <T-NAMESELF>, but fail(s)."<br /> );<br /> }<br /><br /> return success;<br /> }<br />}<br /></pre>
<p> The rest of the <code>invoke()</code> 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). </p>
<p> 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 <code>maliciousAffect()</code> 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 <code>value()
> 0</code> (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 <code>maliciousAffect()</code>
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. </p>
<p> If this skill had not been malicious, we could have made
a call to the <code>beneficialAffect()</code> method instead.
That method has the same parameters as <code>maliciousAffect()</code>,
though it lacks the final parameter for a further saving throw,
since beneficial affects require no saving throw. </p>
<p> Now, if the success variable had been false, then we
made a call to the <code>maliciousFizzle()</code> 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 <code> beneficialWordsFizzle()</code> method,
or the <code>beneficialVisualFizzle()</code> method, depending
upon whether the skill is verbal or somantic based. Most spells
are verbal based, for instance, while most skills are somantic.
</p>
<p> Finally, we return the results of the success variable
from the <code>invoke()</code> 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.
</p>
<img src="images/fireball.jpg" alt="Spells" />
<h2><a name="SPC" id="SPC">Spells, Prayers, and Chants</a></h2>
<p> 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. </p>
<h3><a name="spells" id="spells">Spells</a></h3>
<p> Spells will follow all the rules mentioned above in the
Skill Abilities section, with a few differences: </p>
<pre>public class Spell_ResistFire extends com.planet_ink.coffee_mud.Abilities.Spells.Spell<br />{<br /> public String ID()<br /> {<br /> return "Spell_ResistFire";<br /> }<br /><br /> public String name()<br /> {<br /> return "Resist Fire";<br /> }<br /><br /> public String displayText()<br /> {<br /> return "(Resist Fire)";<br /> }<br /><br /> public int abstractQuality()<br /> {<br /> return Ability.QUALITY_BENEFICIAL_OTHERS;<br /> }<br /><br /> protected int canAffectCode()<br /> {<br /> return CAN_MOBS;<br /> }<br /><br /> public int classificationCode()<br /> {<br /> return Ability.ACODE_SPELL|Ability.DOMAIN_ABJURATION;<br /> }<br /></pre>
<p> 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 <code>classificationCode()</code>
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: </p>
<a name="spelldomain" id="spelldomain"> </a>
<table border="1">
<tbody>
<tr>
<td> DOMAIN_DIVINATION
</td>
<td> Spells that grant knowledge.
</td>
</tr>
<tr>
<td> DOMAIN_ABJURATION
</td>
<td> Spells that protect.
</td>
</tr>
<tr>
<td> DOMAIN_ILLUSION </td>
<td> Spells that fool the senses.
</td>
</tr>
<tr>
<td> DOMAIN_EVOCATION </td>
<td> Spells that bring forth the elements.
</td>
</tr>
<tr>
<td> DOMAIN_ALTERATION
</td>
<td> Spells that change things.
</td>
</tr>
<tr>
<td> DOMAIN_TRANSMUTATION
</td>
<td> Spells that change people.
</td>
</tr>
<tr>
<td> DOMAIN_ENCHANTMENT
</td>
<td> Spells that enchant items or the
mind. </td>
</tr>
<tr>
<td> DOMAIN_CONJURATION
</td>
<td> Spells that transport people or
items. </td>
</tr>
</tbody>
</table>
<pre> public boolean invoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel<br /> )<br /> {<br /> MOB target = getTarget( mob, commands, givenTarget );<br /> if( target == null )<br /> {<br /> return false;<br /> }<br /><br /> if( !super.invoke( mob, commands, givenTarget, auto ) )<br /> {<br /> return false;<br /> }<br /><br /> boolean success = proficiencyCheck( mob, 0, auto );<br /> if( success )<br /> {<br /> CMMsg msg = CMClass.getMsg( mob,<br /> target,<br /> this,<br /> affectType( auto ),<br /> auto ?<br /> "<T-NAME> feel(s) cooly protected."<br /> : "^S<S-NAME> invoke(s) a cool field of protection around <T-NAMESELF>.^?"<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /> beneficialAffect( mob, target, asLevel, 0 );<br /> }<br /> }<br /> else<br /> {<br /> beneficialWordsFizzle( mob,<br /> target,<br /> "<S-NAME> attempt(s) to invoke fire protection, but fail(s)."<br /> );<br /> }<br /><br /> return success;<br /> }<br />}<br /></pre>
<p> The <code>invoke()</code> 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
<code>beneficialAffect()</code> and <code>beneficialWordsFizzle()</code>
instead of <code>maliciousAffect()</code> and <code>maliciousFizzle()</code>.
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 <code>affectType()</code>,
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. </p>
<h3><a name="prayers" id="prayers">Prayers</a></h3>
<p> Prayers will follow all the rules mentioned above in
the Skill Abilities section, with a few differences: </p>
<pre>public class Prayer_Anger extends com.planet_ink.coffee_mud.Abilities.Prayers.Prayer<br />{<br /> public String ID()<br /> {<br /> return "Prayer_Anger";<br /> }<br /><br /> public String name()<br /> {<br /> return "Anger";<br /> }<br /><br /> public int abstractQuality()<br /> {<br /> return Ability.QUALITY_MALICIOUS;<br /> }<br /><br /> public long flags()<br /> {<br /> return Ability.FLAG_UNHOLY;<br /> }<br /><br /> public boolean invoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel<br /> )<br /> {<br /> if( !super.invoke( mob, commands, givenTarget, auto ) )<br /> {<br /> return false;<br /> }<br /><br /> boolean success = proficiencyCheck( mob, 0, auto );<br /><br /> boolean someoneIsFighting = false;<br /> for( int i = 0; i < mob.location().numInhabitants(); i++ )<br /> {<br /> MOB inhab = mob.location().fetchInhabitant( i );<br /> if( ( inhab != null ) && ( inhab.isInCombat() ) )<br /> {<br /> someoneIsFighting = true;<br /> }<br /> }<br /><br /> if( success<br /> &&( !someoneIsFighting )<br /> &&( mob.location().numInhabitants() > 3 )<br /> )<br /> {<br /> // it worked, so build a copy of this ability,<br /> // and add it to the effects list of the<br /> // affected MOB. Then tell everyone else<br /> // what happened.<br /> CMMsg msg = CMClass.getMsg( mob,<br /> null,<br /> this,<br /> affectType( auto ),<br /> auto ? "A feeling of anger descends" : "^S<S-NAME> rage(s) for anger.^?"<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /><br />[.......]<br />}<br /></pre>
<p> 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 <code>classificationCode()</code> method
returns the proper value. </p>
<p> You should also take note of the <code>flags()</code>
method. All Prayers must return a value from <code>flags()</code>
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.
</p>
<p> The last special note is down in the message construction
in the <code>invoke()</code> method. The <code>invoke()</code>
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 <code>affectType()</code>,
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. </p>
<h3><a name="chants" id="chants">Chants</a></h3>
<p> Chants will follow all the rules mentioned above in the
Skill Abilities section, with a few differences: </p>
<pre>public class Chant_AlterTime extends com.planet_ink.coffee_mud.Abilities.Druid.Chant<br />{<br /> public String ID()<br /> {<br /> return "Chant_AlterTime";<br /> }<br /><br /> public String name()<br /> {<br /> return "Alter Time";<br /> }<br /><br /> public String displayText()<br /> {<br /> return "";<br /> }<br /><br /> public int overrideMana()<br /> {<br /> return 100;<br /> }<br /><br /> public int abstractQuality()<br /> {<br /> return Ability.QUALITY_INDIFFERENT;<br /> }<br /><br /> protected int canAffectCode()<br /> {<br /> return 0;<br /> }<br /><br /> protected int canTargetCode()<br /> {<br /> return 0;<br /> }<br /><br /> public boolean invoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel<br /> )<br /> {<br /> if( !super.invoke( mob, commands, givenTarget, auto ) )<br /> {<br /> return false;<br /> }<br /><br /> boolean success = proficiencyCheck( mob, 0, auto );<br /> if( success )<br /> {<br /> // it worked, so build a copy of this ability,<br /> // and add it to the effects list of the<br /> // affected MOB. Then tell everyone else<br /> // what happened.<br /> CMMsg msg = CMClass.getMsg( mob,<br /> null,<br /> this,<br /> affectType( auto ),<br /> auto ? "" : "^S<S-NAME> chant(s), and reality seems to start blurring.^?"<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /> int x = CMath.s_int( text() );<br /> while( x == 0 )<br /> {<br /> x = CMLib.dice().roll( 1, 3, -2 );<br /> }<br /><br /> if( x > 0 )<br /> {<br /> mob.location().showHappens( CMMsg.MSG_OK_VISUAL, "Time moves forwards!" );<br /> }<br /> else<br /> {<br /> mob.location().showHappens( CMMsg.MSG_OK_VISUAL, "Time moves backwards!" );<br /> }<br /><br /> if( CMLib.map().numAreas() > 0 )<br /> {<br /> CMLib.map().getFirstArea().tickTock( x );<br /> }<br /> }<br /> }<br /> else<br /> {<br /> return beneficialWordsFizzle( mob,<br /> null,<br /> "<S-NAME> chant(s), but the magic fades"<br /> );<br /> }<br /><br /> // return whether it worked<br /> return success;<br /> }<br />}<br /></pre>
<p> 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 <code>classificationCode()</code>
method returns the proper value. </p>
<p> You should also take note that the <code>overrideMana()</code>
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. </p>
<p> The last special note is down in the message
construction in the <code>invoke()</code> method. The <code>invoke()</code>
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 <code>affectType()</code>,
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. </p>
<img src="images/elvis.jpg" alt="Songs" />
<h2><a name="SONGS" id="SONGS">Songs</a></h2>
<p> 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. </p>
<p> 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. </p>
<pre>public class Song_Protection extends com.planet_ink.coffee_mud.Abilities.Songs.Song<br />{<br /> public String ID()<br /> {<br /> return "Song_Protection";<br /> }<br /><br /> public String name()<br /> {<br /> return "Protection";<br /> }<br /></pre>
<p> Like the skill abilities above, <code>ID()</code> and
<code>name()</code> are implemented. The <code>name()</code>
will get intermingled into the invocation text, so name your songs
carefully, so they sound right when invoked! </p>
<pre> public int abstractQuality()<br /> {<br /> return Ability.QUALITY_BENEFICIAL_OTHERS;<br /> }<br /> </pre>
<p> 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! </p>
<pre> public void affectEnvStats( Environmental affected, EnvStats affectableStats )<br /> {<br /> super.affectEnvStats( affected, affectableStats );<br /> if( invoker == null )<br /> {<br /> return;<br /> }<br /><br /> affectableStats.setAttackAdjustment( affectableStats.attackAdjustment() - 5 );<br /> }<br /> </pre>
<p> This particular song uses affectEnvStats 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. </p>
<pre> public void affectCharStats( MOB affected, CharStats affectableStats )<br /> {<br /> super.affectCharStats( affected, affectableStats );<br /> if( invoker == null )<br /> {<br /> return;<br /> }<br /><br /> affectableStats.setStat( CharStats.STAT_DEXTERITY,<br /> affectableStats.getStat( CharStats.STAT_DEXTERITY ) - 1 );<br /><br /> affectableStats.setStat( CharStats.STAT_SAVE_ACID,<br /> affectableStats.getStat( CharStats.STAT_SAVE_ACID )<br /> + (<br /> invoker.charStats().getStat(<br /> CharStats.STAT_CHARISMA<br /> ) * 4<br /> )<br /> );<br /><br /> affectableStats.setStat( CharStats.STAT_SAVE_COLD,<br /> affectableStats.getStat( CharStats.STAT_SAVE_COLD )<br /> + (<br /> invoker.charStats().getStat(<br /> CharStats.STAT_CHARISMA<br /> ) * 4<br /> )<br /> );<br /><br /> affectableStats.setStat( CharStats.STAT_SAVE_ELECTRIC,<br /> affectableStats.getStat( CharStats.STAT_SAVE_ELECTRIC )<br /> + (<br /> invoker.charStats().getStat(<br /> CharStats.STAT_CHARISMA<br /> ) * 4<br /> )<br /> );<br /><br /> affectableStats.setStat( CharStats.STAT_SAVE_FIRE,<br /> affectableStats.getStat( CharStats.STAT_SAVE_FIRE )<br /> + (<br /> invoker.charStats().getStat(<br /> CharStats.STAT_CHARISMA<br /> ) * 4<br /> )<br /> );<br /><br /> affectableStats.setStat( CharStats.STAT_SAVE_GAS,<br /> affectableStats.getStat( CharStats.STAT_SAVE_GAS )<br /> + (<br /> invoker.charStats().getStat(<br /> CharStats.STAT_CHARISMA<br /> ) * 4<br /> )<br /> );<br /> }<br />}<br /></pre>
<p> The most important thing our sample song does
is improve the saving throws of everyone who hears it. The <code>affectCharStats()</code>
method makes that happen by modifying the appropriate saving throws
in affectableStats. </p>
<img src="images/fun.jpg" alt="Common Skills" />
<h2><a name="COMMON" id="COMMON">Common Skills</a></h2>
<p> 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. </p>
<p><a name="skillgathering" id="skillgathering"> </a>
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. </p>
<pre>public class Fishing extends com.planet_ink.coffee_mud.Abilities.Common.GatheringSkill<br />{<br /> public String ID()<br /> {<br /> return "Fishing";<br /> }<br /><br /> public String name()<br /> {<br /> return "Fishing";<br /> }<br /> </pre>
<p> If you've read the Skill Abilities section above, you
will recognize these methods and their importance. As always,
the <code>ID()</code> must match the class name, while the
<code>name()</code> can be whatever you want to call the
skill. </p>
<pre> private static final String[] triggerStrings = { "FISH" };<br /> public String[] triggerStrings()<br /> {<br /> return triggerStrings;<br /> }<br /> </pre>
<p> And again, like a normal skill, the common skills create
and return their invocation words (or "trigger strings" as they
are called in skills). </p>
<pre> public long flags()<br /> {<br /> return FLAG_GATHERING;<br /> }<br /><br /> public String supportedResourceString()<br /> {<br /> return "FLESH";<br /> }<br /> </pre>
<p> The <code>flags()</code> 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. </p>
<p> The <code>supportedResourceString()</code> 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. </p>
<pre> protected Item found = null;<br /> protected String foundShortName = "";<br /> </pre>
<p> 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. </p>
<pre> public Fishing()<br /> {<br /> super();<br /> displayText = "You are fishing...";<br /> verb = "fishing";<br /> }<br /> </pre>
<p> 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. </p>
<pre> public boolean tick( Tickable ticking, int tickID )<br /> {<br /> if( ( affected != null )<br /> && ( affected instanceof MOB )<br /> && ( tickID == Tickable.TICKID_MOB )<br /> )<br /> {<br /> MOB mob = (MOB)affected;<br /> if( tickUp == 6 )<br /> {<br /> if( found != null )<br /> {<br /> commonTell( mob, "You got a tug on the line!" );<br /> }<br /> else<br /> {<br /> StringBuffer str = new StringBuffer( "Nothing is biting around here.\n\r" );<br /> commonTell( mob, str.toString() );<br /> unInvoke();<br /> }<br /> }<br /> }<br /><br /> return super.tick( ticking, tickID );<br /> }<br /> </pre>
<p> 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
<code>unInvoke()</code> the skill. </p>
<p> The <code>commonTell()</code> 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, <code>commonTell()</code>
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!". </p>
<pre> public void unInvoke()<br /> {<br /> if( canBeUninvoked() )<br /> {<br /> if( ( affected != null ) && ( affected instanceof MOB ) )<br /> {<br /> MOB mob = (MOB)affected;<br /> if( ( found != null )<br /> && ( !aborted )<br /> &&( !helping )<br /> )<br /> {<br /> int amount = CMLib.dice().roll( 1, 5, 0 ) * ( abilityCode() );<br /> String s = "s";<br /> if( amount == 1 )<br /> {<br /> s = "";<br /> }<br /><br /> mob.location().show( mob,<br /> null,<br /> CMMsg.MSG_NOISYMOVEMENT,<br /> "<S-NAME> manage(s) to catch "<br /> + amount<br /> + " pound"<br /> + s<br /> + " of "<br /> + foundShortName<br /> + "."<br /> );<br /><br /> for( int i = 0; i < amount; i++ )<br /> {<br /> Item newFound = (Item)found.copyOf();<br /> mob.location().addItemRefuse( newFound, Item.REFUSE_PLAYER_DROP );<br /><br /> if( ( mob.riding() != null )<br /> && ( mob.riding() instanceof Container )<br /> )<br /> {<br /> newFound.setContainer( (Container)mob.riding() );<br /> }<br /><br /> CMLib.commands().postGet( mob, null, newFound, true );<br /> }<br /> }<br /> }<br /> }<br /><br /> super.unInvoke();<br /> }<br /> </pre>
<p> As mentioned above, the <code>unInvoke()</code> 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 addItemRefuse, and force the player to get them into
their inventory (if they can). </p>
<pre> public boolean invoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel<br /> )<br /> {<br /> bundling = false;<br /> if( (!auto)<br /> && ( commands.size() > 0 )<br /> && ( ( (String)commands.firstElement() ).equalsIgnoreCase( "bundle" ) )<br /> )<br /> {<br /> bundling = true;<br /> if( super.invoke( mob, commands, givenTarget, auto, asLevel ) )<br /> {<br /> return super.bundle( mob, commands );<br /> }<br /><br /> return false;<br /> }<br /> </pre>
<p> The <code>invoke()</code> 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. </p>
<p> 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 <code>supportedResourceString()</code>
method above to determine what the player is allowed to
bundle. </p>
<pre> int foundFish = -1;<br /> boolean maybeFish = false;<br /> if( mob.location() != null )<br /> {<br /> for( int i = 0; i < RawMaterial.FISHES.length; i++ )<br /> {<br /> if( mob.location().myResource() == RawMaterial.FISHES[i] )<br /> {<br /> foundFish = RawMaterial.FISHES[i];<br /> maybeFish = true;<br /> }<br /> else if( ( mob.location().resourceChoices() != null )<br /> && ( mob.location().resourceChoices().contains(<br /> new Integer(<br /> RawMaterial.FISHES[i]<br /> )<br /> )<br /> )<br /> )<br /> {<br /> maybeFish = true;<br /> }<br /> }<br /> }<br /> </pre>
<p> 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. </p>
<pre> if( !maybeFish )<br /> {<br /> commonTell( mob, "The fishing doesn't look too good around here." );<br /> return false;<br /> }<br /> </pre>
<p> If maybeFish is false, we are in a location where no
fish are even possibly available (such as a Desert room).
</p>
<pre> verb = "fishing";<br /> found = null;<br /> playSound = "fishreel.wav";<br /> </pre>
<p> 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. </p>
<pre> if( !super.invoke( mob, commands, givenTarget, auto, asLevel ) )<br /> {<br /> return false;<br /> }<br /> </pre>
<p> 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. </p>
<pre> if( ( proficiencyCheck( mob, 0, auto ) )<br /> && ( foundFish > 0 )<br /> )<br /> {<br /> found = (Item)CMLib.materials().makeResource( foundFish, mob.location().domainType(), false );<br /> foundShortName = "nothing";<br /> if( found != null )<br /> {<br /> foundShortName = RawMaterial.RESOURCE_DESCS[ found.material()&RawMaterial.RESOURCE_MASK ].toLowerCase();<br /> }<br /> }<br /> </pre>
<p> 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 <code>utensils()</code> 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. </p>
<pre> int duration = 35 - mob.envStats().level();<br /> if( duration < 10 )<br /> {<br /> duration=10;<br /> }<br /><br /> CMMsg msg = CMClass.getMsg( mob,<br /> found,<br /> this,<br /> CMMsg.MSG_NOISYMOVEMENT,<br /> "<S-NAME> start(s) fishing."<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /> found = (Item)msg.target();<br /> beneficialAffect( mob, mob, asLevel, duration );<br /> }<br /> return true;<br /> }<br />}<br /> </pre>
<p> 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 <code>msg.target()</code>. 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 <code>msg.target()</code> is done to support
code which may have modified our target to something else.
</p>
<p><a name="skillcrafting" id="skillcrafting"> </a>
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! </p>
<pre>public class GlassBlowing extends CraftingSkill implements ItemCraftor<br />{<br /> public String ID()<br /> {<br /> return "GlassBlowing";<br /> }<br /><br /> public String name()<br /> {<br /> return "Glass Blowing";<br /> }<br /> </pre>
<p> If you've read the Skill Abilities section above, you
will recognize these methods and their importance. As always,
the <code>ID()</code> must match the class name, while the
<code>name()</code> can be whatever you want to call the
skill. </p>
<pre> private static final String[] triggerStrings = { "GLASSBLOW", "GLASSBLOWING" };<br /> public String[] triggerStrings()<br /> {<br /> return triggerStrings;<br /> }<br /> </pre>
<p> And again, like a normal skill, the common skills create
and return their invocation words (or "trigger strings" as they
are called in skills). </p>
<pre> public String supportedResourceString()<br /> {<br /> return "GLASS|SAND";<br /> }<br /> </pre>
<p> The <code>supportedResourceString()</code> 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. </p>
<pre> protected static final int RCP_FINALNAME = 0;<br /> protected static final int RCP_LEVEL = 1;<br /> protected static final int RCP_TICKS = 2;<br /> protected static final int RCP_WOOD = 3;<br /> protected static final int RCP_VALUE = 4;<br /> protected static final int RCP_CLASSTYPE = 5;<br /> protected static final int RCP_MISCTYPE = 6;<br /> protected static final int RCP_CAPACITY = 7;<br /> protected static final int RCP_SPELL = 8;<br /> </pre>
<p> 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. </p>
<pre> protected Item building = null;<br /> protected Item fire = null;<br /> protected boolean messedUp = false;<br /> </pre>
<p> 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. </p>
<pre> public boolean tick( Tickable ticking, int tickID )<br /> {<br /> if( ( affected != null )<br /> && ( affected instanceof MOB )<br /> && ( tickID == Tickable.TICKID_MOB )<br /> )<br /> {<br /> MOB mob = (MOB)affected;<br /> if( ( building == null )<br /> || ( fire == null )<br /> || ( !CMLib.flags().isOnFire( fire ) )<br /> || ( !mob.location().isContent( fire ) )<br /> || ( mob.isMine( fire ) )<br /> )<br /> {<br /> messedUp = true;<br /> unInvoke();<br /> }<br /> }<br /> return super.tick( ticking, tickID );<br /> }<br /> </pre>
<p> 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. </p>
<pre> protected Vector loadRecipes()<br /> {<br /> return super.loadRecipes( "glassblowing.txt" );<br /> }<br /> </pre>
<p> Overriding the <code>loadRecipes()</code> 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.
</p>
<pre> public void unInvoke()<br /> {<br /> if( canBeUninvoked() )<br /> {<br /> if( ( affected != null ) && ( affected instanceof MOB ) )<br /> {<br /> MOB mob = (MOB)affected;<br /><br /> if( ( building != null ) && ( !aborted ) )<br /> {<br /> if( messedUp )<br /> {<br /> commonTell( mob,<br /> CMStrings.capitalizeAndLower(<br /> building.name())<br /> + " explodes!"<br /> );<br /> }<br /> else<br /> {<br /> mob.location().addItemRefuse( building, Item.REFUSE_PLAYER_DROP );<br /> }<br /> }<br /><br /> building = null;<br /> }<br /> }<br /> super.unInvoke();<br /> }<br /> </pre>
<p> Just like in the gathering skill, the <code>unInvoke()</code>
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. </p>
<pre> public boolean invoke( MOB mob,<br /> Vector commands,<br /> Environmental givenTarget,<br /> boolean auto,<br /> int asLevel<br /> )<br /> {<br /> int autoGenerate = 0;<br /><br /> if( ( auto )<br /> && ( givenTarget == this )<br /> && ( commands.size() > 0 )<br /> && ( commands.firstElement() instanceof Integer )<br /> )<br /> {<br /> autoGenerate = ( (Integer)commands.firstElement() ).intValue();<br /> commands.removeElementAt( 0 );<br /> givenTarget = null;<br /> }<br /> </pre>
<p> 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 sending
in a commands vector (which is normally the parameter strings
entered by a user) with the first element as an Integer object
instead. This object then represents the material out of which the
item should be made, and maps back to one of the RawMaterial.RESOURCE_*
constants. </p>
<pre> randomRecipeFix( mob,<br /> addRecipes( mob, loadRecipes() ),<br /> commands,<br /> autoGenerate<br /> );<br /> </pre>
<p> 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 (<code>loadRecipes()</code>), another
to append to this vector any recipe Items in the mobs inventory
(<code>addRecipes(..)</code>), and lastly, to randomly select a
recipe based on the autoGenerate flag or if the invoker is an NPC
(<code>randomRecipeFix()</code>). <code>randomRecipeFix()</code>
can handle things like modifying the parameter list (commands)
so that it has the name of the random recipe selected.
</p>
<pre> if( commands.size() == 0 )<br /> {<br /> commonTell( mob, "Make what? Enter \"glassblow list\" for a list." );<br /> return false;<br /> }<br /><br /> if( ( !auto )<br /> && ( commands.size() > 0 )<br /> &&( ( (String)commands.firstElement() ).equalsIgnoreCase( "bundle" ) )<br /> )<br /> {<br /> bundling = true;<br /> if( super.invoke( mob, commands, givenTarget, auto, asLevel ) )<br /> {<br /> return super.bundle( mob, commands );<br /> }<br /><br /> return false;<br /> }<br /> </pre>
<p> Now we can finally start dealing the 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. </p>
<pre> Vector recipes = addRecipes( mob, loadRecipes() );<br /> </pre>
<p> 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 <code>loadRecipes()</code> 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.
</p>
<pre> String str = (String)commands.elementAt( 0 );<br /> String startStr = null;<br /> bundling = false;<br /> int completion = 4;<br /> </pre>
<p> 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. </p>
<pre> if( str.equalsIgnoreCase( "list" ) )<br /> {<br /> StringBuffer buf = new StringBuffer(<br /> CMStrings.padRight( "Item", 16 )<br /> + " Lvl Sand required\n\r"<br /> );<br /><br /> for( int r = 0; r < recipes.size(); r++ )<br /> {<br /> Vector V = (Vector)recipes.elementAt( r );<br /> if( V.size() > 0 )<br /> {<br /> String item = replacePercent( (String)V.elementAt( RCP_FINALNAME ), "" );<br /> int level = CMath.s_int( (String)V.elementAt( RCP_LEVEL ) );<br /> int wood = CMath.s_int( (String)V.elementAt( RCP_WOOD ) );<br /> if( level <= mob.envStats().level() )<br /> {<br /> buf.append(<br /> CMStrings.padRight( item, 16 )<br /> + " "<br /> + CMStrings.padRight( "" + level, 3 )<br /> + " "<br /> + wood<br /> + "\n\r"<br /> );<br /> }<br /> }<br /> }<br /><br /> commonTell( mob, buf.toString() );<br /> return true;<br /> }<br /> </pre>
<p> If the player entered "list" as the first word in
the parameters, we display the recipes to them. </p>
<pre> fire = getRequiredFire( mob, autoGenerate );<br /> if( fire == null )<br /> {<br /> return false;<br /> }<br /><br /> building = null;<br /> messedUp = false;<br /> </pre>
<p> 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 <code>getRequiredFire(..)</code> 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. </p>
<pre> int amount = -1;<br /> if( ( commands.size() > 1 )<br /> && ( CMath.isNumber( (String)commands.lastElement() ) )<br /> )<br /> {<br /> amount = CMath.s_int( (String)commands.lastElement() );<br /> commands.removeElementAt( commands.size() - 1 );<br /> }<br /> </pre>
<p> 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. </p>
<pre> String recipeName = CMParms.combine( commands, 0 );<br /> Vector foundRecipe = null;<br /> Vector matches = matchingRecipeNames( recipes, recipeName, true );<br /> for( int r = 0; r < matches.size(); r++ )<br /> {<br /> Vector V = (Vector)matches.elementAt( r );<br /> if( V.size() > 0 )<br /> {<br /> int level = CMath.s_int( (String)V.elementAt( RCP_LEVEL ) );<br /> if( ( autoGenerate > 0 ) || ( level <= mob.envStats().level() ) )<br /> {<br /> foundRecipe = V;<br /> break;<br /> }<br /> }<br /> }<br /> </pre>
<p> 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.
</p>
<pre> if( foundRecipe == null )<br /> {<br /> commonTell( mob,<br /> "You don't know how to make a '"<br /> + recipeName<br /> + "'. Try \"glassblow list\" for a list."<br /> );<br /> return false;<br /> }<br /> </pre>
<p> 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. </p>
<pre> int woodRequired = CMath.s_int( (String)foundRecipe.elementAt( RCP_WOOD ) );<br /> if( amount > woodRequired )<br /> {<br /> woodRequired = amount;<br /> }<br /><br /> String misctype = (String)foundRecipe.elementAt( RCP_MISCTYPE );<br /> bundling = misctype.equalsIgnoreCase( "BUNDLE" );<br /> int[] pm = { RawMaterial.RESOURCE_SAND,<br /> RawMaterial.RESOURCE_CRYSTAL,<br /> RawMaterial.RESOURCE_GLASS<br /> };<br /><br /> int[][] data = fetchFoundResourceData( mob,<br /> woodRequired,<br /> "sand",<br /> pm,<br /> 0,<br /> null,<br /> null,<br /> bundling,<br /> autoGenerate<br /> );<br /> if( data == null )<br /> {<br /> return false;<br /> }<br /><br /> woodRequired = data[0][FOUND_AMT];<br /> </pre>
<p> 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. </p>
<p> 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. </p>
<pre> if( !super.invoke( mob, commands, givenTarget, auto, asLevel ) )<br /> {<br /> return false;<br /> }<br /> </pre>
<p> 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. </p>
<pre> int lostValue = destroyResources( mob.location(),<br /> woodRequired,<br /> data[0][FOUND_CODE],<br /> 0,<br /> null,<br /> autoGenerate<br /> );<br /><br /> building = CMClass.getItem( (String)foundRecipe.elementAt( RCP_CLASSTYPE ) );<br /><br /> if( building == null )<br /> {<br /> commonTell( mob,<br /> "There's no such thing as a "<br /> + foundRecipe.elementAt( RCP_CLASSTYPE )<br /> + "!!!" );<br /> return false;<br /> }<br /> </pre>
<p> Our next step is to call another superclass
method <code>destroyResources()</code> 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 <code>unInvoke()</code>
method is called, when it will be given to the craftor.
</p>
<pre> completion = CMath.s_int(<br /> (String)foundRecipe.elementAt( RCP_TICKS )<br /> )<br /> - (<br /> (<br /> mob.envStats().level()<br /> - CMath.s_int(<br /> (String)foundRecipe.elementAt( RCP_LEVEL )<br /> )<br /> ) * 2<br /> );<br /><br /> String itemName = replacePercent(<br /> (String)foundRecipe.elementAt( RCP_FINALNAME ),<br /> RawMaterial.RESOURCE_DESCS[<br /> (data[0][FOUND_CODE]&RawMaterial.RESOURCE_MASK)<br /> ]<br /> ).toLowerCase();<br /><br /> if( bundling )<br /> {<br /> itemName = "a " + woodRequired + "# " + itemName;<br /> }<br /> else<br /> {<br /> itemName = CMStrings.startWithAorAn( itemName );<br /> }<br /><br /> building.setName( itemName );<br /> startStr = "<S-NAME> start(s) blowing " + building.name() + ".";<br /> displayText = "You are blowing " + building.name();<br /> verb = "blowing " + building.name();<br /> playSound = "fire.wav";<br /> building.setDisplayText( itemName + " is here" );<br /> building.setDescription( itemName + ". " );<br /> building.baseEnvStats().setWeight( woodRequired );<br /> building.setBaseValue( CMath.s_int( (String)foundRecipe.elementAt( RCP_VALUE ) ) );<br /> </pre>
<p> 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. </p>
<pre> if( data[0][FOUND_CODE] == RawMaterial.RESOURCE_SAND )<br /> {<br /> building.setMaterial( RawMaterial.RESOURCE_GLASS );<br /> }<br /> else<br /> {<br /> building.setMaterial( data[0][FOUND_CODE] );<br /> }<br /><br /> building.baseEnvStats().setLevel(<br /> CMath.s_int(<br /> (String)foundRecipe.elementAt( RCP_LEVEL )<br /> )<br /> );<br /><br /> building.setSecretIdentity( "This is the work of " + mob.Name() + "." );<br /> int capacity = CMath.s_int( (String)foundRecipe.elementAt( RCP_CAPACITY ) );<br /> String spell = ( foundRecipe.size() > RCP_SPELL ) ?<br /> ( (String)foundRecipe.elementAt( RCP_SPELL ) ).trim()<br /> : "";<br /><br /> addSpells( building, spell );<br /> </pre>
<p> 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 <code>addSpells()</code>.
There is also a column in the recipe file for the capacity of
the item if it is a container. </p>
<pre> if( building instanceof Container )<br /> {<br /> if( capacity > 0 )<br /> {<br /> ( (Container)building ).setCapacity( capacity + woodRequired );<br /> }<br /><br /> if( misctype.equalsIgnoreCase( "LID" ) )<br /> {<br /> ( (Container)building ).setLidsNLocks( true, false, false, false );<br /> }<br /> else if( misctype.equalsIgnoreCase( "LOCK" ) )<br /> {<br /> ( (Container)building ).setLidsNLocks( true, false, true, false );<br /> ( (Container)building ).setKeyName(<br /> new Double(<br /> Math.random()<br /> ).toString()<br /> );<br /> }<br /><br /> ( (Container)building ).setContainTypes( Container.CONTAIN_ANYTHING );<br /> }<br /> </pre>
<p> 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. </p>
<pre> if( building instanceof Drink )<br /> {<br /> if( CMLib.flags().isGettable( building ) )<br /> {<br /> ( (Drink)building ).setLiquidRemaining( 0 );<br /> ( (Drink)building ).setLiquidHeld( capacity * 50 );<br /> ( (Drink)building ).setThirstQuenched( 250 );<br /><br /> if( ( capacity * 50 ) < 250 )<br /> {<br /> ( (Drink)building ).setThirstQuenched( capacity * 50 );<br /> }<br /> }<br /> }<br /><br /> if( bundling )<br /> {<br /> building.setBaseValue( lostValue );<br /> }<br /> </pre>
<p> 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. </p>
<pre> building.recoverEnvStats();<br /> building.text();<br /> building.recoverEnvStats();<br /> </pre>
<p> The filling out of the item is complete, so we
call <code>recoverEnvStats()</code>, populate the miscText field if the
item is Generic, and then recover the env stats again in case
that changed anything. </p>
<pre> messedUp =! proficiencyCheck( mob, 0, auto );<br /> if( completion < 4 )<br /> {<br /> completion = 4;<br /> }<br /><br /> if( bundling )<br /> {<br /> messedUp = false;<br /> completion = 1;<br /> verb = "bundling "<br /> + RawMaterial.RESOURCE_DESCS[<br /> ( building.material()&RawMaterial.RESOURCE_MASK)<br /> ].toLowerCase();<br /><br /> startStr = "<S-NAME> start(s) " + verb + ".";<br /> displayText = "You are " + verb;<br /> }<br /> </pre>
<p> 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. </p>
<pre> if( autoGenerate > 0 )<br /> {<br /> commands.addElement( building );<br /> return true;<br /> }<br /> </pre>
<p> If the invoke method was called simply to generate
the item, we are done -- we can add the item to the commands vector
(where it will be expected), and return. </p>
<pre> CMMsg msg = CMClass.getMsg( mob,<br /> building,<br /> this,<br /> CMMsg.MSG_NOISYMOVEMENT,<br /> startStr<br /> );<br /><br /> if( mob.location().okMessage( mob, msg ) )<br /> {<br /> mob.location().send( mob, msg );<br /> building = (Item)msg.target();<br /> beneficialAffect( mob, mob, asLevel, completion );<br /> }<br /> else if( bundling )<br /> {<br /> messedUp = false;<br /> aborted = false;<br /> unInvoke();<br /> }<br /> return true;<br /> }<br />}<br /> </pre>
<p> 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. </p>
<img src="images/prayer.jpg" alt="poisons" />
<h2><a name="POISON" id="POISON">Poisons</a></h2>
<pre>public class Poison_BeeSting extends com.planet_ink.coffee_mud.Abilities.Poisons.Poison<br />{<br /> public String ID()<br /> {<br /> return "Poison_BeeSting";<br /> }<br /><br /> public String name()<br /> {<br /> return "Bee Sting";<br /> }<br /></pre>
<p> 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. </p>
<pre> private static final String[] triggerStrings = { "POISONSTING" };<br /> public String[] triggerStrings()<br /> {<br /> return triggerStrings;<br /> }<br /></pre>
<p> 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). </p>
<pre> protected String POISON_DONE()<br /> {<br /> return "The stinging poison runs its course.";<br /> }<br /><br /> protected String POISON_START()<br /> {<br /> return "^G<S-NAME> turn(s) green.^?";<br /> }<br /><br /> protected String POISON_CAST()<br /> {<br /> return "^F<S-NAME> sting(s) <T-NAMESELF>!^?";<br /> }<br /><br /> protected String POISON_FAIL()<br /> {<br /> return "<S-NAME> attempt(s) to sting <T-NAMESELF>, but fail(s).";<br /> }<br /></pre>
<p> In this set of methods, strings are defined for the invocation
of the poison, all the way through its recovery string.
</p>
<pre> protected int POISON_TICKS()<br /> {<br /> return 10; // 0 means no adjustment!<br /> }<br /></pre>
<p> Poisons can have a variable duration dependent upon level
(by returning 0) or can have a set duration on the poisoned creature.
</p>
<pre> protected int POISON_DELAY()<br /> {<br /> return 2;<br /> }<br /><br /> protected int POISON_DAMAGE()<br /> {<br /> return ( invoker != null ) ? 2 : 0;<br /> }<br /><br /> protected String POISON_AFFECT()<br /> {<br /> return "<S-NAME> cringe(s) from the poisonous itch.";<br /> }<br /></pre>
<p> 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. </p>
<pre> public void affectCharStats( MOB affected, CharStats affectableStats )<br /> {<br /> affectableStats.setStat(<br /> CharStats.STAT_CONSTITUTION,<br /> affectableStats.getStat(<br /> CharStats.STAT_CONSTITUTION<br /> ) - 1<br /> );<br /><br /> affectableStats.setStat(<br /> CharStats.STAT_STRENGTH,<br /> affectableStats.getStat(<br /> CharStats.STAT_STRENGTH<br /> ) - 1<br /> );<br /><br /> if( affectableStats.getStat( CharStats.STAT_CONSTITUTION ) <= 0 )<br /> {<br /> affectableStats.setStat( CharStats.STAT_CONSTITUTION, 1 );<br /> }<br /><br /> if( affectableStats.getStat( CharStats.STAT_STRENGTH ) <= 0 )<br /> {<br /> affectableStats.setStat( CharStats.STAT_STRENGTH, 1 );<br /> }<br /> }<br />}<br /></pre>
<p> 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.
</p>
<img src="images/disease.jpg" alt="Diseases" />
<h2><a name="DISEASE" id="DISEASE">Diseases</a></h2>
<p> Like Poison, the Disease base class in the Diseases package
provides a tidy template upon which your more common, mundane
diseases can be based. </p>
<pre>public class Disease_Cold extends com.planet_ink.coffee_mud.Abilities.Diseases.Disease<br />{<br /> public String ID()<br /> {<br /> return "Disease_Cold";<br /> }<br /><br /> public String name()<br /> {<br /> return "Cold";<br /> }<br /><br /> public String displayText()<br /> {<br /> return "(Cold Virus)";<br /> }<br /><br /> protected int canAffectCode()<br /> {<br /> return CAN_MOBS;<br /> }<br /><br /> protected int canTargetCode()<br /> {<br /> return CAN_MOBS;<br /> }<br /><br /> public int abstractQuality()<br /> {<br /> return Ability.QUALITY_MALICIOUS;<br /> }<br /><br /> public boolean putInCommandlist()<br /> {<br /> return false;<br /> }<br /></pre>
<p> 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. </p>
<pre> protected String DISEASE_DONE()<br /> {<br /> return "Your cold clears up.";<br /> }<br /><br /> protected String DISEASE_START()<br /> {<br /> return "^G<S-NAME> come(s) down with a cold.^?";<br /> }<br /></pre>
<p> In this set of methods, strings are defined for the invocation
of the disease as well as its recovery string. </p>
<pre> protected int DISEASE_TICKS()<br /> {<br /> return 24;<br /> }<br /></pre>
<p> Diseases can have a variable duration dependent upon
level (by returning 0) or can have a set duration on the diseased
creature. </p>
<pre> protected int DISEASE_DELAY()<br /> {<br /> return 5;<br /> }<br /><br /> protected String DISEASE_AFFECT()<br /> {<br /> return "<S-NAME> sneeze(s). AAAAAAAAAAAAAACHOOO!!!!";<br /> }<br /></pre>
<p> 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. </p>
<pre> public int abilityCode()<br /> {<br /> return DiseaseAffect.SPREAD_CONSUMPTION<br /> |DiseaseAffect.SPREAD_PROXIMITY<br /> |DiseaseAffect.SPREAD_CONTACT<br /> |DiseaseAffect.SPREAD_STD;<br /> }<br /></pre>
<p> 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. </p>
<pre> public boolean tick( Tickable ticking, int tickID )<br /> {<br /> if( !super.tick( ticking,tickID ) )<br /> {<br /> return false;<br /> }<br /><br /> if( affected == null )<br /> {<br /> return false;<br /> }<br /><br /> if( !( affected instanceof MOB ) )<br /> {<br /> return true;<br /> }<br /><br /> MOB mob = (MOB)affected;<br /> MOB diseaser = invoker;<br /> if( diseaser == null )<br /> {<br /> diseaser = mob;<br /> }<br /></pre>
<p> If a disease does anything during its delay cycle (defined
above by <code>DISEASE_DELAY()</code>), 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) </p>
<pre> if( ( getTickDownRemaining() == 1 )<br /> &&( CMLib.dice().rollPercentage() > mob.charStats().getSave( CharStats.STAT_SAVE_COLD ) )<br /> &&( CMLib.dice().rollPercentage() < 25 - mob.charStats().getStat( CharStats.STAT_CONSTITUTION ) )<br /> &&( !mob.amDead() )<br /> &&( !mob.isMonster() )<br /> )<br /> {<br /> mob.delEffect( this );<br /> Ability A = CMClass.getAbility( "Disease_Pneumonia" );<br /> A.invoke( diseaser, mob, true );<br /> }<br /></pre>
<p> 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 <code>getTickDownRemaining()</code>,
we check out counter which runs downwards from <code>DISEASE_TICKS()</code>
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. </p>
<pre> else if( ( !mob.amDead() ) && ( ( --diseaseTick ) <= 0 ) )<br /> {<br /> diseaseTick = DISEASE_DELAY();<br /> mob.location().show( mob, null, CMMsg.MSG_NOISE, DISEASE_AFFECT() );<br /> if( mob.curState().getHitPoints() > ( ( 2 * diseaser.envStats().level() ) + 1 ) )<br /> {<br /> int damage = CMLib.dice().roll( 2, diseaser.envStats().level(), 1 );<br /> CMLib.combat().postDamage( diseaser,<br /> mob,<br /> this,<br /> damage,<br /> CMMsg.MASK_ALWAYS|CMMsg.TYP_DISEASE,<br /> -1,<br /> null<br /> );<br /> }<br /><br /> catchIt( mob );<br /> return true;<br /> }<br /> return true;<br /> }<br /></pre>
<p> The last thing we do in this method is, every <code>DISEASE_DELAY()</code>
ticks, we emote our DISEASE_AFFECT string, and then allow the
creature to take a few points of disease damage by calling the
<code>MUDFight.postDamage()</code> method. After this, we
also call the <code>catchIt(MOB mob)</code> 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 <code>abilityCode()</code> above.
</p>
<pre> public void affectCharStats( MOB affected, CharStats affectableStats )<br /> {<br /> if( affected == null )<br /> {<br /> return;<br /> }<br /><br /> affectableStats.setStat(<br /> CharStats.STAT_CONSTITUTION,<br /> affectableStats.getStat(<br /> CharStats.STAT_CONSTITUTION<br /> ) - 2<br /> );<br /><br /> affectableStats.setStat(<br /> CharStats.STAT_STRENGTH,<br /> affectableStats.getStat(<br /> CharStats.STAT_STRENGTH<br /> ) - 3<br /> );<br /><br /> if( affectableStats.getStat( CharStats.STAT_CONSTITUTION ) <= 0 )<br /> {<br /> affectableStats.setStat( CharStats.STAT_CONSTITUTION, 1 );<br /> }<br /><br /> if( affectableStats.getStat( CharStats.STAT_STRENGTH ) <= 0 )<br /> {<br /> affectableStats.setStat( CharStats.STAT_STRENGTH, 1 );<br /> }<br /> }<br />}<br /></pre>
<p> 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.
</p>
<img src="images/traps.jpg" alt="Traps" />
<h2><a name="TRAPS" id="TRAPS">Traps</a></h2>
<p> 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. </p>
<pre>public class Trap_ElectricShock extends com.planet_ink.coffee_mud.Abilities.Traps.StdTrap<br />{<br /> public String ID()<br /> {<br /> return "Trap_ElectricShock";<br /> }<br /><br /> public String name()<br /> {<br /> return "electric shock";<br /> }<br /> </pre>
<p> If you've read the Skill Abilities section above,
you will recognize these methods and their importance. As always,
the <code>ID()</code> must match the class name, while the <code>name()</code>
can be whatever you want to call the skill. </p>
<pre> protected int canAffectCode()<br /> {<br /> return Ability.CAN_ITEMS|Ability.CAN_EXITS;<br /> }<br /><br /> protected int canTargetCode()<br /> {<br /> return 0;<br /> }<br /> </pre>
<p> It is very important, even more so than normal
skills, to make sure that your StdAbility <code>canAffectCode()</code>
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. </p>
<pre> protected int trapLevel()<br /> {<br /> return 19;<br /> }<br /> </pre>
<p> The <code>trapLevel()</code> 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. </p>
<pre> public String requiresToSet()<br /> {<br /> return "10 pounds of metal";<br /> }<br /> </pre>
<p> 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. </p>
<pre> public Trap setTrap( MOB mob,<br /> Environmental E,<br /> int trapBonus,<br /> int qualifyingClassLevel,<br /> boolean permanent<br /> )<br /> {<br /> if( E == null )<br /> {<br /> return null;<br /> }<br /><br /> if( mob != null )<br /> {<br /> Item I = findMostOfMaterial( mob.location(), RawMaterial.MATERIAL_METAL );<br /> if( I != null )<br /> {<br /> super.destroyResources( mob.location(), I.material(), 10 );<br /> }<br /> }<br /> return super.setTrap( mob, E, trapBonus, qualifyingClassLevel, permanent );<br /> }<br /> </pre>
<p> This method is used to actually set the trap,
well before the trap is sprung. Springing is handles by the StdTrap
superclass system, and is based on what is returned by the
<code>canAffectCode()</code> 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. <code>findMostOfMaterial()</code> 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 <code>destroyResources()</code> method then will
remove 10 of those from the room. </p>
<pre> public boolean canSetTrapOn( MOB mob, Environmental E )<br /> {<br /> if( !super.canSetTrapOn( mob, E ) )<br /> {<br /> return false;<br /> }<br /><br /> if( mob != null )<br /> {<br /> Item I = findMostOfMaterial( mob.location(), RawMaterial.MATERIAL_METAL );<br /> if( ( I == null )<br /> || ( super.findNumberOfResource( mob.location(), I.material() ) < 10 )<br /> )<br /> {<br /> mob.tell( "You'll need to set down at least 10 pounds of metal first." );<br /> return false;<br /> }<br /> }<br /> return true;<br /> }<br /> </pre>
<p> This method is called before the <code>setTrap()</code>
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 <code>findMostOfMaterial()</code> to determine
what the most numerous metal resource on the room is, then call
another StdTrap superclass method, <code>findNumberOfResource()</code>,
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! </p>
<pre> public void spring( MOB target )<br /> {<br /> if( ( target != invoker() ) && ( target.location() != null ) )<br /> {<br /> if( ( !invoker().mayIFight( target ) )<br /> || ( CMLib.dice().rollPercentage() <= target.charStats().getSave( CharStats.STAT_SAVE_TRAPS) )<br /> )<br /> {<br /> target.location().show( target,<br /> null,<br /> null,<br /> CMMsg.MASK_ALWAYS|CMMsg.MSG_NOISE,<br /> "<S-NAME> avoid(s) setting off a shocking trap!"<br /> );<br /> }<br /> else if( target.location().show( target,<br /> target,<br /> this,<br /> CMMsg.MASK_ALWAYS|CMMsg.MSG_NOISE,<br /> "<S-NAME> set(s) off an shocking trap!"<br /> )<br /> )<br /> {<br /> super.spring( target );<br /> CMLib.combat().postDamage( invoker(),<br /> target,<br /> null,<br /> CMLib.dice().roll( trapLevel(), 8, 1 ),<br /> CMMsg.MASK_ALWAYS|CMMsg.TYP_ELECTRIC,<br /> Weapon.TYPE_STRIKING,<br /> "The shock <DAMAGE> <T-NAME>!"<br /> + CMProps.msp( "shock.wav",30 )<br /> );<br /><br /> if( ( canBeUninvoked() ) && ( affected instanceof Item ) )<br /> {<br /> disable();<br /> }<br /> }<br /> }<br /> }<br />}<br /> </pre>
<p> 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 <code>invoker()</code> 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 <code>super.spring()</code>.
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 <code>super.spring()</code>.
Anyway, since the trap has gone off, we make a library call to
the <code>combat()</code> engine's <code>postDamage()</code> 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 <code>disable()</code>
method, which makes the trap unviable FOREVER. It effectively destroys
the trap. </p>
<img src="images/language.jpg" alt="Languages" />
<h2><a name="LANGS" id="LANGS">Languages</a></h2>
<p> 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 Language base class
in the Languages package. </p>
<pre>public class Elvish extends com.planet_ink.coffee_mud.Abilities.Languages.Language<br />{<br /> public String ID()<br /> {<br /> return "Elvish";<br /> }<br /><br /> public String name()<br /> {<br /> return "Elvish";<br /> }<br /></pre>
<p> 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. </p>
<pre> private static boolean mapped = false;<br /> public Elvish()<br /> {<br /> super();<br /> if( !mapped )<br /> {<br /> mapped = true;<br /> CMAble.addCharAbilityMapping( "All", 1, ID(), false );<br /> }<br /> }<br /></pre>
<p> 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 CMAble method we saw up in Character Class creation.
</p>
<pre> public static Vector wordLists = null;<br /> public Vector translationVector()<br /> {<br /> if(wordLists==null)<br /> {<br /> String[] one = { "a", "e",<br /> "i", "o",<br /> "á", "é",<br /> "í", "ó"<br /> };<br /><br /> String[] two = { "os", "vi",<br /> "ne", "vo",<br /> "li", "eh",<br /> "no", "ai",<br /> "by", "et",<br /> "ce", "un",<br /> "il"<br /> };<br /><br /> String[] three = { "ána", "cil",<br /> "sar", "tan",<br /> "hel", "loa",<br /> "sir", "hep",<br /> "yur", "nol",<br /> "hol", "qua",<br /> "éth"<br /> };<br /><br /> String[] four = { "séya", "qual", "quel",<br /> "lara", "uqua", "sana",<br /> "yava", "masse", "yanna",<br /> "quettaparma", "manna", "manan",<br /> "merme", "carma", "harno",<br /> "harne", "varno", "essar",<br /> "saira", "cilta", "veuma",<br /> "norta", "turme", "saita"<br /> };<br /><br /> String[] five = { "cuiva", "cuina", "nonwa",<br /> "imire", "nauta", "cilta",<br /> "entuc", "norta", "latin",<br /> "lòtea", "veuya", "veuro",<br /> "apama", "hampa", "nurta",<br /> "firta", "saira", "holle",<br /> "herwa", "uquen", "arcoa",<br /> "calte", "cemma", "hanta",<br /> "tanen"<br /> };<br /><br /> String[] six = { "mahtale", "porisalque", "hairie",<br /> "tararan", "ambarwa", "latina",<br /> "olòtie", "amawil", "apacen",<br /> "yavinqua", "apalume", "linquilea",<br /> "menelwa", "alassea", "nurmea",<br /> "parmasse", "ceniril", "heldasse",<br /> "imirin", "earina", "calatengew",<br /> "lapselunga", "rianna", "eneques"<br /> };<br /><br /> wordLists=new Vector();<br /> wordLists.addElement( one );<br /> wordLists.addElement( two );<br /> wordLists.addElement( three );<br /> wordLists.addElement( four );<br /> wordLists.addElement( five );<br /> wordLists.addElement( six );<br /> }<br /> return wordLists;<br /> }<br /></pre>
<p> The first, often only, and certainly most important Language
method is <code>translationVector()</code>, which returns a Vector
object containing a set of String arrays. Each String array 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.
</p>
<p> 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. </p>
<pre> private static final Hashtable hashwords = new Hashtable();<br /> public Hashtable translationHash()<br /> {<br /> if( ( hashwords != null ) && ( hashwords.size() > 0 ) )<br /> {<br /> return hashwords;<br /> }<br /><br /> hashwords.put( "ABANDON", "avarta" );<br /> hashwords.put( "ABLE", "pol" );<br /> hashwords.put( "ACCOMMODATE", "camta" );<br /> hashwords.put( "ACT", "car" );<br /><br /> ...<br /><br /> hashwords.put( "WRONG", "raicë" );<br /> hashwords.put( "YES", "yé" );<br /> hashwords.put( "YESTERDAY", "tellaurë" );<br /> return hashwords;<br /> }<br />}<br /></pre>
<p> The last Language method is <code>translationHash()</code>.
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. </p>
</td>
</tr>
</tbody>
</table>
</center>
<br />
<br />
<br />
</body>
</html>
