BlobbieScript was designed and written to replace the archaic Easyact system which had far outlived its usefulness. Easyacts were originally designed by Dimwit (Aaron Buhr) and are the basis of mobprogs in Merc 2.2. BlobbieScript is fully backward compatible with previously written easyact code (and thus quite possibly with mobprogs). Despite the compatibility, the features and power of the BlobbieScript engine are nowhere near as limited as that offered by these older engines. BlobbieScript was designed and coded from the ground up and is a bytecode language rather than a run-time interpreter. A quick benchmark has shown that the engine can process 60,000+ lines of BlobbieScript per second. Optimizations are known and are scheduled for sometime in the near future that could bump this up to about 80,000 lines per second. To see a couple of examples of BlobbieScript, please see the examples section.

Flaws in the Easyact Engine

The Easyact engine was a great engine in its hay day and served to be the basis for many other MUD scripting engines; however, it is well past its usefulness having reached somewhere around 10 years of age. Someone really should have put it out of its misery a long time ago. The following outlines the deficiencies encountered in the Easyact engine:

Not real-time, variables are expanded macros
Scripts are parsed on every run
No looping constructs
Nothing ensuring data is valid for duration of execution
Poor support for expressions
No concept of instance variables
Code is a mess and poorly scalable
No simple way to access internal data fields

Flaws in the Easyact Engine

Almost all of the features in the new BlobbieScript engine arose to solve inadequacies of the easyact engine. The following is a list of features that were (or will be) implemented to meet and exceed the shortcomings of the Easyact engine:

Backward compatible with existing Easyact code
Real-time data access
Looping constructs
Block protection for time sensitive routines (mutexes)
Fully exploitable precedence based operations
On the fly declaration and access of instance variables
Static variables
Associative array data containers
Contextual resolutions for accessing internal data fields
Variables use copy-on-write method of copying
Easily extensible
Return values from scripts for scriptlet embedding
Line continuation breaks
Error messages which pinpoint problems
context manipulation (thread management)
User function declaration (after initial engine)

Expressions

Previously the Easyact engine supported some simple block control mechanisms. Some of the mechanisms worked well, others not so well. The 'if' statement is a good example for one that generally works well. One of the greatest drawbacks of the 'if' statement though, is its lack of support for joining conditional expressions. This is solved in the new engine. The following control blocks are supported by BlobbieScript:

Keyword	Description
static	Initialize static variables
if	Test for conditional block entry
elseif	Test for conditional block entry where priors have failed
else	When all prior tests fail then enter this block
endif	Close a series of conditionals
for	Initialize and loop over some expression while it evaluates to true.
endfor	Loop back to beginning of the matching for block.
foreach	Iterate over an array's values.
endforeach	Loop back to beginning of the matching foreach block.
do	Enter a looping block
dowhile	Test conditional for re-entry into 'do' block
while	Test conditional for entry into block
endwhile	Loop back to beginning of a 'while' conditional loop
switch	Select the first matching case and continue evaluation from that point.
case	A conditional starting point based on the case value matching the switch value.
default	If all case statements for the switch block fail, then evaluation will continue at the default statement.
endswitch	Marker for the end of a switch block.
wait	Wait for a number of time units (secs, hsecs, qsecs, tsecs)
protect	Run code in block to completion
endprotect	Marker for end of protected block
break	Break out of innermost loop or switch statement; if none then return
continue	Jump to beginning of looping block immediately
label	Set a marker for a 'jumpto' statement
jumpto	Jumpto a given labelled point in the script
return	Exit script optionally providing a return value
retval	Return a value but do not exit script
null	The special null value / datatype.
true	Boolean true value.
false	Boolean false value.
<<	The final evaluation of the whole line is fed into the mud's interpreter as though the script owner had issued it as a command.
\	Indicates line continues or is a continuation
{ or }	A line containing only these and spaces is ignored

Expression Evaluation

One of the biggest problems in creating the BlobbieScript engine was to try and add in real language support while adding the flexibility of evaluating expressions as can be done in almost any other programming language. To maximize ease and backward compatibility there exist two modes of expression evaluation: pure and impure.

Pure expressions are any expressions that are part of a block control expression or part of a function's parameter part. These are called pure because they do not require special treatment to be evaluated in their context. To illustrate, the following is now possible:

if( %getLevel( $n ) < 50 and !%getRandom( 1, 10 ) )
{
   damage $n %( (1d10 + 1) * 3 )
}
else-
if( %getAlign( $n ) / 10 > 60 or %getAlign( $n ) < -60 )
{
   damage $n %( 1d(1d10) )
}
endif

The difference between pure and impure expressions is also illustrated above. Notice to get the power of expression evaluation within a non- block control statement the expression needs to be evaluated with the special %() function. This is because for backward compatibility reasons the new engine guesses that anything in a block control statement is any of variable, function, or string. Given this interpretation all tokens extracted are considered to be implicitly joined by an invisible concatenation operator. Since this may become confusing if a variable is used that blends into an actual word the following can be used to ensure the end of the variable:

0001 @name = %getName( $n )

0002 echoto r all @{name}'s mother is a wench!

The advantage of such expression evaluation is that it gets rid of the old system of $.calc( 1, +, 3 ) since this can be expressed as %( 1 + 3 ). Moreover the engine fully supports integers, floats, strings, and associative arrays (AKA: dictionary, string indexed array, hash).

Other Types of Expressions

In addition to block control expressions and normal expressions there are comments, continuations, and block tags. Comments begin when a pair of forward slashes "//" are encountered and end at the end of the line.

Example:

//
// Get a list of creatures in the room.
//
@list = %roomGetMobs()     // Creatures are stored in @list

*
* This is a deprecated style, and only works when
* the "*" is the first non-whitespace character on
* a line.
*

The \ at the beginning of a line denotes that the expression continues from the previous line. This was added so conditionals can be nicely formatted for easy reading.

Example:

echoto room all
\   You can feel the rush of winds building in strength to
\   a deafening roar. You clasp your ears to mitigate the
\   painful effects of the sound.

Block control tags are more for aesthetic purposes. I come from programming background which uses braces to denote code blocks. Normally BlobbieScript doesn't support these blocks due to backwards compatibility; however, for the sake of good looking code (IMHO) any line containing only a sequence of "{" or "}" characters will be ignored.

Example:

if( @n->name == "The Overlord" )
{
   echoto notc @n Grovel before your master heathens!
}
else
{{{{
   spit @n
}}}}
endif

Finally a semi-colon is permitted on most pure expressions where one would make sense. The behaviour of the engine is to strip it if it is the last character on the line. Note that commands normally passed on to the game's command interpreter will retain any trailing semi-colons.

Example:

@i = 20;
while( (@i -= 1) > 0 )
{
   echoto room all A fireball suddenly explodes before you.
   damage room all %( 20 + 1d15 ) fire

   wait 20 secs;
}
endwhile;

Expression - for

The for construct enables easy iteration over an expression. Unlike the while construct, the for loop provides a means to initialize, test, and update the evaluation.

    Example:


    for( @i = 0; @i < 10; @i++ )
    {   
        %echoTo( @i, @self )
    } 
    endfor;

The above for loop will output the numbers 0 to 9 inclusive to @self. Studying the expression we notice the following pattern:

    Example:


    for( [INITIALIZE]; [TEST]; [UPDATE] )
    {   
        %echoTo( @i, @self )
    } 
    endfor;

So when the for loop is encountered the INITIALIZE portion is processed, then the TEST part is processed to determine if the contents of the for block should be processed. If the contents are processed, then upon reaching the endfor construct the engine will process the UPDATE expression and then the TEST part. Subsequent runs through the loop will repeat this UPDATE/TEST parts until the TEST fails and the loop ends.

Expression - foreach

The foreach construct enables easy iteration over an array's values. This simplifies the task of updating a series of items, mobiles, rooms, or anything else in an array.

    Example:


    foreach( %roomGetMobiles() as @mob )
    {   
        //
        // Give a little regen bonus.
        //
        @mob->hitpoints += 2d3
    } 
    endwhile;

    Example (with index):


    @mobiles = %roomGetMobiles()
    foreach( @mobiles as @index => @mob )
    {   
        //
        // Move to Elkin fountain.
        //
        %move( @mobiles->@index, 115611 );
    } 
    endwhile;

Operators

Operators

Operators are at the epicentre of any kind of logical and mathematical processing. To facilitate the power that BlobbieScript will exhibit, many of the most common programming operators have been implemented. Some of the operators can be expressed in more than one way since not all programming languages use the same style. Remember operators will only be functional if found within a pure context, otherwise they are treated as part of the plain text input to the MUD's command interpreter.

Operator	Description
=	Assign the right operand's value to the left operand (C style).
:=	Assign the right operand's value to the left operand (Pascal Style).
+=	Add the right operand to the left operand and assign the value to the left operand.
-=	Subtract the right operand from the left operand and assign the value to the left operand.
/=	Divide the right operand into the left operand and assign the value to the left operand.
*=	Multiply the left operand by the right operand and assign the value to the left operand.
%=	Assign to the left operand the remainder from dividing the right operand into the left operand. If the left operand and the right operand are both of the same sign then the remainder will be positive. Otherwise the remainder will be negative.
^^=	Raise the left operand to the power of the right operand and assign the value to the left operand.
&=	Take the bitwise AND of the left operand with the right operand and assign to the left operand.
\|=	Take the bitwise OR of the left operand with the right operand and assign to the left operand.
^=	Take the bitwise XOR of the left operand with the right operand and assign to the left operand.
<<=	Shift the bits of the value of the left operand to the left by the value of the right operand and assign to the left operand.
>>=	Shift the bits of the value of the left operand to the right by the value of the right operand and assign to the left operand.
.=	Concatenate the right operand to the end of the left operand and assign the new value to the left operand.
++	When this operator preceds the operand it increments the value of the operand and returns the incremented value. When the operator follows the operand then it increments the value of the operand after returning the value.
--	When this operator preceds the operand it decrements the value of the operand and returns the decremented value. When the operator follows the operand then it decrements the value of the operand after returning the value.
\|\|	Return the the boolean value of taking the logical OR of the left and right operands.
OR	Same as '\|\|'.
&&	Return the the boolean value of taking the logical AND of the left and right operands.
AND	Same as '&&'.
&	Return the value of taking the bitwise AND of the left operand with the right operand.
\|	Return the value of taking the bitwise OR of the left operand with the right operand.
^	Return the value of taking the bitwise XOR of the left operand with the right operand.
==	Return the the boolean value of comparing the values of the left and right operands.
!=	Return the the boolean value of applying the logical NOT operator to the boolean value of comparing the values of the left and right operands.
===	Return the the boolean value of comparing the values of the left and right operands with datatype checking. In other words if the datatypes of the left and right operands differ then this will return false, even if the values would normally return true when using the == operator.
!==	Return the the boolean value of applying the logical NOT operator to the boolean value of comparing the values of the left and right operands with datatype checking. In other words if the datatypes of the left and right operands differ then this will return true, even if the comparison would normally return false when using the != operator.
<	Return the the boolean value of checking to see if the left operand is less than the right operand.
>	Return the the boolean value of checking to see if the left operand is greater than the right operand.
<=	Return the the boolean value of checking to see if the left operand is less than or equal to the right operand.
>=	Return the the boolean value of checking to see if the left operand is greater than or equal to the right operand.
<<	Return the result of shifting the bits of the left operand to the left by the value of the right operand.
>>	Return the result of shifting the bits of the left operand to the right by the value of the right operand.
.	Concatenation operator if one existed :) Concatenation occurs invisibly when two operands are detected with no joining operator. Thus the following is legitimate: %( Random: 1d100 ) which will a string of the form "Random: 73".
MIN	The left operand is limited to a minimum value as defined by the right operand.
MAX	The left operand is limited to a maximum value as defined by the right operand.
+	Return the result of adding the right operand to the left operand. This may also be used as a unary operator; however, as such it's benefits are aesthetic only.
-	Return the result of subtracting the right operand from the left operand. This may also be used as a unary operator to signify the negation of the right operand.
/	Return the result of dividing the right operand into the left operand.
*	Return the result of multiplying the left operand by the right operand.
%	Return the remainder when the left operand is divided by the right operand. If the left operand and the right operand are both of the same sign then the remainder will be positive. Otherwise the remainder will be negative.
^^	Return the result of raising the left operand to the power of the right operand.
D	Given that the left operand signifies a number of die and the right operand signifies the number of faces for each dice. Return an entry from the set of all possible dice roll totals with these criteria.
!	Return the logical NOT of the right operand.
~	Return the bitwise NOT of the right operand.
->	Please see "The Resolution Operator" section below.
->+	The array add operator. This is used in conjunction with the = operator to add elements to an array with auto indexing (@foo->+ = @value).
( )	Force the evaluation of the expression within the parenthesis to occur before any other evaluation.

Precedence

As with all expression evaluation mechanism there must exist a set of rules of precedence to ensure that what the user expects to happen, actually happens. BlobbieScript uses the following order of precedence, from highest to lowest, for its evaluations -- operators on the same line are of equal precedence:

Order of Precedence
( )
->
! ~ ++ -- + (unary) - (unary)
D
^^
% * /
- +
MIN MAX
. (implicit and cannot be used explicitly)
<< >>
== != === !== < > <= >=
&
\| ^
&&
\|\|
+= -= /= *= %= ^^= &= \|= ^= <<= >>= .= := ->+

Variables

Traditionally Easyacts only supported pre-set variables of a single character nature. While the most triggers still support these basic preset variables, newer triggers now use more readable named variables. For instance $i traditionally was a variable whose contents were a text pointer to entity for which the script was defined. While this can still be used, the more object oriented nomenclature of @this, or @self is preferred. These can also be written using $ but to break from the past it is suggested that all variables use @ instead of $ (similarly for function $. has been deprecated in favour of %). Additionally, script authors can now declare variables of their own naming on the fly.

0001 @charName = %getName( @self )

0002 @randNum = %getRandom( 1, 500 )

Local and Static Variable

There are currently five types of variables used in the Worlds of Carnage. The first two are types used by BlobbieScript. This style should always be denoted with the '@' marker such as @foo. These types of variables are only known to the script in which they appear, meaning two different scripts, even two different instances of the same script, will see a different value for @foo. As I have said there are two types, script variables can be declared as static, if so their values are remembered from one script instance to the next (and subsequently can be shared by multiple instances of the same script). The programmer needs to take care when declaring static variables since ANY variable in the static expression will become static and can thus block normal script variables.

static @foo
static @foo = @fee = (60 * 60) / 14

Strange Behaviour:

//
// Normal variable.
//
@foo = 3

//
// Static declaration, the original @foo has been clobbered and it's
// value forgotten.
//
static @foo

Entity Variables

Another type of variable is the entity variable. Entity variables can be applied to a rooms, mobiles, or objects. Entity variables can be set using %setEntityVar(), retrieved using %getEntityVar(), and unset using %deleteEntityVar(). These variables are a great way to share information across multiple scripts, especially quest, or game information. For convenience three other functions exist: %setVar(), %getvar(), and %deleteVar(). These are a shorthand for accessing the entity variables of the script owner. For instance:

%setVar( foo, 1 )       is identical to     %setEntityVar( @i, foo, 1 )
%getVar( foo )          is identical to     %getEntityVar( @i, foo )
%deleteVar( foo )       is identical to     %deleteEntityVar( @i, foo )

Another shorter method of accessing entity variables has also been developed using the evars resolution:

0001 @i->evars->foo = 1 is identical to %setEntityVar( @i, foo, 1 )

0002 @i->evars->foo is identical to %getEntityVar( @i, foo )

Persistent Variables

The fourth type of variable is persistent. These variables are saved and can be restored even after a crash. Such variables can be used to ensure an object is unique or to save ownership of some residential portion of the world. There is a multitude of uses for such data. When saving a persistent variable, the variable is shared amongst all entity instances with the same vnum. These variables are manipulated with the following functions:

%setSavedVar()
%getSavedVar()
%deleteSavedVar()

Another shorter method of accessing saved variables has also been developed using the svars resolution:

0001 @i->svars->foo = 1 is identical to %setSavedVar( @i, foo, 1 )

0002 @i->svars->foo is identical to %getSavedVar( @i, foo )

Player Variables

The fifth and final variable type persists in the player's save file. These are known as player vars and can be set for players, objects, and rooms. The following functions are used to manipulate their values:

%setPlayerVar()
%getPlayerVar()
%deletePlayerVar()

Another shorter method of accessing player variables has also been developed using the pvars resolution:

0001 @i->pvars->foo = 1 is identical to %setPlayerVar( @i, foo, 1 )

0002 @i->pvars->foo is identical to %getPlayerVar( @i, foo )

Player vars set on a room are exactly the same as saved vars since rooms can't be saved to player files, but only one instance of a room with a given vnum can ever exist. The following table summarizes the variable types:

Type	Set / Get / Delete	Persistence
Local	@var1 = 1d5 @var1 Unable to Delete	Variable expires when script completes.
Static	static @var1 = 1d5 @var1 Unable to delete	Variable and value persist through all invocations of the script for any given boot of the MUD server.
Entity	@i->evars->varname %setEntityVar( ) %getEntityVar( ) %deleteEntityVar( )	Variable and value are set on a given room, mobile, or object and the value persists for any given boot of the MUD server.
Saved	@i->svars->varname %setSavedVar( ) %getSavedVar( ) %deleteSavedVar( )	Variable and value are shared by all homogenous entities with the same vnum and value persists through MUD reboots.
Player	@i->pvars->varname %setPlayerVar( ) %getPlayerVar( ) %deletePlayerVar( )	Variable and value are saved in player files specific to a given player or object instance and persist through MUD reboots.

Predefined Variables

Scripts are fired when events occur. These events can be triggered by a player, a signal, or for a multitude of other reasons. There exists a set of default variables (many cryptic due to backwards compatibility) that are instanciated to facilitate knowledge of what elements played a key part in the firing of the script. These variables are listed below:

Variable	Description
@this @self @i	A pointer to the owner of the script. Currently this may be a room, character, or object. The @i version was used historically and so has been retained.
@room	A pointer to the room containing the script owner at the time the script is run.
@roomId	The ID of the room containing the script owner at the time the script is run.
@I	The name of the script owner defined by @i. This is set to "something" for rooms and "nothing" for any invalid owners.
@p	Short name of object if the script owner is a character and can see the object defined by @o. If the object is not visible to the owner then it is set to "something". If the owner is not a character then it is set to "nothing".
@P	Short name of target object defined by @t if the script owner defined by @i is a character and can see the object. If the object is not visible to the owner then it is set to "something". If the owner is not a character then it is set to "nothing".
@n	Pointer to the actor that triggered the script. This is usually a character.
@N	The nice'd name of the script actor defined by @n if visible to the script owner. If not visible to the script owner then it is set to "someone". If the script owner is not a character then @n will be considered to be visible. If @n is not a pointer to a character then this will be set to "nobody".
@s	The gender specific possessive for a character script actor defined by @n. This will be one of: his, hers, its. If the actor is not a character then this will be set to "nothing".
@e	The gender specific pronoun for a character script actor defined @by n. This will be one of: he, she, it. If the actor is not a character then this will be set to "nothing".
@m	The gender specific objective for a character script actor defined by @n. This will be one of: him, her, it. If the actor is not a character then this will be set to "nothing".
@h	Pointer to a character being hunted by the character script owner defined by @i. If the owner is not a character then this will be set to "nobody".
@H	The nice'd name of the character defined by @h if visible to the script owner. If not visible to the script owner then it is set to "someone". If the script owner is not a character then this will be set to "nobody".
@t	Pointer to a provided target of the script. In the case of a script triggered by combat, @t will usually be set to the opponent.
@T	The nice'd name of the script target defined by @t if visible to the script owner. If not visible to the script owner then it is set to "someone". If the script owner is not a character then @t will be considered to be visible. If @t is not a pointer to a character then this will be set to "nobody".
@A	Conjunction for a target object as defined by @t. This will have an appropriate value of "a" or "an" (i.e. an apple).
@S	The gender specific possessive for a character script target defined by @n. This will be one of: his, hers, its. If the target is not a character then this will be set to "nothing".
@E	The gender specific pronoun for a character script target defined by @n. This will be one of: he, she, it. If the target is not a character then this will be set to "nothing".
@M	The gender specific objective for a character script target defined by @n. This will be one of: him, her, it. If the target is not a character then this will be set to "nothing".
@a	Conjunction for a the object defined by @o. This will have an appropriate value of "a" or "an" (i.e. an apple).
@o	Pointer to an object that played a part in the script's firing.
@O	Short name of the object defined by @o if the character owner defined by @i can see the object or the owner is not a character. If the script owner is a character and cannot see the object then this is set to "something". If the object defined by @o is not valid then this is set to "nothing".
@x	An arbitrary string that may be set by whatever triggers the script. The prupose of this value is highly dependent on the script. For instance the catch death act populates @x with the name of the creature that died since the creature itself cannot be accessed.
@X	The first word of the string defined by @x.
@q	Pointer to a random object in the current room if any exist.
@Q	Short name of the object defined by @q if the character owner defined by @i can see the object or the owner is not a character. If the script owner is a character and cannot see the object then this is set to "something". If the object defined by @q is not valid then this is set to "nothing".
@r	Pointer to a random creature in the current room if any exist.
@R	The nice'd name of the random character defined by @r if visible to the script owner. If not visible to the script owner then it is set to "someone". If the script owner is not a character then @r will be considered to be visible. If @r is not a pointer to a character then this will be set to "nobody".

Triggers

Many events in the game can be be caught by various event handlers. These event handlers are known as triggers since they trigger some kind of functionality when the event occurs. There are three entity types that can trigger an event. These entities are rooms, mobiles, and objects. Some event types can be triggered by multiple entity types, such as the random event. Most triggers will run an associated script; however, the text ones will merely present some text to player that cause the trigger to fire. Additionally there are a few types that don't do either and are for hacking in special functionality such as the set_skill trigger. Following are the lists of events that apply for each entity type:

Rooms	Mobiles	Objects
adj_sound catch_act_act catch_bash_door catch_close_door catch_combat_start_act catch_death_act catch_destroy_act catch_enter_game catch_entry_act catch_examine_act catch_exit_act catch_level_up catch_lock_door catch_open_door catch_pick_door catch_relocation catch_say_act catch_script_call catch_script_special catch_signal_act catch_speech_act catch_talk catch_unlock_door catch_weapon_strike check_can_bash_door check_can_close_door check_can_enter check_can_exit check_can_lock_door check_can_open_door check_can_pick_door check_can_relocate check_can_unlock_door check_pc_can_idle custom_command_act custom_mobile_attacks custom_mobile_prompt custom_mobile_status dream_for_area dream_for_continent dream_for_room dream_for_world dream_for_zone on_area_load on_entry on_hour_of_day on_load on_real_hour_of_day on_tick on_zone_load on_zone_unload preempt_death_act preempt_destroy_act random_act spec_proc trigger_assignment	adj_sound catch_act_act catch_ask_act catch_ask_text catch_attack_act catch_bash_door catch_close_door catch_combat_start_act catch_death_act catch_destroy_act catch_enter_game catch_entry_act catch_examine_act catch_exit_act catch_give_act catch_identify_act catch_level_up catch_lock_door catch_open_door catch_pick_door catch_practice_act catch_relocation catch_say_act catch_say_text catch_script_call catch_script_special catch_signal_act catch_social_act catch_speech_act catch_speech_text catch_talk catch_tell_act catch_unlock_door catch_weapon_strike check_can_bash_door check_can_close_door check_can_enter check_can_exit check_can_lock_door check_can_open_door check_can_pick_door check_can_relocate check_can_unlock_door check_pc_can_idle custom_command_act custom_mobile_attacks custom_mobile_prompt custom_mobile_status fight_act if_inroom on_area_load on_entry on_exit on_hour_of_day on_immortal_goto_enter on_immortal_goto_exit on_load on_location_change on_real_hour_of_day on_tick on_zone_load on_zone_unload preempt_death_act preempt_destroy_act random_act set_affect2 set_skill set_teach spec_proc trigger_assignment	adj_sound catch_act_act catch_affect_dispel catch_affect_list catch_affect_show catch_attach_act catch_attack_act catch_bash_door catch_close_door catch_combat_start_act catch_death_act catch_destroy_act catch_detach_act catch_drop_act catch_enter_game catch_entry_act catch_examine_act catch_exit_act catch_get_act catch_get_from_act catch_identify_act catch_level_up catch_lock_door catch_open_door catch_pick_door catch_put_into_act catch_relocation catch_remove_act catch_room_affect_show catch_say_act catch_script_call catch_script_special catch_signal_act catch_social_act catch_speech_act catch_talk catch_unlock_door catch_use_act catch_weapon_strike catch_wear_act check_board_permissions_act check_can_attach check_can_bash_door check_can_close_door check_can_enter check_can_exit check_can_lock_door check_can_open_door check_can_pick_door check_can_put_into check_can_relocate check_can_unlock_door check_pc_can_idle custom_command_act custom_equipment_location custom_mobile_attacks custom_mobile_examine_info custom_mobile_prompt custom_mobile_status fight_act on_area_load on_eaten on_entry on_exit on_expire on_hour_of_day on_immortal_goto_enter on_immortal_goto_exit on_immortal_qsave on_load on_location_change on_real_hour_of_day on_tick on_weapon_strike on_zone_load on_zone_unload preempt_death_act preempt_destroy_act random_act spec_proc trigger_assignment

Functions

The easyact system provided a fairly rich set of functions for accessing the data structures that define the state of the mud at any given point of time. For the most part these functions have been carried forward with the same functionality. Where errors have been detected in the conversion process the errors have been corrected. One concept that was deprecated was the "*ERR*" or any similar type of return value when data is erroneous. Rather than this a null data structure is returned which can be tested with the %isNull( ) function. This is a more consistent and flexible approach to error handling. Generally speaking functions names are case-insensitive; however, for historical reason the %v( ) and %V( ) functions are case-sensitive. Functions are shown with any aliases they may have. I'm high on long names for clarity of code, so you'll notice some function names are just longer versions of the traditional short versions.

%abortHunt()	%getPcPointer()	%printValue()
%act()	%getPet()	%pulseActivity()
%actionDisown()	%getPlayerVar()	%pulseActivityDuration()
%actionIsRunning()	%getPositionId()	%pulseTick()
%affectCheckFlag()	%getRace()	%pulseViolence()
%affectGetAntidotes()	%getRacePointer()	%pulseViolenceDuration()
%affectGetOwner()	%getRealTime()	%pure()
%affectGetSkillName()	%getReputation()	%purge()
%affectSetOwner()	%getRoomPointer()	%randBetween()
%affectSetSkillName()	%getSavedVar()	%randK()
%applyBuoyancy()	%getServerBootId()	%randPlayer()
%areaGetItems()	%getShortName()	%randSelect()
%areaGetMobs()	%getSubClass()	%randSelectMultiUnique()
%areaGetNpcs()	%getTarget()	%roomGetExits()
%areaGetPcs()	%getTargets()	%roomGetItems()
%areaGetStat()	%getTime()	%roomGetMobs()
%array()	%getTotalHere()	%roomGetNpcs()
%arrayGetHead()	%getTranslation()	%roomGetPcs()
%arrayGetKeyForValue()	%getVar()	%roomGetRadiusItems()
%arrayGetKeys()	%getWeight()	%roomGetRadiusMobs()
%arrayGetSize()	%globalDebug()	%roomGetRadiusRooms()
%arrayGetTail()	%hasAffectItem()	%roomGetRandom()
%arrayGetValues()	%hasItem()	%roomGetStat()
%arrayHasValue()	%hates()	%roomSetStat()
%arrayImplode()	%height()	%runCommand()
%arrayMergeValues()	%hitsCond()	%saveVersusBreath()
%arrayShuffle()	%int()	%saveVersusBreathMod()
%arrayUnset()	%intCeiling()	%saveVersusParalyze()
%arrayValuesToKeys()	%intFloor()	%saveVersusParalyzeMod()
%asArray()	%intRound()	%saveVersusPetrify()
%asInt()	%isAffectedBy()	%saveVersusPetrifyMod()
%asNull()	%isAffectedByBits()	%saveVersusPrayer()
%asString()	%isArray()	%saveVersusPrayerMod()
%attackCheckAttempt()	%isAwake()	%saveVersusRod()
%attackCheckOpponentCount()	%isCharm()	%saveVersusRodMod()
%attackDeny()	%isDark()	%saveVersusSkill()
%average()	%isDaytime()	%saveVersusSkillMod()
%buffGetByLabel()	%isEarlyTwilight()	%saveVersusSpell()
%calculate()	%isEquipmentLocation()	%saveVersusSpellMod()
%canAttack()	%isEquippedItem()	%scriptAlreadyRunning()
%canBodyAttack()	%isEvil()	%scriptAlreadyRunningExit()
%canSee()	%isExit()	%scriptAttach()
%canTake()	%isExtra()	%scriptCall()
%canTarget()	%isFighting()	%scriptCallMultiple()
%canWear()	%isFloat()	%scriptExists()
%clone()	%isFollowing()	%scriptGetAttached()
%combatClear()	%isGhost()	%scriptUsurp()
%combatStart()	%isGladiating()	%serialize()
%combatStop()	%isGood()	%serverGetProfile()
%commandGetFlags()	%isHunting()	%serverLog()
%containerGetStat()	%isImmortal()	%setEntityVar()
%contextContinue()	%isImmune()	%setHatred()
%contextDisown()	%isInt()	%setPlayerVar()
%contextGetId()	%isItem()	%setSavedVar()
%contextGetVar()	%isItemHere()	%setSilenceOff()
%contextGetVars()	%isItemId()	%setSilenceOn()
%contextIsValid()	%isJailed()	%setVar()
%contextKill()	%isLateTwilight()	%skillAffectAdd()
%contextPause()	%isLeader()	%skillAffectExists()
%contextSetVar()	%isLinkDead()	%skillAffectItemExists()
%corpseGetId()	%isMob()	%skillAffectMerge()
%corpseGetName()	%isMobHere()	%skillAffectRemove()
%corpseGetStat()	%isMobId()	%skillCheckGain()
%corpseIsDecapitated()	%isNeutral()	%skillGetELevel()
%corpseIsNpc()	%isNighttime()	%skillGetId()
%corpseIsPc()	%isNpc()	%skillGetQuality()
%corpseSetStat()	%isNull()	%skillGetTeachable()
%damage()	%isOutside()	%skillSetELevel()
%damageGetPhrases()	%isPc()	%spell()
%damageMessages()	%isPet()	%spellRoutineCheckAllowedTarget()
%deathtrap()	%isResistant()	%spellRoutineCheckDefender()
%deleteEntityVar()	%isRoom()	%spellRoutineCheckOpponentCount()
%deletePlayerVar()	%isRoomId()	%spellRoutineExecuteRest()
%deleteSavedVar()	%isString()	%spellRoutineItemsOnly()
%deleteVar()	%isSusceptable()	%spellRoutineItemTargets()
%doZoneActivate()	%isValid()	%spellRoutineMitemTargets()
%dream()	%isVampire()	%spellRoutineMobsOnly()
%drinkGetStat()	%isWaiting()	%spellRoutineMobsTargets()
%drinkSetStat()	%itemClearType()	%spellRoutineMobTargets()
%echo()	%itemGetLoadCount()	%spellRoutineNoGhosts()
%echoTo()	%itemGetStat()	%spellRoutineSelfOnly()
%eqPos()	%itemInitType()	%spellRoutineVerifyTargets()
%equipment()	%itemIsTypeAffect()	%sprintf()
%equipmentLocationInfo()	%itemIsTypeArmour()	%string()
%ereg()	%itemIsTypeArrow()	%stringExplode()
%eregi()	%itemIsTypeBoat()	%stringFind()
%evades()	%itemIsTypeBodyPart()	%stringFindI()
%exitGetStat()	%itemIsTypeBow()	%stringFormat()
%exitSetStat()	%itemIsTypeContainer()	%stringGetModifiableIndexes()
%fastCommand()	%itemIsTypeCorpse()	%stringGetSize()
%filterActionWords()	%itemIsTypeDrink()	%stringIsPrefix()
%filterGroup()	%itemIsTypeFood()	%stringIsPrefixI()
%filterId()	%itemIsTypeHerb()	%stringLcFirst()
%filterInArea()	%itemIsTypeKey()	%stringPad()
%filterInContinent()	%itemIsTypeLight()	%stringRepeat()
%filterInRoom()	%itemIsTypeMissile()	%stringReplace()
%filterInZone()	%itemIsTypeMoney()	%stringReplaceI()
%filterKeyword()	%itemIsTypeNote()	%stringSmokify()
%filterNotGroup()	%itemIsTypeOther()	%stringSubString()
%filterNotInArea()	%itemIsTypePen()	%stringToLowerCase()
%filterNotInContinent()	%itemIsTypePotion()	%stringToUpperCase()
%filterNotInRoom()	%itemIsTypeRod()	%stringToWords()
%filterNotInZone()	%itemIsTypeScroll()	%stringTrim()
%filterNpcs()	%itemIsTypeStaff()	%stringTrimLead()
%filterOut()	%itemIsTypeTome()	%stringTrimTail()
%filterPcs()	%itemIsTypeTrap()	%stringUcFirst()
%filterVisible()	%itemIsTypeTrash()	%stringUcFirstAll()
%float()	%itemIsTypeTreasure()	%stun()
%follow()	%itemIsTypeWand()	%sunrise()
%gainExperience()	%itemIsTypeWeapon()	%sunset()
%gainPuzzlePoints()	%itemIsTypeWorn()	%triggerDispel()
%getAffectItems()	%itemSetStat()	%triggerInvoke()
%getBounded()	%itemZap()	%unserialize()
%getClass()	%jumpTo()	%updatePosition()
%getContainer()	%kill()	%viewExitComplete()
%getContents()	%load()	%viewExitDescription()
%getContinent()	%math()	%viewExtraDescription()
%getEntityVar()	%mobCheckImmortalLevels()	%viewItemComplete()
%getEquipment()	%mobGetAffectItemsById()	%viewItemDescription()
%getEquippedItem()	%mobGetAffectItemsBySkill()	%viewItemInventory()
%getFollowers()	%mobGetStat()	%viewItemInventoryList()
%getGender()	%mobIsUndead()	%viewItemRoomList()
%getGenderPossess()	%mobPageBufferClear()	%viewItemTypeSpecific()
%getGenderTarget()	%mobPageBufferClose()	%viewMobileComplete()
%getGuildId()	%mobPageBufferCopyContents()	%viewMobileDescription()
%getHomeId()	%mobPageBufferGetContents()	%viewMobileEquipment()
%getHomeTownRoomId()	%mobPageBufferOpen()	%viewMobileGroup()
%getHuntDirection()	%mobPulseActivity()	%viewMobileHealth()
%getHuntPrey()	%mobPulseTick()	%viewMobileHealthStatus()
%getId()	%mobPulseViolence()	%viewMobileInventory()
%getInventory()	%mobPurgeSkills()	%viewMobileItemAffects()
%getItemPointer()	%mobRankAtLeast()	%viewMobileList()
%getItemsWithId()	%mobRankAtMost()	%viewMobileScoreSheet()
%getLanguage()	%mobSendBufferClear()	%viewRoomComplete()
%getLanguageId()	%mobSendBufferClose()	%viewRoomContents()
%getLeader()	%mobSendBufferCopyContents()	%viewRoomDescription()
%getLevel()	%mobSendBufferGetContents()	%viewRoomExits()
%getLoadCount()	%mobSendBufferOpen()	%viewRoomItems()
%getMax()	%mobSetStat()	%viewRoomMobiles()
%getMaxIndex()	%move()	%viewRoomTitle()
%getMin()	%nAct()	%weaponGetType()
%getMinIndex()	%noteGetStat()	%weatherGetId()
%getMobPointer()	%noteSetStat()	%where()
%getMobsWithId()	%npcGetLoadCount()	%worldGetItems()
%getName()	%null()	%worldGetMobs()
%getNpcPointer()	%partyGetMobs()	%worldGetNpcs()
%getObjTypeId()	%partyGetNpcs()	%worldGetPcs()
%getOpponent()	%partyGetPcs()	%zoneGetItems()
%getOpponents()	%partyRoomIsInFrontRow()	%zoneGetMobs()
%getOrderId()	%positionAtLeast()	%zoneGetNpcs()
%getOwner()	%positionAtMost()	%zoneGetPcs()

Resolutions

This operator is powerful enough to warrant an entire section describing its use. Unlike other operators the resolution operator "->" is highly contextual and the actual functionality is completely dependent on the leftmost value of the resolution. Since this operator may be strung together in sequence to resolve a multi-level path for a container, it may not always behave as expected when the leftmost operand does not support multi-level resolution. This is true of strings. Currently the resolution operator may be used on both strings, associative arrays, and any of the entity pointer types (rooms, mobiles, objects, and exits). It is especially convenient that this operator can be used on room, mobile, object, and exit pointers.

'fun fun fun'->5
@string->3
@array->index
@n->hitpoints
@room->objects

Application of the resolution operator to a string requires that the right operand be an integer index. Use in this manner will return a string consisting of the single character found at the appropriate valid index. Indexes are 1-based. This means the first character of the string is denoted by an index of value 1. Contrast this to languages such as C which are 0 based. If the index is not valid, or the right operand is not an integer then null will be returned. This behaviour is modified when the resolution is being set via the assignment operator. When the resolution is setting a string then once again the right operand must be an integer, however the value to set the indexed character may either be a string or an integer. If it is a string then the first character of the string will be used to update the resolved string, whereas if the value to set is an integer then it will be used as the ascii value of the character with which to update the resolved string. When the value is set, the right operand of the assignment operator is returned.

Examples:

@text = "Blobbie was here."         // Set up the @text variable

@text->6                            // Returns the string "i"

@text->3 = u                        // Sets the 3rd character to "u"
                                    // and returns "u"

@text                               // Returns "Blubbie was here."

@text->10 = 105                     // Sets the 10th character to the
                                    // character represented by ascii
                                    // value 105 ("i") and returns 105

@text                               // Returns "Blubbie wis here."

If the left operand is an associative array then the resolution operator will return the value indexed by the right operand. The right operand will be converted to a string equivalent and used to resolve a value matching that key. The associative array is also known as a dictionary in other languages. Values may be other associative arrays leading to the possibility for multi-level access to a given data element.

Example:

//
// Set up a multi-level associative array
// of immortals.
//

@immortals->name->1 = Blobule
@immortals->name->2 = Galimatazo
@immortals->name->3 = Pazam
@immortals->name->4 = Sang
@immortals->name->5 = DevilDoll
@immortals->name->6 = Brack

@immortals->race->1 = Slime
@immortals->race->2 = Reptile
@immortals->race->3 = Gnome
@immortals->race->4 = Draconian
@immortals->race->5 = Demon
@immortals->race->6 = Doppleganger

//
// Method 1...
//

@immortals->name->1 " the " @immortals->race->1  // Blobule the Slime
@immortals->name->2 " the " @immortals->race->2  // Galimatazo the Reptile
@immortals->name->3 " the " @immortals->race->3  // Pazam the Gnome
@immortals->name->4 " the " @immortals->race->4  // Sang the Draconian
@immortals->name->5 " the " @immortals->race->5  // DevilDoll the Demon
@immortals->name->6 " the " @immortals->race->6  // Brack the Doppleganger

//
// Method 2...
//

@names = @immortals->name                   // Get list of immortal names
@races = @immortals->race                   // Get list of immortal races

@names->1 " the " @races->1                 // Blobule the Slime
@names->2 " the " @races->2                 // Galimatazo the Reptile
@names->3 " the " @races->3                 // Pazam the Gnome
@names->4 " the " @races->4                 // Sang the Draconian
@names->5 " the " @races->5                 // DevilDoll the Demon
@names->6 " the " @races->6                 // Brack the Doppleganger

As mentioned previously, the resolution operator also works on room, mobile, object, and exit pointers. This provides the ability to easily retrieve and set various values related to the entity being resolved. For instance a regeneration script might want to increase the hitpoints of everyone in the room. This could be done as follows:

foreach( @room->mobiles as @target )
{
   if( (@target->hitpoints += 1d5) > @target->maxHitpoints )
   {
       @target->hitpoints = @target->maxHitpoints
   }
   endif
}
endforeach

There are a couple of places in the above sample script where the resolution operator is used on an entity. The first is:

0001 @targets = @room->mobiles

which is used to retrieve a list of all the mobiles in the room denoted by the room pointer @room. The next place is when we increment the a mobile's hitpoints:

0001 if( (@target->hitpoints += 1d5) > @target->maxHitpoints )

This increments the target's hitpoints by 1 to 5 points and then checks if they exceed the target's maximum hitpoints. If they do then the next line:

0001 @target->hitpoints = @target->maxHitpoints

ensures that they do not exceed the target's maximum hitpoints. The resolution operator is so powerful that it even serves to provide meta functionality by assigning values to certain fields. For instance to move a player from one room to another is as simple as the following line:

0001 @destination->mobiles->last = @n

This moves the mobile stored in the variable @n to the room denoted by @destination. Removal of the player from their existing location is done for you. There are literally hundreds of fields that can be accessed using this method. For details on each entity type see the links at the top.

Appendix A - Examples

The Traveller

@message->1 = "emote looks around to get her bearings."
@message->2 = "emote pulls out a map, looks at it, and makes a few markings."
@message->3 = "talk" @r "Travelling is fun, I can tell you"
\             "how to get just about anywhere!"

<< @message->(1d3)

The Repair Gnome

protect
{
   if( !%canSee( @this, @o ) )
   {
       echoto char @n @I doesn't seem to notice the @O.
       break
   }
   endif

   if( !%canSee( @this, @n ) )
   {
        say Hmmm? Where did this come from?
        drop @o
        break
   }
   endif

   if( @o->hitpoints >= @o->maxHitpoints ) )
   {
        talk @n This is already in perfect condition!
        give @o @n
        drop @o
        break
   }
   endif

   @repairCost =
   \   @o->sellValue * (@o->maxHitpoints - @o->hitpoints) / @o->maxHitpoints

   @repairCost = %asInteger( @repairCost )

   if( @n->gold < @repairCost )
   {
       talk @n You need @repairCost gold pieces to get that fixed.
       talk @n Please come back when you have more gold.
       give @o @n
       drop @o
       break
   }
   endif

   @o->hitpoints = @o->maxHitpoints
   emote rapidly fiddles with @O, %sexPossess( @this ) hands moving
   \   faster than the eye can follow.
   say There we go, right as rain!
   give @o @n
   drop @o

   echoto char @n You give @repairCost gold coins to @I.
   echoto notc @n gives some gold to @I.

   @n->gold = @n->gold - @repairCost
   @this->gold = @this->gold + %asInt( @repairCost / 25 )
}
endprotect

Greedy the Giant

if( !%isAwake( @this ) )
{
   return
}
endif

foreach( %getRoomObects() as @object )
{
   if( %canTake( @object )
   \   &&
   \   (%isObjectTypeKey( @object )
   \    ||
   \    %isObjectTypeWand( @object )
   \    ||
   \    %isObjectTypeStaff( @object )
   \    ||
   \    %isObjectTypePotion( @object )
   \    ||
   \    %isObjectTypeScroll( @object )
   \    ||
   \    %isObjectTypeWeapon( @object )
   \    ||
   \    %getObjStat( @object, "sellValue" ) >= 50000) )
   {
       say Oh goodie goodie...
       get @object
       return
   }
   endif
}
endwhile

Appendix B - Triggers

Trigger: adj_sound

Response Type	plaintext
Entities	Rooms, Mobiles, Objects
Parameters	-

    This works under the same principle as the "random_act" trigger except
    that instead of a script being executed the plaintext is output to each of
    the connexting rooms.

Trigger: catch_act_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	substring

    This trigger will fire when the substring matches any non-communication
    output from an object, room, or mobile. The variables setup for this
    trigger can vary wildly since so many possibilities are possible.
    Generally speaking the following is set:

    @n - The mobile, if any, that generated the output.

    @t - The target mobile or object, if any, of the action.

    @o - The object, if any, that generated the output.

    @x - Usually set to the name of the target mobile or object, if any.

Trigger: catch_ask_act

Response Type	script
Entities	Mobiles
Parameters	keyword1 [, keyword2, keyword3, ...]

    This trigger will fire when one of the keywords in the parameter list
    matches a keyword in the text that something asks the target. When this
    trigger is fired the following variables will be set:

    @n - A pointer to the mobile, if any, that executed the "ask" command.

    @t - The recipient of the "ask" command. The same as @i.

    @o - A pointer to the object, if any, that executed the "ask" command.

    @x - The content of the "ask" command.

Trigger: catch_ask_text

Response Type	plaintext
Entities	Mobiles
Parameters	-

    This trigger will fire when one of the keywords in the parameter list
    matches a keyword in the text that something asks the target.

Trigger: catch_attack_act

Response Type	script
Entities	Mobiles, Objects
Parameters	-

    This trigger will fire whenever an attack is made. In the case the mobile
    makes more than one attack during the damage round then this will fire for
    every attack.

    @n - The owner of the weapon owning the trigger.

    @t - The target of the attack or null if the target has died.

    @o - The weapon making the attack. The same as @i.

    @x - The amount of damage done by the attack, -1 if the attack missed,
         or 0 if a thrown weapon missed.

Trigger: catch_combat_start_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger fires when combat is initiated for a mobile in the room where
    the trigger resides by the room itself or by any mobiles or objects
    present in the room.

        @n, @attacker   - The attacker initiating the combat.

        @attackerName   - The name of the attacker.

        @t, @victim     - The target of the attack.

        @x, @victimName - The name of victim.

Trigger: catch_death_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger fires when a mobile dies and can be caught by the room in
    which they die or by any mobiles or objects present in the room.

        @n, @attacker   - The attacker, if any, that killed the mob.

        @t, @victim     - The mob that has died, just before it is purged.

        @o, @corpse     - The corpse object that is created for the death.
                          Note: inventory and equipment are still on the
                                mobile when this trigger fires.

        @x, @victimName - The name of the mobile that died.

        @deathType      - The manner of death occurring.

    Corpses contain a small amount of useful information about what they were
    when alive; however, without copying the entire mobile structure they
    cannot keep track of all the information. For this reason the
    catch_death_act passes the soon to be purged mob pointer in @n. Thus your
    script can retrieve any information about the mob provided a protected
    block exists at the beginning of the script in which any necessary
    information is saved to variables. If you do not use a protected block
    then there is no guarantee how far along your script will get before the
    @n becomes a null pointer. When @n becomes null, all attempts to retrieve
    data will also return null.

    The type of death occuring can be determined by the value of @deathType.
    So far the following values exist:

        airLack   - this occurs when the mobile drowns

        damage    - this generally occurs in combat

        deathtrap - sucker hit a deathtrap

        fall      - this occurs when fly wear off

        gladiator - gladiator mode death

        noPenalty - no panalty death (noobs usually)

        pkill     - killed by another player

        rebirth   - player has enabled rebirth

        slay      - npcslay or one of the other slay commands

        sunlight  - this occurs when vampires get roasted in the sun

        waterLack - this occurs when a waterOnly mobile is out of water

Trigger: catch_dispel

Response Type	script
Entities	Objects (in room or in affects inventory)
Parameters	-

    This trigger allows special purpose objects that are used to implement
    spell or skill affects (or otherwise) to intercept "dispel" actions. A
    "dispel" action is not necessarily denoted by the spell "dispel magic" but
    rather any spell or skill or special action that can possibly "dispel"
    some kind of affect. For instance the following types of "dispel" events
    can currently fire:

        corrupt                     heal
        cure blindness              remove curse
        cure critical               remove deadly poison
        cure deadly poison          remove poison
        cure light                  sane mind
        cure serious                unhide
        cure sickness               vigor
        dispel evil                 weaken
        dispel magic

    Additionally a script can use the %triggerDispel() function to fire a
    dispel event of any kind it wants on a target mobile or room. This can be
    used effectively to create unique affects that work just like spells but
    which are unique to a particular quest or prize.

    @n       - The entity responsible for triggering the dispel (if any).

    @t       - The mobile affected by the affect object (if any).

    @type    - The type of dispel (ie. cure critical).

    @level   - The level at which the dispel was triggered.

    @quality - The quality of the dispel event (0 to 100).


    Example:

    //
    // Catch "heal" dispel event and act accordingly.
    //
    if( @type == "heal" && 1d100 < @quality )
    {
        %echoTo(
        \   "You feel better as the disease leaves your body.\n", @t )
                   
        %purge( @this )
    }
    endif

Trigger: catch_drop_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire for an object when something attempts to "drop" it.
    This trigger has a lot of hidden purpose since it fires for many different
    types of "drop".

    @n - The mobile that is "dropping" the object.

    @o - The object that the mobile is "dropping".

    @x - The type of get being performed.

    The values for @x are listed below since there are so many different
    values and they are very important for deciding how to handle the trigger.


    bought

        The item is being bought from the mobile in a shop.

    died

        The mobile died and so dropped the item.

    dropped

        The object was literally "dropped".

    evaded

        The object was thrown and evaded by the target.

    fumbled

        The object was fumbled from its owner.

    given

        The object has been given away.

    moveobj-drop

        The object has been put in a room via the "moveobj" command.

    moveobj-put

        The object has been put in a container object via the "moveobj"
        command.

    put-room

        The object is being put in a container that is in the room.

    put-self

        The object is being put in a container that is being carried by the
        mobile.

    sold

        The object has been sold to a shop.

    stolen

        The object has been stolen.

Trigger: catch_enter_game

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger fires when a player enters the game. It can fire for the room
    in which they would normally enter, any mobiles in the room, or any
    objects in their possession.

        @n, @player - The player entering the game.

    If a script catched the player entering the game it can return 1 to
    prevent other scripts from also catching the event. This is useful in the
    event that the player is moved from the original entry location. While
    rooms and mobiles can catch entry to the game they should never return a
    true value to indicate such since the primary purpose of this trigger is
    for affect objects to handle the game entry semantics. That said, mobs or
    rooms can still catch it (they get first shot before objects) and perform
    a zero second wait after which they can check if the player is still in
    the room and then possibly do something.

Trigger: catch_entry_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile enters a room. The parameters may be
    set to a list of directions in which the mobile is travelling that will
    cause the trigger to fire. If no direction parameters are set then all
    directions are considered to cause the trigger to fire. You may also set a
    "no" parameter for mobiles which stop the trigger from firing if the
    script owner cannot see the mobile. Additionally a "fastTrigger" parameter
    may be set which allows the script to catch the entry before the
    travelling mobile has had a chance to "look" at the room.

    @n - The mobile that entered the room.

    @o - The same as @i if the trigger owner is an object.

    @direction - One of north, south, east, west, up, or down

    @fromRoom  - The room in which the player started.

    @toRoom    - The room in which the player will end.

Trigger: catch_examine_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	keyword1 [, keyword2, keyword3, ...]

    This trigger will fire when a mobile attempts to look at something
    and one of the keywords match the target that the viewing mobile is
    attempting to examine.

    @n - The mobile that is attempting to examine something.

    @x - The target word used by the viewing mobile.

Trigger: catch_exit_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile exits a room. The parameters may be
    set to a list of directions in which the mobile is travelling that will
    cause the trigger to fire. If no direction parameters are set then all
    directions are considered to cause the trigger to fire. You may also set a
    "no" parameter for mobiles which stop the trigger from firing if the
    script owner cannot see the mobile. Additionally a "fastTrigger" parameter
    may be set which allows the script to catch the entry before the
    travelling mobile has had a chance to "look" at the room.

        @n - The mobile that exitted the room.

        @o - The same as @i if the trigger owner is an object.

        @direction - One of north, south, east, west, up, or down

        @fromRoom  - The room in which the player started.

        @toRoom    - The room in which the player will end.

    If you want to change the destination of the mobile then you can return
    the ID of the room to which you want the mobile to end up. For this to
    work properly you will need to have enabled the fastTrigger option.

    Example:

        //
        // Redirect the mobile to one of 10 random rooms.
        //

        return 115600 + 1d10

Trigger: catch_get_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire for an object when something attempts to "get" it.
    This trigger has a lot of hidden purpose since it fires for many different
    types of "get".

    @n - The mobile that is "getting" the object.

    @o - The object that the mobile is "getting".

    @x - The type of get being performed.

    The values for @x are listed below since there are so many different
    values and they are very important for deciding how to handle the trigger.


    bought

        The item is being bought from a shop by the mobile.

    container

        The item is being moved from a containing object. Specifically this
        fires when the object is moved from a container with the "moveobj"
        command or when the containing object expires and the object
        automatically moves to another container owned by the mobile or to the
        mobiles inventory itself.

    container-owner

        The mobile is getting the object from a container they are carrying.

    container-room

        The mobile is getting the object from a container in the room.

    given

        The mobile is getting the object by being given it by another mobile.

    loaded

        The object has been newly loaded and assigned to the mobile. This
        happens when an immortal loads an object, or when a player enters the
        game and is carrying or is equipped with such an object, or when a
        zone is loaded and a mobile is to be equipped with the item.

    room

        The mobile is getting the object from their current room.

    stolen

        The mobile has stolen the object from another mobile.

Trigger: catch_get_from_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire for a container when someone attempts to "get from"
    it. 

    @n          - The mobile that is "getting" the object.
    @actor

    @o          - The object that the mobile is "getting".
    @item

    @container  - The container from which the item is being retrieved.

    @x          - The type of "get from" being performed.
    @criteria

    The values for @criteria are listed below. As this trigger matures new
    types may be added:

    get

        The item is being retrieved via the 'get' command.

    shoot

        The item is being retrieved via the shoot command (such as when
        arrows are automatically retrieved from a quiver).

Trigger: catch_give_act

Response Type	script
Entities	Mobiles
Parameters	coins OR keyword OR all

    This trigger fires when a mobile is given an object. If the given object
    is coins then the parameter must either be "coins" or "all". Otherwise if
    it is an object then the parameter must be all or a keyword found in
    object's keywords.

    @n - The mobile giving the object or coins.

    @t - The recipient of the object or coins.

    @o - The object being given or null if coins are being given.

    @x - The name of the object.

    @X - First keyword of item of number of coins given.

Trigger: catch_identify_act

Response Type	script
Entities	Mobiles, Objects
Parameters	-

    Spice up your objects and mobiles by using this trigger to reveal
    additional information when the item or mobile is identified. Not only can
    you output additional information after the usual identify information but
    you can use this triugger to add special effects like perhaps revealing
    information about a powerful object then exploding it so they can't use it
    till next time :)

    @n, @actor  - The player or mobile that cast the spell.

    @level      - The level at which the spell was cast.

    @quality    - The quality at which the spell was cast.

Trigger: catch_level_up

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger type can be used catch when a mobile gains a level. The
    following variables are set:

    @n        - The mobile that gained a level.

    @oldLevel - The level of the mobile before it gained a level.

    @newLevel - The current level of the mobile.

    While it is trivial to retrieve the level information from the mobile
    itself the level variables are offered for convenience.

    Example:

    protect
    {
        if( @newLevel < @self->level )
        {
            talk @n Congratulations... but yer still a putz!
        }
        endif
    }
    endprotect

Trigger: catch_list_affect

Response Type	script
Entities	Objects (in affects inventory)
Parameters	-

    This type of trigger is used specifically to provide information to the
    owner that they are affected by whatever affect the catching object is
    implementing. For instance the "slit throat affect object" returns the
    following string for display in the user's affects list in their score
    output:

        "Blood flows quickly from a wound in your neck."

    Alternatively the "continual light affect object" returns the following
    string for display in the affects list:

        "You are affected by the spell 'continual light'."

    To provide something to be displayed in the score's affect list the script
    must RETURN a string. It should not echo the output since such output will
    not display in the score, but rather will display just before the score.

    @n - The mobile affected by the affect object.


    Example:

    return "Blood flows quickly from a wound in your neck."

Trigger: catch_practice_act

Response Type	script
Entities	Mobiles
Parameters	-

    This trigger type can be used to intercept a player attempting to practice
    with the recipient mobile. The following variables are set:

    @teacher - The mobile that owns the script.

    @student - The mobile attempting to practice with the @teacher.

    @mode    - The mode in which the @student invoked the practice command.
               This will have a value of either "list" or "learn" depending on
               whether the student wants the list of skills taught by the
               teacher or whether they are actually trying to practice a
               skill.

    @skill   - The name of the skill the @student is attempting to learn
               (if any).

    @skillId - The numerical ID of the skill the @student is attempting to
               learn (if any).


    If the script returns a non-zero value then the attempt to practice will
    be considered handled by the internal engine. In other other words, no
    further handling will be done internally.

    Example:

    protect
    {
        if( %getRace( @student ) == Troll )
        {
            talk @student I don't teach dirty trolls such as yourself!

            //
            // The "retval" statement returns a value but does NOT exit
            // the script.
            //
            retval 1

            wait 3 secs
            kill @student
        }
        endif
    }
    endprotect

Trigger: catch_put_into_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire for a container when someone attempts to "put" something
    "into" it. 

    @n          - The mobile that is "putting" the object.
    @actor

    @o          - The object that the mobile is "putting".
    @item

    @container  - The container into which the item is being placed.

    @x          - The type of "put into" being performed.
    @criteria

    The values for @criteria are listed below. As this trigger matures new
    types may be added:

    put

        The item is being placed via the 'put' command.

Trigger: catch_remove_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire when a mobile removes the object.

        @n, @actor      - The mobile that removed the object.

        @o, @item       - The object that the mobile has removed.

        @x, @locationId - The ID of the equipment slot from which the
                          item has been removed.

        @mode           - the mode in which the item is being removed.

    The following values are possible for the @mode parameter:

        "remove"    - The item is being removed normally.

        "consumed"  - The item is being removed having been consumed. This
                      happens for potions when quaffed, scrolls when recited,
                      tomes when studied, etc, etc.

        "fumble"    - The item is being remove via a fumble such as might
                      happen for a failed draw attempt or the fumble spell.

        "weakness"  - The player's strength has dropped below what is
                      required to wield or hold the item.

        "draw"      - The item is being removed to be replaced by a newly
                      drawn weapon.

        "steal"     - The item is being removed by a thief stealing it.

        null        - Blobbie probably forgot to set a mode :B

Trigger: catch_room_affect_show

Response Type	script
Entities	Objects (in affects inventory)
Parameters	-

    This type of trigger is used specifically to provide information to an
    observer in the room about an affect that is currently in the room. For
    instance the poison gas affect uses this technique to inform the player
    that there is a cloud of poisonous vapours.

    @n - The mobile "looking" in the room.

    Example:

        protect
        {
            if( %canSee( @n ) )
            {
                %echoTo( "A cloud of dark swirling poisonous vapors "
                \        "surrounds you.", @n )
            }
            endif
        }
        endprotect

Trigger: catch_say_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	keyword1 [, keyword2, keyword3, ...]

    This trigger will fire when one of the keywords in the parameter list
    matches a keyword in the text that an actor says in the room. This will
    also fire when something talks in the room. When this trigger is fired the
    following variables will be set:

    @n - A pointer to the mobile, if any, that executed the "say" or "talk"
         command.

    @t - The recipient of the "talk" command. The same as @i.

    @o - A pointer to the object, if any, that executed the "say" or "talk"
         command.

    @x - The content of the "say" command.

Trigger: catch_say_text

Response Type	plaintext
Entities	Mobiles
Parameters	-

    This trigger will fire when one of the keywords in the parameter list
    matches a keyword in the text that an actor says in the room. This will
    also fire when something talks in the room.

Trigger: catch_script_call

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	name [, param1Name [, param2Name [, param3Name [, ... ]]]]

    This trigger sets up a callable script which can be run by using either of
    the %callScript() or %usurpScript() BlobbieScript functions. The name is
    used to give the script an identity so that is can be selected via the
    %callScript() or %usurpScript() functions. The name should consist only of
    letters, digits or underscores. After the name you may declare the names
    of as many parameters as you please. The will be converted to variables in
    the actual script and will contain the appropriate sequential values
    provided in the parameter list of the %callScript() or %usurpScript()
    functions. The script may return a value via the return command but this
    will only work properly if the entire script is in a protected block and
    you do not do any waits. This is because this is not a true function call
    (which hopefully I'll have time to do later) and so the state of the
    system cannot be saved midway through a %callScript() or %usurpScript()
    function call. The following variables are intialized when the script is
    run (note that you can clobber these variable if you choose parameters of
    the same name -- which may or may not be a useful feature):

    @i
        - Unlike the usual @i this depends on whether the script is invoked
          with callScript() or %usurpScript().

    @caller
        - A pointer to the calling entity if one is available.

    @owner
        - A pointer to the ACTUAL entity that owns the script. This may be
          different from @i if the script was invoked with %usurpScript().

Trigger: catch_affect_show

Response Type	script
Entities	Objects (in affects inventory)
Parameters	-

    This type of trigger is used specifically to provide information to an
    observer in the room about a mobile currently affected by the object
    implementing the trigger. For instance the "slit throat affect object"
    returns the following string for display under the mobile's room
    description:

        "$n is spraying blood everywhere."

    To provide something to be displayed below the mobile's roomd escription
    the script must RETURN a string. It should not echo the output since such
    output will not display properly. Note that the return string can include
    macros to be expanded as usually expanded by the %act() function.

    @n - The mobile "looking" in the room.

    @t - The mobile affected by the affect object.


    Example:

    return "$n is spraying blood everywhere."

Trigger: catch_signal_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	name

    This trigger will fire when a signal is sent out whose name matches the
    name paramater.

    @n - The mobile entity, if any, that sent the signal.

    @o - The object entity, if any, that sent the signal.

    @x - The extra information passed in the signal.

Trigger: catch_speech_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	keyword1 [, keyword2, keyword3, ...]

    This trigger will fire for any of the commands "say", "talk", or "ask". 
    Depending on which command was used the trigger will have the same
    functionality as the respective trigger. The "say" or "talk" command will
    function the same as for the "catch_say_act" and the "ask" command will
    function the same as for the "catch_ask_act".

Trigger: catch_speech_text

Response Type	plaintext
Entities	Mobiles
Parameters	-

    This trigger will fire for any of the commands "say", "talk", or "ask". 
    Depending on which command was used the trigger will have the same
    functionality as the respective trigger. The "say" or "talk" command will
    function the same as for the "catch_say_text" and the "ask" command will
    function the same as for the "catch_ask_text".

Trigger: catch_talk

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	type, keyword1 [, keyword2, keyword3, ...]

    First parameter determines the type of "talk" to be caught. The rest of
    the parameters determine what keywords in the "talk" will cause the
    trigger to fire. Each of the following first parameters map to a distinct
    trigger type for the handling of the rest of the parameter:

    ask     - catch_ask_act
    say     - catch_say_act
    tell    - catch_tell_act
    all     - catch_speech_act

Trigger: catch_tell_act

Response Type	script
Entities	Mobiles
Parameters	keyword1 [, keyword2, keyword3, ...]

    This trigger will fire when one of the keywords in the parameter list
    matches a keyword in the text that something tells the target. When this
    trigger is fired the following variables will be set:

    @n - A pointer to the mobile, if any, that executed the "tell" command.

    @t - The recipient of the "tell" command. The same as @i.

    @o - A pointer to the object, if any, that executed the "tell" command.

    @x - The content of the "tell" command.

Trigger: catch_use_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire when an attempt is made to use an object. This also
    includes social commands that are applied to objects such as enter, throw,
    flip, tap, etc.

    @n - The mobile that is attempting to use the object.

    @t - The target of the action, such as when throwing or entering.

    @x - The command that was input to use the object ("enter", "tap", etc.).

    @command   - The command that was input to use the object
                 ("enter", "tap", etc.).

    @arguments - Any arguments passed to the command which uses the object. 
                 For instance, "use salt Gruknuk", would result in this
                 variable being set to "Gruknuk".

Trigger: catch_weapon_strike

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger will fire whenever a strike is attempted. In the case the
    weapon attempts more than one strike during the damage round then this
    will fire for every attempt.

    @n - The owner of the weapon owning the trigger.

    @t - The target of the strike or null if the target has died.

    @o - The weapon making the strike.

    @x - The amount of damage done by the strike, -1 if the strike missed,
         or 0 if a thrown weapon missed.

Trigger: catch_wear_act

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire when a mobile wears the object.

        @n, @actor      - The mobile wearing the object.

        @o, @item       - The object that the mobile is wearing.

        @x, @locationId - The ID of the equip slot being filled by
                          wearing the object.

        @mode           - The mode in which the item is being worn.

    The following values are possible for the @mode parameter:

        "wear"      - The item is being worn normally.

        "zone"      - The item is being worn via a zone reset.

        "loaded"    - The item is being worn via a player entering the game.

        "moveObj"   - The item is being worn via the moveObj command.

        null        - Blobbie probably forgot to set a mode :B

Trigger: check_board_permissions_act

Response Type	script
Entities	Objects (specifically boards at the moment)
Parameters	-

    Use this trigger type to allow or deny access to board features. There are
    three types of actions that can be performed on a board: read; write;
    delete. The script should be protected from start to finish and should
    return a value that evaluates to true if the type of action is permitted.

    @n     - The player attempting to perform an action on the board.

    @type  - One of "read", "write", or "delete".

    @o     - when @type is equal to "write" this will be set to the note
             being attached to the board.

    Example:

    //
    // Only allow halflings to post on the board.
    //
    if( %getrace( @n ) == halfling )
    {
        return 1
    }
    else
    {
        echoto char @n Only halflings may post on this board!
    }
    endif

Trigger: check_can_enter

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile attempts to enter a room. There are
    two modes that are important to distinguish between. The first mode is
    "status only" mode, this means the script should only return true or
    false, and not perform any other actions. The other mode is the actual
    attempt to enter the destination. The "status only" mode is usually
    invoked internally by the mud engine to see if the move is viable before
    attempting it. In the other mode if your script prevents entry by
    returning false, then it should also echo some kind of message to the
    creature attempting to enter the target room. Your script should handle
    both modes. The following variables are of interest for this trigger:

    @n - The mobile that wants to enter the room.

    @o - The same as @i if the trigger owner is an object.

    @direction  - One of north, south, east, west, up, or down.

    @fromRoom   - The room from which the mobile wants to leave.

    @toRoom     - The room to which the mobile wants to go.

    @statusOnly - 1 for "status only" mode, 0 for normal mode.

    Your script must return a 1 or a 0 (or equivalent). Any value that does
    not evaluate to true, will prevent the mobile from entering the
    destination room.

Trigger: check_can_exit

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile attempts to leave a room. There are
    two modes that are important to distinguish between. The first mode is
    "status only" mode, this means the script should only return true or
    false, and not perform any other actions. The other mode is the actual
    attempt to exit the room. The "status only" mode is usually invoked
    internally by the mud engine to see if the move is viable before
    attempting it. In the other mode if your script prevents exit by returning
    false, then it should also echo some kind of message to the creature
    attempting to leave the room. Your script should hande both modes. The
    following variables are of interest for this trigger:

    @n - The mobile that wants to enter the room.

    @o - The same as @i if the trigger owner is an object.

    @direction  - One of north, south, east, west, up, or down.

    @fromRoom   - The room from which the mobile wants to leave.

    @toRoom     - The room to which the mobile wants to go.

    @statusOnly - 1 for "status only" mode, 0 for normal mode.

    Your script must return a 1 or a 0 (or equivalent). Any value that does
    not evaluate to true, will prevent the mobile from leaving the source
    room.

Trigger: custom_command_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	command [, command2, command3, ...]

    This trigger is used to override or implement a non-existent command.  Any
    command found in the parameters list will cause this trigger to fire but
    only one trigger can fire for the input command. The order goes from room
    to mobiles, with objects in each being checked before moving on to next. 
    If you want other entities to have a chance at the command (maybe it
    doesn't suit your needs) then you should return 0. You may also set the
    parameters to "all" (excluding the quotes) and all commands will be caught
    by the trigger. When the trigger fires the following variables will be set:

    @actor
        - Contains a pointer to the thing that executed the command. The thing
          may be a room, mobile, or object.

    @commandId
        - Internal assigned ID for the command. Useful for obtaining extra
          information about the command (such as flags). The ID can change
          from reboot to reboot and so it should never be saved. This will
          be 0 for commands that aren't real.

    @rawCommand
        - Contains the exact command input by the user. For instance if you
          type "no" then this will contain "no".

    @command
        - Contains the full command input by the user as it appears in the
          game's command list after accounting for shortcutting. For instance
          if you type "no" then this will contain "north".

    @arguments
        - Contains any arguments that followed the command.


    Example:

    We have a custom_command_act trigger with parameters "roll".
    Blobbie inputs at his console: roll dice
    The script has the following:

    @command: roll
    @arguments: dice

Trigger: custom_mobile_examine_info

Response Type	script
Entities	Objects
Parameters	-

    This trigger is used to add custom information to the information seen by
    players when they use the "equipment" or "examine" command on another
    mobile. For instance the tattoo system uses this to show that a tattoo is
    worn when the player is examined (the tattoo actually resides in the
    special effects inventory). The following variables are provided:

    @actor
        - Contains a pointer to the mobile that is either using the equipment
          command or examining the target.

    @target
        - Contains a pointer to the mobile that is either using the equipment
          command or that is being examined by the actor.

    To provide custom information the script must return a string consisting
    of the data to be displayed.

    Example:

    return 'Runic scars decorate his face.'

Trigger: custom_mobile_prompt

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This powerful trigger is used to override a mobile's prompt. It has far
    reaching possibilities such as the ability to create sequential means of
    retrieving input from a user.  For this reason it best use is in
    conjunction with the custom_command_act trigger.

    @actor
        - Contains a pointer to the mobile that is viewing the contents of the
          room.

    @prompt
        - Contains the current prompt template for the given @actor. This is provided
          in case you just want to modify it (perhaps block out seom set of
          stats temporarily).

    To override the prompt the script need only return new text to be used in
    place of the usual prompt template.

    Example:

    if( %getEntityVar( @actor, "inputStatus" ) == "itemName" )
    {
        return "Please input a name for your pet: "
    }
    endif

Trigger: custom_mobile_status

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger is used to override the room status of a mobile. For instance
    it is normal to see such things as "is standing here." or "is sitting
    here.". This enables the builder to override such mundane status
    descriptions and enrich the game.

    @actor
        - Contains a pointer to the mobile that is viewing the contents of the
          room.

    @target
        - Contains a pointer to the mobile that is currently being viewed from
          the list of room occupants.

    To override the status the script need only return the new text to be used
    in place of the usual text. Visibility issues are handled internally for
    you.

    Example:

    return @target->name " is quickly sinking deeper into quicksand."

Trigger: dream_for_area

Response Type	script
Entities	Rooms
Parameters	area1 [, area2 [, ...] ]

    You can use this trigger type to register an area dream. An area dream is
    a dream that anyone in one of the areas specified in the parameters can
    receive when sleeping. The area can be specified by either its load name
    or by its ID. Multi-word area names should be placed in double quotes.

    
    Following is the current breakdown of dream probabilities for each dream
    type given that a mobile is to receive one:

        dream_for_world      50%
        dream_for_continent  20%
        dream_for_area       10%
        dream_for_zone       10%
        dream_for_room       10% 

    When a player is ready to dream these probabilities are used to order the
    dream categories. This ordering is then used to find an actual dream for
    the player. If a category contains no dreams then the engine moves on to
    the next category. For each potential dream the engine runs the dream
    script which can then determine if it the dream is applicable or not. If
    the dream is not applicable then the script can return 0 to inform the
    engine to try the next dream. If no dreams succeed for a category then
    again the engine moves on to the next category. In a given category all
    dreams have equal probability of running. If you wish to decrease the
    probability of your dream running, you can return 0 after doing a simple
    dice roll to accomodate the decreased odds. In contrast you cannot
    increase the probability that your dream will run. Because the engine
    requires a return value (no return value counts as success) you must place
    your dream script in a protected block.

        @dreamer - The player receiving the dream.

        Example:

            if( @dreamer->race != "troll" )
            {
                //
                // Only trolls can receive this dream.
                //
                return 0
            }
            endif

            #%dream(
            \   "You dream that you are on the front lines of a great "
            \   "battle between your mighty troll brethren and the weak "
            \   "and pathetic elves. You scream your battle cry and "
            \   "smoosh the head of a fallen elf under your foot.",
            \   @dreamer )

Trigger: dream_for_continent

Response Type	script
Entities	Rooms
Parameters	continent1 [, continent2 [, ...] ]

    You can use this trigger type to register a continent dream. A continent
    dream is a dream that anyone on one of the continents specified in the
    parameters can receive when sleeping. The continent must be specified by
    name. Multi-word continent names should be placed in double quotes. The
    following continents currently exist (this is obviously a loose concept of
    continent *heheh*):

        Cythera                 Astral
        Carnage                 Ship - Crete
        Western Islands         Ship - Vhronia
        Eastern Islands         Ship - Lilith

    
    Following is the current breakdown of dream probabilities for each dream
    type given that a mobile is to receive one:

        dream_for_world      50%
        dream_for_continent  20%
        dream_for_area       10%
        dream_for_zone       10%
        dream_for_room       10% 

    When a player is ready to dream these probabilities are used to order the
    dream categories. This ordering is then used to find an actual dream for
    the player. If a category contains no dreams then the engine moves on to
    the next category. For each potential dream the engine runs the dream
    script which can then determine if it the dream is applicable or not. If
    the dream is not applicable then the script can return 0 to inform the
    engine to try the next dream. If no dreams succeed for a category then
    again the engine moves on to the next category. In a given category all
    dreams have equal probability of running. If you wish to decrease the
    probability of your dream running, you can return 0 after doing a simple
    dice roll to accomodate the decreased odds. In contrast you cannot
    increase the probability that your dream will run. Because the engine
    requires a return value (no return value counts as success) you must place
    your dream script in a protected block.

        @dreamer - The player receiving the dream.

        Example:

            if( @dreamer->race != "troll" )
            {
                //
                // Only trolls can receive this dream.
                //
                return 0
            }
            endif

            #%dream(
            \   "You dream that you are on the front lines of a great "
            \   "battle between your mighty troll brethren and the weak "
            \   "and pathetic elves. You scream your battle cry and "
            \   "smoosh the head of a fallen elf under your foot.",
            \   @dreamer )

Trigger: dream_for_room

Response Type	script
Entities	Rooms
Parameters	room1 [, room2 [, ...] ]

    You can use this trigger type to register a room dream. A room dream is a
    dream that anyone in one of the rooms specified in the parameters can
    receive when sleeping. The room must be specified by its ID.

    
    Following is the current breakdown of dream probabilities for each dream
    type given that a mobile is to receive one:

        dream_for_world      50%
        dream_for_continent  20%
        dream_for_area       10%
        dream_for_zone       10%
        dream_for_room       10% 

    When a player is ready to dream these probabilities are used to order the
    dream categories. This ordering is then used to find an actual dream for
    the player. If a category contains no dreams then the engine moves on to
    the next category. For each potential dream the engine runs the dream
    script which can then determine if it the dream is applicable or not. If
    the dream is not applicable then the script can return 0 to inform the
    engine to try the next dream. If no dreams succeed for a category then
    again the engine moves on to the next category. In a given category all
    dreams have equal probability of running. If you wish to decrease the
    probability of your dream running, you can return 0 after doing a simple
    dice roll to accomodate the decreased odds. In contrast you cannot
    increase the probability that your dream will run. Because the engine
    requires a return value (no return value counts as success) you must place
    your dream script in a protected block.

        @dreamer - The player receiving the dream.

        Example:

            if( @dreamer->race != "troll" )
            {
                //
                // Only trolls can receive this dream.
                //
                return 0
            }
            endif

            #%dream(
            \   "You dream that you are on the front lines of a great "
            \   "battle between your mighty troll brethren and the weak "
            \   "and pathetic elves. You scream your battle cry and "
            \   "smoosh the head of a fallen elf under your foot.",
            \   @dreamer )

Trigger: dream_for_world

Response Type	script
Entities	Rooms
Parameters	-

    You can use this trigger type to register a world dream. A world dream is
    a dream that anyone in the game can receive when sleeping. This is in
    contrast to the other dream types which require the player be in a
    specific location dependent on the dream type and parameters.

    
    Following is the current breakdown of dream probabilities for each dream
    type given that a mobile is to receive one:

        dream_for_world      50%
        dream_for_continent  20%
        dream_for_area       10%
        dream_for_zone       10%
        dream_for_room       10% 

    When a player is ready to dream these probabilities are used to order the
    dream categories. This ordering is then used to find an actual dream for
    the player. If a category contains no dreams then the engine moves on to
    the next category. For each potential dream the engine runs the dream
    script which can then determine if it the dream is applicable or not. If
    the dream is not applicable then the script can return 0 to inform the
    engine to try the next dream. If no dreams succeed for a category then
    again the engine moves on to the next category. In a given category all
    dreams have equal probability of running. If you wish to decrease the
    probability of your dream running, you can return 0 after doing a simple
    dice roll to accomodate the decreased odds. In contrast you cannot
    increase the probability that your dream will run. Because the engine
    requires a return value (no return value counts as success) you must place
    your dream script in a protected block.

        @dreamer - The player receiving the dream.

        Example:

            if( @dreamer->race != "troll" )
            {
                //
                // Only trolls can receive this dream.
                //
                return 0
            }
            endif

            #%dream(
            \   "You dream that you are on the front lines of a great "
            \   "battle between your mighty troll brethren and the weak "
            \   "and pathetic elves. You scream your battle cry and "
            \   "smoosh the head of a fallen elf under your foot.",
            \   @dreamer )

Trigger: dream_for_zone

Response Type	script
Entities	Rooms
Parameters	zone1 [, zone2 [, ...] ]

    You can use this trigger type to register a zone dream. A zone dream is a
    dream that anyone in one of the zones specified in the parameters can
    receive when sleeping. The zone must be specified by its ID.

    
    Following is the current breakdown of dream probabilities for each dream
    type given that a mobile is to receive one:

        dream_for_world      50%
        dream_for_continent  20%
        dream_for_area       10%
        dream_for_zone       10%
        dream_for_room       10% 

    When a player is ready to dream these probabilities are used to order the
    dream categories. This ordering is then used to find an actual dream for
    the player. If a category contains no dreams then the engine moves on to
    the next category. For each potential dream the engine runs the dream
    script which can then determine if it the dream is applicable or not. If
    the dream is not applicable then the script can return 0 to inform the
    engine to try the next dream. If no dreams succeed for a category then
    again the engine moves on to the next category. In a given category all
    dreams have equal probability of running. If you wish to decrease the
    probability of your dream running, you can return 0 after doing a simple
    dice roll to accomodate the decreased odds. In contrast you cannot
    increase the probability that your dream will run. Because the engine
    requires a return value (no return value counts as success) you must place
    your dream script in a protected block.

        @dreamer - The player receiving the dream.

        Example:

            if( @dreamer->race != "troll" )
            {
                //
                // Only trolls can receive this dream.
                //
                return 0
            }
            endif

            #%dream(
            \   "You dream that you are on the front lines of a great "
            \   "battle between your mighty troll brethren and the weak "
            \   "and pathetic elves. You scream your battle cry and "
            \   "smoosh the head of a fallen elf under your foot.",
            \   @dreamer )

Trigger: fight_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	threshold

    Rooms:   on_tick, random_act
    Mobiles: on_tick, random_act, if_inroom, fight_act
    Objects: on_tick, random_act, if_inroom, fight_act

    Random events are evaluated every 6 seconds for rooms, mobiles, and
    objects. This is not true if it is the "on_tick" type. The actual
    evaluation is offset for each of these so that room, mobile, and object
    random events do not occur at the same time. When the random event is
    evaluated a 1d1000 dice is rolled and if it rolls under the value of the
    threshold then the random event fires. Only one random event per entity
    may fire on any given pass. Random trigger types are "random_act",
    "on_tick", "fight_act", and "if_inroom". The "on_tick" trigger is always
    given precedence since it may be used as a timing mechanism. The "on_tick"
    trigger will only be avaluated when the tick occurs. All others are
    evaluated in the order of their appearance in the list of triggers. The
    "fight_act" trigger can only fire when the mobile, or object owner is
    engaged in combat. When engaged in combat the "random_act" and "if_inroom"
    triggers cannot fire. If the dice roll fails then the next random event of
    the same type will need to roll under its threshold plus the failed
    threshold.  Thus as failures occur the likelihood of a later random event
    being fired increases. This is a big hack ass job and you are far better
    off to create one random script that handles the individual probabilities
    itself via if statements.

    Type: fight_act
    
        @n - the opponent of the script owner.

        @t - The script owner (if a mobile) or the owner of the object.

        @o - whatever is in the held equipment position.

        @x - pointer to whatever is in the wielded position or "nothing".

    Type: on_tick, random_act, if_inroom

        - No extra variables are set.

Trigger: if_inroom

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	threshold

    Rooms:   on_tick, random_act
    Mobiles: on_tick, random_act, if_inroom, fight_act
    Objects: on_tick, random_act, if_inroom, fight_act

    Random events are evaluated every 6 seconds for rooms, mobiles, and
    objects. This is not true if it is the "on_tick" type. The actual
    evaluation is offset for each of these so that room, mobile, and object
    random events do not occur at the same time. When the random event is
    evaluated a 1d1000 dice is rolled and if it rolls under the value of the
    threshold then the random event fires. Only one random event per entity
    may fire on any given pass. Random trigger types are "random_act",
    "on_tick", "fight_act", and "if_inroom". The "on_tick" trigger is always
    given precedence since it may be used as a timing mechanism. The "on_tick"
    trigger will only be avaluated when the tick occurs. All others are
    evaluated in the order of their appearance in the list of triggers. The
    "fight_act" trigger can only fire when the mobile, or object owner is
    engaged in combat. When engaged in combat the "random_act" and "if_inroom"
    triggers cannot fire. If the dice roll fails then the next random event of
    the same type will need to roll under its threshold plus the failed
    threshold.  Thus as failures occur the likelihood of a later random event
    being fired increases. This is a big hack ass job and you are far better
    off to create one random script that handles the individual probabilities
    itself via if statements.

    Type: fight_act
    
        @n - the opponent of the script owner.

        @t - The script owner (if a mobile) or the owner of the object.

        @o - whatever is in the held equipment position.

        @x - pointer to whatever is in the wielded position or "nothing".

    Type: on_tick, random_act, if_inroom

        - No extra variables are set.

Trigger: on_area_load

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	areaId1 areaId2 areaId3 ...

    This trigger will fire immediately after an area has been loaded or
    reloaded. This is irregardless of whether any of the area's zones are
    active. This can be used to synchronize any out of area zones with this
    area or to manage any scripts that need to be activated or re-activated
    due to an area having been reloaded (this was true for the headbutt
    revival and invulnerability scripts).

    @areaId - The ID of the area being loaded.

Trigger: on_eaten

Response Type	script
Entities	Objects
Parameters	-

    When this trigger is defined it will be fired immediately after the
    object has been eaten and any eat spells have been applied.

    @food   - The item being eaten.

    @eater  - The mobile doing the eating.

    Example:

    if( @eater->race == "Zombie" )
    {
        @eater->hitpoints += 5 + 1d15
    }
    endif

Trigger: on_entry

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	[roomId1 [, roomId2 [, roomId2 [, ...] ] ] ]

    This trigger will fire when a mobile enters the room. The only entities
    capable of catching this trigger are the mobile itself or any objects it
    is carrying or has equipped. If any of the optional roomIdX paramerters
    are set then the trigger will only fire if the mobile or object has
    entered a room matching one of the set IDs.

    @n - The mobile that entered the room.

    @o - The same as @i if the trigger owner is an object.

Trigger: on_exit

Response Type	script
Entities	Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile exits the room. The only entities
    capable of catching this trigger are the mobile itself or any objects it
    is carrying or has equipped.

    @n - The mobile that entered the room.

    @o - The same as @i if the trigger owner is an object.

Trigger: on_expire

Response Type	script
Entities	Objects
Parameters	-

    You can use this trigger to override the normal output associated with an
    expiring object. This is useful for affects implemented as objects which
    need to naturally expire and provide appropriate information to the owner
    when the expiry happens. This is similar to how the "fly" spell lets the
    mobile affected by the spell know when it has worn off. This feature was
    used for the continual light spell as show in the example that follows.

    - No extra variable are set.


    Example:

    if( !%isNull( @owner = %getOwner( @this ) ) )
    {
        %echoTo(
        \   "The light surrounding your body completely fades away.\n",
        \   @owner, allowSleeping )
    }
    endif

Trigger: on_hour_of_day

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	hour \| all

    If you want trigger an action or behaviour at a particular time of day
    then this is the trigger you need. The parameter lets you set a specific
    hour of the day at which your script should fire. The check for the
    trigger firing occurs at the major tick, and if the parameter you have set
    is either the current hour or "all" then your script will run.

    - No extra variables are set.

Trigger: on_immortal_goto_enter

Response Type	script
Entities	Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile uses the goto command. The
    trigger fires just after the mobile is moved to their target
    room. This allows builders and immortals to customize the default
    message output when a mobile jumps to another location via the
    goto command. The script must return 1 to indicate that the
    trigger handled the event; otherwise the default message will
    be used.

    @actor  - The mobile using the goto command.

    @viewer - The mobile viewing the entry.

    Example:

        %act( "A giant rock hand crashes through the ground from "
        \     "which $n steps into the room before the hand "
        \     "retreats back into the depths of the earth.",
        \     0, @actor, null, @viewer, victimOnly )

        return 1

Trigger: on_immortal_goto_exit

Response Type	script
Entities	Mobiles, Objects
Parameters	-

    This trigger will fire when a mobile uses the goto command. The
    trigger fires just before the mobile is moved from their current
    room. This allows builders and immortals to customize the default
    message output when a mobile jumps to another location via the
    goto command. The script must return 1 to indicate that the
    trigger handled the event; otherwise the default message will
    be used.

    @actor  - The mobile using the goto command.

    @viewer - The mobile viewing the exit.

    Example:

        %act( "A giant rock hand crashes through the ground and "
        \     "pulls $n below.",
        \     0, @actor, null, @viewer, victimOnly )

        return 1

Trigger: on_immortal_qsave

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire when a player uses the qsave command. It allows
    an immortal to override the default message when the player leaves the
    game by attaching this trigger to an item they wear.

    @actor - The player leaving the game.

    Example:

        %act( "A giant rock hand crashes through the ground and "
        \     "pulls $n below.",
        \     0, @actor, null, null, skipActor )

        return 1

Trigger: on_load

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger will fire when the room, mobile, or object is loaded into the
    game. This includes when a player enters the game since all of their
    inventory and equipment must be reloaded.

    - No extra variables are set.

Trigger: on_location_change

Response Type	script
Entities	Mobiles, Items
Parameters	-

    This trigger will fire when an item or mobile moves or is moved to
    a new location. This is a very low level trigger and the method in which
    the item or mobile is moved is not considered. One should be very
    careful when changing the location of the item or mobile within the
    handling script. The trigger will fire once the entity is in the new
    location.

    @n - The mobile that has changed location (if a mobile changed
         location)

    @o - The container object that has changed location (if an object
         changed location)

    @oldRoom - Pointer to the originating room if available.

    @newRoom - Pointer to the destination room.

Trigger: on_real_hour_of_day

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	hour \| all

    If you want trigger an action or behaviour at a particular time of day
    (real time of day) then this is the trigger you need. The parameter lets
    you set a specific hour of the day at which your script should fire. The
    check for the trigger firing occurs at the first major tick that fires in
    the new hour, and if the parameter you have set is either the current hour
    or "all" then your script will run. Remember this trigger fires for real
    time and real time is currently usually Eastern Standard Time.

    - No extra variables are set.

Trigger: on_tick

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	threshold

    Rooms:   on_tick, random_act
    Mobiles: on_tick, random_act, if_inroom, fight_act
    Objects: on_tick, random_act, if_inroom, fight_act

    Random events are evaluated every 6 seconds for rooms, mobiles, and
    objects. This is not true if it is the "on_tick" type. The actual
    evaluation is offset for each of these so that room, mobile, and object
    random events do not occur at the same time. When the random event is
    evaluated a 1d1000 dice is rolled and if it rolls under the value of the
    threshold then the random event fires. Only one random event per entity
    may fire on any given pass. Random trigger types are "random_act",
    "on_tick", "fight_act", and "if_inroom". The "on_tick" trigger is always
    given precedence since it may be used as a timing mechanism. The "on_tick"
    trigger will only be avaluated when the tick occurs. All others are
    evaluated in the order of their appearance in the list of triggers. The
    "fight_act" trigger can only fire when the mobile, or object owner is
    engaged in combat. When engaged in combat the "random_act" and "if_inroom"
    triggers cannot fire. If the dice roll fails then the next random event of
    the same type will need to roll under its threshold plus the failed
    threshold.  Thus as failures occur the likelihood of a later random event
    being fired increases. This is a big hack ass job and you are far better
    off to create one random script that handles the individual probabilities
    itself via if statements.

    Type: fight_act
    
        @n - the opponent of the script owner.

        @t - The script owner (if a mobile) or the owner of the object.

        @o - whatever is in the held equipment position.

        @x - pointer to whatever is in the wielded position or "nothing".

    Type: on_tick, random_act, if_inroom

        - No extra variables are set.

Trigger: on_weapon_strike

Response Type	script
Entities	Objects
Parameters	-

    This trigger will fire whenever a strike is attempted. In the case the
    weapon attempts more than one strike during the damage round then this
    will fire for every attempt.

    @n - The owner of the weapon owning the trigger.

    @t - The target of the strike or null if the target has died.

    @o - The weapon making the strike. The same as @i.

    @x - The amount of damage done by the strike, -1 if the strike missed,
         or 0 if a thrown weapon missed.

    Note: This trigger ONLY fires for the weapon making the strike. if
          you want the room or something in the room to trigger then you
          want to use catch_weapon_strike instead.

Trigger: on_zone_load

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	zoneId1 zoneId2 zoneId3 ...

    This trigger will fire when a zone is being loaded whose ID is in the
    parameter list. The script is invoked immediately after the zone has been
    cleared and so it preempts the zone commands themselves and any other
    reset logic. If you want something to occur after the zone commands have
    executed then you can add a 0 second wait to the script which will allow
    it to run almost immediately after the zone has been reloaded.

    @zoneId - The ID of the zone being loaded.

Trigger: on_zone_unload

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	zoneId1 zoneId2 zoneId3 ...

    This trigger will fire when a zone is being unloaded whose ID is in the
    parameter list. The script is invoked immediately beore the zone is
    cleared and so can work with the state of the zone as it was before being
    unloaded.

    @zoneId - The ID of the zone being unloaded.

Trigger: preempt_death_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	-

    This trigger fires when a mobile is just about to die and can be caught by
    the room in which they die or by any mobiles or objects present in the
    room.

        @n, @attacker   - The attacker, if any, that killed the mob.

        @t, @victim     - The mob that has died, just before he is purged and
                          before any catch_death_act is called.

        @x, @victimName - The name of the mobile that died.

        @deathType      - The manner of death occurring.

    Unlike the catch_death_act trigger this particular trigger allows for you
    to save the victim if your script is so inclined. To save the victim you
    MUST return the value 1. Anything else will assume the mobile was not
    saved (although any other preempt_death_act may still save the mobile. If
    your script does save the mobile then any other queued preempt_death_acts
    will not run. Even though you return 1 you will probably want to udpate
    the mobile's position and hitpoints. If the mobile is still in the "dead"
    position after returning 1, then the position will automatically be
    updated to mortally wounded.

    The type of death occuring can be determined by the value of @deathType.
    So far the following values exist:

        airLack   - this occurs when the mobile drowns

        damage    - this generally occurs in combat

        deathtrap - sucker hit a deathtrap

        fall      - this occurs when fly wear off

        gladiator - gladiator mode death

        noPenalty - no panalty death (noobs usually)

        pkill     - killed by another player

        rebirth   - player has enabled rebirth

        slay      - npcslay or one of the other slay commands

        sunlight  - this occurs when vampires get roasted in the sun

        waterLack - this occurs when a waterOnly mobile is out of water

Trigger: random_act

Response Type	script
Entities	Rooms, Mobiles, Objects
Parameters	threshold

    Rooms:   on_tick, random_act
    Mobiles: on_tick, random_act, if_inroom, fight_act
    Objects: on_tick, random_act, if_inroom, fight_act

    Random events are evaluated every 6 seconds for rooms, mobiles, and
    objects. This is not true if it is the "on_tick" type. The actual
    evaluation is offset for each of these so that room, mobile, and object
    random events do not occur at the same time. When the random event is
    evaluated a 1d1000 dice is rolled and if it rolls under the value of the
    threshold then the random event fires. Only one random event per entity
    may fire on any given pass. Random trigger types are "random_act",
    "on_tick", "fight_act", and "if_inroom". The "on_tick" trigger is always
    given precedence since it may be used as a timing mechanism. The "on_tick"
    trigger will only be avaluated when the tick occurs. All others are
    evaluated in the order of their appearance in the list of triggers. The
    "fight_act" trigger can only fire when the mobile, or object owner is
    engaged in combat. When engaged in combat the "random_act" and "if_inroom"
    triggers cannot fire. If the dice roll fails then the next random event of
    the same type will need to roll under its threshold plus the failed
    threshold.  Thus as failures occur the likelihood of a later random event
    being fired increases. This is a big hack ass job and you are far better
    off to create one random script that handles the individual probabilities
    itself via if statements.

    Type: fight_act
    
        @n - the opponent of the script owner.

        @t - The script owner (if a mobile) or the owner of the object.

        @o - whatever is in the held equipment position.

        @x - pointer to whatever is in the wielded position or "nothing".

    Type: on_tick, random_act, if_inroom

        - No extra variables are set.

Trigger: set_affect2

Response Type	special
Entities	Mobiles
Parameters	bitInteger

    Sets the bits in a mobile's second bitstream. This value of the parameter can
    either be an integer that represents the bits that are set or a bitstring
    of the form: b000111010101011

Trigger: set_skill

Response Type	special
Entities	Mobiles
Parameters	-

    Used to directly set the skill values of a mobile. Pairs of skill and
    amount learned are input. The skill may be defined by its ID or partial
    name. The two styles may intermix.

    Example:

    heal 99 harm 99 77 99 43 99 "lich touch" 99 fireball 99

Trigger: set_teach

Response Type	special
Entities	Mobiles
Parameters	-

    Used to set the skills a mob can teach. Either the ID of the skill or a
    partial name may be used. The two styles may be intermixed.

    Example:

    25 43 heal 78 "magic missile" harm fireball "lich touch"

Trigger: spec_proc

Response Type	special
Entities	Rooms, Mobiles, Objects
Parameters	procName

    Sets a special procedure for a room, mobile, or object. Any ONE of the
    following special procedures can be declared for the procName parameter:

    Room Special procedures:

        bank                - Makes the room capable of banking actions.
        corlathSlayer       - No idea.
        dump                - Items dropped in the room are purged.
        kingsHall           - No idea.
        movers              - Allows players to change their hometown.
        prayForItems        - No idea.
        recruiting_center   - Once a day high level players can recruit.
        recruitingCenter    - Alias for "recruiting_center".
        temple              - No idea.

    Mob Special Procedures:

        awayTeam            - No idea.
        bknight             - No idea.
        blackKnight         - Alias for "bknight".
        cretan              - Cretan guards do something via this.
        DoppleGanger        - No idea.
        fido                - Eat corpses but leave behind items.
        greedy              - Deprecated I think.
        guard               - No idea.
        janitor             - Go around purging stuff lying about.
        linkteacher         - Teach link skill.
        mayor               - No idea.
        pospriest           - No idea.
        puff                - No idea.
        receptionist        - Allow players to rent out.
        sheriff             - No idea.
        Skeeter             - No idea.
        snake               - No idea.
        sundhavenGuard      - Ask BadMood.
        sundhavenGuardian   - Ask Badmood.
        teacher             - Can teach skills, use with "set_teach".
        Terminator          - No idea.
        vulture             - Alias for "fido".

    Object Special Procedures:

        atm                 - ATM machine for small banking needs.
        badmoodMirror       - Portal mirror.
        board               - Can post messages on boards.
        chalice             - No idea.
        crashProofChest     - Contents survive crashes.
        fountain            - Can drink infinite water from fountains.
        incinerator         - Purges things put in it.
        magicFountain       - Like a fountain but VERY refreshing.
        magicTelescopeArea  - Object can be used to view players in the area.
        magicTelescopeWorld - Object can be used to view players in the world.
        magicTelescopeZone  - Object can be used to view players in the zone.
        mailbox             - Interface to MUDmail system.
        messageBoard        - Alias for "board".
        poster              - The greatest poster in Elkin.
        sundhavenPortal     - Another portal thingy.
        tankard             - No idea.
        teleportal          - Yet another portal thingy.
        vampireChalice      - Fill with blood for creating vampires.

Trigger: trigger_assignment

Response Type	special
Entities	Rooms, Mobiles, Objects
Parameters	-

    A special trigger type to facilitate mass assignment of existing triggers
    to an alternate entity than the one for which they are defined. For
    instance, a combat behaviour could be implemented on mob A and assigned to
    mob B, C, D, etc.

    Assignments are made as one assignment per line with the following
    structure:

        :: -> :

    Additionally, multiple assignments can be made in a single statement when
    the vnums are sequential:

        :: -> :-

    The following illustrates these as actual declarations:

        room:155000:arenaDeath -> room:155001-155199
        mob:100165:customCombat -> mob:172051
        mob:100165:customCombat -> mob:172057

    This is especially powerful since assignment declarations don't need to
    belong to either the source or target area. The assignment system is also
    area reload safe (regardless of which area is reloaded -- the assigner,
    the source, or the target).

Appendix C - Functions

Function: %actionDisown()

Aliases	%actionDisown( )
Parameters	-

    This allows the current action script (command or spell script) to be
    detached from the user's currently active command. This means the user
    will be able to issue another command, and that no abort script can be run
    for the script. This is useful for commands or spells that should have
    lasting script functionality.

Function: %actionIsRunning()

Aliases	%actionIsRunning( )
Parameters	-

    This allows a script to dermine if its owner already has a running action.
    This is useful to prevent issuing another action command that will abort a
    running command.

    Example:

        if( %actionIsRunning() )
        {
            return
        }
        endif

Function: %act()

Aliases	%act( )
Parameters	string @text, integer @hideInvis, character @actor, object @object, character @victim, string @type [, integer @roomId [, integer @canIgnore ] ]

    This function mirrors the MUD's internal act() function and provides the
    same functionality and benefits (namely for script purposes, script
    triggering via output). The following describes the parmaters:

    @text       - This is the text to output. It supports the embedded codes
                  supported by the internal act command (not described
                  here).

    @hideInvis  - If this is set to true (non zero) then the output will
                  not be displayed to characters in the room that cannot
                  see the @actor.

    @actor      - The character that is doing the action. This value may
                  be null.

    @object     - This defines the an object for the action. This value
                  may also be null.

    @victim     - This defines a possible target for the action. Once
                  again the value may be null.

    @type       - This determines the way the function should handle the
                  various parameters previously described and the
                  destination of the output. Possible values are:

                    skipActor   (send to everyone in room but @actor)
                    victimOnly  (send only to the @victim)
                    skipPair    (send to all in room but @actor and @victim)
                    actorOnly   (send to the @actor only)

    @roomId     - Set this to change the room in which the action output
                  should go. When this is not set it defaults to the current
                  room of the owner mobile, object, or room. If the owner
                  is not one of these things, then it defaults to the room
                  in which the script was invoked.

    @canIgnore  - Determines whether the action can be throttled for players
                  ignoring the person who issued the action.

    Example:
    --------------------------------------------------------------------------

    %act( "$n gooses you.", 1, @this, null, @target, toVictim );

See Also	%nAct(), Act Macros

Function: %affectCheckFlag()

Aliases	%affectCheckFlag( )
Parameters	object @affect, string @flag1 [, string @flag2 [, ... ] ]

    Returns 1 if all of the given flags (@flag1 to @flagX) are set for the
    given @affect object. If all of the given flags are not set then 0 is
    returned. The following flag names are supported:

        isPositiveBuff
        isNegativeBuff

    Example:
    --------------------------------------------------------------------------

    if( %affectCheckFlag( @affect, isNegativeBuff ) )
    {
        //
        // Eeeeek! Try and dispel/cure the affect.
        //
    }
    endif

Function: %affectGetAntidotes()

Aliases	%affectGetAntidotes( )
Parameters	object @affect

    Returns a list of possible antidotes for the given @affect object. This
    can be used to determine how to relieve the affect (useful if the affect
    is punitive).

    Example:
    --------------------------------------------------------------------------

    foreach( %affectGetAntidotes( @affect ) as @antidote )
    {
        if( @antidote == "dispel magic" )
        {
            cast dispel magic self
            break
        }
        elseif( @antidote == "remove poison" )
        {
            cast remove poison self
            break
        }
        elseif( @antidote == "remove curse" )
        {
            cast remove curse self
            break
        }
        elseif( @antidote == "cure blindness" )
        {
            cast cure blindness self
            break
        }
        endif
    }
    endforeach

Function: %affectGetOwner()

Aliases	%affectGetOwner( )
Parameters	object @affect

    Returns a text pointer to the owner (if one exists) of the given @affect.
    The owner of an affect is usually the caster. If there is no owner, or the
    given @affect is not valid then null is returned.

    Example:
    --------------------------------------------------------------------------

    //
    // Do fire damage to everyone in the room except the caster.
    //

    damage notchar %affectGetOwner( @self ) %(10 + 1d10) fire

Function: %affectGetSkillName()

Aliases	%affectGetSkillName( )
Parameters	object @affect

    Returns the name of the skill (if any) to which the @affect object is
    associated.  For instance a "disease" skill might implement an affect
    object.

    Example:
    --------------------------------------------------------------------------

    @text = ""
    foreach( %getAffectItems( @n ) as @affect )
    {
        @text .= "\n" %affectGetSkillName( @affect )
    }
    endforeach

    if( @text == "" )
    {
        %echoTo( "You are not affected by any skills.\n", @n )
    }
    else
    {
        @text .= "\n"
        %echoTo( "You are affected by the following skills:" @text, @n )
    }
    endif

Function: %affectSetOwner()

Aliases	%affectSetOwner( )
Parameters	object @affect, entity @owner

    Sets the @owner of the given @affect object. If the owner is successfully
    set the 1 is returned; otherwise 0 is returned.

    Example:
    --------------------------------------------------------------------------

    %setOwner( @affect, @caster )

Function: %affectSetSkillName()

Aliases	%affectSetSkillName( )
Parameters	object @affect, mixed @skill

    Sets the associated skill name for the target @affect object. The given
    @skill may either be the ID of a valid in-game skill, or the name of the
    skill. If the name is used, it does not necessarily have to exist in the
    game.  Support for non-existent skills is allowed since your scripts may
    have special purposes for the affect and thus require a unique name. If
    the skill name is successfully set then 1 is returned; otherwise 0 is
    returned.

    Example:
    --------------------------------------------------------------------------

    %affectSetSkillName( @affect, "deadly vapours" )

Function: %areaGetItems()

Aliases	%areaGetItems( ), %areaGetItems( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the objects
    currently in the given area. The list is indexed by consecutive integers
    counting from 1 onward. If no parameter is used, then the area in which
    the script owner resides is used as default. The entity may be one of the
    following: an explicit room number; a pointer to a room, character, or
    object; a keyword for a mob, or object. If the entity is valid then the
    area for the room in which it resides will be searched.

Function: %areaGetMobs()

Aliases	%areaGetMobs( ), %areaGetMobs( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the
    characters currently in the given area. The list is indexed by consecutive
    integers counting from 1 onward. If no parameter is used, then the area in
    which the script owner resides is used as default. The entity may be one
    of the following: an explicit room number; a pointer to a room, character,
    or object; a keyword for a mob, or object. If the entity is valid then the
    area for the room in which it resides will be searched.

Function: %areaGetNpcs()

Aliases	%areaGetNpcs( )
Parameters	[mixed @entity]

    This function works just like %areaGetMobs() with the exception that it
    only returns the NPC (Non-Playing Character) matches.

Function: %areaGetPcs()

Aliases	%areaGetPcs( )
Parameters	[mixed @entity]

    This function works just like %areaGetMobs() with the exception that it
    only returns the PC (Playing Character) matches.

Function: %areaGetStat()

Aliases	%areaGetStat( )
Parameters	mixed @area, string @statName

    Returns the value for a given statName that belongs to the area defined by
    @area.  The value of @area may either be the load name of an area or the
    ID of the area. The value of @statName must be one of the following:

        id          - the ID of the area
        name        - the load name of the area (eg. midway)
        niceName    - the nice name of the area (eg. The Midway)
        continent   - The continent to which the area belongs
        comments    - The area's description
        creator     - The creator of the area
        minRange    - Lower bound of vnum range for area
        maxRange    - Upper bound of vnum range for area
        status      - State area's status (new, unstable, stable)

    Example:

    %echoTo( "Name:      " %areaGetStat( elkin, niceName ), @n )
    %echoTo( "Creator:   " %areaGetStat( elkin, creator ), @n )
    %echoTo( "Continent: " %areaGetStat( elkin, continent ), @n )

Function: %arrayGetHead()

Aliases	%arrayGetHead( )
Parameters	array @data

    Returns the first value in the passed array.

Function: %arrayGetKeyForValue()

Aliases	%arrayGetKeyForValue( )
Parameters	array @array, mixed @value

    Returns the associated key for the first value in @array that matches
    @value. If no such value is found then null is returned.

See Also	%arrayHasValue( )

Function: %arrayGetKeys()

Aliases	%arrayGetKeys( )
Parameters	array @data

    Returns an associative array of all of the keys of the given array data.
    The key values will be indexed in consecutive integers counting up from 1
    in the order that the indexes were added to the array with the resolution
    operator "->". Retrieving the keys in this manner makes it possible to
    loop through the entries of the array until such time as a foreach loop is
    designed :)

    Example:

    @keys = %arrayGetKeys( @myValues )

    for( @i = 1; @i <= %arrayGetSize( @keys ); @i += 1 )
    {
        %echo( "Key: " @keys->@i )
    }
    endfor

Function: %arrayGetSize()

Aliases	%arrayGetSize( )
Parameters	array @data

    Returns the number of elements in the passed array.

Function: %arrayGetTail()

Aliases	%arrayGetTail( )
Parameters	array @data

    Returns the last value in the passed array.

Function: %arrayGetValues()

Aliases	%arrayGetValues( )
Parameters	array @data

    Returns an associative array of all of the values of the given array data.
    The values will be indexed in consecutive integers counting up from 1 in
    the order that the indexes of the values were added to the array with the
    resolution operator "->".

    Example:

    @values = %arrayGetValues( @room->mobiles )

    for( @i = 1; @i <= %arrayGetSize( @values ); @i += 1 )
    {
        %echo( "Value: " @values->@i )
    }
    endfor

Function: %arrayHasValue()

Aliases	%arrayHasValue( )
Parameters	array @array, mixed @value

    Returns 1 if the given @array contains a value equivalent to the given
    @value; otherwise 0 is returned.

    Example:

    if( %arrayHasValue( @memberList, %getName( @n ) )
    {
        talk @n Welcome! You may enter.
    }

Function: %arrayImplode()

Aliases	%arrayImplode()
Parameters	array @array [, string @separator]

    This function will join together the values of @array with @separator
    being joined between each value. If @separator is not defined then the
    values will be joined together without any separator.

    Example:

        @data = %array( one, two, three )
        %echo( %arrayImplode( @data, ", " ) )

    Output:

        one, two, three

See Also	%stringExplode()

Function: %arrayMergeValues()

Aliases	%arrayMergeValues( )
Parameters	array @array1, array @array2 [, array @array3 [, ...]]

    This function takes 2 or more arrays and returns a single unified array
    with all of the values re-indexed from 1 onward. The order of the merge is
    the same as the order of appearance in the parameter list.

    Example:

        @foo->1 = "Foo 1"
        @foo->2 = "Foo 2"
        @foo->3 = "Foo 3"

        @fee->1 = "Fee 1"
        @fee->2 = "Fee 2"
        @fee->3 = "Fee 3"

        @merged = %arrayMergeValues( @foo, @fee )

        foreach( @merged as @key => @value )
        {
            echo Key: @key, Value: @value
        }
        endforeach

    Output:

        Key: 1, Value: Foo 1
        Key: 2, Value: Foo 2
        Key: 3, Value: Foo 3
        Key: 4, Value: Fee 1
        Key: 5, Value: Fee 2
        Key: 6, Value: Fee 3

Function: %arrayShuffle()

Aliases	%arrayShuffle( )
Parameters	array @anArray

    This function takes an array and shuffles the order of the values and
    returns the randomly ordered array with all of the values re-indexed from
    1 onward.

    Example:

        @foo->1 = "Foo 1"
        @foo->2 = "Foo 2"
        @foo->3 = "Foo 3"
        @foo->4 = "Foo 4"
        @foo->5 = "Foo 5"

        @shuffled = %arrayShuffle( @foo )

        foreach( @shuffled as @key => @value )
        {
            echo Key: @key, Value: @value
        }
        endforeach

    Output:

        Key: 1, Value: Foo 4
        Key: 2, Value: Foo 2
        Key: 3, Value: Foo 3
        Key: 4, Value: Foo 5
        Key: 5, Value: Foo 1

Function: %array()

Aliases	%array( )
Parameters	-

    Returns an empty associative array data type.

Function: %arrayUnset()

Aliases	%arrayUnset( )
Parameters	array @target, string @key

    Removes the array association with the given key. This means the key and
    value are fully deleted from the associative array.

Function: %arrayValuesToKeys()

Aliases	%arrayValuesToKeys( )
Parameters	array @array, [, array @array2 [, array @array3 [, ... ] ] ]

    Returns a new array for which the keys are the values of all the given
    arrays.

    Example:

        @foo = %array( one, two, three, four )
        %printValue( @foo, @self )

        @fee = %array( four, five, six, seven )
        %printValue( @fee, @self )

        @new = %arrayValuesToKeys( @foo, @fee )
        %printValue( @new, @self )

    Output:

        [foo] => (array)
        (
            [1] => (string)[one]
            [2] => (string)[two]
            [3] => (string)[three]
            [4] => (string)[four]
        )

        [fee] => (array)
        (
            [1] => (string)[four]
            [2] => (string)[five]
            [3] => (string)[six]
            [4] => (string)[seven]
        )

        [new] => (array)
        (
            [one] => (string)[one]
            [two] => (string)[two]
            [three] => (string)[three]
            [four] => (string)[four]
            [five] => (string)[five]
            [six] => (string)[six]
            [seven] => (string)[seven]
        )

Function: %asArray()

Aliases	%asArray( )
Parameters	mixed @value

    If the given value is not an array then an empty array will be returned,
    otherwise a copy of the array is returned.

Function: %asInt()

Aliases	%asInt( ), %asInteger( )
Parameters	mixed @data

    Returns the result of converting the parameter to an Integer. Null is
    returned as 0. Strings are returned as their integer interpretation.
    Floats are truncated and lists are converted to the number of members they
    contain.

Function: %asNull()

Aliases	%asNull( )
Parameters	mixed @value

    Returns null. This function is mostly available for completeness.

Function: %asString()

Aliases	%asString( )
Parameters	mixed @value

    Returns the given value converted to a string. If the value is an array
    the the string will contain the word HASH.

Function: %buffGetByLabel()

Aliases	%buffGetByLabel( )
Parameters	entity @entity, string @label

    This function can be used to retrieve a specific buff pointer from an
    object or mobile @entity via a defined label. If the @label parameter is
    empty then a pointer to the first unlabeled buff will be returned.

    Example:

        //
        // Presumably a buff with the label "powerCharge" was defined for
        // the object via the web editor (alternatively it could have been
        // assigned via the ->label resolution on a buff pointer.
        //

        if( %isEquippedItem( %getOwner( @this ), @this ) )
        {
            @timer = %getPlayerVar( @this, "powerChargeTimer" )
            @timer -= 1

            @buff = %buffGetByLabel( @this, "powerCharge" )

            if( @timer < 10 )
            {
                @buff->modifier = 10
            }
            elseif( @timer < 1 )
            {
                @buff->modifier = 0
                @timer = 40
            }

            %setPlayerVar( @this, "powerChargeTimer", @timer )
        }
        endif

Function: %calculate()

Aliases	%calculate( ), %calc( )
Parameters	mixed @lOperand, string @operator, mixed @rOperand

    Historical calculation function in use by many of the old scripts. This
    command is deprecated since it isn't nearly as functional as using the
    eval function %( ) to evaluate any logical expression. Traditionally the
    function took a left operand, an operator (+, -, *, /, %), and a right
    operand and then returned the result of applying operator to the right and
    left operands in INTEGER arithmetic.

    DEPRECATED - use the eval function %() for calculations within commands
                 and just do calculations if within a logic expression like
                 if, elseif, or while.

Function: %canAttack()

Aliases	%canAttack( )
Parameters	character @aggressor, character @victim

    Returns 1 if the aggressor can attack the victim and 0 otherwise. This
    function takes into consideration player killer status, immortal status,
    pets, charms, champion mode and any other considerations normally adhered
    to by the game. The agressor and victim may be a character pointer or
    keyword.

    Example:

        if( @n != @r && %canAttack( @n, @r ) )
        {
            silentforce @n hit @r
        }
        endif

Function: %canSee()

Aliases	%canSee( )
Parameters	mobile @actor [, mixed @target]

    Returns 1 if the @actor can see the @target. The target entity may be an
    object or character pointer or keyword. This differs from %canTarget()
    such that this will return 0 for hidden mobiles while %canTarget() will
    return 1 if the @actor can sense life. If the target is not defined then
    it defaults to the current room.

Function: %canTake()

Aliases	%canTake( )
Parameters	object @entity

    Returns 1 if the object can be picked up, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %canTarget()

Aliases	%canTarget( )
Parameters	mobile @actor, mixed @target

    Returns 1 if the @actor can target the @target. The target entity may be
    an object or character pointer or keyword. This function is different from
    %canSee() such that %canSee() will return false for a hidden mobile and
    this will return true if the @actor can sense life.

Function: %canWear()

Aliases	%canWear( )
Parameters	@mobile, @item [, @location]

    Returns 1 if the @mobile can wear the @item on the given @location.  The
    @location parameter is optional in which case the function just tests to
    see if the mobile can wear the item somewhere. The @mobile and @item
    parameters should be pointers to a mobile and item respectively. If the
    @location parameter is used then it should be one of the following
    location names:

        light               arms
        lFinger             shield
        leftFinger          about
        left finger         waist
        rFinger             lWrist
        rightFinger         leftWrist
        right finger        left wrist
        neck1               rWrist
        neck 1              rightWrist
        neck2               right wrist
        neck 2              wield
        body                wielded
        head                wielding
        legs                held
        feet                hold
        hands               holding

    Example:

        if( %canWear( @actor, @item, "head" ) )
        {
            %move( @item, @actor, "head" );
        }
        else
        {
            %echoTo( "You can't wear it on your head!", @actor )

            if( !%canWear( @actor, @item ) )
            {
                %echoTo( "You can't wear it anywhere!", @actor )
            }
            endif
        }
        endif

Function: %clone()

Aliases	%clone( )
Parameters	mixed @entity

    Clones the given entity and returns a pointer to it. Currently only items
    and rooms can be cloned.

    Items:

        If the script owner is a mobile then the clone will be placed in their
        inventory, otherwise it will be placed in the same room as the script
        owner (or @roomId). You can feel free to move it wherever you want via
        the returned pointer.

    Example:

        @clone = %clone( @o )      // Clone whatever @o is.
        %move( @clone, 115611 )    // Move to Elkin fountain room.

    Rooms:

        Due to the nature of rooms being unique, when you clone a room you
        create a duplicate room in almost every way. However, the room's ID
        will be assigned from the available pool of free assingment room IDs.
        Additionally, only triggers that have labels will be cloned for the
        room. Cloned triggers are facilitated through the trigger assignment
        engine, which means that a reload of the area for the master room will
        update the triggers for the clone-- this will kill any running scripts
        and so you should be sure to re-generate any necessary scripts if this
        is an issue for your room (see the on_area_load trigger).

    Example:

        @shelterRoomId = 123456

        @clone = %clone( @shelterRoomId )

        @exit = %load( exit, down, @shelterRoomId, @clone->id )
        @exit->flags->isNoDirection = true

        %echo( "You have finished building your shelter." );
        %echo( "You can now 'enter' it." );

Function: %combatClear()

Aliases	%combatClear( )
Parameters	character @entity

    Halts combat for the character entity and for all opponents of the
    character entity.

    Example:

    %combatClear( @n )

Function: %combatStart()

Aliases	%combatStart( ), %setFighting( )
Parameters	character @actor, character @target

    Initiates combat between the actor and the target. This is useful to
    bypass evade, or to change fight configuration on the fly. Character
    entity for both the actor and the target, may be a character pointer or
    keyword.

    Example:

    //
    // Implements a custom rescue system where @a rescues @b from @c.
    //
    %combatStop( @c )
    talk @b Don't worry buddy, I'll save you!!!
    %combatStart( @a, @c )
    %combatStart( @c, @a )

Function: %combatStop()

Aliases	%combatStop( ), %stopFighting( )
Parameters	character @entity

    Halts combat for the character entity. Note that while the character stops
    fighting, any opponents, do not stop fighting the character.

    Example:

    %combatStop( @n )

Function: %containerGetStat()

Aliases	%containerGetStat( )
Parameters	object @entity, string @statName

    Returns the value for a given @statName that belongs to the @entity
    container object.  The @entity may be an object pointer or object keyword. 
    The @statName may be any one of the following:

        maxCapacity
        usedCapacity
        canClose
        isCloseable
        isClosed
        hasLock
        isLocked
        isPickproof
        isFreeStorage
        isInverted
        keys
        pickResilience
        forceResilience

    Example:

    if( !%containerGetStat( @o, isClosed ) )
    {
        %echoTo( "It's not even closed!", @n )
    }
    endif

Function: %containerSetStat()

Aliases	%containerGetStat( )
Parameters	object @entity, string @statName

    Returns the value for a given @statName that belongs to the @entity
    container object.  The @entity may be an object pointer or object keyword. 
    The @statName may be any one of the following:

        maxCapacity
        canClose
        isCloseable
        isClosed
        hasLock
        isLocked
        isPickproof
        isFreeStorage
        isInverted
        keys
        pickResilience
        forceResilience

    Example:

    %echoTo( "You manage to pick the lock with the twig.", @n )
    %containerSetStat( @chest, isLocked, 0 )

Function: %contextContinue()

Aliases	%contextContinue( )
Parameters	integer @contextId

    Causes the context defined by @contextId to continue processing. This has
    no effect on running contexts, but essentially "wakes up" a waiting
    (paused, sleeping) context.  If the context is valid then this function
    returns 1; othrwise 0 is returned.

Function: %contextDisown()

Aliases	%contextDisown( )
Parameters	[integer @contextId]

    Disowns the current context, or if @contextId is set then disowns the
    associated context (if valid). If an associated context is disowned
    then 1 is returned; otherwise 0 is returned. A context that is disowned
    may live beyond the existence of the entity that originally owned it.
    As such it can live forever.

Function: %contextGetId()

Aliases	%contextGetId( )
Parameters	-

    Returns an integer that uniquely defines the current running context and
    which can be used in context manipulation functions.

Function: %contextGetVar()

Aliases	%contextGetVar( )
Parameters	string @key [, integer @contextId]

    Returns the variable value the given key defined by @key for the current
    context. If @contextId is defined then the variable value for the
    associated context (if valid) is returned. If the variable does not exist
    or the context is invalid then null is returned.

Function: %contextGetVars()

Aliases	%contextGetVars( )
Parameters	[integer @contextId]

    Returns all the variables defined for the current context. If @contextId
    is defined then the variables defined for the associated context (if
    valid) are returned. If no such context exists then null is returned.

Function: %contextIsValid()

Aliases	%contextIsValid( )
Parameters	integer @contextId

    Returns 1 if the context associated with the given @contextId is valid
    (running or sleeping); otherwise returns 0.

Function: %contextKill()

Aliases	%contextKill( )
Parameters	[integer @contextId]

    Kills the current context, or if @contextId is set then kills the
    associated context (if valid). If an associated context is killed then 1
    is returned; otherwise 0 is returned. Note that the context is not killed
    immediately, but rather is queued for killing when next it runs (the
    context will not be able to run any more code).

Function: %contextPause()

Aliases	%contextPause( )
Parameters	string @timeString [, integer @contextId]

    Pauses the current context by the time defined by @timeString. The value
    of @timeString follows the same syntax as that for the wait keyword. If
    @contextId is defined and is valid, then the associated context is paused
    for the given time. If a context is paused then this function returns 1;
    othrwise 0 is returned.

    Example:
    --------------------------------------------------------------------------

    %contextPause( 20 secs, 1002384723 )

Function: %contextSetVar()

Aliases	%contextSetVar( )
Parameters	string @key, mixed @value [, integer @contextId]

    Sets a variable in the current context with name @key and value defined by
    @value. If the @contextId parameter is set then the variable is set in the
    associated context (if valid). If the value is successfully set then
    @value is returned, otherwise null is returned.

Function: %corpseGetId()

Aliases	%corpseGetId( ), %corpseGetId( )
Parameters	object @entity

    Returns the vnum of the mobile to whom the corpse belongs.

Function: %corpseGetName()

Aliases	%corpseGetName( ), %corpseGetName( )
Parameters	object @entity

    Returns the name of the mobile or player to whom the corpse belongs.

Function: %corpseGetStat()

Aliases	%corpseGetStat( )
Parameters	object @corpse, string @statName

    Returns the value for a given @statName that belongs to the @corpse object.
    The @corpse may be an object pointer or object keyword. The @statName may be
    any one of the following stat names:

        id
        name
        isPc
        isNpc
        isDecapitated

    Example:

    if( %corpseGetStat( @corpse, isPc ) )
    {
        get all @corpse
        grin
    }
    endif

Function: %corpseIsDecapitated()

Aliases	%corpseIsDecapitated( ), %corpseIsDecapitated( )
Parameters	object @entity

    Returns 1 if the object is a corpse and has had its head removed. Returns
    0 if the object is a corpse and has not had its head removed. Returns null
    in any other case.

Function: %corpseIsNpc()

Aliases	%corpseIsNpc( ), %corpseIsNpc( )
Parameters	object @entity

    Returns 1 if the object is a corpse and belongs to an NPC. Returns 0 if
    the object is a corpse and does not belong to an NPC. Returns null in any
    other case.

Function: %corpseIsPc()

Aliases	%corpseIsPc( ), isCorpsePc( )
Parameters	object @entity

    Returns 1 if the object is a corpse and belongs to a PC. Returns 0 if the
    object is a corpse and does not belong to a PC. Returns null in any other
    case.

Function: %corpseSetStat()

Aliases	%corpseSetStat( )
Parameters	object @entity, string @statName, mixed @newValue

    Sets the value for a given @statName that belongs to the @corpse object to @newValue.  The
    @corpse may be an object pointer or object keyword. The @statName may be any
    one of the following stat IDs:

        id
        name
        isPc
        isNpc
        isDecapitated

    Example:

    //
    // This makes it seem like the mob running the script has created a zombie
    // abomination from the corpse... assuming that we have an abomination
    // mobile with vnum 999. Any corpse will do since we directly set the vnum
    // of the corpse which tricks the monster zombie spell into thinking that
    // was the mob that died.
    //

    %corpseSetStat( @corpse, id, 999 )
    %corpseSetStat( @corpse, isNpc, 1 )

    cast 'monster zombie' @corpse

Function: %damage()

Aliases	%damage( )
Parameters	mixed @source, entity @victim, integer @damage [, array @damageFlags [, mixed @attackType [, array @messages]]]

    This function is used to have the @source entity inflict damage upon the
    @victim. The @source may be null. The @victim may be either an object
    or a character pointer. The @damageFlags array is used to determine the
    type of damage which can then be blocked, increased, or decreased
    depending on the target's immunity, susceptibility, and resistance
    respectively. The following flags are recognized:

        hit                 electric                plus 2
        bludgeon            negative energy         plus 3
        pierce              positive energy         plus 4
        slash               mental                  weapon
        fire                deadly poison           light weapon
        cold                non-magical             physical
        acid                magical                 non-physical
        poison              plus 1                  all

    Additionally the following special damage flags also exist:

        skipStartFight  - do not initiate combat when damage is dealt
        skipMessages    - do not output damage messages as is usual
        skipMinimum     - deal damage to object regardless of threshold

    The @attackType is used to determine the source of the damage (not to be
    confused with @source which is more specifically the initiator). This can
    be used to auotmatically produce any special affects normally associated
    with the attack type (such as damage messages). The following attack types
    are recognized.

        acid                drain life              positive energy
        bite                electric                slash
        bludgeon            fire                    smash
        breath              hit                     sting
        claw                mental                  suffering
        cold                negative energy         whip
        crush               pierce                  skill 
        deadly poison       poison                  spell 

    Finally the @messages parameter is used to override any damage messages
    that may or may not be associated with the given @attackType. This
    parameter requires that the following fields be set (as they would be in
    the web editor for a skill or spell).

        godAttacker         hitAttacker
        godVictim           hitVictim
        godObservers        hitObservers
        deathAttacker       missAttacker
        deathVictim         missVictim
        deathObservers      missObservers

    Now for a big fat example. Even though some of this function's parameters
    are optional, this example will use them anyways, just so you can see how
    they are set.

    Example:
    --------------------------------------------------------------------------

    @damageFlags->1 = magic
    @damageFlags->2 = acid
    @damageFlags->3 = "negative energy"

    @messages->godAttacker =
    \   "$N wonders who the hell you think you are!"

    @messages->godVictim =
    \   "$n tries to dissolve you with acid. What a joker!"

    @messages->godObservers =
    \   "$n, in an almost laughable attempt to hurt $N, casts acid splash."

    @messages->deathAttacker =
    \   "$N's skin begins to bubble and then slowly melts off $S bones."

    @messages->deathVictim =
    \   "Your skin begins to boil then melts off your bones. OUCH! You die."

    @messages->deathObservers =
    \   "$N's skin begins to bubble and then slowly melts off $S bones."

    @messages->hitAttacker =
    \   "The acid begins to boil $N's skin and dissolve $S armor."

    @messages->hitVictim =
    \   "$n's acid burns your skin and dissolves your armor."

    @messages->hitObservers =
    \   "$N's armor and skin boil from $n's acid splash."

    @messages->missAttacker =
    \   "You miss! The acid begins to boil the ground behind $N."

    @messages->missVictim =
    \   "$n misses you with $s acid splash. Whew!"

    @messages->missObservers =
    \   "$N nimbly evades $n's acid splash which boils the ground behind $M."

    @damage = 10 + 1d20

    %damage(
    \   @actor, @target, @damage, @damageFlags,
    \   "spell acid splash", @messages )

Function: %deathtrap()

Aliases	%deathtrap( )
Parameters	character @entity, string @description, boolean @preemptable = 1

    Immediately kills the target @entity as though they had just walked into a
    deathtrap. This means the standard 4 random items are purged form the
    player (2 from inventory and 2 from equipment). Additionally, the player
    is removed form the game and sent the entrance menu. They will re-enter
    the game as though they had died. No experience penalty occurs.

    The @description parameter may be set to a brief description of how or why
    the player was deathtrapped and this will appear in the log message for
    the death.

    The @preemptable parameter defaults to the value 1, and determines if a
    preemptDeath triggers should be checked (if this is set to 0 then the
    target cannot be saved by preemptDeath triggers.

    Example:

        %nact( "You chop $N's head off with one fell swing of your sword.",
        \      0, @self, null, @victim, actorOnly )

        %nact( "$n chops $N's head off with one fell swing of $s sword.",
        \      0, @self, null, @victim, skipPair )

        %nact( "$n chops your head off with one fell swing of $s sword.",
        \      0, @self, null, @victim, victimOnly )

        if( !%deathtrap( @victim, "super sword swing" ) )
        {
            tell @victim Saved this time, but I'll get you yet!
        }
        endif

Function: %deleteEntityVar()

Aliases	%deleteEntityVar( )
Parameters	mixed @entity, string @varName

    Deletes the variable with name varName that is within the variable context
    of the entity and returns 1. If the variable does not exist then a 0 is
    returned. The entity may be a pointer to a room, mob, or object. It may
    also be a keyword of a mob or object. If the entity is not valid then the
    value is retrieved from the global variable context.

    Example:

    %deleteEntityVar( @n, questStage )

Function: %deletePlayerVar()

Aliases	%deletePlayerVar( )
Parameters	mixed @entity, string @varName

    Deletes the variable that is within the saved player file persistence
    context of the entity. Since rooms cannot be saved to player files and
    there can only ever be one instance of a room with a given vnum, this
    function has identical functionality to the %setSavedVar() function when
    applied to a room. The entity may be a pointer to a room, mob, or object.
    It may also be a keyword of a mob or object or the vnum of a room.  If the
    variable is not found then null is returned. These variables are saved in
    the player's data file and are restored whenever the player re-enters the
    game.

    Example:

    %deletePlayerVar( @n, lastEnteredSkurvash )

Function: %deleteSavedVar()

Aliases	%deleteSavedVar( )
Parameters	mixed @entity, string @varName [, @entityType ]

    Deletes the value of the variable that is within the persistent variable
    context of the entity. The entity may be a pointer to a room, mob, or
    object. It may also be the vnum of a room or a keyword of a mob or object.
    A query is made to remove the variable from the MySQL database everytime
    this function is called. For this reason it is advisable to not call the
    function unless you really want to delete the variable. It is important to
    know that there can only be one shared saved variable for all mobs, or all
    objects, or all rooms with the same vnum.

    The @entity parameter may also be set to the vnum of a mobile or object. 
    If this is done then the optional @entityType parameter must be set to
    "mobile" or "object" respectively.

    Example:

    %deleteSavedVar( 10005, towerOwner )

Function: %deleteVar()

Aliases	%deleteVar( )
Parameters	string @varName

    Deletes the variable with name varName that has been assigned to the
    script owner and returns 1. If the variable does not exist then a 0 is
    returned.

    Example:

    %deleteVar( lastVisitor )

Function: %doZoneActivate()

Aliases	%doZoneActivate( )
Parameters	integer @zoneId

    While all areas are loaded when the MUD server boots up, the mobiles and
    objects that populate the rooms of the zones are only loaded when a non
    NPC player enters an unloaded zone. This is a good idea since it reduces
    the necessary resources needed for the game to run, especially when an
    area isn't being used. Unfortunately there are time when you need a zone
    to be loaded because you have a creature or object which must interact
    with occupants of another zone. For these case you can directly activate
    the zone with this function.

    Example:

    %doZoneActivate( 4600 )
    at 4637 buy recall inga

Function: %dream()

Aliases	%dream( )
Parameters	string @text, array @targets

    This function will output the given text to everyone listed in the targets
    array that is sleeping.

    @text       - This denotes the text to output to everyone in the room.

    @targets    - A target mobile pointer OR an array whose values define the
                  target mobiles to receive the text.

    Example:
    --------------------------------------------------------------------------

    %dream( "You float gently through a grassy field.", @dreamer )

Function: %drinkGetStat()

Aliases	%drinkGetStat( )
Parameters	object @entity, string @statName

    Returns the value for a given statName that belongs to the drink object.
    The entity may be an object pointer or object keyword. The statName may be
    any one of the following stat IDs:

        poisoned        affectDrunk
        name            affectHunger
        colour          affectThirst
        maxCapacity
        usedCapacity

    Example:

    @usedCapacity = %drinkGetStat( @o, usedCapacity )

Function: %drinkSetStat()

Aliases	%drinkSetStat( )
Parameters	object @entity, string @statName, mixed @value

    Sets the value for a given statName that belongs to the drink object.  The
    entity may be an object pointer or object keyword. The statName may be any
    one of the following stat IDs:

        poisoned        affectDrunk
        name            affectHunger
        colour          affectThirst
        maxCapacity
        usedCapacity

    Example:

    %drinkSetStat( @o, usedCapacity, %drinkGetStat( @o, maxCapacity ) )

Function: %echo()

Aliases	%echo( )
Parameters	string @text [, integer @roomId [, string @flag1 [, string @flag2 [, ...]]]]

    This function will output the given text to everyone in the room that is
    not sleeping or otherwise incapacitated. The following parameters modify
    the behaviour of this function.

    @text       - This denotes the text to output to everyone in the room.

    @roomId     - This determines the room in which to output the @text. If
                  this parameter is not defined then it defaults to the room
                  in which the script was invoked.

    @flag1..X   - The rest of the parameters denote boolean flags for setting
                  extra functionility. The mere inclusion of the flag enables
                  it, and by default it is disabled. The following flag names
                  are recognized:

                    allowSleeping - enables text to be sent to sleeping
                                    players in the room.

                    skipOwner     - prevents text from going to the owner of
                                    the script (@this).

                    noFormat      - prevents the content from being formatted
                                    with word-wrapping.

    Example:
    --------------------------------------------------------------------------

    %echo( @N " lets loose a thunderous fart.\n", null, skipOwner )

Function: %echoTo()

Aliases	%echoTo( )
Parameters	string @text, array @targets [, string @flag1 [, string @flag2 [, ...]]]]

    This function will output the given text to everyone listed in the targets
    array that is not sleeping or otherwise incapacitated. The following
    parameters modify the behaviour of this function.

    @text       - This denotes the text to output to everyone in the room.

    @targets    - A target mobile pointer OR an array whose values define the
                  target mobiles to receive the text.

    @flag1..X   - The rest of the parameters denote boolean flags for setting
                  extra functionility. The mere inclusion of the flag enables
                  it, and by default it is disabled. The following flag names
                  are recognized:

                    allowSleeping - enables text to be sent to sleeping
                                    players in the room.

                    skipOwner     - prevents text from going to the owner of
                                    the script (@this).

                    noFormat      - prevents the content from being formatted
                                    with word-wrapping.

    Example:
    --------------------------------------------------------------------------

    %echoTo( "You hear a faint shuffling sound.\n", %roomGetMobs() )

Function: %eqPos()

Aliases	%eqPos( )
Parameters	character @entity, object @entity

    Checks that the character is wearing the given object and returns the wear
    position ID if found. Returns -1 if not found. Character entity may be a
    character pointer or keyword. The object entity may be an object pointer,
    keyword, or vnum. Following is a list of IDs and the position they
    represent:

        1 light             10 hands
        2 left finger       11 arms
        3 right finger      12 shield
        4 neck 1            13 about body
        5 neck 2            14 waist
        6 body              15 left wrist
        7 head              16 right wrist
        8 legs              17 wielded
        9 feet              18 held

    Example:

    if( %eqPos( @n, idol_of_iskar ) == 1 )
    {
        talk @n You have done well adventurer!
        wait 2 secs
        talk @n Are you ready for the next stage of your quest?
    }
    endif

Function: %equipmentLocationInfo()

Aliases	%equipmentLocationInfo( ), %eqLocationInfo()
Parameters	@id

    Returns an array of info about the requested equipment location. The value
    of @id may be either the numerical ID or the tagName of the equipment
    location. The following fields are returned in the array:

        id              - the numerical ID of the equipment location
        rank            - the display order of the location (eq command)
        isMulti         - set to 1 if the location spans multiple body parts
        tagName         - the unique textual name of the location
        name            - the name of the equipment location
        nameSingular    - the singular name of the equipment location
        namePlural      - the plural name of the equipment location

    The following details the information provided when the function is used
    to retrieve information about the legs equipment location:

        id              - 8
        rank            - 11
        isMulti         - 1
        tagName         - legs
        name            - legs
        nameSingular    - leg
        namePlural      - legs

    If you are going to store the location beyond a reboot (by using saved or
    player vars) then it is advisable to store the tagName value since this is
    the only value guaranteed not to change in the future.

    Example:

        @info = %eqLocationInfo( @locationId )

Function: %equipment()

Aliases	%equipment( )
Parameters	character @entity, integer @wearID

    Checks if the character has anything equipped in the given wearID position
    of the equipped inventory. If something is found then 1 is returned,
    otherwise 0 is returned. Character entity may be a character pointer or
    keyword. Following is a list of IDs and the position they represent:

        1 - light               10 - hands
        2 - left finger         11 - arms
        3 - right finger        12 - shield
        4 - neck 1              13 - about body
        5 - neck 2              14 - waist
        6 - body                15 - left wrist
        7 - head                16 - right wrist
        8 - legs                17 - wielded
        9 - feet                18 - held

    Example:

    if( %equipped( @n, 16 ) )
    {
        %purge( %getEquippedItem( @n, 16 ) )
    }
    endif

Function: %eregi()

Aliases	%eregi()
Parameters	string @pattern, string @text

    Returns a 1 if the text is matched by the regular expression defined by
    pattern, otherwise returns 0. This function differs from its counterpart,
    %ereg(), in that the matching is performed in a case-insensitive fashion.
    This function uses the POSIX extended regular expression syntax which is
    beyond the scope of this document and is left to the reader. The internet
    should yield many valuable resources about this topic.

    Example:

        if( %eregi( ".*troll.*", %getRace( @n ) )
        {
            echoto char AH-HAH! A stinky troll!
        }
        endif

Function: %ereg()

Aliases	%ereg()
Parameters	string @pattern, string @text

    Returns a 1 if the text is matched by the regular expression defined by
    pattern, otherwise returns 0. This function uses the POSIX extended
    regular expression syntax which is beyond the scope of this document and
    is left to the reader. The internet should yield many valuable resources
    about this topic.

    Example:

        if( !%ereg( "^[[:space:]]*[[:digit:]]+[[:space:]]*$", @arguments ) )
        {
            echoto char @n You may only input a number!
            return
        }
        endif

Function: %evades()

Aliases	%evades( )
Parameters	character @evader, character @attacker [, integer @modifier [, integer @showMessage [, string @attackMessage ]]]

    Returns 1 if the @evader manages to evade an attack by @attacker;
    otherwise returns 0. The @modifier should be set to a percentage by which
    to modify the actualy evade check. For instance if you want the @evader to
    be twice as likely to evade then you can set @modifier to 200. The
    @showMessage parameter determines whether a message should be sent to the
    combatants and any observers in the room if the @evader successfully
    evades. The @attackMessage can be used to customize the evade message when
    the @evader successfully evades.

    Example:
    --------------------------------------------------------------------------

    if( %evades( @target, @actor, 100, 1, "attempt to slit $s throat" ) )
    {
        return
    }
    endif


    Output (on successful evade):
    --------------------------------------------------------------------------

    Target nimbly evades Actor's attempt to slit his throat!

Function: %exitGetStat()

Aliases	%exitGetStat( )
Parameters	exit @entity, string @statName

    Returns the value for a given statName that belongs to the exit. The
    entity must be an exit pointer. The statName may be any one of the
    following stat IDs:

        uniqueid        - unique ID of exit
        room            - pointer to room in which exit exists
        roomid          - ID of room in which exit exists
        keywords        - keywords of exit
        description     - description of exit when looked at
        destination     - pointer to destination room
        destinationid   - ID of destination room
        otherSide       - Returns exit pointer for other side exit
        pickResilience  - resilience of lock to being picked
        forceResilience - resilience of lock to being forced
        issecret        - is exit secret (hidden when bumped into)?
        isnodirection   - special exit that requires entry (Elkin fountain)
        hasdoor         - does the exit have a door?
        isclosed        - is the door closed?
        haslock         - does the door have a lock?
        islocked        - is the door locked?
        ispickproof     - is the lock on the door pickproof?

    The null value is returned when the stat makes no senses. For example,
    testing if a door is locked for an exit that has no door will return null.

    Example:

        if( %exitGetStat( %roomGetExits( @roomNumber )->east, isClosed ) )
        {
            unlock door east
        }
        endif

    The otherSide field is great for retrieving the exit that travels in the
    opposite direction from the given exit. The other side exit is important
    when you are setting flags on an exit that should also be set for the
    other side such as if the door is open or not.

    Example:

        @exit = %roomGetExits( @roomNumber )->east;
        @otherSide = %exitGetStat( @exit, otherSide );

        %exitSetStat( @exit, islocked, 1 )
        %exitSetStat( @otherSide, islocked, 1 )

Function: %exitSetStat()

Aliases	%exitSetStat( )
Parameters	exit @entity, string @statName, mixed @newValue

    Sets the value for a given statName that belongs to the exit. The entity
    must be an exit pointer. The statName may be any one of the following stat
    IDs:

        keywords        - keywords of exit
        description     - description of exit when looked at
        destination     - pointer or vnum of destination room
        pickResilience  - resilience of lock to being picked
        forceResilience - resilience of lock to being forced
        issecret        - is exit secret (hidden when bumped into)?
        isnodirection   - special exit that requires entry (Elkin fountain)
        hasdoor         - does the exit have a door?
        isclosed        - is the door closed?
        haslock         - does the door have a lock?
        islocked        - is the door locked?
        ispickproof     - is the lock on the door pickproof?

    Ateempting to set stats that make no sense will cause the exit to maintain
    integrity by possibly setting or unsetting other stats. For example,
    setting an exit to locked when there is no door will cause it to have a
    door created with a lock, th door will then be closed and locked. likewise
    removing a lock will unset the locked status and pickproof status.

    Example:

        //
        // Lock the north exit.
        //
        %exitSetStat( %roomGetExits( @roomNumber )->north, isLocked, 1 )

        //
        // Now unlock the north exit.
        //
        %exitSetStat( %roomGetExits( @roomNumber )->north, isLocked, 0 )

Function: %fastCommand()

Aliases	%do( )
Parameters	mixed @sourcePointer, string @command [, array @options]

    Runs the given @command string through the MUD's interpreter as though the
    @sourcePointer entity had issued it directly -- with one difference -- the
    @command is run through the system immediately, and will not undergo any
    of the usual command related lag. Unlike %runCommand() the primary purpose
    of this function is to enable other command features within the given
    script without any overhead. For instance in the "backstab" command, this
    function is used to invoke the "hide" command for the person who issued
    the "backstab".  The options array allows you to specify some flags for
    how the command is treated by the MUD's ineterpreter. The following flags
    may be set.

    noSpecials
        - Prevent command from being caught by special procedures. The default
          for this option is to ALLOW specials procedures.

    ignoreOverrides
        - Prevent trigger from catching command and running a BlobbieScript.
          The default for this option is to NOT IGNORE overrides. If you are
          actually handling the command but still want the normal
          functionality to run then set this to true, if however you are not
          handling the command and want other entities to have a chance at it,
          then either omit this or set it to false.

    skipCommOut
        - Ensures the actor doesn't say "Yes, sir!". The default value is to
          allow it to be said. I don't really recall why this flag exists but
          I'm sure it has a purpose.

    skipAbort
        - If the command is being run in the midst of another command that is
          an action command (hunt, cast, kick, etc.) then this will prevent
          the running command from being aborted.

    delayed
        - This is the same as the delayAppend flag.

    delayedPrepend
        - Instead of running the command immediately it is placed at the
          beginning of the @actor's command queue and so will run as soon as
          the current command completes.

    delayedAppend
        - Instead of running the command immediately it is placed in the
          @actor's command queue and run when all previous commands have
          completed.

    forceLook
        - Some trigger's force the @actor to view the contents of a room, when
          this happen the user will not double view the room because
          internally this state is tracked. However, at times this is not the
          desired affect, for instance your @actor might have just been
          teleported by your script and so you want to ensure he views the
          contents of his new destination room. In such cases you will set
          this flag.

    Example:

        %do( @n, "hide" )

    Example:

        @opts->forceLook = true
        %do( @n, "look", @opts )

Function: %filterActionWords()

Aliases	%filterActionWords( )
Parameters	mixed @words

    Takes a string or array parameter. If the parameter is a string then a
    string will be returned with filler (non-action) words removed. If the
    parameter is an array then an array will be returned with the filler word
    values removed and re-indexed from 1 onward. The following are considered
    filler words:

        a, an, in, into, from, with,
        within, the, on, onto, at, to

    Example:

        @input = "put the apple in the bucket"
        @input = %filterActionWords( @input )

        echo Action Input: @input

    Output:

        Action Input: put apple bucket


    Example:

        @input = "put the apple in the bucket"
        @input = %stringToWords( @input )
        @input = %filterActionWords( @input )

        foreach( @input as @key => @value )
        {
            echo Key: @key, Value: @value
        }
        endforeach

    Output:

        Key: 1, Value: put
        Key: 2, Value: apple
        Key: 3, Value: bucket

Function: %filterGroup()

Aliases	%filterGroup( )
Parameters	array @characters, character @control

    This function returns an array consisting of all the characters found in
    the given characters array that are members of the group defined by the
    given control character entity. In contrast to the %partyGetMobs()
    function, this can be used to get only the group members in the current
    room, zone, or whatever. All entities in the characters array should be
    pointers and will more than likely have been retrieved from one of the
    %xxxGetMobs() functions (where xxx is room, zone, area, etc). The array of
    entities returned will be indexed from 1 onward.

    Example:

        @members = %filterGroup( %roomGetMobs(), @n )

Function: %filterKeyword()

Aliases	%filterKeyword( )
Parameters	array @entities, string @keyword

    An extremely powerful function for filtering targets from the given
    entities parameter. Depending on the keyword there are several possible
    outcomes which mimic the MUD's own internal routines for targetting. The
    keyword may use any of the following formats:

        keyword     - explicit keyword, all matches returned
        x.keyword   - indexed keyword, 0 or 1 matches returned
        x*keyword   - limitted keyword, at most x matches returned
        keyw/       - substring match, all matches returned
        x.keyw/     - indexed substring match, 0 or 1 matches returned
        x*keyw/     - limitted substring keyword, at most x matches returned

    Example:

        @targets = %arrayMergeValues( %roomGetItems(), %roomGetMobs() )

        //
        // Example 1, explicit match
        //
        @realTargets = %filterKeyword( @targets, "troll" )

        //
        // Example 2, substring match.
        //
        @realTargets = %filterKeyword( @targets, "trol/" )

        //
        // Example 3, indexed match.
        //
        @realTargets = %filterKeyword( @targets, "3.troll" )

        //
        // Example 4, limitted sibstring match.
        //
        @realTargets = %filterKeyword( @targets, "3*trol/" )

        //
        // Example 5, Quan's light bulb.
        //
        @realTargets = %filterKeyword( @targets, @argument )

Function: %filterNotGroup()

Aliases	%filterNotGroup( )
Parameters	array @characters, character @control

    This function returns an array consisting of all the characters found in
    the given characters array that are NOT members of the group defined by
    the given control character entity. This can be used to get only the
    non-group members in the current room, zone, or whatever. All entities in
    the characters array should be pointers and will more than likely have
    been retrieved from one of the %xxxGetMobs() functions (where xxx is room,
    zone, area, etc). The array of entities returned will be indexed from 1
    onward.

    Example:

        @notMembers = %filterNotGroup( %roomGetMobs(), @n )

Function: %filterNpcs()

Aliases	%filterNpcs( )
Parameters	array @characters

    This function returns an array consisting of all NPC character entities
    found within the characters array. All entities in the characters array
    should be pointers and will more than likely have been retrieved from one
    of the %xxxGetMobs() functions (where xxx is room, zone, area, etc). The
    array of entities returned will be indexed from 1 onward.

    Example:

        @targets = %roomGetMobs()
        @npcs = %filterNpcs( @targets )

Function: %filterOut()

Aliases	%filterOut( )
Parameters	array @anArray, mixed @value1 [, mixed @value2 [, ... ] ]

    A useful function that returns an array consisting of all the elements in
    @anArray with the given @value1, @value2, ..., @valueX values removed.

    Example:

        @targets = %filterOut( %roomGetMobs(), @n, @t )
        %echoTo( "The sounds of fighting disturb your thoughts.", @targets )

Function: %filterPcs()

Aliases	%filterPcs( )
Parameters	array @characters

    This function returns an array consisting of all PC character entities
    found within the characters array. All entities in the characters array
    should be pointers and will more than likely have been retrieved from one
    of the %xxxGetMobs() functions (where xxx is room, zone, area, etc). The
    array of entities returned will be indexed from 1 onward.

    Example:

        @targets = %roomGetMobs()
        @pcs = %filterPcs( @targets )

Function: %filterVisible()

Aliases	%filterVisible( )
Parameters	array @entities, character entity

    This function returns an array consisting of all entities within the
    entities array that are visible to the character entity. All entities in
    the entities array should be pointers and will more than likely have been
    retrieved from one of the %xxxGetItems() or %xxxGetMobs() functions (where
    xxx is room, zone, area, etc). The character entity; however, may be a
    character keyword or pointer. The array of entities returned will be
    indexed from 1 onward.

    Example:

        @targets = %arrayMergeValues( %roomGetItems(), %roomGetMobs() )
        @visible = %filterVisible( @targets, @n )

Function: %float()

Aliases	%float( )
Parameters	-

    Returns a new float with value 0.0. This function is mostly available for
    completeness.

Function: %follow()

Aliases	%follow( )
Parameters	mobile @leader, mobile @follower [, mobile @follower2 [, ...]]

    Makes all of the given @followers follow the @leader. You can specifiy as
    many targets as you want to follow the @leader. You may use a text pointer
    or keyword for each of the parameters.

    Example:

        %follow(
        \   khazad_ivan, khazad_torm, khazad_darth, khazad_dorin,
        \   khazad_tarfin, khazad_kallak )

Function: %gainExperience()

Aliases	%gainExperience( ), %gainExp( )
Parameters	mobile @target, integer @experience, string @description

    Since the worlds of Carnage now uses a stat gain system that is based on
    dice rolls when experience is gained, it is no longer useful to just
    increase a player's experience when experience is the reward. Instead the
    gained experience must be passed through the system's internal system to
    see if the player should receive any stat gains. The %gainExperience()
    function was designed for exactly this purpose.

    NOTE: whenever this function is used a log is made of what script called
          it, who received the experience, and how much. DO NOT ABUSE!

    The @description parameter should contain a short description describing
    the reason for the experience gain.

    Example:

    %gainExperience( @n, 5000 + 1d1000, "Completed cheese quest" )

Function: %getAffectItems()

Aliases	%getAffectItems( )
Parameters	character @target

    Returns a list of affect objects in the given @target's affect objects
    inventory. Entries are indexed from 1 onward.

Function: %getBounded()

Aliases	%getBounded( )
Parameters	float @lowerBound, float @value, float @upperBound

    Returns the result of bounding @value between the given @lowerBound and
    @upperBound. In otherwords if @value is less then @lowerBound then
    @lowerBound is returned. If @value is greater than @upperBound then
    @upperBound is returned. Otherwise @value is returned. If you wish to
    constrain only one boundary then you may set one of the boundary values to
    null thus making it open ended. if you set both the @lowerBound and the
    @upperBound to null then you are an idiot because @value will always be
    returned and you have wasted CPU time.

    Example:

    @n->hitpoints = %getBounded( 1, 10d20, @n->maxHitpoints )

Function: %getClass()

Aliases	%class( ), %getClass( )
Parameters	character @entity

    Returns the sub-class of the target @entity. If the @entity has no
    sub-class then null is returned. The @entity may be a character pointer or
    keyword.

Function: %getContainer()

Aliases	%getContainer( )
Parameters	object @entity

    Returns an object pointer to the immediate container (if any) that is
    holding the passed object. The entity may be an object pointer or object
    keyword.

    Example:

    @container = %getContainer( @this )

Function: %getContents()

Aliases	%getContents( )
Parameters	mixed @target

    Returns the contents of the target as an array of object pointers. If the
    target resolves to a room then the contents of the room, both objects and
    mobiles, are returned in an associative array indexed from 1 counting
    onward. If the target is a mobile then the contents of the mobile, both
    inventory and equipment, are returned.  If the target is a container
    object then the contents of the container are returned. The target may be
    a room pointer, room number, mobile pointer, mobile keyword, object
    pointer, or object keyword.

Function: %getContinent()

Aliases	%getContinent( )
Parameters	entity @target

    Returns the name of the continent in which the target entity exists. The
    following two values are currently possible:

        Carnage
        Cythera

    If the @target is not a valid entity then null is returned.

    Example:
    --------------------------------------------------------------------------

    if( %getContinent( @n ) != Carnage )
    {
        talk @n Hello stranger! From what lands do you hail?
    }
    endif

Function: %getEntityVar()

Aliases	%getEntityVar( )
Parameters	mixed @entity, string @varName

    Retrieves the value of the variable with name varName that is within the
    variable context of the entity. The entity may be a pointer to a room,
    mob, or object. It may also be a keyword of a mob or object. If the
    entity is not valid then the value is retrieved from the global variable
    context.

    Example:

    @questStage = %getEntityVar( @n, questStage )

Function: %getEquipment()

Aliases	%getEquipment( )
Parameters	mixed @target

    Returns the equipment list of the target mobile as an array of object
    pointers. The target may be a mobile pointer or keyword.

Function: %getEquippedItem()

Aliases	%getEquippedItem( )
Parameters	character @entity, string @location

    Returns a pointer to the object worn in the position described by the wear
    name. If no object is equipped in that position then null is returned. If
    the given equipment location is invalid, then -1 is returned.  The
    character entity may be a mobile pointer or a mobile keyword. See the help
    for %isEquipmentLocation() for valid @location values.

    Example:

        @item = %getEquippedItem( @actor, @location );

        if( %isValid( @item ) )
        {
            //
            // move the item to their inventory.
            //
            %move( @item, @actor )
        }
        else
        if( @item === -1 )
        {
            %echoTo( "Please provide a valid equipment location.", @actor )
        }
        else
        {
            %echoTo( "You're not wearing anything there!", @actor )
        }
        endif

Function: %getFollowers()

Aliases	%getFollowers( )
Parameters	character @entity

    Returns an associative array of all the creatures currently following the
    target character entity. Character entity may be a character pointer or
    keyword.

    Example:

    headbutt %arrayShuffle( %getFollowers( @this ) )->1

Function: %getGenderPossess()

Aliases	%getSexPossess( ), %getSexPossess( ), %getGenderPossess( ), %getgenderPosess( )
Parameters	character @entity

    Returns the gender possession word for the given character. The gender
    possession word will be one of "his", "hers", or "its". The character
    entity may be a character pointer or a keyword of a character.

Function: %getGender()

Aliases	%getSex( ), %getSex( ), %getGender( ), %getGender( )
Parameters	character @entity [, string @type]

    Returns the pronoun string for the target character entity of the
    requested type. If no type is chosen or if the type is invalid, then the
    gender type will be returned.  The character entity may be a character
    pointer or a keyword of a character.

    Types

    default:        male        female      neuter
    subjective:     he          she         it
    objective:      him         her         it
    possessive:     his         her         its

    Examples:

    echoto notc @n @N swings %getSex( @n, possessive ) sword wildly.

    echoto char @t @N is a powerful %getSex( @n ) %getRace( @n ).

    echoto char @n You give it to %getSex( %getOwner( @o ), objective ).

Function: %getGenderTarget()

Aliases	%getSexTarget( ), %getSexTarget( ), %getGenderTarget( ), %getGenderTarget( )
Parameters	character @entity

    Returns the gender target word for the given character. The gender target
    word will be one of "him", "her", or "it". The character entity may be a
    character pointer or a keyword of a character.

Function: %getGuildId()

Aliases	%guild( ), %getGuildId( )
Parameters	character @entity

    Returns the ID of a guild for which the character is a member. If the
    character is not a member of any guild then returns 0. Character entity
    may be a character pointer or keyword. The ID returned will correspond to
    one of the following guilds:

        1   - The Order of the Silver Banner
        2   - The Order of the Black Circle
        3   - The Legion of Doom
        4   - Raw Power
        5   - The Scarlet Underground
        126 - The Walking Targets

    Example:

    if( %getGuildId( @n ) != 4 )
    {
        talk @n You do not belong here!!
        yell HELP!! We are under attack by @N
        kill @n
    }
    endif

Function: %getHomeId()

Aliases	%getHomeId( ), %homeCity( ), %homeTown( )
Parameters	character @entity

    Returns the ID of the given character's home location. Character entity
    may be a character pointer or keyword. The ID returned will correspond to
    one of the following hometowns:

        1 - Elkin
        2 - Wikam
        3 - Verona
        4 - Grand Marnier
        5 - Shayol Ghul
        6 - Latvia
        7 - Crete
        8 - Cimmura

Function: %getHomeTownRoomId()

Aliases	%getHomeTownRoomId( )
Parameters	character @entity

    Returns the starting room ID for the hometown of the given @target
    mobile. The starting room ID is the ID for the same room that a player
    is transfered to by the "word of recall" spell. If the @target is not
    valid then null is returned.

    Example:
    --------------------------------------------------------------------------

    talk @n Thank you for return the amulet. Please accept this reward.
    give @reward @n

    wait 3 secs
    talk @n Allow me to save you the journey home and transport you there
    \       with my magic.

    %move( @n, %getHomeTownRoomId( @n ) )
    %runCommand( @n, "look" )

Function: %getHuntDirection()

Aliases	%getHuntDirection( )
Parameters	character @entity

    If the character entity is not hunting then this will return null. If the
    character is currently hunting, and has a path to their target, then one
    of this will either return the direction to travel (in all lower-case), or
    in the case of a non-standard direction, then the keyword to use to enter
    the location. Character entity may be a character pointer or keyword.

    Example:

    @directions->north = 1
    @directions->south = 1
    @directions->east  = 1
    @directions->west  = 1
    @directions->up    = 1
    @directions->down  = 1

    @direction = %getHuntDirection( @n )
    if( !%isNull( @direction ) )
    {
        //
        // These fail if exit has a closed door.
        //
        if( @directions->@direction )
        {
            @direction
        }
        else
        {
            enter @direction
        }
        endif
    }
    endif

Function: %getHuntPrey()

Aliases	%getHuntPrey( )
Parameters	mobile @hunter

    Return the prey of the specified @hunter. If the @hunter is hunting
    another mobile then the return value will be a pointer to the prey. 
    Alternatively if the mobile is hunting via a call to "walktoroom" then the
    ID of the room will be returned. If the @hunter is not hunting anything
    then null will be returned.

    Example:

    if( if( %getHuntPrey( @n ) == @self )
    {
        talk @n I hear you've been looking for me. Now that you've
        \       found me, prepare to die!

        cast soul strike @n
    }
    endif

Function: %getId()

Aliases	%getId( ), %getId( ),
Parameters	mixed @entity

    Returns the vnum of the entity. The entity may be a room pointer,
    character pointer, object pointer or a keyword of a character or object.

Function: %getInventory()

Aliases	%getInventory( )
Parameters	mixed @target

    Returns the inventory of the target mobile as an array of object pointers.
    The target may be a mobile pointer or keyword.

Function: %getItemPointer()

Aliases	%getItemPointer( ), %getItemPtr( )
Parameters	mixed @entity

    Returns an object pointer for the given entity parameter or null on
    failure. If @entity is set to an object pointer then it is checked for
    validity and returned if valid. Alternatively if @entity is set to an
    integer value then the first object in the game having a vnum of that value
    is returned. Finally if @entity contains one or more keywords then a
    pointer to the first object matching the keywords is returned.

    It is strongly advised that if you use the keyword approach that you use a
    keyword that is very unlikely to be used by any other object. For instance
    setting @entity to "fountain" will more than likely cause your script to
    break at some point since the most recently loaded object to have
    "fountain" as a keyword will be returned (and many areas have fountains).

    Examples:
    
        @item = %getItemPointer( @keyword )

        @item = %getItemPointer( 135192 )

        @item = %getItemPointer( "pendant_of_the_moon_god" )

Function: %getItemsWithId()

Aliases	%getItemsWithId( )
Parameters	integer @id1 [, integer @id2 [, integer @id3 [, ...]]]

    Returns an array of entity pointers to all objects in the world with any
    one of the given IDs.

    Example:

    foreach( %getItemsWithId( 37820 ) as @crystal )
    {
        if( %getOwner( @crystal ) == @n )
        {
            return
        }
        endif
    }
    endforeach

    @crystal = %load( object, 37820, @this )
    give @crystal @n

Function: %getLanguageId()

Aliases	%getLanguageId( )
Parameters	mixed @target

    Returns the language ID for the given @target. If @target is a mobile then
    the return value will be the ID of the language currently used by the
    mobile. Alternatively, if the @target is a language name then the ID of
    the language associated with the given name will be returned.

    The following language names are currently possible:

        common              goblin
        centaur             halfling
        dwarven             orcish
        elven               reptilian
        fairy               trollish
        gnomish


    Example:
    --------------------------------------------------------------------------

    if( %getLanguageId( @n ) != %getLanguageId( @i ) )
    {
        emote looks at you blankly.
    }
    endif

Function: %getLanguage()

Aliases	%getLanguage( )
Parameters	mixed @target

    Returns the language name for the given @target. If @target is a mobile
    then the return value will be the name of the language currently used by
    the mobile. Alternatively, if the @target is a number then the name of the
    language associated with the given numerical ID will be returned.

    The following language names are currently possible:

        common              goblin
        centaur             halfling
        dwarven             orcish
        elven               reptilian
        fairy               trollish
        gnomish


    Example:
    --------------------------------------------------------------------------

    if( %getLanguage( @n ) != "trollish" )
    {
        speak common

        talk @n You would be wise to speak the language of the trolls when
        \       you are about these parts.

        speak trollish
    }
    endif

Function: %getLeader()

Aliases	%leader( ), %getLeader( )
Parameters	character @entity [, integer @defaultSelf]

    If the character is currently following someone then a pointer to the
    leader will be returned. Otherwise null is returned. Character entity may
    be a character pointer or keyword. If the optional @defaultSelf parameter
    is set to a non zero value then if no leader is found the
    @entity itself will be returned.

    Example:

        if( %getLeader( @n ) )
        {
            talk @n Take me to your leader!
        }
        endif

    Example:

        cast soul strike %getLeader( @n, 1 )

Function: %getLevel()

Aliases	%level( ), %getLevel( )
Parameters	character @entity

    Returns the the level of the the character. Character entity may be a
    character pointer or keyword.

Function: %getLoadCount()

Aliases	%getLoadCount( )
Parameters	[string @entityType,] mixed @entity

    Returns the total number of the given entity currently in the game. If
    @entityType is provided then the entity is matched to its type. The value
    of @entity may be one or more keywords, an id, or a pointer.

    If the @entityType is not provided and @entity is not a pointer, then the
    matching may be ambiguous between items and mobiles. In such cases the
    mobile is given preference.

    NOTE: %npcGetLoadCount() and %itemGetLoadCount() are much better functions.

Function: %getMaxIndex()

Aliases	%getMaxIndex( )
Parameters	mixed @value1 [, mixed @value2 [, mixed @value3 [, ...]]]

    If there is only one value given and it is an associative array, then this
    function will return the key for the maximum value found within that
    array. Otherwise the index of the maximum value found in the list of
    parameters is returned.  The index will be the entry count of the
    parameter as counted from 1 onward.

Function: %getMax()

Aliases	%getMax( )
Parameters	mixed @value1 [, mixed @value2 [, mixed @value3 [, ...]]]

    If there is only one value given and it is an associative array, then this
    function will return the maximum value found within that array. Otherwise
    the maximum value found in the list of parameters is returned.

Function: %getMinIndex()

Aliases	%getMinIndex( )
Parameters	mixed @value1 [, mixed @value2 [, mixed @value3 [, ...]]]

    If there is only one value given and it is an associative array, then this
    function will return the key for the minimum value found within that
    array. Otherwise the index of the minimum value found in the list of
    parameters is returned.  The index will be the entry count of the
    parameter as counted from 1 onward.

Function: %getMin()

Aliases	%getMin( )
Parameters	mixed @value1 [, mixed @value2 [, mixed @value3 [, ...]]]

    If there is only one value given and it is an associative array, then this
    function will return the minimum value found within that array. Otherwise
    the minimum value found in the list of parameters is returned.

Function: %getMobPointer()

Aliases	%getMobPointer( ), %getMobPtr( )
Parameters	mixed @entity

    Returns a mobile pointer for the given entity parameter or null on
    failure. If @entity is set to a mobile pointer then it is checked for
    validity and returned if valid. Alternatively if @entity is set to an
    integer value then the first NPC mobile in the game having a vnum of that
    value is returned. Finally if @entity contains one or more keywords then a
    pointer to the first mobile (PC or NPC) matching the keywords is returned.

    It is strongly advised that if you use the keyword approach that you use a
    keyword that is very unlikely to be used by any other mobile. For instance
    setting @entity to "thief" will more than likely cause your script to
    break at some point since the most recently loaded mobile to have "thief"
    as a keyword will be returned.

    The %getNpcPointer() and %getPcPointer() functions are better alternatives
    to this function since generally you don't want an arbitrary pointer than
    can be either a PC or NPC.

    Examples:
    
        @mob = %getMobPointer( @keyword )

        @mob = %getMobPointer( 101090 )

        @mob = %getMobPointer( "greedy_the_giant" )

Function: %getMobsWithId()

Aliases	%getMobsWithId( )
Parameters	integer @id1 [, integer @id2 [, integer @id3 [, ...]]]

    Returns an array of entity pointers to all mobiles in the world with any
    one of the given IDs.

    Example:

    foreach( %getMobsWithId( 37820 ) as @gremlin )
    {
        %purge( @gremlin )
    }
    endforeach

Function: %getName()

Aliases	%getName( ), %getName( )
Parameters	mixed @entity

    Returns the name of the room, character, or object. If the entity is a
    room then the name will be returned unchanged. If the entity is a
    character or object then the name will be returned with any leading "a",
    "an", and "the" trimmed. The entity may be a room vnum, room pointer,
    character pointer, object pointer, or a keyword for a character or object.

Function: %getNpcPointer()

Aliases	%getNpcPointer( ), %getNpcPtr( )
Parameters	mixed @entity

    Returns an NPC mobile pointer for the given entity parameter or null on
    failure. If @entity is set to an NPC mobile pointer then it is checked for
    validity and returned if valid. Alternatively if @entity is set to an
    integer value then the first mobile in the game having a vnum of that
    value is returned. Finally if @entity contains one or more keywords then a
    pointer to the first mobile matching the keywords is returned.

    It is strongly advised that if you use the keyword approach that you use a
    keyword that is very unlikely to be used by any other mobile. For instance
    setting @entity to "thief" will more than likely cause your script to
    break at some point since the most recently loaded mobile to have "thief"
    as a keyword will be returned.

    Examples:
    
        @npc = %getNpcPointer( @keyword )

        @npc = %getNpcPointer( 101090 )

        @npc = %getNpcPointer( "greedy_the_giant" )

Function: %getObjTypeId()

Aliases	%objType( ), %objectType( ), %getObjTypeId( ), %getObjectTypeId( )
Parameters	object @entity

    Returns the ID of ther type of the given object. The entity may be an
    object pointer or a keyword for an object. The ID returned will correspond
    to one of the following object types:

        1  - light          12 - other
        2  - scroll         13 - trash
        3  - wand           14 - trap
        4  - staff          15 - container
        5  - weapon         16 - note
        6  - rod            17 - drink
        7  - missile        18 - key
        8  - treasure       19 - food
        9  - armor          20 - money
        10 - potion         21 - pen
        11 - worn           22 - boat

Function: %getOpponent()

Aliases	%getOpponent( ), %fighting( ), %fight( )
Parameters	character @entity

    Returns a pointer to the opponent of the given character otherwise returns
    "nobody" if the character is not fighting.  Character entity may be a
    character pointer or keyword.

    Example:

    if( %getLevel( %getOpponent( @n ) ) > %getLevel( @n ) )
    {
        silentforce @n scream
    }
    endif

Function: %getOpponents()

Aliases	%getOpponents( )
Parameters	character @entity

    Returns an associative array of all the creatures currently attacking the
    target character entity. This is in contrast to the %getOpponent( )
    function because the %getOpponent( ) function returns the creature that
    the character is attacking.  Character entity may be a character pointer
    or keyword.

    Example:

    kick %arrayShuffle( %getOpponents( @this ) )->1

Function: %getOrderId()

Aliases	%getOrderId( ), %getOrderId( ), %getOrderId( ), %getOrderId( )
Parameters	character @entity

    Given any number of the same vnum character in the room of the script
    owner, this will return the numerical order of that character. The number
    returned can be used in regular MUD commands to target that character
    (i.e. 1.troll, 2.troll, ...). The entity may be a character pointer or a
    keyword for a character-- this function is kinda dumb, best to just use
    pointers since they always reference the correct target.

Function: %getOwner()

Aliases	%getOwner( ), %getOwner( )
Parameters	object @entity

    Returns a character pointer to the owner character (if any) of the given
    object. The entity may be an object pointer or object keyword.

Function: %getPcPointer()

Aliases	%getPcPointer( ), %getPcPtr( )
Parameters	mixed @entity

    Returns a PC mobile pointer for the given entity parameter or null on
    failure. If @entity is set to a PC mobile pointer then it is checked for
    validity and returned if valid. Alternatively if @entity contains a
    keyword (players can't have more than one) then a pointer to the first PC
    mobile matching the keyword is returned.

    Unlike %getNpcPointer() and %getMobPointer() this function is safe to use
    with a keyword since the match is completely unambiguous. Additionally
    unlike the other pointer functions this function does an exact match on
    the keyword and will not return a partial match.

    Examples:
    
        @pc = %getPcPointer( %getSavedVar( @self, "master" ) )

Function: %getPet()

Aliases	%getPet( )
Parameters	character entity

    If the character has a pet then a pointer to the pet will be returned.
    Otherwise null will be returned. Character entity may be a character
    pointer or keyword.

Function: %getPlayerVar()

Aliases	%getPlayerVar( )
Parameters	mixed @entity, string @varName

    Retrieves the value of the variable that is within the saved player file
    persistence context of the entity. Since rooms cannot be saved to player
    files and there can only ever be one instance of a room with a given vnum,
    this function has identical functionality to the %getSavedVar() function
    when applied to a room. The entity may be a pointer to a room, mob, or
    object. It may also be a keyword of a mob or object or the vnum of a room.
    If the variable is not found then null is returned. These variables are
    saved in the player's data file and are restored whenever the player
    re-enters the game.

    Example:

    %getPlayerVar( @n, lastEnteredSkurvash )

Function: %getPositionId()

Aliases	%getPositionId( ), %getPositionId( ), %getPositionId( ), %getPositionId( )
Parameters	character @entity

    Returns the position ID for the given character. The entity may be a
    character pointer or a keyword for a character. The ID returned will
    correspond to one of the following states:

        0 - dead
        1 - mortally wounded
        2 - incapacitated
        3 - stunned
        4 - sleeping
        5 - resting
        6 - sitting
        7 - fighting
        8 - standing

Function: %getRacePointer()

Aliases	%getRacePointer( ), %getRacePtr( )
Parameters	mixed @id

    Returns an race pointer for the given @id. The value of @id may be a race
    text pointer, the integer ID of a race, or the tag name of the desired
    race. If a matching race cannot be found then null is returned.

    Examples:
    
        @race = %getRacePtr( @mob->realRaceId )

        @race = %getRacePtr( "insectGiant" )

Function: %getRace()

Aliases	%getRace( ), %getRace( )
Parameters	character @entity

    Returns the race for the given character. The race will be in lower-case
    such as "troll" or "halfling". The entity may be a character pointer or a
    keyword for a character.

Function: %getRealTime()

Aliases	%getRealTime( ), %getRealTime( ), %getRealTime( )
Parameters	string @aspectName

    Returns the real time for the given aspect. Multiple calls to this
    function can be used to create a fully readable time string. The following
    may be used for the aspectName:

        day           month         absHour
        hour          wday          absMin
        min           yday          absSec
        sec           year          absMicro

    The absHour, absMin, and absSec parameters will return the number of
    hours, minutes, or seconds respectively since the Epoch (00:00:00 UTC,
    January 1, 1970). The absMicro field returns is the same as absSec
    with the addition that partial seconds are also returned.

Function: %getReputation()

Aliases	%getReputation( )
Parameters	character @target

    Returns the reputation of the given @target.

    Example:
    --------------------------------------------------------------------------

    if( %getReputation( @target ) > @someThreshold )
    {
        talk @target GET OUT OF MY TOWN SCUMBAG!
        hit @target
    }
    endif

Function: %getRoomPointer()

Aliases	%getRoomPointer( ), %getRoomPtr( )
Parameters	mixed @entity

    Returns a room pointer for the given entity parameter or null on failure. 
    If @entity is set to a room pointer then it is checked for validity and
    returned if valid. Alternatively if @entity is set to an integer value
    then a pointer to the room (if any) with that vnum is returned.  Finally
    if @entity is a pointer to a mobile or object then a pointer to the room
    in which the mobile or object resides is returned.

    Examples:
    
        @room = %getRoomPointer( @n )

        @room = %getRoomPointer( 115611 )

Function: %getSavedVar()

Aliases	%getSavedVar( )
Parameters	mixed @entity, string @varName [, @entityType ]

    Retrieves the value of the variable that is within the persistent variable
    context of the entity. The entity may be a pointer to a room, mob, or
    object. It may also be the vnum of a room or a keyword of a mob or object.
    If variable is not found then null is returned. Persistent variables are
    stored in the MySQL database. The first time a retrieval is done the
    variable is loaded if it exists and cached for quicker subsequent
    retrieval. It is important to know that there can only be one shared saved
    variable OF THE SAME NAME for all mobs, or all objects, or all rooms with
    the same vnum.

    The @entity parameter may also be set to the vnum of a mobile or object. 
    If this is done then the optional @entityType parameter must be set to
    "mobile" or "object" respectively.

    Example:

    @owner = %getSavedVar( 10005, towerOwner )

Function: %getServerBootId()

Aliases	%getServerBootId( )
Parameters	-

    Returns a unique ID for the current server boot. This can be used in
    conjunction with saved variables and player variables to determine if an
    affect or object's data should expire since the game ha reboot. For
    instance if your object saved the pointer for a mobile, then that pointer
    would become invalid when the game reboots. For this reason you could
    check against a saved boot ID and the current boot ID to determine if the
    pointer is still valid.

    Example:
    --------------------------------------------------------------------------

    if( %getServerBootId() != %getPlayerVar( @this, savedBootId ) )
    {
        %purge( @this )
    }
    endif

Function: %getShortName()

Aliases	%getShortName( ), %getShortName( )
Parameters	character @entity

    Returns the short name of the character. Unlike the %getName( ) function
    this function does not perform any trimming. The character entity may be a
    character pointer or a keyword of a character.

Function: %getSubClass()

Aliases	%subClass( ), %getSubClass( )
Parameters	character @entity

    Returns the class of the target @entity. If the @entity has no class (jack
    of all trades) then null is returned. The @entity may be a character
    pointer or keyword.

Function: %getTarget()

Aliases	%getTarget( )
Parameters	string @keywords, string @range, [, integer @visible [, object @container [, entity @source [, integer @roomId]]]]

    This function works EXACTLY the same as the %getTargets() function except
    that there is no @max parameter since only 1 target will be returned. It
    is equivalent to the following:

    %getTargets(
    \   @keywords, @range, 1, @visible, @container, @source, @roomId )

Function: %getTargets()

Aliases	%getTargets( )
Parameters	string @keywords, string @range, integer @max, [, integer @visible [, object @container [, entity @source [, integer @roomId]]]]

    Use this function to retrieve a list of targets from the world. This
    function can find objects, mobiles, exits, and extras from anywhere in the
    world. The following information is EXTREMELY useful for determining how
    to find a target from a range or series of ranges.

    @keywords   - This should be a string of the form used when playing the
                  game. For instance if you wanted to target a troll, you
                  might type any of the folloing:

                    troll       tro/        trol
                    1.troll     1.tr/       1.trol

                  Note that this function does not require the trailing / on a
                  partial match. A partial match without a trailing / will
                  attempt to match exactly first, if tha fails then a partial
                  match will be attempted.

    @range      - This parameter defines a search pattern for finding targets
                  in the world. The general syntax is of the form:

                    "range1[types] range2[types]"

                  The range may be any one of the following characters and has
                  the given meaning:

                    w - the entire world in which @roomId exists
                    t - the entire continent in which @roomId exists
                    a - the entire area in which @roomId exists
                    z - the entire zone in which @roomId exists
                    r - the room defined by @roomId
                    i - the inventory of @source
                    e - the equipped items of @source
                    c - the contents of @container

                The types may be any of the following characters or character
                combinations and has the given meaning:

                    m - search for a mobile in the controlling range
                    p - search for a PC mobile in the controlling range
                    n - search for an NPC mobile in the controlling range
                    o - search for an object in the controlling range
                    e - search for an exit in the controlling range

                    x - search for an extra in the controlling range, this
                        option MUST be followed by one of the following
                        options:

                    r - room extras
                    o - object extras
                    i - inventory
                    e - equipment extras
                    c - container extras (with @container defined)

                For example to first find a mobile target in the current room,
                then an inventory target, then an equipment list target, and
                finally a room object target then you would set the range to
                the following:

                    "r[m] i[o] e[o] r[o]"

                On the other hand, if you weren't interested in inventory or
                equipped items, you could have just done:

                    "r[mo]"

                Finally, if the first character of the range is '!' or '*'
                then the matching will be restricted to exact or partial
                matching respectively.

    @max        - Limit the number of returned targets to at most @max.

    @visible    - If this is set to true (non zero), then the actor defined by
                  @source must be able to see the target. If no @source is
                  defined then this parameter has no bearing on the matched
                  targets. Ifthis parameter is not defined then it defaults to
                  true (non zero).

    @container  - When searching containers for targets, this parameter should
                  be set to the container to be searched.

    @source     - This should be set to the source entity that is doing the
                  targetting. If this is not set then it defaults to the owner
                  of the script, @this. If this is set to the null value then
                  the source is ignored, and so parameters relating to
                  visibility, inventory, and equipment are ignored.

    @roomId     - If you would like the search to take place in a specific
                  location, then you may set this parameter to an appropriate
                  room ID.  If this value is not set, then it defaults to the
                  room in which the script was invoked.

    This function is extremly power, and enables a script developer to find
    complex targets int he world with very few instructions. For instance,
    let's say you want to override a command input by a player and somehow
    affect the target before or after the real command runs, then you might do
    the following:

    Example:
    --------------------------------------------------------------------------

    catch_custom_command
    headbutt

    protect
    {
        @keyword = %stringToWords( %filterActionWords( @arguments ) )->1

        //
        // Check that a keyword was input.
        //
        if( @keyword == "" )
        {
            return
        }
        endif

        //
        // Search for the target mobile in the room.
        //
        @target = %getTargets( @keyword, "r[m]", 1 )

        //
        // Run the normal command first.
        //
        %runCommand( @actor, @command " " @arguments )

        //
        // Do something to the target.
        //
    }
    endprotect

Function: %getTime()

Aliases	%getTime( ), %getTime( )
Parameters	[string @aspectName]

    When no parameters are given this returns the current hour of the in game
    day. Otherwise if aspectName is set then it returns the apprpriate in game
    time for the given aspectName. The aspectName may be any of the following:

        hour          wday
        day           wdaynum
        month         yday
        monthnum      year

Function: %getTotalHere()

Aliases	%getTotalHere( ), %getTotalHere( ), %getTotalHere( )
Parameters	[string @entityType,] mixed @entity

    Returns the number of characters or objects in the same room as the script
    owner that have the same vnum. The entity may be a character pointer,
    object pointer, or a keyword for a character or object.


    Returns the total number of entities having the same ID as the given
    @entity that are in the same room. If @entityType is provided then the
    entity is matched to its type. The value of @entity may be one or more
    keywords, an id, or a pointer. If an ID is given then the room matched
    will be the same as the script owner.

    If the @entityType is not provided and @entity is not a pointer, then the
    matching may be ambiguous between items and mobiles. In such cases the
    mobile is given preference.

    NOTE: It is advisable to use a pointer or @entityType with an ID.

Function: %getTranslation()

Aliases	%getTranslation( )
Parameters	string @speech, mobile @listener, mixed @language

    Returns the given @speech translated with regards to the @listener's
    ability to undertand the specified @language. The value for @language may
    either be the name of a language, the ID of a language, or a mobile. If
    the @language is a mobile, then the language will be that mobile's
    currently spoken language.

    The following language names are currently possible:

        common              goblin
        centaur             halfling
        dwarven             orcish
        elven               reptilian
        fairy               trollish
        gnomish


    Example:
    --------------------------------------------------------------------------

    @speech = "You must leave this place at once!"

    @translation = %getTranslation( @speech, @n, "orcish" )

    $echoTo( "A voice booms all around you, '" @translation "'", @n )

Function: %getVar()

Aliases	%getVar( )
Parameters	string @varName

    Retrieves the value of the variable with name varName that has been assigned
    to the script owner. If the variable does not exist then null is returned.

    Example:

    @lastVisitor = %getVar( lastVisitor )

Function: %getWeight()

Aliases	%getWeight( ), %getWeight( )
Parameters	character @entity

    Returns the weight of the given character. Character entity may be a
    character pointer or keyword.

Function: %hasAffectItem()

Aliases	%hasAffectItem( )
Parameters	character @target, integer @vnum

    Checks to see if the @target has one or more affect objects in their
    affect objects inventory with the given @vnum. Returns 1 if such an affect
    object is found; otherwise returns 0.

Function: %hasItem()

Aliases	%hasItem( ), %hasItem( )
Parameters	character @target, object @object

    Checks to see if the @target has the @object in their direct inventory. If
    the @object is found then returns 1, otherwise 0. This function only checks
    tge first level of inventory and does not check equipped items at all. If
    the owner of the script is a character then they must be able to see the
    @object. The @object may be a pointer to an object, the name of an object,
    or the vnum of an object.

Function: %hates()

Aliases	%hates( )
Parameters	character @hater [, character @hated]

    Traditionally the Worlds of Carnage only supported the hating of one
    target at a time and this behaviour is reflected in the return value of
    this function if only one parameter is provided. If only one parameter is
    provided then a pointer to the first creature the hater hates is returned.
    If the second parameter is provided then a 1 is returned if the hater
    hates the hated, and 0 is returned otherwise. The hater and hated may be a
    character pointer or keyword.

Function: %height()

Aliases	%getHeight( ), %height( )
Parameters	character @entity

    Returns the height of the given character. Character entity may be a
    character pointer or keyword.

Function: %hitsCond()

Aliases	%hitsCond( ), %hitCond( ), %getHitsCondition( )
Parameters	character @entity

    Returns the remaining percentage of the given character's hitpoints in
    relation to their total hitpoints. Character entity may be a character
    pointer or keyword.

Function: %int()

Aliases	%int( ), %integer( )
Parameters	-

    Returns a new integer with value 0. This function is mostly available for
    completeness.

Function: %isAffectedByBits()

Aliases	%isAffectedByBits( )
Parameters	character @entity, integer @bitMask

    Returns 1 if the given character is affected by all of the affects denoted
    by the set bits of the bitMask integer value. Returns 0 otherwise. This
    function shouldn't be used, instead you shoulduse the %isAffectedBy()
    function.

Function: %isAffectedBy()

Aliases	%isAffectedBy( )
Parameters	mixed @entity, string @affectName, [string @affectName2, ...]

    Returns 1 if the given character or object is affected by all of the named
    affects, which follow the entity as parameters, are set on the entity.
    The following named affects can be used:

    Mobiles:

        bash                    fear                paralysis
        blindness               feign death         parry
        champion mode           fly                 poison
        channel                 follow              protection from evil
        charm                   group               sanctuary
        chill touch             half hp regen       sense life
        curse                   half mana regen     shocking grasp
        deadly poison           half move regen     silence
        death's door            heat of battle      sleep
        detect evil             hide                sneak
        detect invisibile       immortal stealth    strength
        detect magic            infravision         summoned
        dominated               invisibility        sweeping
        double hp regen         lich touch          water breath
        double mana regen       light               water walk
        double move regen       movement impaired

    Objects:

        anti-evil               glow                no remove
        anti-good               hum                 paladin only
        anti-neutral            invisible           ranger only
        bless                   mage only           striking
        cleric only             magic               thief only
        dark                    no drop             two-handed
        evil                    curse               warrior only
        expire                  no give             wear expire

    Example:

        //
        // This checks that BOTH affects are active.
        //
        if( %isAffectedBy( @n, "chill touch", "lich touch" ) )
        {
            cast dispel magic @n
        }
        endif

        //
        // This checks if EITHER affect is active.
        //
        if( %isAffectedBy( @n, poison )
        \   ||
        \   $isAffectedBy( @n, "deadly poison" ) )
        {
            talk @n You look like you're in pretty rough shape!
        }
        endif

Function: %isArray()

Aliases	%isArray( )
Parameters	-

    Returns 1 if the given value is of type array, otherwise 0 is returned.

Function: %isAwake()

Aliases	%isAwake( )
Parameters	character @entity

    If the given character is awake then returns 1, otherwise returns 0.
    Character entity may be a character pointer or keyword.

Function: %isCharm()

Aliases	%isCharm( )
Parameters	mobile @entity

    Returns 1 if the given @entity is a player's charm; returns 0 otherwise. 
    The @entity may be a character pointer or keyword. Note that pets are NOT
    considered to be charms.

    Example:

    if( %isCharm( @n ) )
    {
        talk @n Yummy, yummy, a tasty morsel for me!!
        emote eats @N
        %purge( @n )
    }
    endif

Function: %isChar()

Aliases	%isChar( )
Parameters	mixed @entity

    Returns 1 if @entity is a text pointer to a mobile; otherwise 0 is
    returned.

Function: %isDark()

Aliases	%isDark( )
Parameters	mixed @entity

    Returns 1 if the containing room for a given character or object reference
    is dark (without light). If the entity is a room then returns 1 if that
    room is dark. The entity may be the vnum of a room, or a pointer to a
    room, mob, or object. It may also be a keyword of a mob or object.

Function: %isDaytime()

Aliases	%isDaytime( )
Parameters	-

    Returns 1 if the current day cycle is "daytime"; otherwise 0 is returned. 
    Daytime is defined as the time 1 hour after sunrise till 1 hour before
    sunset.

    Example:

    if( %isDaytime() )
    {
        talk @n Thank god it's daytime, lest the vampires be out!
    }
    endif

Function: %isEarlyTwilight()

Aliases	%isEarlyTwilight( )
Parameters	-

    Returns 1 if the current day cycle is "early twilight"; otherwise 0 is
    returned.  Early twilight is defined as the hour the sun rises. It is
    worth noting that vampires are safe during twilight, although they are
    weakened during early twilight.

    Example:

    if( %isEarlyTwilight() )
    {
        yell The sun will soon be up, we will be safe once more!
    }
    endif

Function: %isEquipmentLocation()

Aliases	%isEquipmentLocation( ), %isEqLocation()
Parameters	@name

    Returns 1 if the given @location is a valid equipment location; otherwise
    returns 0. The following are valid location names:

        light               arms
        lFinger             shield
        leftFinger          about
        left finger         waist
        rFinger             lWrist
        rightFinger         leftWrist
        right finger        left wrist
        neck1               rWrist
        neck 1              rightWrist
        neck2               right wrist
        neck 2              wield
        body                wielded
        head                wielding
        legs                held
        feet                hold
        hands               holding

    Example:

        if( !%isEquipmentLocation( @input ) )
        {
            %echoTo( "That's not a valid equipment location.", @actor )
        }
        else
        {
            //
            // Move @item into the given location on @target mobile.
            //
            %move( @item, @target, @input )
        }
        endif

Function: %isEquippedItem()

Aliases	%isEquippedItem( )
Parameters	character @entity, object @entity

    Returns true if the given character has equipped the given object.
    Character entity may be a character pointer or keyword. The object entity
    may be an object pointer, keyword, or vnum.

    Example:

    if( %isEquippedItem( @n, black_tabard ) )
    {
        damage char @n %( 3d5 + 5 )
    }
    endif

Function: %isEvil()

Aliases	%isEvil( )
Parameters	character @entity

    If the given character is of evil alignment then returns 1, otherwise
    returns 0. Character entity may be a character pointer or keyword.

Function: %isExit()

Aliases	%isExit( )
Parameters	mixed @entity

    Returns 1 if @entity is a text pointer to an exit; otherwise 0 is
    returned.

Function: %isExtra()

Aliases	%isExtra( )
Parameters	mixed @entity

    Returns 1 if @entity is a text pointer to an extra; otherwise 0 is
    returned.

Function: %isFighting()

Aliases	%isFight( ), %isFighting( )
Parameters	character @entity

    If the given character is currently fighting then returns 1, otherwise
    returns 0. Character entity may be a character pointer or keyword.

    Example:

    if( %isFighting( @n ) )
    {
        silentforce @n flee
    }
    endif

Function: %isFloat()

Aliases	%isFloat( )
Parameters	-

    Returns 1 if the given value is of type float, otherwise 0 is returned.

Function: %isFollowing()

Aliases	%isFollowing( ), %isFollow( )
Parameters	character @entity

    If the given character is currently following someone then returns 1,
    otherwise returns 0. Character entity may be a character pointer or
    keyword.

Function: %isGhost()

Aliases	%isGhost( )
Parameters	character @target

    Returns 1 if the @target is a ghost; otherwise returns 0.

    Example:
    --------------------------------------------------------------------------

    if( %isGhost( @target ) )
    {
        talk @target
        \   I'm sorry but I cannot help a ghost. You should seek a cleric!
    }
    endif

Function: %isGladiating()

Aliases	%isGladiating( )
Parameters	character @actor, character @victim

    If @actor and @victim are capable of engaging in gladiatorial comabat then
    1 is returned. Otherwise 0 is returned.

Function: %isGood()

Aliases	%isGood( ), %isGoodly( )
Parameters	character @entity

    If the given character is of goodly alignment then returns 1, otherwise
    returns 0. Character entity may be a character pointer or keyword.

Function: %isHunting()

Aliases	%isHunting( ), %isHunt( )
Parameters	character @entity

    If the given character is currently hunting someone then returns 1,
    otherwise returns 0. Character entity may be a character pointer or
    keyword.

Function: %isImmortal()

Aliases	%isImmortal( ), %isImmort( )
Parameters	character @entity

    If the given character is of immortal status then returns 1, otherwise
    returns 0. Character entity may be a character pointer or keyword.

Function: %isImmune()

Aliases	%isImmune( )
Parameters	mobile @target, string @type

    Returns 1 if @target mobile is immune to the given @type; otherwise
    returns 0. The following types are recognized:

        acid                hit                     plus 4
        blindness           light weapon            poison
        bludgeon            magic                   positive energy
        charm               mental                  pword fear
        cold                negative energy         slash
        deadly poison       non-magic               steal
        detection           paralyze                summon
        dispel              pierce                  weapon
        electric            plus 1                  whirlwind
        fire                plus 2
        fumble              plus 3

    Example:
    --------------------------------------------------------------------------

    if( !%isImmune( @target, "whirlwind" ) )
    {
        %move( @target, @room->exits->east )
    }
    endif

Function: %isInt()

Aliases	%isInt( ), %isInteger( )
Parameters	mixed @value

    Returns 1 if the given value is of type integer, otherwise 0 is returned.

Function: %isItemHere()

Aliases	%isItemHere( ), %isItemHere( ), %isItemHere( ), %isItemHere( )
Parameters	object @entity

    Returns 1 if the object is in the same room as the script owner, otherwise
    returns 0.  The object must be visible to the script owner. The entity may
    be an object pointer or a keyword for an object.

Function: %isItemId()

Aliases	%isItemId( )
Parameters	integer @id

    Returns 1 if @id corresponds to a valid item description. This is useful
    for checking to see if a given item exists before attempting to load it.
    In most cases you won't need to do such a check, but in rare instances
    when the area may not be loaded for the item, then this will prevent the
    %load() function from firing an error if it can't find the item.

    Example:

        if( %isItemId( @someId ) )
        {
            %load( item, @someId, @roomId )
        }
        endif

Function: %isItem()

Aliases	%isItem( ), %isItem( )
Parameters	mixed @entity

    Returns 1 if @entity is a text pointer to an object; otherwise 0 is
    returned.

Function: %isJailed()

Aliases	%isJailed( )
Parameters	character @target

    Returns 1 if the @target is in jail (or should be); otherwise returns 0.

    Example:
    --------------------------------------------------------------------------

    if( %isJailed( @target ) )
    {
        talk @target
        \   Better watch out buddy, there's guards everywhere and
        \   they'll send you back to jail in a jiffy.
    }
    endif

Function: %isLateTwilight()

Aliases	%isLateTwilight( )
Parameters	-

    Returns 1 if the current day cycle is "late twilight"; otherwise 0 is
    returned.  Late twilight is defined as the hour the sun sets. It is worth
    noting that vampires are safe during twilight, although they are weakened
    during early twilight.

    Example:

    if( %isLateTwilight() )
    {
        yell HURRY! HURRY! The vampires will be upon us soon!
    }
    endif

Function: %isLeader()

Aliases	%isLeader( )
Parameters	character @entity

    If the given character is the leader of a group then returns 1, otherwise
    returns 0. Character entity may be a character pointer or keyword.

Function: %isLinkDead()

Aliases	%isLinkDead( )
Parameters	mixed @character

    Returns 1 if the PC character defined by @character is current LINK-DEAD.
    0 is returned if the PC character is not link dead or is a mobile. If no
    character could be matched then null is returned.

Function: %isMobHere()

Aliases	%isMobHere( ), %isMobHere( ), %isMobHere( )
Parameters	character @entity

    Returns 1 if the character is in the same room as the script owner.
    Otherwise returns 0. The entity may be the vnum for a mob, character
    pointer, or keyword for the character.

Function: %isMobId()

Aliases	%isMobId( )
Parameters	integer @id

    Returns 1 if @id corresponds to a valid mobile description. This is useful
    for checking to see if a given mobile exists before attempting to load it.
    In most cases you won't need to do such a check, but in rare instances
    when the area may not be loaded for the mobile, then this will prevent the
    %load() function from firing an error if it can't find the mobile.

    Example:

        if( %isMobId( @someId ) )
        {
            %load( mobile, @someId, @roomId )
        }
        endif

Function: %isNeutral()

Aliases	%isNeut( ), %isNeutral( )
Parameters	character @entity

    If the given character is of neutral alignment then returns 1, otherwise
    returns 0. Character entity may be a character pointer or keyword.

Function: %isNighttime()

Aliases	%isNighttime( )
Parameters	-

    Returns 1 if the current day cycle is "nighttime"; otherwise 0 is
    returned.  Nighttime is defined as the time 1 hour after sunset till
    1 hour before sunrise.

    Example:

    if( %isNighttime() )
    {
        talk @n I wouldn't go outside now, it's nighttime and the vampires
        \       will be feeding.
    }
    endif

Function: %isNpc()

Aliases	%isNpc( )
Parameters	character @entity

    Returns 1 if the character is a Non-Playing Character (mobile), otherwise
    returns 0. Character entity may be a character pointer or keyword.

Function: %isNull()

Aliases	%isNull( )
Parameters	mixed @data

    Returns 1 if the given data is null, otherwise returns 0.

Function: %isOutside()

Aliases	%isOutside( ), %isOutside( )
Parameters	mixed @entity

    Returns 1 if the containing room for a given character or object reference
    is outside. If the entity is a room then returns 1 if that room is
    outside. The entity may be the vnum of a room, or a pointer to a room,
    mob, or object. It may also be a keyword of a mob or object.

Function: %isPc()

Aliases	%isPc( )
Parameters	character @entity

    Returns 1 if the character is a Playing Character (not a mobile),
    otherwise returns 0. Character entity may be a character pointer or
    keyword.

Function: %isPet()

Aliases	%isPet( )
Parameters	character @entity

    Returns 1 if the character is a player's pet and returns 0 otherwise.
    Character entity may be a character pointer or keyword.

Function: %isResistant()

Aliases	%isResistant( )
Parameters	@target, string @type

    Returns 1 if @target mobile is resistant to the given @type; otherwise
    returns 0. See the description for %isImmune() for the list of types.

Function: %isRoomId()

Aliases	%isRoomId( )
Parameters	integer @id

    Returns 1 if @id corresponds to a valid room description. This is useful
    for checking to see if a given room exists before attempting to move
    something into it via the %move() function or either the transfer or
    npctrans functions. In most cases you won't need to do such a check, but
    in rare instances when the area may not be loaded for the room, then this
    will prevent an error being generated when the room can't be found.

    Example:

        if( %isRoomId( @someId ) )
        {
            %move( @actor, @roomId )
        }
        endif

Function: %isRoom()

Aliases	%isRoom( )
Parameters	mixed @entity

    Returns 1 if @entity is a text pointer to a room; otherwise 0 is
    returned.

Function: %isString()

Aliases	%isString( )
Parameters	-

    Returns 1 if the given value is of type string, otherwise 0 is returned.

Function: %isSusceptable()

Aliases	%isSusceptable( )
Parameters	@target, string @type

    Returns 1 if @target mobile is susceptible to the given @type; otherwise
    returns 0. See the description for %isImmune() for the list of types.

Function: %isValid()

Aliases	%isValid( ), %isValid( )
Parameters	mixed @entity

    Returns 1 if the given entity is valid, otherwise returns 0. More
    specifically the object is considered invalid if it is a string and
    matches any of "none", "nobody", "nothing", "*ERR*", "-1". It is also
    considered invalid if it is the null value or if it an entity pointer for
    which the target entity is no longer in existence.

Function: %isVampire()

Aliases	%isVampire( )
Parameters	character @target

    Returns 1 if the @target is a vampire; otherwise returns 0.

    Example:
    --------------------------------------------------------------------------

    if( %isVampire( @target ) )
    {
        yell HELP!!! THE UNDEAD ARE AMONGST US!
        throw holy @target
        flee
    }
    endif

Function: %isWaiting()

Aliases	%isWaiting( )
Parameters	character @entity

    Returns 1 if the character is wait stated and 0 otherwise. Wait state is
    when the creature or player normally cannot perform another command
    because they have just performed one such as headbutt. This is extremely
    useful since commands issued from scripts ALWAYS run, they ignore the wait
    state, meaning if you want to cook your own combat sequence or something
    else, you should use this to determine if they could normally issue the
    next command. Character entity may be a character pointer or keyword.

    Example:

    if( !%isWaiting( @this ) )
    {
        kick %getOpponent( @this )
    }
    endif

Function: %itemClearType()

Aliases	%itemClearType( )
Parameters	object @entity, string @type

    Attempts to clear the given object @type from the object @entity. Once
    this is done the associated fields for that object type become invalid
    and the item ceases to be usable for that kind of object. The following
    are the possible values for the @type parameter:

        affect              key                 scroll
        armor               light               staff
        armour              missile             tome
        artifact            money               trap
        boat                note                trash
        container           other               treasure
        corpse              pen                 wand
        drink               potion              weapon
        food                resource            worn
        gold                rod

    Example:
    --------------------------------------------------------------------------

    %itemClearType( @obj, wand )

Function: %itemGetLoadCount()

Aliases	%itemGetLoadCount( ), %itemGetLoadCount( ), %itemGetLoadCount( ), %itemGetLoadCount( )
Parameters	integer @objectId

    Returns the total number of objects currently in the game with the given
    objectId (vnum).

Function: %itemGetStat()

Aliases	%itemGetStat( ), %itemGetStat( ), %itemGetStat( )
Parameters	object @entity, string @statName

    Returns the value for a given statName that belongs to the object. The
    entity may be an object pointer or object keyword. The statName may be any
    one of the following stat IDs:

        areaId      level       hitpoints
        id          buyValue    maxHitpoints
        uniqueId    sellValue   name
        keywords    rentCost    descInventory
        shortName   weight      descRoom
        longName

    The following keywords still work but are deprecated:

        hp
        maxhp

    Example:

    @weight = %itemGetStat( @o, weight )

Function: %itemInitType()

Aliases	%itemInitType( )
Parameters	object @entity, string @type

    Attempts to initialize the given object @type for the object @entity. Once
    this is done the associated fields for that object type can be
    manipulated. Following are the possible values for the @type parameter:

        affect              key                 scroll
        armor               light               staff
        armour              missile             tome
        artifact            money               trap
        boat                note                trash
        container           other               treasure
        corpse              pen                 wand
        drink               potion              weapon
        food                resource            worn
        gold                rod

    Example:
    --------------------------------------------------------------------------

    %itemInitType( @obj, food )
    @obj->food->portionSize = 10

Function: %itemIsTypeAffect()

Aliases	%itemIsTypeAffect( )
Parameters	object @entity

    Returns 1 if the given @entity is an affect object; otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

    Example:
    --------------------------------------------------------------------------

    if( !%itemIsTypeAffect( @obj ) )
    {
        %purge( @obj )
    }
    endif

Function: %itemIsTypeArmour()

Aliases	%itemIsTypeArmour( ), %itemIsTypeArmor( )
Parameters	object @entity

    Returns a 1 if the object entity is armor, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeArrow()

Aliases	%itemIsTypeArrow( )
Parameters	object @entity

    Returns a 1 if the object entity is a arrow, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeBoat()

Aliases	%itemIsTypeBoat( )
Parameters	object @entity

    Returns a 1 if the object entity is a boat of some kind, otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypeBodyPart()

Aliases	%itemIsTypeBodyPart( )
Parameters	object @entity

    Returns a 1 if the object entity is a body part otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypeBow()

Aliases	%itemIsTypeBow( )
Parameters	object @entity

    Returns a 1 if the object entity is a bow, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeContainer()

Aliases	%itemIsTypeContainer( )
Parameters	object @entity

    Returns a 1 if the object entity is a container, otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypeCorpse()

Aliases	%itemIsTypeCorpse( )
Parameters	object @entity

    Returns a 1 if the object entity is a corpse otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypeDrink()

Aliases	%itemIsTypeDrink( )
Parameters	object @entity

    Returns a 1 if the object entity is a drink, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeFood()

Aliases	%itemIsTypeFood( )
Parameters	object @entity

    Returns a 1 if the object entity is food, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeHerb()

Aliases	%itemIsTypeHerb( )
Parameters	object @entity

    Returns 1 if the object entity is an herb; otherwise 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeKey()

Aliases	%itemIsTypeKey( )
Parameters	object @entity

    Returns a 1 if the object entity is of type key, otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypeLight()

Aliases	%itemIsTypeLight( )
Parameters	object @entity

    Returns a 1 if the object entity is a light source, otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypeMissile()

Aliases	%itemIsTypeMissile( )
Parameters	object @entity

    Returns a 1 if the object entity is a missile, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeMoney()

Aliases	%itemIsTypeMoney( )
Parameters	object @entity

    Returns a 1 if the object entity money, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeNote()

Aliases	%itemIsTypeNote( )
Parameters	object @entity

    Returns a 1 if the object entity is a note, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeOther()

Aliases	%itemIsTypeOther( )
Parameters	object @entity

    Returns a 1 if the object entity is of type other, otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypePen()

Aliases	%itemIsTypePen( )
Parameters	object @entity

    Returns a 1 if the object entity is writing tool, otherwise a 0 is
    returned. The object entity may be an object pointer or keyword.

Function: %itemIsTypePotion()

Aliases	%itemIsTypePotion( )
Parameters	object @entity

    Returns a 1 if the object entity is a potion, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeRod()

Aliases	%itemIsTypeRod( )
Parameters	object @entity

    Returns a 1 if the object entity is a rod, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeScroll()

Aliases	%itemIsTypeScroll( )
Parameters	object @entity

    Returns a 1 if the object entity is a scroll, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeStaff()

Aliases	%itemIsTypeStaff( )
Parameters	object @entity

    Returns a 1 if the object entity is a staff, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeTome()

Aliases	%itemIsTypeTome( )
Parameters	object @entity

    Returns a 1 if the object entity is a tome, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeTrap()

Aliases	%itemIsTypeTrap( )
Parameters	object @entity

    Returns a 1 if the object entity is a trap, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeTrash()

Aliases	%itemIsTypeTrash( )
Parameters	object @entity

    Returns a 1 if the object entity is trash, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeTreasure()

Aliases	%itemIsTypeTreasure( )
Parameters	object @entity

    Returns a 1 if the object entity is treasure, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeWand()

Aliases	%itemIsTypeWand( )
Parameters	object @entity

    Returns a 1 if the object entity is a wand, otherwise a 0 is returned. The
    object entity may be an object pointer or keyword.

Function: %itemIsTypeWeapon()

Aliases	%itemIsTypeWeapon( )
Parameters	object @entity

    Returns a 1 if the object entity is a weapon, otherwise a 0 is returned.
    The object entity may be an object pointer or keyword.

Function: %itemIsTypeWorn()

Aliases	%itemIsTypeWorn( )
Parameters	object @entity

    Returns a 1 if the object entity is of type worn or if it can be worn,
    otherwise a 0 is returned. The object entity may be an object pointer or
    keyword.

Function: %itemSetStat()

Aliases	%itemSetStat( ), %itemSetStat( ), %itemSetStat( )
Parameters	object @entity, string @statName, mixed @value

    Sets the value for a given statName that belongs to the object. The entity
    may be an object pointer or object keyword. The statName may be any one of
    the following stat IDs:

        keywords        level           name
        shortName       buyValue        descInventory
        longName        sellValue       descRoom
        hitpoints       rentCost
        maxHitpoints    weight

    Example:

    %itemSetStat( @o, level, 45 )

Function: %itemZap()

Aliases	%itemZap( )
Parameters	[object @entity]

    Zaps the item from the players equipped position. Funcitonally identical
    to when an item gets zapped for which the wearer doesn't have the proper
    alignment.

    Example:
    --------------------------------------------------------------------------

    %itemZap( @this )

Function: %jumpTo()

Aliases	%jumpTo()
Parameters	string @label

    The jumpTo expression normally used for jumping to labels within a script
    cannot jump to variable labels. It is hard wired for efficiency at script
    compile time. To support less efficient dynamic label jumping, the
    %jumpTo() function can be used instead.
    
    Example:

        @options = %array( good, neutral, evil )
        %jumpTo( %arrayShuffle( @options )->1 )

        label good
        {
            cast bless @n
            cast sanctuary @n

            return
        }

        label neutral
        {
            cast vigour @n
            wink @n

            return
        }

        label evil
        {
            point @n
            laugh @n
            cast soul strike @n

            return
        }

Function: %load()

Aliases	%load( )
Parameters	string @type, integer @id, mixed @entity [, mixed @wearName]

    Loads an entity of the given @type and @id onto the target @entity,
    optionally into an equipment position defined by wearName. The value of
    the type parameter must be one of the following:

        room
        mobile
        object
        exit
        extra
        buff
        money

    The target may be a pointer to a character, a pointer to a container
    object, a pointer to a room, or a room number. You CANNOT use keywords for
    the target entity, if you feel the need to use a keyword, then use
    %getRoomPointer( keyword ), %getItemPointer( keyword ), or
    %getMobPointer( keyword ) to get a pointer. If the target is a
    pointer to a character then you may optionally supply a fourth parameter
    for a wear location. You may use the ID of the wear location or one of the
    following keywords:

        light               legs                rightWrist
        leftFinger          feet                rWrist
        lFinger             hands               wield
        rightFinger         arms                wielded
        rFinger             shield              wielding
        neck1               about               hold
        neck2               waist               held
        body                leftWrist
        head                lWrist              affects

    Examples:

        //
        // Load object to inventory and save pointer to new object.
        //
        @helmet = %load( object, 12604, @n )

        //
        // Load object to equipment and save pointer to new object.
        //
        @helmet = %load( object, 12604, @n, head )

        //
        // Load object to elkin fountain room.
        //
        @helmet = %load( object, 12604, 115611 )

        //
        // Load object to a container denoted by @o (maybe a chest).
        //
        @helmet = %load( object, 12604, @o )

        //
        // Load Felix the pimp to elkin fountain room.
        //
        %load( mobile, 19005, 115611 )

        //
        // Load up a pile of 50000 gold coins at the elkin fountain.
        //
        %load( money, 50000, 115611 )

        //
        // Load a new extra description at the elkin fountain.
        //
        %load( extra, "crack", "Water leaks from a crack.", 115611 )

    Loading exits are somewhat different than objects or mobiles. The
    parameter format for exits is as follows:

        string type, string direction, integer fromRoom, integer toRoom

    Example:

        //
        // Load an upward exit in the Elkin inn which goes to the
        // Elkin post office.
        //
        @source = 115643
        @target = 115636
        %load( exit, up, @source, @target )

Function: %math()

Aliases	%math( )
Parameters	integer @passValue

    This function enables evaluation of a simple mathematical string. For
    instance it can be used to evaluate an instance of a weapon's damage.

    Example:

        if( %isValid( (@wielded = @actor->eq->wielded) ) )
        \   &&
        \   %itemIsTypeWeapon( @wielded ) )
        {
            @damage = %math( @wielded->weapon->damageString )
            @actor->hitpoints -= @damage
        }
        endif

See Also	%average()

Function: %mobGetAffectItemsById()

Aliases	%mobGetAffectItemsById( )
Parameters	mobile @mob, integer @id

    Returns all of the affect items on the target @mob that match the given
    item @id. The affect items will be returned as an array of item
    pointers and will only be retrieved from the mobile's special affects
    inventory.

    Example:

        if( !%isNull( @item = %mobGetAffectItemsById( @n, 123456 )->1 ) )
        {
            @item = %load( object, 123456, @n, affects )
        }
        endif

Function: %mobGetAffectItemsBySkill()

Aliases	%mobGetAffectItemsBySkill( )
Parameters	mobile @mob, mixed @skill

    Returns all of the affect items on the target @mob that match the given
    @skill name or ID. The affect items will be returned as an array of item
    pointers and will only be retrieved from the mobile's special affects
    inventory.

    Example:

        if( !%isNull( @item = %mobGetAffectItemsBySkill( @n, "bless" )->1 ) )
        {
            @item = %load( object, 123456, @n, affects )
        }
        endif

Function: %mobGetStat()

Aliases	%mobGetStat( ), %mobGetStat( ), %mobGetStat( )
Parameters	character @entity, string @statName

    Returns the value for a given statName that belongs to the character. The
    entity may be a character pointer or character keyword. The statName may
    be any one of the following stat IDs:

        areaId                  keywords
        id                      shortDescription
        uniqueId                longDescription
        startRoomId             realName (not disguise)

        strength                realStrength                hitpoints
        strengthBonus           realStrengthBonus           mana
        intelligence            realIntelligence            moves
        wisdom                  realWisdom
        dexterity               realDexterity               maxHitpoints
        constitution            realConstitution            maxMana
        charisma                realCharisma                maxMoves

        hitrollBonus        practices           drunk           saveParalyze
        damageBonus         wimpy               hunger          saveRod
        thac0               height              thirst          savePetrify
        alignment           weight                              saveBreath
        gold                                                    saveSpell
        bank                experience
        level               npcgroup

    The following keywords still work but are deprecated:

        str         real_str        bankgold        dam_bonus
        exstr       real_exstr                      damroll
        int         real_int        mana
        wis         real_wis        move            hit_bonus
        dex         real_dex        max_hp          hitroll
        con         real_con        max_mana
        chr         real_chr        max_move

    Example:

    @gold = %mobGetStat( @n, gold )
    @bank = %mobGetStat( @n, bank )

    @bank += @gold
    @gold  = 0

    %mobSetStat( @n, gold, @gold )
    %mobSetStat( @n, bank, @bank )

Function: %mobIsUndead()

Aliases	%mobIsUndead( )
Parameters	mobile @entity

    Returns 1 if the mobile is an undead race; otherwise returns 0. Mobile
    @entity must be a pointer.

Function: %mobPulseActivity()

Aliases	%mobPulseActivity( )
Parameters	mobile @mob [, float @rounds=1]

    Causes the mobile (PC or NPC) to have action commands delay for the
    specified number of mobile activity @rounds. During this time any action
    commands issued by the mobile will be queued. This is only true for
    commands not issued via script. Scripts wishing to respect action command
    delays should check the @mob->actionDelay variable.

Function: %mobPulseTick()

Aliases	%mobPulseTick( )
Parameters	mobile @mob [, float @rounds=1]

    Causes the mobile (PC or NPC) to have action commands delay for the
    specified number of tick @rounds. During this time any action commands
    issued by the mobile will be queued. This is only true for commands not
    issued via script. Scripts wishing to respect action command delays should
    check the @mob->actionDelay variable.

Function: %mobPulseViolence()

Aliases	%mobPulseViolence( )
Parameters	mobile @mob [, float @rounds=1]

    Causes the mobile (PC or NPC) to have action commands delay for the
    specified number of violence activity @rounds. During this time any action
    commands issued by the mobile will be queued. This is only true for
    commands not issued via script. Scripts wishing to respect action command
    delays should check the @mob->actionDelay variable.

Function: %mobPurgeSkills()

Aliases	%mobPurgeSkills( )
Parameters	mobile @entity

    Purges all skills from the given @entity mobile. The value for @entity
    must be a pointer to a mobile. This will NOT work on PC mobiles.


    Example:

    %mobPurgeSkills( @n->pet )

Function: %mobRankAtLeast()

Aliases	%mobRankAtLeast( )
Parameters	mobile @target, string @rankName

    Returns 1 if the given @target has a rank of at least the given @rankName;
    otherwise returns 0. The @target must be a pointer to a mobile. The
    @rankName may be one of the following:

        dweeb
        masterDweeb
        novice
        capable
        veteran
        expert
        master
        champion
        livingLegend
        mythicRenown
        demiGod
        immortal

    The above names are also in order of increasing rank.

    Example:

    if( %mobRankAtLeast( @n, champion ) )
    {
        cast deadly poison @n
    }
    else
    {
        cast poison @n
    }
    endif

Function: %mobRankAtMost()

Aliases	%mobRankAtMost( )
Parameters	mobile @target, string @rankName

    Returns 1 if the given @target has a rank of at most the given @rankName;
    otherwise returns 0. The @target must be a pointer to a mobile. The
    @rankName may be one of the following:

        dweeb
        masterDweeb
        novice
        capable
        veteran
        expert
        master
        champion
        livingLegend
        mythicRenown
        demiGod
        immortal

    The above names are also in order of increasing rank.

    Example:

    if( %mobRankAtMost( @n, veteran ) )
    {
        whisper @n I heard there's gold buried in the bandit priest's tent!
    }
    endif

Function: %mobSetStat()

Aliases	%mobSetStat( ), %mobSetStat( ), %mobSetStat( )
Parameters	character @entity, string @statName, mixed @value

    Sets the value for a given statName that belongs to the character. The
    entity may be a character pointer or charcter keyword. The statName may be
    any one of the following stat IDs:

        keywords                shortDescription            longDescription

        startRoomId

        strength                realStrength                hitpoints
        strengthBonus           realStrengthBonus           mana
        intelligence            realIntelligence            moves
        wisdom                  realWisdom
        dexterity               realDexterity               maxHitpoints
        constitution            realConstitution            maxMana
        charisma                realCharisma                maxMoves

        hitrollBonus        practices           drunk           saveParalyze
        damageBonus         wimpy               hunger          saveRod
        thac0               height              thirst          savePetrify
        alignment           weight                              saveBreath
        gold                hometown                            saveSpell
        bank                experience
        level               npcgroup

    *** Please note that many of these stats will log a message when used on
        a PC. The log message will indicate the area, entity, script, stat
        being set, target player, and new value. Do not use inappropriately.

    Example:

    %mobSetStat( @n, thirst, 75 )

Function: %move()

Aliases	%move( )
Parameters	mixed @sourcePointer, mixed @targetPointr [, string @wearName]

    Moves the source to the target. The source may be either a pointer to a
    mobile, a pointer to an item, or an array of mobile or item pointers. The
    number of successfully moved entities is returned. You CANNOT use
    keywords, if you feel the need to use a keyword, then use
    %getItemPointer( keyword ), or %getMobPointer( keyword ) to get a pointer. 
    The target may be a pointer to a mobile, a pointer to a container item, a
    pointer to a room, or a room number. If the target is a pointer to a
    character then you may optionally supply a third parameter for a wear
    location. You may use the ID of the wear location or one of the following
    keywords:

        light               legs                rightWrist
        leftFinger          feet                rWrist
        lFinger             hands               wield
        rightFinger         arms                wielded
        rFinger             shield              wielding
        neck1               about               hold
        neck2               waist               held
        body                leftWrist
        head                lWrist              affects

Function: %nAct()

Aliases	%nAct( )
Parameters	string @text, integer @hideInvis, character @actor, object @object, character @victim, string @type [, integer @roomId [, integer @canIgnore ] ]

    This function behaves exactly like the %act() function with the exception
    that actions output can not be caught with the catch_act_act trigger
    handler. It's utility is in being able to use the $ macro expansions.

See Also	%act(), Act Macros

Function: %noteGetStat()

Aliases	%noteGetStat( )
Parameters	object @entity, string @statName

    Returns the value for a given statName that belongs to the note object.
    The entity may be an object pointer or object keyword. The statName may be
    any one of the following stat IDs:

        content

    Example:

    @message = %noteGetStat( @o, content )

Function: %noteSetStat()

Aliases	%noteSetStat( )
Parameters	object @entity, string @statName, mixed @value

    Sets the value for a given statName that belongs to the note object.  The
    entity may be an object pointer or object keyword. The statName may be any
    one of the following stat IDs:

        content

    Example:

    @burpScript =
    \   "while( 1 )                         \n"
    \   "{                                  \n"
    \   "   silentforce @n burp             \n"
    \   "   wait 20 + 1d120 secs            \n"
    \   "}                                  \n"
    \   "endwhile                           \n"

    //
    // Load a note object into an arbitrary room and set it's content. In
    // this case the content is a script... just for giggles and kicks.
    //
    @note = %load( object, 601, 24001 )
    %noteSetStat( @note, content, @burpScript )

    //
    // Now we evaluate the note onto a player but keep the room as the
    // owner so that renting doesn't clear it *heheh*. The actorChar is
    // the player which the script will see as @n.
    //
    eval -note @note -ownerRoom 24001 -actorChar Jabberwocky

    //
    // Purge the note since we don't need it anymore.
    //
    %purge( @note )

Function: %npcGetLoadCount()

Aliases	%npcGetLoadCount( )
Parameters	integer @vnum

    Returns the total number of mobiles currently in the game with the given
    vnum.

Function: %null()

Aliases	%null( )
Parameters	-

    Returns a null data type.

Function: %partyGetMobs()

Aliases	%partyGetMobs( ), %partyGetMobs( )
Parameters	character @entity

    Returns an associative array of all the creatures currently grouped with
    the target character entity (including the character entity). Character
    entity may be a character pointer or keyword.

    Example:

    cast 'soul strike' %arrayShuffle( %partyGetMobs( @this ) )->1

Function: %partyGetNpcs()

Aliases	%partyGetNpcs( )
Parameters	character @entity

    This function works just like %partyGetMobs() with the exception that it
    only returns the NPC (Non-Playing Character) matches.

    Example:

    cast 'soul strike' %arrayShuffle( %partyGetNpcs( @this ) )->1

Function: %partyGetPcs()

Aliases	%partyGetPcs( )
Parameters	character @entity

    This function works just like %partyGetMobs() with the exception that it
    only returns the PC (Playing Character) matches.

    Example:

    cast 'soul strike' %arrayShuffle( %partyGetPcs( @this ) )->1

Function: %partyRoomIsInFrontRow()

Aliases	%partyRoomIsInFrontRow( )
Parameters	mobile @target

    Returns 1 if the given @target is in the front row with respect to group
    members in the same room; otherwise returns 0.

    Example:

    if( %partyRoomIsInFrontRow( @n ) )
    {
        cast soul strike @n
    }
    endif

Function: %positionAtLeast()

Aliases	%positionAtLeast( )
Parameters	mobile @target, string @position

    Returns 1 if the given @target is at least of the given position;
    otherwise returns 0. The @target may be a text pointer or keyword. The
    @position must be one of the following position names:

        dead
        mortally wounded
        incapacitated
        stunned
        sleeping
        resting
        sitting
        fighting
        standing

    Incidentally they are also in order so "fighting" is less than "standing"
    and "stunned" is less than "resting" etc.

    Example:

    if( %positionAtLeast( @n, fighting ) )
    {
        headbutt @n
    }
    endif

Function: %positionAtMost()

Aliases	%positionAtMost( )
Parameters	mobile @target, string @position

    Returns 1 if the given @target is at least of the given position;
    otherwise returns 0. The @target may be a text pointer or keyword. The
    @position must be one of the following position names:

        dead
        mortally wounded
        incapacitated
        stunned
        sleeping
        resting
        sitting
        fighting
        standing

    Incidentally they are also in order so "fighting" is less than "standing"
    and "stunned" is less than "resting" etc.

    Example:

    if( %positionAtMost( @n, sleeping ) )
    {
        steal gold @n
    }
    endif

Function: %printValue()

Aliases	%printValue( )
Parameters	mixed @value, character @entity

    Displays the contents of the value to the character entity. This includes
    any nested value if it is an associative array. Character entity may be a
    character pointer or keyword.

Function: %pulseActivityDuration()

Aliases	%pulseActivityDuration( )
Parameters	[float @rounds]

    Returns the duration in seconds (possibly fractional) for the number of
    mobile activity rounds indicated by the @rounds parameter.

    Example:

        @waitTime = %pulseActivityDuration( 2 + 1d2 )
        wait @waitTime secs

Function: %pulseActivity()

Aliases	%pulseActivity( )
Parameters	[float @rounds]

    Causes the running script to delay for the period of time internally
    defined as PULSE_MOBILE. As far as the game relates this is the period of
    time between two rounds of a mobile being able to perform random actions. 
    If the @rounds parameter is provided then the script will pause for a
    multiple of the mobile pulse defined by @rounds.

Function: %pulseTickDuration()

Aliases	%pulseViolenceDuration( )
Parameters	[float @rounds]

    Returns the duration in seconds (possibly fractional) for the number of
    rounds of violence indicated by the @rounds parameter.

    Example:

        @stunTime = %pulseViolenceDuration( 2 + 1d2 )
        %stun( @mob, @stunTime )

Function: %pulseTick()

Aliases	%pulseTick( )
Parameters	[float @rounds]

    Causes the running script to delay for the period of time internally
    defined as PULSE_TICK. As far as the game relates this is the period of
    time known to players as 1 game hour. If the @rounds parameter is provided
    then the script will pause for a multiple of the tick pulse defined by
    @rounds.

Function: %pulseViolenceDuration()

Aliases	%pulseViolenceDuration( )
Parameters	[float @rounds]

    Returns the duration in seconds (possibly fractional) for the number of
    rounds of violence indicated by the @rounds parameter.

    Example:

        @stunTime = %pulseViolenceDuration( 2 + 1d2 )
        %stun( @mob, @stunTime )

Function: %pulseViolence()

Aliases	%pulseViolence( )
Parameters	[float @rounds]

    Causes the running script to delay for the period of time internally
    defined as PULSE_VIOLENCE. As far as the game relates this is the period
    of time between one combat round and another. If the @rounds parameter is
    provided then the script will pause for a multiple of the violence pulse
    defined by @rounds.

Function: %pure()

Aliases	%( ), %pure( )
Parameters	mixed @a [, mixed @b [, mixed @c [, ...]]]

    All arguments to this function are concatenated together and returned as a
    string value. This function is generally used to get pure expression
    evaluation within a non pure expression type.

    Example:

    echoto c @n You have %( @carriedGold + @bankGold ) in total!

Function: %purge()

Aliases	%purge( )
Parameters	mixed @entity [, mixed @entity2 [, mixed @entity3 [, ...] ] ]

    Purges the target entities from the game immediately. The number of purged
    entities is returned. Entity may be a mobile, object, exit, or buff
    pointer. It may also be a keyword for a mobile or object. Arrays of
    pointers may also be passed but the values may not be keywords (they must
    be pointers). it is strongly recommended that this function be given
    pointers rather than keywords. Keywords can cause improper targets to be
    purged when an unexpected target shares the keyword.

    Examples:

    %purge( @n, @t )

    %purge( %getItemPointer( gold_chain ) )

    %purge( %roomGetExits( 4611 )->east )

    %purge( %getItemsWithId( 123456 ) )

Function: %randBetween()

Aliases	%randBetween( ), %randBetween( ), %randBetween( )
Parameters	integer @min, integer @max

    A random number will be returned between the absolute value of min
    and the absolute value of max inclusive.

Function: %randK()

Aliases	%randK( ), %randK( ), %randK( ), %randK( )
Parameters	integer @rollUnder

    A single dice with a thousand faces will be rolled. If the number rolled
    is less than the given rollUnder value then 1 will be returned, otherwise
    0 will be returned.

Function: %randPlayer()

Aliases	%randPlayer( )
Parameters	[array @criteria]

    Retrieves the name of a player at random from the database based on
    criteria set in the @criteria array. The following criteria are supported:

        global          - if set to 1 then a player name will be retrieved
                          from the database regardless of whether the player
                          is logged in or not. If set to 0 then a name will
                          only be returned for a player currently logged in.
                          This option has a default value of 1.

        minLevel        - restricts the random player name to any player whose
                          level is greater than or equal to minLevel.

        maxLevel        - restricts the random player name to any player whose
                          level is less than or equal to maxLevel. This option
                          has a default value of 150 (thus by default
                          immortals will not be returned).

        minExperience   - restricts the random player name to any player whose
                          experience is greater than or equal to minExperience.

        maxExperience   - restricts the random player name to any player whose
                          experience is less than or equal to minExperience.

    This function is used in many of the help files where examples of command
    use take mobile targets. For example, you can see its effect if you view
    the help for headbutt.

    Example:
    --------------------------------------------------------------------------

    @criteria->global   = 0
    @criteria->maxLevel = 10

    @name = %randPlayer( @criteria )

    commune @name sucks!!!

Function: %randSelect()

Aliases	%randSelect( )
Parameters	array @candidates [, number max [, string @chanceKey [, string @returnKey]]]

    Selects and returns an entry at random from an array of candidates. In its
    simplest form the key of the selected candidate is returned; however,
    other parameters can change this behaviour. The following parameters are
    supported:

        candidates  - A list of candidates from which to select a winner.
        
        max         - Maximum range for random value generation. By default
                      the max is 100. If set to true then it will be the total
                      sum of all chances. If the total sum of all chances
                      exceeds max, then max will be set to the total sum.
        
        chanceKey   - For candidates that have array values. This defines
                      which key points to the probability chance.
        
        returnKey   - By default the winning candidate's key/index is
                      returned. Set this to false to return the value itself
                      or set it to a non empty value to return the value for
                      the associated sub-key in the winning value (expected to
                      be an array).

    This function is used to simplify defining potential actions or prizes
    such that the deifnition structure can be fed to this function and the
    complicated work is done by the function.

    Example:

        // Random action to choose.

        @actions->dance = 10    // 10/100 => 10% chance
        @actions->smile = 20    // 20/100 => 20% chance
        @actions->growl =  4    //  4/100 =>  4% chance
        @actions->glare = 12    // 12/100 => 12% chance

        @action = %randSelect( @actions )

    Result:

        The @action variable will contain a value of "dance", "smile",
        "growl", "glare", or null. Since the combined chances only add up to
        46% there is a 54% chance of no action being selected (since the
        default range is 100).

    Example:

        @actions->dance = 10    // 10/200 =>  5% chance
        @actions->smile = 20    // 20/200 => 10% chance
        @actions->growl =  4    //  4/200 =>  2% chance
        @actions->glare = 12    // 12/200 =>  6% chance

        @action = %randSelect( @actions, 200 )

    Result:

        This time we have set the max range to 200 which has the effect of
        halving the probabilities of any action being selected. There is now
        a corresponding 77% chance of no action.

    Example:

        @actions->dance = 10    // 10/46 => 21.7% chance
        @actions->smile = 20    // 20/46 => 43.5% chance
        @actions->growl =  4    //  4/46 =>  8.7% chance
        @actions->glare = 12    // 12/46 => 26.1% chance

        @action = %randSelect( @actions, true )

    Result:

        This time we have set the max range to true which has the effect of
        making the function calculate the sum of all chances and using that as
        the range. Since the range is based exclusively on the candidates
        chance value, it is guaranteed that an entry will be selected with the
        shown probabilities.

    Example:

        @actions->dance->chance = 10
        @actions->dance->action = "dance " @r

        @actions->smile->chance = 20
        @actions->smile->action = "smile " @r

        @actions->growl->chance =  4
        @actions->growl->action = "growl " @r

        @actions->glare->chance = 12
        @actions->glare->action = "glare " @r

        @action = %randSelect( @actions, true, "chance" )

    Result:

        This time our candidates are arrays. As a result we need to set the
        third parameter, @chanceKey, to say where the chance information can
        be found. In our case we created an entry called chance and so we pass
        "chance" as the third parameter. Similar to earlier examples this will
        still return a value of "dance", "smile", "growl", or "glare". To use
        the more complicated action that targets a person in the room we would
        just get the value using @actions->@action->action :) The next example
        shows how to simplify this.

    Example:

        @actions->dance->chance = 10
        @actions->dance->action = "dance " @r

        @actions->smile->chance = 20
        @actions->smile->action = "smile " @r

        @actions->growl->chance =  4
        @actions->growl->action = "growl " @r

        @actions->glare->chance = 12
        @actions->glare->action = "glare " @r

        @action = %randSelect( @actions, true, "chance", false )

    Result:

        In this example we have added the fourth parameter, @returnKey, to
        false so that instead of returning the selected candidate's key it
        will instead return the value. Instead of using
        @actions->@action->action we can now just use @action->action. The
        next example simplifies this further:

    Example:

        @actions->dance->chance = 10
        @actions->dance->action = "dance " @r

        @actions->smile->chance = 20
        @actions->smile->action = "smile " @r

        @actions->growl->chance =  4
        @actions->growl->action = "growl " @r

        @actions->glare->chance = 12
        @actions->glare->action = "glare " @r

        @action = %randSelect( @actions, true, "chance", "action" )

    Result:

        In this example we have changed the fourth parameter, @returnKey, from
        false to "action". This time the returned value will be the value
        found at that key in the selected candidate's array. In other word,
        if the selected candidate was "growl" the returned value saved in
        @action would be "glare @r". So now we can just use @action.

    Example (Very Practical Example):

        @i = 0

        @i += 1
        @loot->@i->desc   = "a Super Awesome Sword"
        @loot->@i->chance = 5
        @loot->@i->count  = 1
        @loot->@i->itemId = 12001

        @i += 1
        @loot->@i->desc   = "some semi-decent potions of self reflection"
        @loot->@i->chance = 15
        @loot->@i->count  = 3
        @loot->@i->itemId = 12008

        @i += 1
        @loot->@i->desc   = "trash, some seriously disappointing trash"
        @loot->@i->chance = 80
        @loot->@i->count  = 3
        @loot->@i->itemId = 12042

        @prize = %randSelect( @loot, true, "chance", false )

        %echoTo( "Something falls from the sky, it's... " @prize->desc )
        while( @prize->count > 0 )
        {
            %load( item, @prize->itemId, @room )
            @prize->count -= 1
        }
        endwhile

See Also	%randSelectMulti(), %randSelectMultiUnique()

Function: %roomGetExits()

Aliases	%roomGetExits( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the exits
    currently in the given room. The list is indexed by the direction of the
    exit (north, east, south, west, up, down). If no parameter is used, then
    the room in which the script owner resides is used as default. The entity
    may be one of the following: an explicit room number; a pointer to a room,
    character, or object; a keyword for a mob, or object. If the entity is
    valid then the room in which the entity resides will be searched.

    Example:

    @exits = %roomGetExits( @n )

Function: %roomGetItems()

Aliases	%roomGetItems( ), %roomGetItems( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the objects
    currently in the given room. The list is indexed by consecutive integers
    counting from 1 onward. If no parameter is used, then the room in which
    the script owner resides is used as default. The entity may be one of the
    following: an explicit room number; a pointer to a room, character, or
    object; a keyword for a mob, or object. If the entity is valid then the
    room in which the entity resides will be searched.

Function: %roomGetMobs()

Aliases	%roomGetMobs( ), %roomGetMobs( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the
    characters currently in the given room. The list is indexed by consecutive
    integers counting from 1 onward. If no parameter is used, then the room in
    which the script owner resides is used as default. The entity may be one
    of the following: an explicit room number; a pointer to a room, character,
    or object; a keyword for a mob, or object. If the entity is valid then the
    room in which the entity resides will be searched.

Function: %roomGetNpcs()

Aliases	%roomGetNpcs( )
Parameters	[mixed @entity]

    This function works just like %roomGetMobs() with the exception that it
    only returns the NPC (Non-Playing Character) matches.

Function: %roomGetPcs()

Aliases	%roomGetPcs( )
Parameters	[mixed @entity]

    This function works just like %roomGetMobs() with the exception that it
    only returns the PC (Playing Character) matches.

Function: %roomGetStat()

Aliases	%roomGetStat( ), %roomGetStat( )
Parameters	room @entity, string @statName

    Returns the value for a given statName that belongs to the room. The
    entity may be "here" or a room vnum. The statName may be any one of the
    following stat IDs:

        id              - vnum of room
        uniqueid        - unique ID of room
        zoneid          - zone to which room belongs
        areaid          - area to which room belongs
        level           - level of room (for casting)
        terraintype     - type of terrain (inside, mountain, air, ...)
        terraintypeid   - id of terrain type (deprecated)
        sizetype        - type of room size (micro, tiny, enormous, ...)
        sizetypeid      - is of size type (deprecated)
        name            - name (or title if you will) of room
        description     - room description when looking
        lights          - number of light sources in room

        exitnorth       - pointer to north exit
        exiteast        - pointer to east exit
        exitsouth       - pointer to south exit
        exitwest        - pointer to west exit
        exitup          - pointer to up exit
        exitdown        - pointer to down exit

    The following terrain types are recognized:

        inside          - bedroom, living room, tunnel, ...
        city            - cobblestone road, path, ...
        field           - flowers, grass, ...
        forest          - trees everywhere
        hills           - rolling hills with rounded tops
        mountain        - steep hills often with pointy tops
        swimWater       - water through which you can walk
        noSwimWater     - water for which you will need a boat
        underwater      - glug, glug, for the fishes
        desert          - extremely dry area, maybe with sand
        air             - flap, flap... see Icarus

    The following size types are recognized:

        micro           - bugs and stuff can go here
        tiny            - mice, voles, and faeries
        small           - halflings
        medium          - humans
        large           - dumb trolls
        huge            - dragons
        enormous        - whatever

    The following flag types are recognized and return 1 or 0:

        isdark          - is the room currently dark?
        islight         - is the room currently not dark?
        isdeathtrap     - is the room a deathtrap?
        isnomobs        - does the room allow mobiles?
        isinside        - is the room considered inside?
        isindoors       - alias for isinside.
        isnoaggro       - are mobiles allowed to be aggressive?
        isgladiator     - is killing in the room considered gladiatorial?
        isfreedeath     - is a death in this room a free death?
        isnomagic       - is magic disallowed in this room?
        istunnel        - is the room considered to be a tunnel?
        isprivate       - is the room considered private? (2 chars max)
        isnosummon      - can a mobile or player be summoned to the room?
        isshop          - is the room a shop?
        islawful        - not supported yet!
        isneutral       - not supported yet!
        ischaotic       - not supported yet!

    Example:

        if( %roomGetStat( here, terraintype ) == mountain )
        {
            echoto char @n The mountainous terrain makes for tiring travel.
        }
        endif

Function: %roomSetStat()

Aliases	%roomSetStat( ), %roomSetStat( )
Parameters	room @entity, string @statName, mixed @newValue

    Sets the value for a given statName that belongs to the room. The entity
    may be "here" or room vnum. The statName may be any one of the following
    stat IDs:

        level           - level of room (for casting)
        terraintype     - type of terrain (inside, mountain, air, ...)
        terraintypeid   - id of terrain type (deprecated)
        sizetype        - type of room size (micro, tiny, enormous, ...)
        sizetypeid      - is of size type (deprecated)
        name            - name (or title if you will) of room
        description     - room description when looking

    See %roomGetStat() documentation for terrain and size types.

    Example:

    if( @pulledLever )
    {
        echoto char @n Your foolish act has caused the room to begin
        \   filling with water!

        %roomSetStat( here, terraintype, underwater )
    }
    endif

Function: %runCommand()

Aliases	%doQueued( )
Parameters	mixed @sourcePointer, string @command [, array @options]

    Runs the given @command string through the MUD's interpreter as though the
    @sourcePointer entity had issued the command directly. Unlike
    %fastCommand(), any issued command will be accompanied by its usual delay
    features. For the most part you will want this function, it is the proper
    way to pass a command back through the MUD if some criteria was not met.
    The options array allows you to specify some flags for how the command is
    treated by the MUD's ineterpreter. The following flags may be set.

    noSpecials
        - Prevent command from being caught by special procedures. The default
          for this option is to ALLOW specials procedures.

    ignoreOverrides
        - Prevent trigger from catching command and running a BlobbieScript.
          The default for this option is to NOT IGNORE overrides. If you are
          actually handling the command but still want the normal
          functionality to run then set this to true, if however you are not
          handling the command and want other entities to have a chance at it,
          then either omit this or set it to false.

    skipCommOut
        - Ensures the actor doesn't say "Yes, sir!". The default value is to
          allow it to be said. I don't really recall why this flag exists but
          I'm sure it has a purpose.

    skipAbort
        - If the command is being run in the midst of another command that is
          an action command (hunt, cast, kick, etc.) then this will prevent
          the running command from being aborted.

    delayed
        - This is the same as the delayAppend flag.

    delayedPrepend
        - Instead of running the command immediately it is placed at the
          beginning of the @actor's command queue and so will run as soon as
          the current command completes.

    delayedAppend
        - Instead of running the command immediately it is placed in the
          @actor's command queue and run when all previous commands have
          completed.

    forceLook
        - Some trigger's force the @actor to view the contents of a room, when
          this happen the user will not double view the room because
          internally this state is tracked. However, at times this is not the
          desired affect, for instance your @actor might have just been
          teleported by your script and so you want to ensure he views the
          contents of his new destination room. In such cases you will set
          this flag.

    Example:

        %doQueued( @n, "look in backpack" )

    Example:

        @opts->forceLook = true
        %do( @n, "look", @opts )

Function: %saveVersusBreathMod()

Aliases	%saveVersusBreathMod( )
Parameters	integer @value

    Often when a mobile or player saves versus something if there is damage
    associated with the save then the damage if reduced. This function will
    take a value (presumably damage) and reduce it according the internal
    reduction system. This allows any updates to the reduction calculation to
    be propogated throughout the game which results in greater game
    consistency and easier maintenance.

Function: %saveVersusBreath()

Aliases	%saveVersusBreath( )
Parameters	character @victim, entity @actor, integer @level

    A dice roll is made to determine if @victim saves versus breath. The dice
    roll is calculated against the @victim's save versus breath modifier and
    the @level provided. If the @victim makes their save then 1 is returned;
    otherwise 0 is returned.

Function: %saveVersusParalyzeMod()

Aliases	%saveVersusParalyzeMod( )
Parameters	integer @value

    Often when a mobile or player saves versus something if there is damage
    associated with the save then the damage if reduced. This function will
    take a value (presumably damage) and reduce it according the internal
    reduction system. This allows any updates to the reduction calculation to
    be propogated throughout the game which results in greater game
    consistency and easier maintenance.

Function: %saveVersusParalyze()

Aliases	%saveVersusParalyze( )
Parameters	character @victim, entity @actor, integer @level

    A dice roll is made to determine if @victim saves versus paralysis. The
    dice roll is calculated against the @victim's save versus paralysis
    modifier and the @level provided. If the @victim makes their save then 1
    is returned; otherwise 0 is returned.

Function: %saveVersusPetrifyMod()

Aliases	%saveVersusPetrifyMod( )
Parameters	integer @value

    Often when a mobile or player saves versus something if there is damage
    associated with the save then the damage if reduced. This function will
    take a value (presumably damage) and reduce it according the internal
    reduction system. This allows any updates to the reduction calculation to
    be propogated throughout the game which results in greater game
    consistency and easier maintenance.

Function: %saveVersusPetrify()

Aliases	%saveVersusPetrify( )
Parameters	character @victim, entity @actor, integer @level

    A dice roll is made to determine if @victim saves versus petrification.
    The dice roll is calculated against the @victim's save versus
    petrification modifier and the @level provided. If the @victim makes their
    save then 1 is returned; otherwise 0 is returned.

Function: %saveVersusPrayerMod()

Aliases	%saveVersusPrayerMod( )
Parameters	integer @value

    Often when a mobile or player saves versus something if there is damage
    associated with the save then the damage if reduced. This function will
    take a value (presumably damage) and reduce it according the internal
    reduction system. This allows any updates to the reduction calculation to
    be propogated throughout the game which results in greater game
    consistency and easier maintenance.

Function: %saveVersusPrayer()

Aliases	%saveVersusPrayer( )
Parameters	chacracter @victim, entity @actor, integer @level

    A dice roll is made to determine if @victim saves versus prayers. The dice
    roll is calculated against the @victim's save versus prayer modifier and
    the @level provided. If the @victim makes their save then 1 is returned;
    otherwise 0 is returned.

Function: %saveVersusRodMod()

Aliases	%saveVersusRodMod( )
Parameters	integer @value

    Often when a mobile or player saves versus something if there is damage
    associated with the save then the damage if reduced. This function will
    take a value (presumably damage) and reduce it according the internal
    reduction system. This allows any updates to the reduction calculation to
    be propogated throughout the game which results in greater game
    consistency and easier maintenance.

Function: %saveVersusRod()

Aliases	%saveVersusRod( )
Parameters	character @victim, entity @actor, integer @level

    A dice roll is made to determine if @victim saves versus rods. The dice
    roll is calculated against the @victim's save versus rod modifier and the
    @level provided. If the @victim makes their save then 1 is returned;
    otherwise 0 is returned.

Function: %saveVersusSpellMod()

Aliases	%saveVersusSpellMod( )
Parameters	integer @value

    Often when a mobile or player saves versus something if there is damage
    associated with the save then the damage if reduced. This function will
    take a value (presumably damage) and reduce it according the internal
    reduction system. This allows any updates to the reduction calculation to
    be propogated throughout the game which results in greater game
    consistency and easier maintenance.

Function: %saveVersusSpell()

Aliases	%saveVersusSpell( )
Parameters	character @victim, entity @actor, integer @level

    A dice roll is made to determine if @victim saves versus spells. The dice
    roll is calculated against the @victim's save versus spell modifier and
    the @level provided. If the @victim makes their save then 1 is returned;
    otherwise 0 is returned.

Function: %scriptCallMultiple()

Aliases	%scriptCallMultiple( )
Parameters	mixed @owner, string @name [, @param1 [, @param2 [, ...]]]

    Runs the script with @name presumably defined for each of the targets in
    the @targets array. The parameters are passed to the script and assume the
    variable names the script itself sets out for them. This function is used
    in conjunction with the catch_call_script trigger type which is described
    in the triggers documentation. Note that if the script returns a value you
    can retrieve it by assigning the value of running the function. The
    returned values will be returned in an array with indexes corresponding to
    the index of the target in the @targets array.

    Example:

        //
        // Calls a script on multiple targets (in this example all the mobs
        // in zone @room->zoneId having the ID 145200.
        //
        @room = %getRoomPointer( @n )
        @targets = %filterZoneId( %getMobsWithId( 145200 ), @room->zoneId )
        %scriptCallMultiple( @targets, "huntIntruder", @n )

Function: %scriptCall()

Aliases	%scriptCall( )
Parameters	mixed @owner, string @name [, @param1 [, @param2 [, ...]]]

    Runs the script owned by the owner entity which has the given name.  The
    parameters are passed to the script and assume the variable names the
    script itself sets out for them. This function is used in conjunction with
    the catch_call_script trigger type which is described in the triggers
    documentation. This combination is powerful but you may be looking for the
    solution procided by the %scriptUsurp() function which your are STRONGLY
    advised to read about now. Note that if the script returns a value you can
    retrieve it by assigning the value of the running the function.

    Example:

        %scriptCall( @n, "repairItem" )

Function: %scriptUsurp()

Aliases	%scriptUsurp( )
Parameters	mixed @owner, string @name [, @param1 [, @param2 [, ...]]]

    This function is "almost" exactly like the %scriptCall() function with one
    extremely useful difference. This runs the script owned by the owner
    entity which has the given name BUT when the script is run all commands
    are processed as though the entity calling the script were the actual
    owner of the script. This is useful because you could share an entire
    combat system in a script which is then invoked via %scriptUsurp() and
    thus processed as though the script had been defined for the entity
    itself. The parameters are passed to the script and assume the variable
    names the script itself sets out for them. This function is used in
    conjunction with the catch_call_script trigger type which is described in
    the triggers documentation. This combination is powerful but you may be
    looking for the solution provided by the %scriptCall() function which your
    are STRONGLY advised to read about now. Note that if the script returns a
    value you can retrieve it by assigning the value of the running the
    function.

    Example:

        %scriptUsurp( @n, "guardCombat" )

Function: %serialize()

Aliases	%serialize( )
Parameters	mixed @data

    Takes any data type or variable and serializes the contents into an XML
    string encoding. This function generally won't be used by builders,
    however the underlying serialization mechanism is used to store persistent
    data in the MySQL database.

    Example:

    @data->name  = %getShortName( @n )
    @data->level = %getLevel( @n )
    @data->race  = %getRace( @n )

    signal world 1 c death_proclaimer player_died %serialize( @data )

Function: %serverGetProfile()

Aliases	%serverGetProfile( )
Parameters	-

    Returns the profile for the currently running server instance. This
    function is useful for adding debugging output that you don't want to be
    available on the main game port.

    Example:

    if( %serverGetProfile() == "testport" )
    {
        %printValue( %contextGetVars(), Blobbie )
    }
    endif

Function: %serverLog()

Aliases	%serverLog( )
Parameters	string @message

    Generates a server log entry which can be used for tracking various
    important events. Such as when the repair gnome destroys a player's
    equipment *heheh*.

    Example:

    %serverLog( "Repair gnome destroyed " @O " belonging to " @N "." )

Function: %setEntityVar()

Aliases	%setEntityVar( )
Parameters	mixed @entity, string @varName, mixed @value

    Sets the value of the variable with name varName that is within the
    variable context of the entity. If the variable does not exist then a new
    one is created in the context of the entity. The entity may be a pointer
    to a room, mob, or object. It may also be a keyword of a mob or object. If
    the entity is not valid then the value is assigned to the global variable
    context. This function is better than using the "setvar" mud command since
    it guarantees the variable's value is update immediately. Commands issued
    by the owner to the mud interpreter are queued for each execution window a
    script's process is given and evaluated when the execution window closes.

    Example:

    %setEntityVar( @n, questStage, "getting statue" )

Function: %setHatred()

Aliases	%setHatred( )
Parameters	mobile @hated [, mobile @hater]

    This causes the given @hater to start hating the given @hated. If no
    parameter is given for @hater, then the script owner is assumed. The
    values may either be text pointers or keywords for the target mobiles.

    Example:

    %setHatred( @n, @gateGuard )

Function: %setPlayerVar()

Aliases	%setPlayerVar( )
Parameters	mixed @entity, string @varName, mixed @value

    Sets the value of the variable that is within the saved player file
    persistence context of the entity. Since rooms cannot be saved to player
    files and there can only ever be one instance of a room with a given vnum,
    this function has identical functionality to the %setSavedVar() function
    when applied to a room. The entity may be a pointer to a room, mob, or
    object. It may also be a keyword of a mob or object or the vnum of a room.
    If the variable is not found then null is returned. These variables are
    saved in the player's data file and are restored whenever the player
    re-enters the game.

    Example:

    %setPlayerVar( @n, lastEnteredSkurvash, %getRealTime( absSec ) )

Function: %setSavedVar()

Aliases	%setSavedVar( )
Parameters	mixed @entity, string @varName, mixed @value [, string @entityType ]

    Sets the value of the variable that is within the persistent variable
    context of the entity. The entity may be a pointer to a room, mob, or
    object. It may also be the vnum of a room or a keyword of a mob or object.
    A query is made to update the stored value of the variable everytime this
    function is called. For this reason it is advisable to not call the
    function for intermediate updates during calculations since the query is
    resource consuming. The value being set is returned. It is important to
    know that there can only be one shared saved variable OF THE SAME NAME for
    all mobs, or all objects, or all rooms with the same vnum.

    The @entity parameter may also be set to the vnum of a mobile or object. 
    If this is done then the optional @entityType parameter must be set to
    "mobile" or "object" respectively.

    Example:

    if( %isPc( @n )
    {
        %setSavedVar( 10005, towerOwner, %getShortName( @n ) )
    }
    endif

Function: %setSilenceOff()

Aliases	%setSilenceOff( )
Parameters	-

    Turns silence off thus causing ALL output to players to occur as would
    normally be expected.

    Example:

    %setSilenceOn()
    kick @n
    %setSilenceOff()

Function: %setSilenceOn()

Aliases	%setSilenceOn( )
Parameters	-

    Prevents ALL output from going to players. Since this could potentially
    wreak havoc on the game by forgetting to turn it back off, it will
    automatically be turned off when your script returns control to the MUD.
    For this reason you will need to put it in a protected block. This may
    change in the future as I may add support for the script context to
    remember it's silence state so I do recommend you still make the effort to
    turn it off manually.

    Example:

    %setSilenceOn()
    damage room pc 3d5 8
    %setSilenceOff()

Function: %setVar()

Aliases	%setVar( )
Parameters	string @varName, mixed @value

    Sets the value of the variable with name varName that is owned by the
    script owner. If the variable does not exist then a new one is created in
    the context of the script owner. This function is better than using the
    "setvar" mud command since it guarantees the variable's value is update
    immediately. Commands issued by the owner to the mud interpreter are
    queued for each execution window a script's process is given and evaluated
    when the execution window closes.

    Example:

    %setVar( lastVisitor, @n )

Function: %skillAffectAdd()

Aliases	%skillAffectAdd( )
Parameters	character @target, mixed @skill, string @location, integer @modifier, integer @duration [, mixed @flags ]

    Applies the affect described by @skill to the given @target. The @skill
    may either be the name of the skill ("detect invisible") or it may be the
    ID of the skill. The @location describes what type of stat the affect
    modifies. The following locations are recognized:

        abilities           hurtStealth             savePrayer
        ac                  immune                  saveRod
        age                 intelligence            saveSpell
        charisma            level                   sex
        class               mana                    skill
        constitution        manaRegen               spell
        damage              manaUpkeep              strength
        damroll             material                striking
        dexterity           moves                   susceptable
        eatSpell            movesRegen              thac0
        experience          movesUpkeep             thaco
        gold                pairedWeapon            timer
        height              rent                    visible
        hitroll             resistant               weaponSpell
        hits                saveAll                 weight
        hitsRegen           saveBreath              wisdom
        hitsUpkeep          saveParalyze
        hurtArcana          savePetrify             NONE

    The @modifier denotes the amount by which to modify the given location.
    For instance the @location might be set to strength and the @modifier set
    to 2 which would increase the target's strength by 2 points for the given
    @duration. The @duration parameter should be set to the number of in game
    hours (ticks) that the affect should last. The final, optional parameter,
    @flags can be set to the name of a boolean affect, or alternatively to an
    array whose values are names of boolean affects. The following boolean
    affect names are recognized:

        anti magic              feeble mind         mana shield
        bash                    feign death         move impaired
        blindness               fiery vortex        poison
        charm                   fists of fury       protection from evil
        chill touch             fly                 regenerate
        curse                   follow              sanctuary
        deadly poison           glamorie            sense life
        death's door            half hp regen       shide
        detect evil             half mana regen     shocking grasp
        detect invisibility     half move regen     sickness
        detect magic            hide                silence
        dominated               infravision         sleep
        double hp regen         insanity            snare
        double mana regen       invisibility        sneak
        double move regen       invulnerability     water breath
        fear                    lich touch          water walk

    Sometimes you will only want to have a boolean affect like "fly" or
    "infravision". In these case you can set the @location value to NONE, and
    the modifier to 0. Note that this function only applies affects defined by
    the traditional internal affect system.

    Example 1:
    --------------------------------------------------------------------------

    //
    // Affect the @target with "bless" spell which provides +1 to hitroll
    // and enables them to "detect evil" for 6 hours (ticks).
    //

    %skillAffectAdd( @target, bless, hitroll, 1, 6, "detect evil" )


    Example 2:
    --------------------------------------------------------------------------

    //
    // Affect the @target with "bless" spell which provides ability to "sense
    // life", "detect evil", "detect magic", "detect invisibility", and
    // "infravision" for 10 hours (ticks).
    //

    @bits->1 = "sense life"
    @bits->2 = "detect evil"
    @bits->3 = "detect invisibility"
    @bits->4 = "detect magic"
    @bits->5 = "infravision"

    %skillAffectAdd( @target, "bless", NONE, 0, 10, @bits )

Function: %skillAffectExists()

Aliases	%skillAffectExists( )
Parameters	character @target, mixed @skill

    Checks to see if the @target is affected by the given @skill. The @skill
    may either be the name of the skill ("detect invisible") or it may be the
    ID of the skill. If the affect exists then 1 is returned; otherwise 0 is
    returned. Note that this function does not look for affects implemented by
    affect objects, but rather is limitted to traditional internal affect
    system.

    Example:
    --------------------------------------------------------------------------

    if( %skillAffectExists( @target, "detect evil" ) )
    {
        %echoTo( "You can already detect the auras of evil!\n", @target )
        return
    }
    endif

Function: %skillAffectItemExists()

Aliases	%skillAffectItemExists( )
Parameters	character @target, mixed @skill

    Checks to see if the @target is affected by an affect object of the
    @skill. The @skill may either be the name of the skill ("poison") or it
    may be the ID of the skill. If the affect exists then 1 is returned;
    otherwise 0 is returned. Note that this function does not look for
    traditional internal affects that are not implemented as affect objects.

    Example:
    --------------------------------------------------------------------------

    if( !%skillAffectItemExists( @target, "disease" ) )
    {
        cast disease @target
    }
    endif

Function: %skillAffectMerge()

Aliases	%skillAffectMerge( )
Parameters	character @target, mixed @skill, string @location, integer @modifier, integer @duration [, mixed @flags [, @aveDuration [, @aveModifier ]]]

    This function enables the merging of an existing affect of the given skill
    @type with affect defined by this function's parameters. For the first 6
    parameters see the description for the %skillAffectAdd() function. The
    @aveDuration parameter should be set to a 1 or a 0. When set to 1 the
    duration of the existing affect and the current affect to be merged are
    averaged. The @aveDuration parameters should also be set to a 1 or 0. When
    set to 1 the modifier amount of the existing affect and the current affect
    ot be marged are averaged. the default values for @aveDuration and
    @aveModifer are both 0 -- in other words the new merge affect takes the
    duration and modifier provided to this function.

    Example:
    --------------------------------------------------------------------------

    //
    // Sleep target for 10 hours (ticks). If the target is already asleep
    // then they will now sleep for another 10 hours.
    //
    %skillAffectMerge( @target, "sleep", NONE, 0, 10 )

Function: %skillAffectRemove()

Aliases	%skillAffectRemove( )
Parameters	character @target, mixed @skill

    Attempts to remove the affect described by @skill from the given @target.
    The @skill may either be the name of the skill ("detect invisible") or it
    may be the ID of the skill. If the affect is removed then 1 is returned;
    otherwise 0 is returned. Note that this function does not look for affects
    implemented by affect objects, but rather is limitted to traditional
    internal affect system.

    Example:
    --------------------------------------------------------------------------

    if( %skillAffectRemove( @target, "sanctuary" ) )
    {
        talk @target Hah! I have made you defenseless!
    }
    else
    {
        talk @target Hah! You are a defenseless weakling!
    }
    endif

Function: %skillCheckGain()

Aliases	%skillCheckGain( )
Parameters	mobile @target, mixed @skill

    Using this function the @target gets the opportunity for their effective
    proficiency in the given @skill to make a gain. If the gain is successful
    then the function returns 1; otherwise 0 is returned. The @target may be a
    text pointer or keyword. The @skill may eithe rbe the name of the skill or
    the ID of a skill.

    Example:

    %skillCheckGain( @n, forage )

Function: %skillGetELevel()

Aliases	%skillGetELevel( ), %skillGetELevel( ), %skillGetELevel( ), %skillGetELevel( ), %skillGetELevel( )
Parameters	character @entity, mixed @skillId

    Returns the amount that the given character has learned the skill defined
    by skillId. The skillId may either be the direct numerical ID of a skill
    or the partial name of the skill. The character entity may be a character
    pointer or a keyword of a character.

Function: %skillGetId()

Aliases	%skillGetId( )
Parameters	string @skillName

    This function can be used to get the internal ID associated with a skill.
    This can be useful when manipulating the affects on items or mobiles. When
    possible it is better to use the skill name, but at times accessing its
    internal ID can be useful.

    Example:

    if( %isValid( (@buff = %buffGetByLabel( @item, "skillBonus" )) ) )
    {
        @skillId = %skillGetId( "lightning bolt" )
        @buff->typeExtra = @skillId
    }
    endif

Function: %skillGetQuality()

Aliases	%skillGetQuality( )
Parameters	mobile @target, mixed @skill

    This function will return the @target's quality value for the given
    @skill. The quality can then be used to determine whether they succeed at
    some action or how well they succeed at some action (duration, power,
    etc). The @target may be a text pointer or keyword. The @skill may either
    be the name of the skill or the ID of a skill.

    Example:

    @quality = %skillGetQuality( @n, "lich touch" )

    if( 1d(101 MAX (@quality + 5)) < @quality )
    {
        %echoTo(
        \   "When you place your withered hands into the river you can feel "
        \   "the life of it's inhabitants slowly being absorbed. Dead fish "
        \   "begin float down the river and still you continue to draw life "
        \   "from the river.", @n )

        wait 5 secs

        //
        // Something cool that could be part of a quest.
        //
    }
    endif

Function: %skillSetELevel()

Aliases	%skillSetELevel( )
Parameters	@entity, mixed @skill, integer @percent [, integer @canTeach]

    Sets the skill level of the @entity to the given @percentage for the
    given @skill. Optionally the fourth parameter, @canTeach, can be set to
    a 1 or a 0 to set whether the @entity can teach or not teach the given
    @skill. The value of @skill may either be the name of the skill or the
    ID of the skill.

    *** Please note this function will log a message when used on a PC. The
        log message will indicate the area, entity, script, skill being set,
        old value, new value, and target player. Do not use inappropriately.

Function: %spell()

Aliases	%spell( )
Parameters	mixed @spell, string @castType [, mixed @targets [, integer @level [, integer @quality [, entity @actor [, entity @master]]]]]

This function can be used to invoke a spell at the lowest level. Unlike using
the hackish "usespell" or "silentspell" commands, %spell() enables the
builder, command, or spell scripter to invoke a spell with all the available
configuration options to make it work exactly as planned. For instance, the
spell can be invoked to work as though it were cast, as though it were on a
wand, as though it were on a staff, or even as though it were on a weapon.
While these might all seem the same to a novice they can have distinct and
advantageous differences. For instance, invokation of %spell() with @spellType
set to "staff" will cause the spell to take on area effect properties.
Additionally, the scripter can customize other variables such as the spell's
level, quality, precise targets, etc.

Unlike many other functions, the %spell() function supports only a small set
of actual parameters, the rest of the customization must be provided by
declaring the custom variables within the script context itself. The reason
for this is to simplify the function for it's most common uses, while making
it possible to easily punt functionality from a scripted spell to a sub-spell.
For instance when a player casts "major heal", the spell actually invokes the
"cure blindness" and "remove poison" spells so that there is no duplication of
code and if either spell is updated, then the "heal" spell will automatically
receive those updates too. All "contextual" parameters are optional and will
receive defaults if not specified.

Customization criteria and how they may be defined:

    @spell              - parameter
    @spellType          - parameter
    @targets            - parameter, context
    @level              - parameter, context, owner
    @quality            - parameter, context, owner
    @actor              - parameter, context, owner
    @master             - parameter, context
    @command            - context
    @arguments          - context
    @commandId          - context
    @commandUserFlags   - context
    @commandSrcFlags    - context
    @commandAttFlags    - context
    @castString         - context
    @costMana           - context
    @costMovement       - context
    @costHitpoints      - context
    @castingTime        - context

The @spell can be either the name of a spell or the ID of a spell. It is
strongly suggested that the spell's name be used for portability and
readability.

Other than @spell, all of the other parameters are described in detail at the
following URL:

    http://www.wocmud.org/Carnage/documents/display.php/documentID/26

In addition to the description for @targets, the variable may also be a
pointer to a single entity upon which to apply the spell.

Example:

    //
    // Cast magic missile on the entire room as though from a staff. The
    // quality will be random between 101 and 120.
    //
    %spell( "magic missile", "staff", %roomGetMobs(), 50, 100 + 1d20 )

Function: %sprintf()

Aliases	%sprintf( )
Parameters	string @format [, mixed @p1 [, mixed @p2 [, ...]

    Functionally equivalent to the C version of sprintf, this function can be
    used to format data for printing or echoing. Make sure when echoing that
    you use the appropriate semantics to prevent wrapping/space collapsing
    where necessary.

    For details on the format parameter you can go here:

        http://www.cplusplus.com/ref/cstdio/sprintf.html


    Example:
    --------------------------------------------------------------------------

    @aveText = %sprintf( "The average is: %.2f", @average )

Function: %stringExplode()

Aliases	%stringExplode()
Parameters	string @text, string @separator

    This function will split apart @text whenever @separator is encountered. 
    The results are returned as an array of text pieces.

    Example:

        %printValue( %stringExplode( "1-2-3-4-5-6", "-" ), @self )

    Output:

        [] => (array)
        (
            [1] => (string)[1]
            [2] => (string)[2]
            [3] => (string)[3]
            [4] => (string)[4]
            [5] => (string)[5]
            [6] => (string)[6]
        )

See Also	%arrayImplode()

Function: %stringFindI()

Aliases	%stringFindI()
Parameters	string @needle, string @haystack

    This function will return the number of occurences of the needle in the
    haystack. This function differs from the %stringFind() function because it
    matches the needle regardless of case.

    Example:

        @text = "One one Two two Three three Four four"
        echo "Two" occurs in "@text" %stringFindI( Two, @text ) times.

    Output:

        "Two" occurs in "One one Two two Three three Four four" 2 times.

Function: %stringFind()

Aliases	%stringFind()
Parameters	string @needle, string @haystack

    This function will return the number of occurences of the needle in the
    haystack.

    Example:

        @text = "One one Two two Three three Four four"
        echo "Two" occurs in "@text" %stringFind( Two, @text ) time.

    Output:

        "Two" occurs in "One one Two two Three three Four four" 1 time.

Function: %stringFormat()

Aliases	%stringFormat( )
Parameters	string @text, bool @withColour, integer @width

    Formats and returns the given @text, optionally with colour when
    @withColour is set to a value that evaluates to true, and wrapped at the
    given @width.

    The following tags can be used in the content of @text to provide extra
    formatting information to the engine:

        <normal>    - return colouring to normal screen defaults
        <bold>      - enable high intensity for colours
        <black>     - black (dark gray when bold enabled)
        <red>       - red (bright red when bold enabled)
        <green>     - green (bright green when bold enabled)
        <brown>     - brown (yellow when bold enabled)
        <blue>      - blue (bright blue when bold enabled)
        <magenta>   - magenta (bright magenta when bold enabled)
        <cyan>      - cyan (bright cyan when bold enabled)
        <gray>      - gray (white when bold enabled)
        <blackBg>   - black background
        <redBg>     - red background
        <greenBg>   - green background
        <brownBg>   - brown background
        <blueBg>    - blue background
        <magentaBg> - magenta background
        <cyanBg>    - cyan background
        <grayBg>    - gray background
        <newLine>   - force a newline
        <space>     - force a space
        <art>       - content between two <art> tags is not formatted

    Additionally the following caveats are applied when formatting the text:

        - Colour tags take up no space (includes normal and bold).

        - Newlines are ignored unless the following line is indented, or a
          second newline is encountered.

        - Lines that are indented but which are too long will wrap without
          indentation.

        - Single tokens that do not fit on current line are wrapped to next
          line or if they do not fit on a newline of their own then the token
          is split.

        - Tokens are gathered from sequential characters not including a
          space.

    Example:

    @text =
    \   %stringFormat(
    \       %areaGetStat( elkin, comments ), @n->flags->ansiColour, 80 )

Function: %stringGetSize()

Aliases	%stringGetSize( ), %stringGetlength( )
Parameters	string @value

    Returns the length of the given string, that is it counts the number of
    characters in the string and returns the count.

    Example:

        @text = "This is some sample text!"
        echo Size: %stringGetSize( @text )

    Output:

        Size: 25

Function: %stringIsPrefixI()

Aliases	%stringIsPrefixI()
Parameters	string @needle, string @haystack

    Returns 1 if the string defined by @needle is a case-insensitive prefix
    for the string defined by @haystack; otherwise returns 0.

    Example:

        if( %stringIsPrefixI( @input, "High" ) )
        {
            talk @n You have chosen high!
        }
        else
        if( %stringIsPrefixI( @input, "Low" ) )
        {
            talk @n You have chosen low!
        }
        else
        {
            talk @n You are an idiot!
        }
        endif

Function: %stringIsPrefix()

Aliases	%stringIsPrefix()
Parameters	string @needle, string @haystack

    Returns 1 if the string defined by @needle is a case-sensitive prefix for
    the string defined by @haystack; otherwise returns 0.

    Example:

        if( %stringIsPrefix( @input, "high" ) )
        {
            talk @n You have chosen high!
        }
        else
        if( %stringIsPrefix( @input, "low" ) )
        {
            talk @n You have chosen low!
        }
        else
        {
            talk @n You are an idiot!
        }
        endif

Function: %stringLcFirst()

Aliases	%stringLcFirst( )
Parameters	string @value

    Returns the given value with the first character replaced with its lower
    case version when applicable.

    Example:

        @text = "A large man is here."
        echo String: [@text]
        echo String: [%stringLcFirst( @text )]

    Output:

        String: [A large man is here.]
        String: [a large man is here.]

Function: %stringRepeat()

Aliases	%stringRepeat()
Parameters	string @text, integer @repeat

    This function will return a string consisting of the given string repeated
    the given number of times. A maximum size of 1000000 bytes is allowed and
    if the exceeded or the repeat is less than 0, then null is returned. If
    the repeat is 0 or the string is empty, and empty string will be returned.

    Example:

        echo String: [%stringRepeat( "*--*", 6 )]
        echo String: [%stringRepeat( "*--*", 0 )]
        echo String: [%stringRepeat( "*--*", 1000000 )]
        echo String: [%stringRepeat( "*--*", -1 )]

    Output:

        String: [*--**--**--**--**--**--*]
        String: []
        String: []
        String: []

Function: %stringReplaceI()

Aliases	%stringReplaceI()
Parameters	string @needle1, string @needle2, string @haystack

    This function will replace all occurrences of the string defined by
    needle1 by the string defined by needle2 in the haystack. This function
    differs from the %stringReplace() function because it matches needle1
    regardless of case.

    Example:

        @oldText = "One one Two two Three three Four four"
        @newText = %stringReplaceI( Two, 2, @oldText )
        echo Old Text: [@oldText]
        echo New Text: [@newText]

    Output:

        Old Text: [One one Two two Three three Four four]
        New Text: [One one 2 2 Three three Four four]

Function: %stringReplace()

Aliases	%stringReplace()
Parameters	string @needle1, string @needle2, string @haystack

    This function will replace all occurrences of the string defined by
    needle1 by the string defined by needle2 in the haystack.

    Example:

        @oldText = "One one Two two Three three Four four"
        @newText = %stringReplace( Two, 2, @oldText )
        echo Old Text: [@oldText]
        echo New Text: [@newText]

    Output:

        Old Text: [One one Two two Three three Four four]
        New Text: [One one 2 two Three three Four four]

Function: %string()

Aliases	%string( )
Parameters	-

    Returns a new empty string. This function is mostly available for
    completeness.

Function: %stringSubString()

Aliases	%stringSubString() %stringSubStr()
Parameters	string @text, integer @start [, integer @length]

    Use this function to extract smaller chunks if text from the given text
    @parameter. There are several way to retrieve just the part of the text
    @you want.

    If the value of @start is non-negative then @start indicates the location
    within @text that you wish to start retriving your substring. If @start is
    a negative value then it indicates the number of characters from the end
    of @text at which you wish to start. If @start is set to 0, then it is
    treated as though it were set to 1.

    The @length parameter may be omitted in which case %stringSubString()
    presumes you want all the text from the @start position onward. If @length
    is set to a non-negative value then it indicates the number of characters
    to retrieve from the @start position. If @length is negative then it is
    taken to mean you want all characters up to the end of @text omitting the
    give number from the end.

    Examples:

        @text = "The cow jumped over the moon."

        //
        // @sub will contain: "cow jumped over the moon."
        //
        @sub = %stringSubString( @text, 5 )

        //
        // @sub will contain: "cow"
        //
        @sub = %stringSubString( @text, 5, 3 )

        //
        // @sub will contain: "The cow"
        //
        @sub = %stringSubString( @text, 1, 7 )

        //
        // @sub will contain: "The cow"
        //
        @sub = %stringSubString( @text, 0, 7 )

        //
        // @sub will contain: "moon."
        //
        @sub = %stringSubString( @text, -5 )

        //
        // @sub will contain: "moon"
        //
        @sub = %stringSubString( @text, -5, -1 )

        //
        // @sub will contain: "cow jumped"
        //
        @sub = %stringSubString( @text, 5, -15 )

Function: %stringToLowerCase()

Aliases	%stringToLowerCase( )
Parameters	string @value

    Returns the given value with all letters replaced with their lower case
    version.

    Example:

        @text = "SOME stupid looKIng TExt."
        echo String: [@text]
        echo String: [%stringToLowerCase( @text )]

    Output:

        String: [SOME stupid looKIng TExt.]
        String: [some stupid looking text.]

Function: %stringToUpperCase()

Aliases	%stringToUpperCase( )
Parameters	string @value

    Returns the given value with all letters replaced with their upper case
    version.

    Example:

        @text = "SOME stupid looKIng TExt."
        echo String: [@text]
        echo String: [%stringToUpperCase( @text )]

    Output:

        String: [SOME stupid looKIng TExt.]
        String: [SOME STUPID LOOKING TEXT.]

Function: %stringToWords()

Aliases	%stringToWords( )
Parameters	string @value

    Returns an associative array consisting of the words of the given value
    extracted and enumerated in order of their extraction.

    Example:

        @text = 'The fox jumped over the moon and said, "yeee haw".
        @words = %stringToWords( @text )

        foreach( @words as @word )
        {
            echo Word: [@word]
        }
        endforeach

    Output:

        Word: [fox]
        Word: [jumped]
        Word: [over]
        Word: [the]
        Word: [moon]
        Word: [and]
        Word: [said,]
        Word: [yeee haw]
        Word: [.]

Function: %stringTrim()

Aliases	%stringTrim( )
Parameters	string @value

    Returns the string with all leading and trailing space characters removed.

    Example:

        @text = "      Spaces all around!!       "
        echo String: [@text]
        echo String: [%stringTrim( @text )]

    Output:

        String: [      Spaces all around!!       ]
        String: [Spaces all around!!]

Function: %stringUcFirstAll()

Aliases	%stringUcFirstAll( )
Parameters	string @value

    Returns the given value with the first character of every word replaced
    with its upper case version when applicable.

    Example:

        @text = "a large beast-man is here."
        echo String: [@text]
        echo String: [%stringUcFirstAll( @text )]

    Output:

        String: [a large beast-man is here.]
        String: [A Large Beast-Man Is Here.]

Function: %stringUcFirst()

Aliases	%stringUcFirst( )
Parameters	string @value

    Returns the given value with the first character replaced with its upper
    case version when applicable.

    Example:

        @text = "a large man is here."
        echo String: [@text]
        echo String: [%stringUcFirst( @text )]

    Output:

        String: [a large man is here.]
        String: [A large man is here.]

Function: %stun()

Aliases	%stun( )
Parameters	character @entity, float @duration

    This function causes the @target mobile to be stunned for the specified
    @duration in seconds.

    Example:
    --------------------------------------------------------------------------

    %stun( @, (30 + 1d10) / 10 )

Function: %sunrise()

Aliases	%sunrise( )
Parameters	-

    Returns the hour of day at which sunrise occurs. You can use this in your
    code to time events that should only occur at sunrise or for which you
    want to ensure occur between sunrise and sunset or vice versa.

    Example:

    if( %getTime() == %sunrise() )
    {
        yell KAAAAAAAWWWWWWWWWK-A-DOOOOOOOOOOOOOOOOOOODLE-DOOOOOOOOOOO!
    }
    endif

Function: %sunset()

Aliases	%sunset( )
Parameters	-

    Returns the hour of day at which sunset occurs. You can use this in your
    code to time events that should only occur at sunset or for which you
    want to ensure occur between sunrise and sunset or vice versa.

    Example:

    if( !(%getTime() >= %sunrise() && %getTime() <= %sunset()) )
    {
        say I think we should be extra careful in these woods. There are
        \   strange folk tales warning about travel through them at night.
    }
    endif

Function: %triggerDispel()

Aliases	%triggerDispel( )
Parameters	entity @actor, entity @victim, string @type, integer @level, integer @quality

    Triggers a dispel event issued by @actor on @victim with the given @type.
    The @level and @quality values can set so that the recipient affect
    objects can determine for themselves if the dispel succeeds or fails.
    Common types of dispel events are as follows:

        corrupt             cure sickness           remove poison
        cure blindness      dispel evil             sane mind
        cure critical       dispel magic            unhide
        cure deadly poison  heal                    vigor
        cure light          remove curse            weaken
        cure serious        remove deadly poison

    It is however perfectly fine to create your own custom trigger events. For
    instance if your area defines it's own affect, let's call it "brain
    disease", and has implemented a dispel handler which handles "cure brain
    disease", then you could create situation whereby it is possible for the
    user to get rid of the disease.  The situation of course would use this
    function within a script. the example below illustrates the usage.

    Example:
    --------------------------------------------------------------------------

    %triggerDispel( @this, @n, "cure brain disease", @this->level, 100 )

Function: %triggerInvoke()

Aliases	%triggerInvoke( )
Parameters	-

    This function can be used to invoke an internal trigger handler. For
    instance if you are create a new kind of attack and you want the
    catch_attack_act to fire for some weapon then you need to invoke it
    manually as would normally done internally in the C code.  Similarly if
    you need to have an attached weapon spell fire, you again need to use this
    function. The %triggerInvoke() function is a multi-pupose function that
    implements an interface to all hooked trigger types. Current only the
    following trigger handlers are supported:

        catch_attack_act
        check_weapon_spell
        
    The usage for each is described below:

    catch_attack_act:

        %triggerInvoke(
        \   "catch_attack_act", @actor, @target, @object, @damage )

        This type can be used to invoke an object's catch_attack_act script. 
        The @actor parameter indicates the mobile that has generated the
        attack. The @target parameter indicates the mobile target of the
        attack. The @object parameter denotes the object for which the
        catch_attack_act should be invoked.  The @damage parameter is a bit of
        a misnomer since it can also be used to indicate success or failure.
        The general standard is to use a negative value for a miss and 0 or
        greater for a successful hit dealing the amount of damage defined by
        @damage. However for missile types (throw, shoot, ...) 0 is used to
        indicate a miss and a number greater than 0 represents the roll
        obtained.

    check_weapon_spell

        %triggerInvoke(
        \   "check_weapon_spell", @actor, @target, @object )

        This type can be used to invoke an object's weaponSpell affect. A
        weapon spell is defined in the objects attached affects.  The @actor
        parameter indicates the mobile that has generated the attack. The
        @target parameter indicates the mobile target of the attack. The
        @object parameter denotes the object for which the weaponSpell should
        be invoked.

Function: %unserialize()

Aliases	%unserialize( )
Parameters	string @xml

    Takes an serialized string and parses the XML back into the appropriate
    data container hierarchy. This function generally won't be used by
    builders, however the underlying mechanism is used to retrieve persistent
    data from the MySQL database.

    Example:

    @data = %unserialize( @x )
    commune %( @data->name ) the %( @data->race ) has died!

Function: %updatePosition()

Aliases	%updatePosition( )
Parameters	character @target

    Updates the position of the given @target. For instance if the target had
    been incapacitated and some spell or affect improved it's hitpoints, then
    you would probably want to call %updatePosition() to update the status of
    the target in case it had gained enough hitpoints to no longer be
    incapacitated.

    Example:
    --------------------------------------------------------------------------

    @n->hitpoints += 1d5
    %updatePosition( @n )

Function: %weaponGetType()

Aliases	%weaponGetType( )
Parameters	object @target

    Returns the the type of the weapon. The type may be any one of the
    following weapon types:

        acid            deadlyPoison        pierce
        bite            drainLife           poison
        bludgeon        electric            positiveEnergy
        breath          fire                slash
        claw            hit                 smash
        cold            mental              sting
        crush           negativeEnergy      whip

    Example:

    if( %weaponGetType( @n->eq->wielded ) == 'slash' )
    {
        %echoTo(
        \   "With one clean slash you slice open the vines blocking "
        \   "your exit.", @n )
    }
    endif

Function: %weatherGetId()

Aliases	%weatherGetId( ), %weatherGetId( )
Parameters	-

    Returns the ID of the current sky weather state. The ID returned will
    correspond to one of the following sky weather states:

        0 - cloudless
        1 - cloudy
        2 - raining
        3 - lightning
        4 - thunder

Function: %where()

Aliases	%where( ), %inRoom( ), %roomNum( ), %roomNumber( ), %getRoomNum( ), %getRoomNumber( )
Parameters	[mixed @entity]

    If no parameter is given then returns the room of the script owner.
    Returns the containing room number for a character or object entity. For a
    room entity the room's vnum is returned. The entity may be a pointer to a
    room, mob, or object. It may also be a keyword of a mob or object.

Function: %worldGetItems()

Aliases	%worldGetItems( ), %worldGetItems( )
Parameters	-

    This function returns an associative array of pointers all the objects
    currently in the world. The list is indexed by consecutive integers
    counting from 1 onward.

Function: %worldGetMobs()

Aliases	%worldGetMobs( ), %worldGetMobs( )
Parameters	-

    This function returns an associative array of pointers to all the
    characters currently in the world. The list is indexed by consecutive
    integers counting from 1 onward.

Function: %worldGetNpcs()

Aliases	%worldGetNpcs( )
Parameters	-

    This function works just like %worldGetMobs() with the exception that it
    only returns the NPC (Non-Playing Character) matches.

Function: %worldGetPcs()

Aliases	%worldGetPcs( )
Parameters	-

    This function works just like %worldGetMobs() with the exception that it
    only returns the PC (Playing Character) matches.

Function: %zoneGetItems()

Aliases	%zoneGetItems( ), %zoneGetItems( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the objects
    currently in the given zone. The list is indexed by consecutive integers
    counting from 1 onward. If no parameter is used, then the zone in which the
    script owner resides is used as default. The entity may be one of the
    following: an explicit room number; a pointer to a zone, room, character,
    or object; a keyword for a mob, or a keyword for an object. If the entity
    is valid then the zone for the room in which it resides will be searched.

    Note: It is advisable to use a pointer or an explicit room ID.

Function: %zoneGetMobs()

Aliases	%zoneGetMobs( ), %zoneGetMobs( )
Parameters	[mixed @entity]

    This function returns an associative array of pointers to all the
    characters currently in the given zone. The list is indexed by consecutive
    integers counting from 1 onward. If no parameter is used, then the zone in
    which the script owner resides is used as default. The entity may be one
    of the following: an explicit room number; a pointer to a room, character,
    or object; a keyword for a mob, or object. If the entity is valid then the
    zone for the room in which it resides will be searched.

Function: %zoneGetNpcs()

Aliases	%zoneGetNpcs( )
Parameters	[mixed @entity]

    This function works just like %zoneGetMobs() with the exception that it
    only returns the NPC (Non-Playing Character) matches.

Function: %zoneGetPcs()

Aliases	%zoneGetPcs( )
Parameters	[mixed @entity]

    This function works just like %zoneGetMobs() with the exception that it
    only returns the PC (Playing Character) matches.

Appendix D - Resolutions

Resolutions: Buffs

Buffs are affects on mobiles, and objects that provide bonuses and penalties to the respective mobile. Object buffs are generally applied to the mobile wearing the object (this is generally the case but not always). The list below indicates valid resolutions and their descriptions. Each description is prefixed with either [G] gettable, [S] settable, or [G,S] gettable and settable. Resolutions are case sensitive.

General Information
General buff fields for working with buff (spell/skill/other affect) information.
@buff->uniqueId	[G] The unique ID of the buff.
@buff->masterId	[G,S] The ID of a master for the buff. This should be the uniqueId of another buff to which this buff is bound. If the master buff is removed then all buffs for which it is the master will also be removed. Additionally buffs with a master do not show in the user score.
@buff->owner	[G] The owner of the buff (may be a mobile or an object).
@buff->label	[G,S] An identifier label for the buff allowing it to be retrieved with %buffGetByLabel()
@buff->typeId	[G,S] The integer type ID of the buff. It is better to use the name of the type (see @buff->type).
@buff->type	[G,S] The type of the buff (what it affects). Any of the following may be assigned: age, applyAffect, applyAffect2, applyEatSpell, applyHitsRegen, applyHitsUpkeep, applyHurtArcana, applyHurtStealth, applyImmunity, applyManaRegen, applyManaUpkeep, applyMaterial, applyMovesRegen, applyMoveUpkeep, applyPairedWeapon, applyRent, applyResistance, applySusceptibility, applyTimer, armour, castSpell, charisma, class, constitution, damroll, dexterity, experience, gender, gold, height, hitpoints, hitroll, intelligence, level, mana, moves, nightVision, noStacking, saveVsAll, saveVsBreath, saveVsParalysis, saveVsPetrification, saveVsPrayer, saveVsRod, saveVsSpell, size, skill, skillQuality, strength, striking, visibility, weaponDamroll, weaponHitroll, weaponSpell, weight, wisdom,
@buff->typeExtra	[G,S] When the buff is of type applyEatSpell, skill, skillQuality, or weaponSpell, then this field will be set to the associated skill/spell. Currently names are not supported. If you need this, bug me to complete it :)
@buff->duration	[G,S] The duration in seconds that the buff should last. A duration of 0 if infinite (objects usually have infinite buffs).
@buff->skillId	[G,S] The source skill/spell ID for the buff. This is used internally to determine when a skill/spell is already in effect. Additionally it is the skill/spell shown in the player's score sheet. It is better to use the name of the skill or spell (See @buff->skill)
@buff->skill	[G,S] The source skill/spell name for the buff. This is used internally to determine when a skill/spell is already in effect. Additionally it is the skill/spell shown in the player's score sheet.
@buff->level	[G,S] The level of the buff. This affects it's power (if applicable) and it's ability to resist being dispelled (if applicable).
@buff->quality	[G,S] The quality of the buff. This affects it's power (if applicable) and it's ability to resist being dispelled (if applicable).
@buff->modifier	[G,S] The amount by which the buff modifies the associated type field. For instance a type of "strength" and a modifier of "3" would increase the user's strength by 3 points.
@buff->description	[G,S] An optional field which allows immortals to track the source of a buff. If this is set then when an immortal stat's the player or object then they can see from whence the buff was applied. This is mostly useful for anonymouse buffs applied to players/mobiles. It is not necessary to set this, if you do not then an automatic value will be assigned indicating the script, trigger, and line number where it was assigned.
@buff->weightLevel	[G,S] Setting this field allows the buff to have its modifier weighted according to the set level and the associated player's level. For instance, setting this to 40 means that players of level 40 and above get the full effect of the modifier, whereas players of lower level get a weighted modifier based on their level. Note that you must also enable @buff->flags->isWeighted for this to work.
@buff->weightMinimum	[G,S] This places a lower bound on the weighted value of a buff's modifier. This works in conjunction with @buff->weightLevel. Note that you must also enable @buff->flags->isWeighted for this to work.

Flags
Flags are boolean values that enable or disable features for the buff. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@buff->flags->antimagic	[G,S] Antimagic status.
@buff->flags->blind	[G,S] Blindness status.
@buff->flags->charm	[G,S] Charm status. This may not be limited to mobile under the influence of charm person / charm monster.
@buff->flags->chillTouch	[G,S] Chill touch status.
@buff->flags->circle	[G,S] Deprecated. DON'T USE.
@buff->flags->comprehension	[G,S] Comprehension status.
@buff->flags->cursed	[G,S] Cursed status.
@buff->flags->deadlyPoison	[G,S] Deadly poison status.
@buff->flags->deathsDoor	[G,S] Death's door status.
@buff->flags->depravity	[G,S] Depravity status.
@buff->flags->detectAura	[G,S] Detect aura status.
@buff->flags->detectInvisible	[G,S] Detect invisible status.
@buff->flags->detectMagic	[G,S] Detect magic status.
@buff->flags->dominated	[G,S] Dominated status. This is usually applied for befriended animals, and possibly in other cases.
@buff->flags->fear	[G,S] Fear status.
@buff->flags->feebleMind	[G,S] Feeble mind status.
@buff->flags->feignDeath	[G,S] Feigning death status.
@buff->flags->fieryVortex	[G,S] Fiery vortex status.
@buff->flags->fistsOfFury	[G,S] Fists of fury status.
@buff->flags->follow	[G,S] Deprecated. DO NOT USE.
@buff->flags->footParalysis	[G,S] Foot paralysis status. When enabled the player cannot travel.
@buff->flags->fly	[G,S] Flying status.
@buff->flags->group	[G,S] Group status -- DON'T USE.
@buff->flags->handParalysis	[G,S] Hand paralysis. When enabled the player cannot use their hands.
@buff->flags->hide	[G,S] Hidden status.
@buff->flags->hitsRegenDouble	[G,S] Double hitpoints regen status.
@buff->flags->hitsRegenHalf	[G,S] Half hitpoints regen status.
@buff->flags->infravision	[G,S] Infravision status.
@buff->flags->insanity	[G,S] Insanity status.
@buff->flags->invisible	[G,S] Invisibility status.
@buff->flags->invulnerability	[G,S] Invulnerability status.
@buff->flags->isWeighted	[G,S] Weighted buff status.
@buff->flags->lichTouch	[G,S] Lich touch status.
@buff->flags->manaRegenDouble	[G,S] Double mana regen status.
@buff->flags->manaRegenHalf	[G,S] Half mana regen status.
@buff->flags->manaShield	[G,S] Mana shield status.
@buff->flags->movesRegenDouble	[G,S] Double moves regen status.
@buff->flags->movesRegenHalf	[G,S] Half moves regen status.
@buff->flags->movesImpaired	[G,S] Movement impaired status. This does not appear to be supported.
@buff->flags->paralysis	[G,S] Paralysis status. A combination of foot and hand paralysis.
@buff->flags->parry	[G,S] Parry status.
@buff->flags->poison	[G,S] Poison status.
@buff->flags->protectionFromEvil	[G,S] Protection from evil status.
@buff->flags->purgeOnEnter	[G,S] Causes the buff to be purged when the player enters the game. This is useful if a permanent buff is add for which a removal mechanism may fail. For instance, the "walk in darkness" spell provides double regeneration while the player is in the dark zone, and the affect is removed when the player leaves. However, if the player is auto rented then the player never actually leaves. This ensures when they re-enter the game, the buff is removed.
@buff->flags->regenerate	[G,S] Regenerate status.
@buff->flags->sanctuary	[G,S] Sanctuary status.
@buff->flags->senseLife	[G,S] Sense life status.
@buff->flags->shide	[G,S] Shidden status.
@buff->flags->shockingGrasp	[G,S] Shocking grasp status.
@buff->flags->sickness	[G,S] Sickness status.
@buff->flags->silence	[G,S] Silenced status.
@buff->flags->sleep	[G,S] Magical sleep status.
@buff->flags->snare	[G,S] Deprecated. DO NOT USE.
@buff->flags->sneak	[G,S] Sneaking status.
@buff->flags->summoned	[G,S] Creature is a summoned creature. Summoned is in the sense that corrupt / dispel evil will do double damage. This is not related to the summon spell.
@buff->flags->sweeping	[G,S] Deprecated. DO NOT USE.
@buff->flags->vampireDaywalk	[G,S] Daywalk for vampires status.
@buff->flags->vampirism	[G,S] Vampirism status.
@buff->flags->waterBreath	[G,S] Water breath status.
@buff->flags->waterWalk	[G,S] Water walk status.

Resolutions: Exits

Exits control the destinations when moving about rooms and control whether a given exit has a door, and what the state of that door may be (open, closed, locked, etc). The list below indicates valid resolutions and their descriptions. Note: when setting a flag for an exit, the game engine will maintain logical integrity. For instance enabled the isLocked flag will also automatically enabling the hasDoor and hasLock flags. Each description is prefixed with either [G] gettable, [S] settable, or [G,S] gettable and settable. Resolutions are case sensitive.

General Information
Various information about the item.
@exit->uniqueId	[G] The unique ID of the exit entity.
@exit->room	[G] A pointer to the room containing the exit.
@exit->roomId	[G] The ID of the room containing the exit.
@exit->direction	[G] The name of the direction in which the exit travels (north, south, east, ...)
@exit->directionId	[G] The ID of the direction in which the exit travels (north, south, east, ...)
@exit->keywords	[G,S] Keywords for the exit (eg. door, gate, trap).
@exit->description	[G,S] The description seen when looking at the exit.
@exit->destination	[G,S] A pointer to the destination room when travelling through the exit.
@exit->destinationId	[G,S] The room ID of the destination room when travelling through the exit.
@exit->reverseExit	[G] Returns a pointer to the exit that leads back to this exit's room in the reverse direction. If no such exit exists then `null` is returned. If one were to go east and then west but not arrive in the original location then the reverse exit is considered non-existent.
@exit->otherSide	[G] An alias for @exit->reverseExit.
@exit->pickResilience	[G,S] How hard it is to pick the exit's lock (if it has a locked door).
@exit->forceResilience	[G,S] How hard it is to force the exit open (if it has a locked door).
@exit->flags->isSecret	[G,S] Secret exit status. When enabled then players will not see that an exit is here when "bumping" into it. Bumping is what happens when you attempt to travel through the exit but it is closed. When this is enabled the mobile will see "You can't go that way." instead of "The door is closed.".
@exit->flags->isNoDirection	[G,S] No direction status. The exit cannot be entered using the cardinal directions. Instead the mobile must use "enter keyword" where keyword is one of the exit's keywords.
@exit->flags->hasDoor	[G,S] Has door status.
@exit->flags->isClosed	[G,S] Closed door status.
@exit->flags->hasLock	[G,S] Door has lock status.
@exit->flags->isLocked	[G,S] Locked status for doors.
@exit->flags->isPickproof	[G,S] Pickproof status.

Resolutions: Mobiles

Mobiles defined the creatures that roam the world. There are two important types of mobile, the Playing Character (PC) and the Non-Playing Character (NPC). PC mobiles are the real-life players that connect to the game, whereas NPC mobiles are the creatures defined by the area builders to inhabit the world. Following are the mobile fields that can currently be retrieved and set via the resolution operator. Each description is prefixed with either [G] gettable, [S] settable, or [G,S] gettable and settable. Resolutions are case sensitive.

General Information
Various information about the mobile/player that doesn't really fall under stats.
@mobile->actionDelay	[G,S] The number of second until the mobile can (normally) perform another action. This delay is ignored for actions issued via scripts unless the appropriate flag is set.
@mobile->templateAreaId	[G] The ID of the area in which the mob is described.
@mobile->templateAreaPtr	[G] A pointer to the area structure in which the mob is described.
@mobile->continentEntryId	[G,S] The ID of the room for which the mobile entered the current continent. This is used when the player dies to start them within the continent of their death rather than their hometown. Boats and portals set the value as necessary when players enter and leave the boat.
@mobile->descLong	[G,S] The text seen when a player views the mobile in a room (via the "look" command).
@mobile->descShort	[G,S] The text seen when a player see the mobile perform an action such as getting an item or moving to an adjacent room.
@mobile->descExamine	[G,S] The text seen when a player examines or looks at a mobile.
@mobile->id	[G] The ID of the mobile. The same ID assigned to it in the builder and used to load it into the game.
@mobile->keywords	[G,S] Keywords by which an mobile may be targetted. Keywords may be separated with spaces, commas, or semi-colons.
@mobile->name	[G] An alias for @mobile->descShort.
@mobile->title	[G] Returns the title of a PC mobile.
@mobile->npcGroup	[G,S] An arbitrary ID which defines buddy groups amongst mobiles having the same ID. mobiles with the same npcGroup ID will assist their buddies in combat.
@mobile->rankName	[G] Rank of mobile (dweeb, novice, livingLegend, etc.)
@mobile->rankTitle	[G] Rank title of mobile (a Novice Adventurer, a Living Legend, etc.)
@mobile->screenHeight	[G] The height in ascii characters of the player's terminal screen. This is not determined automatically but may be set by the player. It affects scrolling when viewing long help or messages.
@mobile->screenWidth	[G] The width in ascii characters of the player's terminal screen. This is not determined automatically but may be set by the player. It affects the width at which many descriptions are automatically wrapped.
@mobile->skipPrompt	[S] Setting this to 1 will prevent the player's prompt from being displayed on the next update cycle. A player usually receives a freshly printed prompt whenever output is sent to their terminal. This is sometimes not desired if the prompt has already been sent for some other reason.
@mobile->startRoomId	[G,S] The ID of the room in which the mobile was first loaded. For PC players this will be the ID of the room in which they entered the game (usually the hometown). This is used by the game engine to have the mobile walk back to the appropriate room if they have been moved via summon, suggest, command, charm, flee, or any other technique.
@mobile->uniqueId	[G] A unique ID assigned to the mobile when it is created. The lifespan of the ID is until the mobile rents or the game reboots.
@mobile->utters	[G] Racial specific utterance for non-talking races (eg. hisses, squawks, screeches, etc.)
@mobile->continentId	[G] The ID of the continent in which the mobile resides. Continents at this time have an influence over summon and gate spells since you can't jump between them using these spells. You should never store the continent ID or compare against a a literal integer value since it could change. It is better to store/compare against the key value.
@mobile->continentPtr	[G] A unique pointer to the continent data structure that can be used with continent specific resolutions.
@mobile->continentKey	[G] The simplified name of the continent which will consist of only alphabetic characters and underscores. If you need to store a continent identifier of compare against an explicit value then you should use this value. Example: western_islands
@mobile->continent	[G] The name of the continent as might be displayed to a player. Example: Western Islands
@mobile->areaId	[G] The ID of the area in which the mobile resides. You should never store the area ID or compare against a a literal integer value since it could change. It is better to store/compare against the key value.
@mobile->areaPtr	[G] A unique pointer to the area data structure that can be used with area specific resolutions.
@mobile->areaKey	[G] The simplified name of the area which will consist of only alphanumeric characters and underscores. If you need to store a area identifier of compare against an explicit value then you should use this value. Example: esa_isle
@mobile->area	[G] The name of the area as might be displayed to a player. Example: Esa Isle
@mobile->zoneId	[G] The ID of the zone in which the mobile resides.
@mobile->zonePtr	[G] A unique pointer to the zone data structure that can be used with zone specific resolutions.
@mobile->zone	[G] The name of the zone as shown when a zone resets or is loaded.
@mobile->roomId	[G] The ID of the room in which the mobile resides.
@mobile->roomPtr	[G] A unique pointer to the room data structure that can be used with room specific resolutions.
@mobile->room	[G] The name of the room as shown when a player looks at a room.

Variables
You can use these fields to retrieve and set entity, player, and saved variables for the mobile.
@mobile->evars->varName	[G,S] Sets or retrieves the value for the mobile's entity variable name "varName".
@mobile->pvars->varName	[G,S] Sets or retrieves the value for the mobile's player variable name "varName".
@mobile->svars->varName	[G,S] Sets or retrieves the value for the mobile's saved variable name "varName".

Primary Stats (100 point system -- includes mods from spells/skills/eq)
These values are the modified values attributed to the player after any modifiers for spells, skills, or equipment have been applied. Using the 100 point stat system for primary stats is preferable over the traditional 25 point system since it provides better granularity and doesn't undergo implicit conversion when stats are set and retrieved. While the stat system is based on 100 points there is nothing preventing values over 100.
@mobile->baseCharisma	[G,S]
@mobile->baseConstitution	[G,S]
@mobile->baseDexterity	[G,S]
@mobile->baseIntelligence	[G,S]
@mobile->baseStrength	[G,S]
@mobile->baseWisdom	[G,S]

Primary Stats (100 point system -- unmodified)
These values are the raw unmodified values attributed to the player before any modifiers for spells, skills, or equipment are applied. Using the 100 point stat system for primary stats is preferable over the traditional 25 point system since it provides better granularity and doesn't undergo implicit conversion when stats are set and retrieved. While the stat system is based on 100 points there is nothing preventing values over 100.
@mobile->realBaseCharisma	[G,S]
@mobile->realBaseConstitution	[G,S]
@mobile->realBaseDexterity	[G,S]
@mobile->realBaseIntelligence	[G,S]
@mobile->realBaseStrength	[G,S]
@mobile->realBaseWisdom	[G,S]

Primary Stats (traditional 25 point system -- includes mods from spells/skills/eq)
These values are the modified values attributed to the player after any modifiers for spells, skills, or equipment have been applied. Access to the traditional 25 point system is primarily provided as a backward compatibility feature for old scripts that were written for the 25 point system. Values set and retrieved using these fields undergo an implicit transformation from the 100 point system to the 25 point system as described in the help for "stat conversions".
@mobile->charisma	[G,S]
@mobile->constitution	[G,S]
@mobile->dexterity	[G,S]
@mobile->intelligence	[G,S]
@mobile->strength	[G,S]
@mobile->strengthBonus	[G,S] The bonus may be a value from 0 to 100.
@mobile->wisdom	[G,S]

Primary Stats (traditional 25 point system -- unmodified)
These values are the raw unmodified values attributed to the player before any modifiers for spells, skills, or equipment are applied. Access to the traditional 25 point system is primarily provided as a backward compatibility feature for old scripts that were written for the 25 point system. Values set and retrieved using these fields undergo an implicit transformation from the 100 point system to the 25 point system as described in the help for "stat conversions".
@mobile->realCharisma	[G,S]
@mobile->realConstitution	[G,S]
@mobile->realDexterity	[G,S]
@mobile->realIntelligence	[G,S]
@mobile->realStrength	[G,S]
@mobile->realStrengthBonus	[G,S] The bonus may be a value from 0 to 100.
@mobile->realWisdom	[G,S]

Miscellaneous Stats (includes mods from spells/skills/eq)
These values are the modified values attributed to the player after any modifiers for spells, skills, or equipment have been applied. Not all fields have an associated field for retrieving the raw value before modifications.
@mobile->alignment	[G,S] The mobile's alignment. This should be between -1000 and 1000.
@mobile->armour	[G,S] The mobile's armour class.
@mobile->bank	[G,S] How much gold is in the bank.
@mobile->classId	[G] The ID of the mobile's primary class (if any). If no primary class exists (such as for jack of all trades) then `0` is returned.
@mobile->classPtr	[G] A pointer to the class data structure which can be used with class resolutions.
@mobile->class	[G,S] The name of the mobile's primary class (if any). If no primary class exists (such as for jack of all trades) then `null` is returned. The name of the class if one exists will be returned in lower-case. A mobile is considered dedicated when @mobile->class == @mobile->subClass. Only NPC targets may have their class set using this method.
@mobile->damageBonus	[G,S] Damage bonus applied to all melee attacks.
@mobile->defender	[G] A meta field that returns a pointer to the mobile that defends this mobile in combat. If the mobile is in a rear row with allies before it then this will return a pointer to the foremost ally. Otherwise it will return a pointer to the mob itself.
@mobile->exp	[G,S] Alias for @mobile->experience.
@mobile->experience	[G,S] The mobile's current experience points.
@mobile->expMax	[G,S] The mobile's maximum ever achieved experience points.
@mobile->expToNextLevel	[G] A meta field that returns the number of experience points required for the mobile to advance to the next level.
@mobile->expTrophy	[G,S] The base number of experience points that this mobile is worth when defeated in combat.
@mobile->expUnused	[G] Returns the overflow points of experience that have not yet been used in a dice roll for stat gains. This value is maintained to ensure that players are never "ripped off" with respect to experience gained for a kill.
@mobile->puzzlePoints	[G] Returns the current number of puzzle points achieved by the target.
@mobile->genderId	[G] Returns the ID of the mobile's gender.
@mobile->gender	[G,S] Describes the gender of the mobile. Valid values are: male, female, neuter.
@mobile->gold	[G,S] The amount of gold the mobile has on-hand.
@mobile->height	[G,S] The height of the mobile in beans. 1 bean is approximately 1cm.
@mobile->hitpoints	[G,S] The mobile's current hitpoints.
@mobile->hitrollBonus	[G,S] Hotroll bonus applied to all melee attacks.
@mobile->hometown	[G,S] The name of the mobile's hometown. This is only applicable to PC mobiles. Values will be returned in lower case (eg. "shayol ghul").
@mobile->invisibilityLevel	[G,S] This determines the minimum level at which a mortal can see the mobile. Unlike the invisibility affect, this cannot be bypassed with the detect invisibility affect. The primary purpose of this field is to prevent access to a mobile by a low level mortal or to prevent the mobile from being detected in cases where it's purpose is to create an effect. Such use of mobiles is mostly historical from a time when the scripting engine was incapable of making complex alterations of the world. In such case "lackey" mobiles were used to catch signals to perform tasks such as unlocking doors in such a way as for the mechanism to be undetected.
@mobile->isActionReady	[G] A meta field that returns if the mobile is ready for issuing an action command. This will be true if action lag from previous actions has expired. If the mobile is ready then 1 is returned; otherwise 0 is returned.
@mobile->level	[G,S] The level of the mobile. This affects the power of its skills and spells and its ability to save versus skills and spells.
@mobile->mana	[G,S] The amount of mana currently available to the mobile.
@mobile->maxHitpoints	[G,S] The maximum number of hitpoints available to the mobile when it is completely rested.
@mobile->maxMana	[G,S] The maximum amount of mana available to the mobile when it is completely rested.
@mobile->maxMoves	[G,S] The maximum number of moves available to the mobile when it is completely rested.
@mobile->moves	[G,S] The number of moves currently available to the mobile. NPC mobiles are not limited when travelling by their movement points.
@mobile->position	[G,S] The current position of the mobile. This can be any one of: dead mortally wounded incapacitated stunned sleeping resting sitting fighting standing
@mobile->positionId	[G,S] The current position ID of the mobile. This field is deprecated since the @mobile->position field is much more flexible and maintainable.
@mobile->positionDefault	[G,S] The default position of the mobile. See @mobile->position for possible values.
@mobile->positionIdDefault	[G,S] The default position ID of the mobile. This field is deprecated since the @mobile->position field is much more flexible and maintainable.
@mobile->practices	[G,S] The number of practice points currently available to the mobile.
@mobile->raceId	[G] The ID of the mobile's race. This field is deprecated since the @mobile->race field is much more flexible and maintainable.
@mobile->racePtr	[G] A pointer to the race data structure for use with race resolutions.
@mobile->race	[G,S] The mobile's race. This will return the textual name of the race in all lower-case (eg. troll, human, halfling, ...). Only NPC targets may have their race set using this method.
@mobile->reputation	[G] Not yet properly supported.
@mobile->row	[G,S] The current row in which the mobile resides with respect to grouping.
@mobile->sex	[G,S] Alias for @mobile->gender.
@mobile->subClassId	[G] The ID of the mobile's secondary class (if any). If no primary class exists (such as for jack of all trades) then `0` is returned.
@mobile->subClassPtr	[G] A pointer to the sub class data structure which can be used with class resolutions.
@mobile->subClass	[G,S] The name of the mobile's secondary class (if any). If no secondary class exists (such as for jack of all trades) then `null` is returned. The name of the class if one exists will be returned in lower-case. A mobile is considered dedicated when @mobile->class == @mobile->subClass. Only NPC targets may have their sub-class set using this method.
@mobile->thac0	[G,S] The current (T)o (H)it (A)rmour (C)lass (0) value for the mobile. Unless you know what you're doing don't use this field. Even if you do know what you're doing you probably shouldn't use this field since it doesn't quite work the way it should.
@mobile->weight	[G,S] The mobile's current weight in stones. 1 stone is approximately 1 pound.
@mobile->wimpy	[G,S] Defines at which point the mobile will attempt to automatically flee from combat. A value of 0 means no automatic attempt to flee will be made.
@mobile->isJailed	[G] A meta field that returns 1 if the mobile has been jailed, and returns 0 otherwise.
@mobile->isPc	[G] A meta field that returns 1 if the mobile is a PC character, and returns 0 otherwise.
@mobile->isNpc	[G] A meta field that returns 1 if the mobile is an NPC character, and returns 0 otherwise.
@mobile->isPet	[G] A meta field that returns 1 if the mobile is a pet, and returns 0 otherwise.
@mobile->isConscious	[G] A meta field that returns 1 if the mobile is conscious (position greater than sleeping), and returns 0 otherwise.
@mobile->isUnconscious	[G] A meta field that returns 1 if the mobile is unconscious (position less than or equal to sleeping), and returns 0 otherwise.
@mobile->isCharm	[G] A meta field that returns 1 if the mobile is a charm, and returns 0 otherwise.
@mobile->isPossessed	[G] A meta field that returns 1 if the mobile is possessed, and returns 0 otherwise.
@mobile->isSwitched	[G] A meta field that returns 1 if the mobile is switche (possessing another mobile), and returns 0 otherwise.
@mobile->isLinkDead	[G] A meta field that returns 1 if the mobile is link-dead, and returns 0 otherwise.

Miscellaneous Stats (unmodified)
These values are the raw unmodified values attributed to the player before any modifiers for spells, skills, or equipment are applied.
@mobile->realArmour	[G,S]
@mobile->realDamageBonus	[G,S]
@mobile->realHitrollBonus	[G,S]
@mobile->realMaxHitpoints	[G,S]
@mobile->realMaxMana	[G,S]
@mobile->realMaxMoves	[G,S]
@mobile->realName	[G]
@mobile->realRaceId	[G]
@mobile->realRacePtr	[G]
@mobile->realRace	[G]
@mobile->realGenderId	[G]
@mobile->realGender	[G]
@mobile->realPositionIdDefault	[G]
@mobile->realPositionDefault	[G]
@mobile->realThac0	[G,S]

Saves (includes mods from spells/skills/eq)
Saves affect a mobiles ability to reduce the affect of an offensive affect for which a saving throw is made. Negative values are better for the mobile than positive values. These values are the modified values attributed to the player after any modifiers for spells, skills, or equipment have been applied. Not all fields have an associated field for retrieving the raw value before modifications.
@mobile->saves->breath	[G,S] Ability to save versus "breath" type affects. For instance when dragon's breath, whirlwind, etc. For some reason even earthquake is under this one :/
@mobile->saves->paralyze	[G,S] Not currently in use.
@mobile->saves->petrify	[G,S] Pword fear uses this one.
@mobile->saves->prayer	[G,S] Most offensive piety based spells use this.
@mobile->saves->rod	[G,S] Not currently used.
@mobile->saves->spell	[G,S] Most offensive arcana based spells use this.

Equipment
These fields relate to a mobile's levels of satiation/drunkeness.
@mobie->buzz @mobile->drunk	[G,S] This defines how "buzzed" the mobile is. 0 means no buzz.
@mobile->hunger	[G,S] This determines how hungry a mobile is. A value of 0 means not hungry at all (equivalent to completely full). The value this can go to is dependent on race with larger more ravenous races having a larger capacity for hunger.
@mobile->thirst	[G,S] This determines how thirsty a mobile is. A value of 0 means not hungry at all (equivalent to completely quenched). The value this can go to is dependent on race with larger more ravenous races having a larger capacity for thirst.

Equipment
These fields allow moving items to specific equipment locations and retrieving any item that is in a specific equipment position. Items worn by assigning the item to the equipment field do not trigger catch_wear scripts.
@mobile->equipment	[G]
@mobile->equipment->about	[G,S]
@mobile->equipment->arms	[G,S]
@mobile->equipment->body	[G,S]
@mobile->equipment->feet	[G,S]
@mobile->equipment->hands	[G,S]
@mobile->equipment->head	[G,S]
@mobile->equipment->held	[G,S]
@mobile->equipment->leftFinger	[G,S]
@mobile->equipment->leftWrist	[G,S]
@mobile->equipment->legs	[G,S]
@mobile->equipment->light	[G,S]
@mobile->equipment->neck1	[G,S]
@mobile->equipment->neck2	[G,S]
@mobile->equipment->rightFinger	[G,S]
@mobile->equipment->rightWrist	[G,S]
@mobile->equipment->shield	[G,S]
@mobile->equipment->waist	[G,S]
@mobile->equipment->wielded	[G,S]

Equipment (short alias)
Exactly the same as the equipment field counterparts except less typing is involved :)
@mobile->eq	[G]
@mobile->eq->about	[G,S]
@mobile->eq->arms	[G,S]
@mobile->eq->body	[G,S]
@mobile->eq->feet	[G,S]
@mobile->eq->hands	[G,S]
@mobile->eq->head	[G,S]
@mobile->eq->held	[G,S]
@mobile->eq->leftFinger	[G,S]
@mobile->eq->leftWrist	[G,S]
@mobile->eq->legs	[G,S]
@mobile->eq->light	[G,S]
@mobile->eq->neck1	[G,S]
@mobile->eq->neck2	[G,S]
@mobile->eq->rightFinger	[G,S]
@mobile->eq->rightWrist	[G,S]
@mobile->eq->shield	[G,S]
@mobile->eq->waist	[G,S]
@mobile->eq->wielded	[G,S]

Inventory
These fields can be used to retrieve and move items into the mobile's inventory.
@mobile->inventory	[G] Returns an array consisting of pointers to the items in the mobile's inventory (this does not included equipped items or items in the special affects inventory).
@mobile->inventory->first	[G,S] Returns the first item in the mobile's inventory. If assigned a value then the assigned item is moved to the first position in the mobile's inventory.
@mobile->inventory->head	[G,S] An alias for @mobile->inventory->first.
@mobile->inventory->last	[G,S] Returns the last item in the mobile's inventory. If assigned a value then the assigned item is moved to the last position in the mobile's inventory.
@mobile->inventory->tail	[G,S] An alias for @mobile->inventory->last.

Inventory (short alias for inventory field)
Exactly the same as the inventory field counterparts except less typing is involved :)
@mobile->inv	[G] Alias for @mobile->inventory.
@mobile->inv->first	[G,S] Alias for @mobile->inventory->first.
@mobile->inv->head	[G,S] Alias for @mobile->inventory->head.
@mobile->inv->last	[G,S] Alias for @mobile->inventory->last.
@mobile->inv->tail	[G,S] Alias for @mobile->inventory->tail.

Buffs
Fields for retrieving information about any buffs on the mobile.
@mobile->buffs	[G] Returns an array of buff pointers currently on the mobile. Entries are indexed sequentially from 1 onward.
@mobile->buffs->first	[G,S] Returns a pointer to the first buff on the mobile.
@mobile->buffs->last	[G,S] Returns a pointer to the last buff on the mobile.
@mobile->buffs->head	[G,S] An alias for @mobile->buffs->first
@mobile->buffs->tail	[G,S] An alias for @mobile->buffs->last
@mobile->buffs->add	[G,S] An alias for @mobile->buffs->last

Special Effects Inventory (mobile cannot interact with these)
The special affects inventory is a special inventory of items with which the mobile cannot directly interact. Special affects are used to apply modifiers to mobiles in the same way as worn equipment, or to hook into the trigger system to provide effects without requiring an item to be worn. For example the vampirism system is implemented using two special effects items that swap in and out between nightime and daytime. Similarly, the spell summon places a special effect item on the target PC and overrides the accept command to facilitate acceptance of the summons. Another example is the slit throat skill and it's use of a special effect item to facilitate continued bleeding and the bleeding description for the room and score views.
@mobile->iaffects	[G,S] Returns an array consisting of pointers to the items in the mobile's special affects inventory.
@mobile->iaffects->first	[G,S] Returns the first item in the mobile's special affects inventory. If assigned a value then the assigned item is moved to the first position in the mobile's special affects inventory.
@mobile->iaffects->head	[G,S] An alias for @mobile->iaffects->first.
@mobile->iaffects->last	[G,S] Returns the last item in the mobile's special affects inventory. If assigned a value then the assigned item is moved to the last position in the mobile's special affects inventory.
@mobile->iaffects->tail	[G,S] An alias for @mobile->iaffects->last.

Flags
Flags are boolean values that enable or disable features for the mobile. Many flags are enabled by virtue of the mobile's race, spell/skill affects, and equipment. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@mobile->flags->aggroToEvil	[G,S] When set the mobile is aggressive toward creatures having alignment <= -350.
@mobile->flags->aggroToGood	[G,S] When set the mobile is aggressive toward creatures having alignment >= 350.
@mobile->flags->ansiColour	[G] When set the mobile has ANSI colours enabled.
@mobile->flags->antimagic	[G,S] When set the mobile is affected by anti-magic.
@mobile->flags->autoSkills	[G,S] When set the internal engine will automatically cause the mobile to use skills as necessary. If you find the automated system is impeding your specialized scripts then you can disable them using this flag and manually craft its AI.
@mobile->flags->autoSpells	[G,S] When set the internal engine will automatically cause the mobile to use spells as necessary. If you find the automated system is impeding your specialized scripts then you can disable them using this flag and manually craft its AI.
@mobile->flags->bash	[G,S] When set the mob has not yet recovered from being bashed.
@mobile->flags->blind	[G,S] When set the mobile is blinded.
@mobile->flags->canSeeEverything	[G,S] When set, the mobile can see everything except things that are wizinvis. This includes things that are hidden, shidden, or obscured by the dark. This should never be set on a PC.
@mobile->flags->channel	[G,S] Deprecated. Do not use.
@mobile->flags->charm	[G,S] When set the mobile is under the influence of charm. This flag is used in multiple scenarios not necessarily relating to the charm spell. For instance recruits, zombies, dancing swords all fall under the influence of this flag.
@mobile->flags->chillTouch	[G,S] When set the mobile has the chill touch ability.
@mobile->flags->circle	[G,S] Not currently used.
@mobile->flags->comprehension	[G,S] When set the mobile can comprehend all languages.
@mobile->flags->cursed	[G,S] When set the mobile is cursed.
@mobile->flags->deadlyPoison	[G,S] When set the mobile will suffer from deadly poison affects.
@mobile->flags->deathsDoor	[G,S] When set the mobile is protected by death's door. This is only valid for PC mobiles.
@mobile->flags->detectAura	[G,S] When set the mobile can detect the auto of other mobiles.
@mobile->flags->detectInvisible	[G,S] When set the mobile can detect invisible mobiles and objects.
@mobile->flags->detectMagic	[G,S] When set the mobile can detect an auro of magic when an item has magical properties (see @object->flags->isMagical).
@mobile->flags->dominated	[G,S] When set the mobile is subjected to the domination. This is similar to charm in that the affected mobile will follow its master around. However, unlike charm domination does not allow the master to issue commands. Befriended animals fall under this category.
@mobile->flags->fear	[G,S] When set th emobile is affected by fear. Fear causes the mobile to flee in panic when in the presence of a mobile it hates.
@mobile->flags->feebleMind	[G,S] When set the mobile is affected by feeble mind. Feeble mind decreases the quality of arcana and piety spells.
@mobile->flags->feignDeath	[G,S] When set the mobile is affected by feign death. They will appear as a corpse in the room to onlookers.
@mobile->flags->fieryVortex	[G,S] When set the mobile will be surrounded by a fiery vortex.
@mobile->flags->fistsOfFury	[G,S] When set the mobile will be affected by fists of fury.
@mobile->flags->fly	[G,S] When set the mobile will be flying.
@mobile->flags->follow	[G,S] When set the mobile is marked as following some leader. The leader may not necessarily be present in the same room.
@mobile->flags->footParalysis	[G,S] Mobile can't use feet (snares use this flag).
@mobile->flags->forceTrophyExp	[G,S] The game normally calculates the experience gained for killing a particular mob so that the process is unform across the game. In exceptional circumstances it can be necessary to force the game to use a defined amount of experience (such as for clones produced by multiplicity spell). When this flag is enabled the value of expTrophy will be awarded when the mobile is killed.
@mobile->flags->group	[G,S] When set the mobile is a member of some group. I don't recall the distinction between this flag and the follow flag.
@mobile->flags->handParalysis	[G,S] Mobile can't use hands (not supported).
@mobile->flags->hide	[G,S] When set the mobile will be hidden from view and only detectable when the viewer is affected by sense life.
@mobile->flags->hitsRegenDouble	[G,S] When set the mobile will regenerate hitpoints at twice their base hitpoint regeneration rate.
@mobile->flags->hitsRegenHalf	[G,S] When set the mobile will regenerate hitpoints at half their base hitpoint regeneration rate.
@mobile->flags->infravision	[G,S] When set the mobile will be affected by infravision and will be able to see mobiles in dark rooms.
@mobile->flags->insanity	[G,S] When set the mobile will be affected by insanity.
@mobile->flags->invisible	[G,S] When set the mobile will be invisible to onlookers not affected by detect invisible. Sense life will also reveal their presence, but they cannot be targetted with sense life alone.
@mobile->flags->invulnerability	[G,S] When set the mobile is immune to damage.
@mobile->flags->isActionReady	[G] A meta field that returns if the mobile is ready for issuing an action command. This will be true if action lag from previous actions has expired. If the mobile is ready then 1 is returned; otherwise 0 is returned.
@mobile->flags->isGuide	[G,S] When set the mobile is marked as a guide and will not return to it's starting location when also marked as a sentinel.
@mobile->flags->isJailed	[G] A meta field that returns 1 if the mobile has been jailed and returns 0 otherwise.
@mobile->flags->isUndead	[G] A meta that returns 1 when the mobile is one of the undead races and 0 otherwise.
@mobile->flags->isJailed	[G] A meta field that returns 1 if the mobile has been jailed, and returns 0 otherwise.
@mobile->flags->isPc	[G] A meta field that returns 1 if the mobile is a PC character, and returns 0 otherwise.
@mobile->flags->isNpc	[G] A meta field that returns 1 if the mobile is an NPC character, and returns 0 otherwise.
@mobile->flags->isPet	[G] A meta field that returns 1 if the mobile is a pet, and returns 0 otherwise.
@mobile->flags->isCharm	[G] A meta field that returns 1 if the mobile is a charm, and returns 0 otherwise.
@mobile->flags->isPossessed	[G] A meta field that returns 1 if the mobile is possessed, and returns 0 otherwise.
@mobile->flags->isSwitched	[G] A meta field that returns 1 if the mobile is switche (possessing another mobile), and returns 0 otherwise.
@mobile->flags->isLinkDead	[G] A meta field that returns 1 if the mobile is link-dead, and returns 0 otherwise.
@mobile->flags->lichTouch	[G,S] When set the mobile is affected by lich touch.
@mobile->flags->manaRegenDouble	[G,S] When set the mobile will regenerate mana at twice their base mana regeneration rate.
@mobile->flags->manaRegenHalf	[G,S] When set the mobile will regenerate mana at half their base mana regeneration rate.
@mobile->flags->manaShield	[G,S] When set the mobile will replace hitpoint penalties with mana penalties when their hitpoints have reached zero and they take damage.
@mobile->flags->movesImpaired	[G,S] Not currently used.
@mobile->flags->movesRegenDouble	[G,S] When set the mobile will regenerate moves at twice their base moves regeneration rate.
@mobile->flags->movesRegenHalf	[G,S] When set the mobile will regenerate moves at half their base moves regeneration rate.
@mobile->flags->niceThief	[G,S] When set on an NPC mobile then the mobile will be "nice" to other mobiles attempting to steal from it. By "nice" the mobile won't attack, but instead give the thief a warning.
@mobile->flags->noCatchLooking	[G,S] When set, the mobile will never be caught looking at another mobile. This can be useful when you want to get the examine information for a mobile via output buffering.
@mobile->flags->noHold	[G,S] When set the mobile is unable to hold items in its off-hand.
@mobile->flags->noStun	[G,S] When set the mobile is immune to lag from commands and actions.
@mobile->flags->noWear	[G,S] When set the mobile cannot wear equipment.
@mobile->flags->noWield	[G,S] When set the mobile cannot wield anything.
@mobile->flags->paralysis	[G,S] When set the mobile is affected by paralysis. This is a meta flag that corresponds the state of both the handParalysis and footParalysis flags. Setting this flag will set both of them, unsetting this flag will unset both of them.
@mobile->flags->parry	[G,S] When set the mobile will attempt to parry melee attacks.
@mobile->flags->poison	[G,S] When set the mobile will suffer from poison affects.
@mobile->flags->protectionFromEvil	[G,S] When set the mobile will not be attackable by evil mobiles of considerably lower level. This flag can be bypased by scripts.
@mobile->flags->regenerate	[G,S] When set the mobile will regenerate hitpoints, mana, and moves 33% faster than their base rate.
@mobile->flags->sanctuary	[G,S] When set the mobile will have any damage dealt to it reduced by 1/3.
@mobile->flags->scavenger	[G,S] When set the mobile will act as a scavenger and randomly pick up stuff lying about. Corpses are excepted from scavenging; however, scripts may explicitly have a mobile pick up or loot a corpse.
@mobile->flags->senseLife	[G,S] When set the mobile can detect lifeforms in the room that may be hidden or invisible. The ability to sense life does not provide the identity of the sense lifeform.
@mobile->flags->sentinel	[G,S] When set the mobile will not wander around the world. If the mobile finds itself in a location other than the room in which it loaded then it will attempt to walk back (this happens when it flees, is commanded, charm runs out, summon, etc).
@mobile->flags->shide	[G,S] When set the mobile will move about the world as though affected by both sneak and hide.
@mobile->flags->shockingGrasp	[G,S] When set the mobile will deal a shock to an opponent engaged in melee combat.
@mobile->flags->shopKeeperAccept	[G,S] When set shopkeeper mobiles may accept items not listed in their shop supplies. This enables shopkeepers to also play parts in quests. When this flag is enabled, the builder should take extra care to ensure that the shopkeeper properly purges items from its inventory that should not be available for sale.
@mobile->flags->sickness	[G,S] When set the mobile will suffer the effects of sickness.
@mobile->flags->silence	[G,S] When set the mobile will be unable to use verbal commands/spells. This is very detrimental to magic user's effectiveness.
@mobile->flags->sleep	[G,S] When set the mobile will be unable to wake up at will.
@mobile->flags->smartCharm	[G,S] When set the mobile will continue to be able to use any scripts defined for when charmed, befriended, or trained.
@mobile->flags->snare	[G,S] Not currently used. This was originally used for the snare skill in old Cythera, but WoC uses the footParalysis flag instead which allows for more generic use.
@mobile->flags->sneak	[G,S] When set the mobile will not be noticed by other mobiles when moving from room to room.
@mobile->flags->stayArea	[G,S] When set an NPC mobile will not wander outside of its current area.
@mobile->flags->stayZone	[G,S] When set an NPC mobile will not wander outside of its current zone.
@mobile->flags->summoned	[G,S] When set the mobile is considered a "summoned" creature. This has no bearing on the summon spell but is used by such spells as "dispel evil", "holy word", "corrupt", and "unholy word".
@mobile->flags->sweeping	[G,S] No longer used.
@mobile->flags->trained	[G,S] When set the mobile is considered trained. This is used by the animal training skill to mark a creature as being a trained pet.
@mobile->flags->vampireDaywalk	[G,S] When set the mobile may walk freely in the sunlight even when it is a vampire.
@mobile->flags->waterBreath	[G,S] When set the mobile can breath underwater.
@mobile->flags->waterOnly	[G,S] When set the mobile will die if removed from a water terrain.
@mobile->flags->waterWalk	[G,S] When set the mobile can walk upon water a la Jesus.
@mobile->flags->wimpy	[G,S] When set the NPC mobile will automatically attempt to flee from combat when its hitpoints drop below 20%.

Imposter Specific Information
Imposter is the generic replacement for the disguise system. Unlike disguise an imposter can be assigned one or many attributes as part of the masquerade. Additionally, NPCs are no longer excluded from the fun. The disguise skill itself uses the imposter system along with an imposter type buff timer for expiration.
@mobile->imposter->isImposter	[G,S] Returns 1 if the mobile is currently masquerading as an imposter; otherwise returns 0. If assigned a value of 1 then a new imposter is intialised without any specific masquerading. If assigned a value of 0 then any the masquerade is removed and the mobile is no longer an imposter.
@mobile->imposter->mobileId	[G] Returns the ID of the mobile (if any) used to generate the imposter's masquerade.
@mobile->imposter->mobile	[G,S] Returns the name of the mobile (if any) used to generate the imposter's masquerade. A mobile ID, mobile pointer, or corpse object pointer may be assigned to this field to have the mobile masquerade as the associated mobile.
@mobile->imposter->raceId	[G] Returns the ID of the imposter's masquerading race if one has been assigned.
@mobile->imposter->racePtr	[G] Returns a pointer to the imposter's masquerading race structure if one has been assigned.
@mobile->imposter->race	[G,S] Returns the name of the imposter's masquerading race if one has been assigned. Alternatively, a race ID, race name, or race pointer can be assigned to the field to have the mobile masquerade as that race.
@mobile->imposter->genderId	[G] Returns the ID of the imposter's masquerading gender if one has been assigned.
@mobile->imposter->gender	[G,S] Returns the name of the imposter's masquerading gender if one has been assigned. Alternatively, a gender ID, gender name, or gender pointer can be assigned to the field to have the mobile masquerade as that gender.
@mobile->imposter->positionIdDefault	[G] Returns the ID of the imposter's masquerading default position if one has been assigned.
@mobile->imposter->positionDefault	[G,S] Returns the name of the imposter's masquerading default position if one has been assigned. Alternatively, a position ID or position name can be assigned to the field to have the mobile masquerade with that default position.
@mobile->imposter->keywords	[G,S] Returns the keywords that can target the imposter. Assigning a value sets the keywords that can target the imposter. When a mobile imposter is generated via the disguise skill, the keywords are merged from the first keyword of the masquerade, the original mobile's keywords, and all the keywords of the masquerade. In this way the imposter can still be targeted by their original keywords.
@mobile->imposter->descAction	[G,S] Returns the short description used for actions and activities. Assigning a value sets the action description for the the imposter. For instance setting this to "a Large Slime" would result in the following kinds of output: "a Large Slime leaves east."; "You are slapped by a Large Slime."
@mobile->imposter->descRoom	[G,S] Returns the longer room description used when the mobile is viewed in a room in their default position. Assigning a value sets the room description for the imposter. If the mobile is not in their default position then the action description is used and appended with their current position.

Vampire Specific Information
Vampirism is a combination of internal attributes on a mobile and the vampirism special affect items. The fields here for the most part hook into the internal structures. In some cases though, notably the isCompleteVapire field, the field is a meta field that provides aggregate behaviour based on both internal and special affect information. For instance, the isCompleteVampire field checks that both the appropriate internal fields exist and that the special affect item is in the special affects inventory. Additionally, assigning 0 to the field causes the internal structure to be wiped and the special affect item to be removed.
@mobile->vampire->bloodline	[G,S] The vampires current bloodline. Currently the only activated bloodline is "Veer Van Vladmeir".
@mobile->vampire->bloodlineId	[G,S] The ID of the bloodline. This field shouldn't be used unless comparing against another ID. The @mobile->vampire->bloodline field is much more maintainable with respect to future changes.
@mobile->vampire->bloodlust	[G,S] How well the vampire's bloodlust is satiated. The higher the better. If the value drops to 0 then the vampire will die.
@mobile->vampire->generation	[G,S] The vampire's generation. A vampire created by drinking from the unholy chalice will be generation 1. Vampires turned by generation 1 vampires will be generation 2. Vampires turned by generation 2 vampires will be generation 3 vampires, etc, etc.
@mobile->vampire->infectedById	[G,S] The unique player ID of the PC mobile that turned the infected mobile. If no such patron/matron exists then this will be 0.
@mobile->vampire->infectedByName	[G,S] The name of the source of the infection. This will also be set if the mobile was turned by the chalice or some other non-mobile source.
@mobile->vampire->infection	[G,S] The current infection level of the mobile. This is used in conjunction with bloodlust to determine when the mobile is ready for completion of the transformation to vampire.
@mobile->vampire->infectionTime	[G,S] A unix timestamp of when the mobile was turned.
@mobile->vampire->infectionTimespan	[G,S] I don't remember lol.
@mobile->vampire->isCompleteVampire	[G,S] A meta field that can be used to check whether a mobile has completely transformed to a vampire or not. Alternatively it can be assigned a 1 or a 0 to make the target mobile a vampire or completely remove vampirism from the mobile respectively.
@mobile->vampire->isVampire	[G,S] Returns true if the mobile is a vampire or is becoming a vampire.

Resolutions: Objects

Items define the non living things that can be found littering the world. Unlike in many other MUDs, items are not limited to only one type (such as food, potion, weapon). In the Worlds of Carnage multiple types can be assigned. So you can create an item that can be drank from and eaten, or a wand that can also be used as a sword. Following are the item fields that can currently be retrieved and set via the resolution operator. Each description is prefixed with either [G] gettable, [S] settable, or [G,S] gettable and settable. Resolutions are case sensitive.

General Information
Various information about the item.
@item->templateAreaId	[G] The ID for the area in which the item is described.
@item->templateAreaPtr	[G] A pointer to the area structure in which the item is described.
@item->buyValue	[G,S] The base value at which the item may be bought from a shop. This value is usually modified by any given shop's trade rates.
@item->container	[G] Returns a pointer to the item containing this object. If no such container item exists then `null` is returned.
@item->descInventory	[G,S] The text shown for the item when a player views it in their inventory.
@item->descRoom	[G,S] The text shown for the item when a player views it in the room.
@item->descExamine	[G,S] The default text presented when a player examines or looks at an item. This usually corresponds to the last extra defined for the item. However, other extras may obscure the default description if there are overlapping keywords.
@item->hitpoints	[G,S] The current number of hitpoints the item has.
@item->id	[G] The ID of the item. The same ID assigned to it in the builder and used to load it into the game.
@item->invisibilityLevel	[G,S] This determines the minimum level at which a mortal can see the item. Unlike the invisibility affect, this cannot be bypassed with the detect invisibility affect. The primary purpose of this field is to prevent access to an item by a low level mortal or to prevent the item from being detected in cases where it's purpose is to create an effect. Orbs created by the illuminate spell set this field to level 155 when dropped on the ground with the resulting effect of simulating the light spilling out into the room.
@item->keywords	[G,S] Keywords by which an item may be targetted. Keywords may be separated with spaces, commas, or semi-colons.
@item->level	[G,S] The level of the item. This currently determines the level at which the item may cast spells.
@item->longName	[G,S] Alias for @item->descRoom.
@item->maxHitpoints	[G,S] The number of hitpoints an item has when it is undamaged. When an item is repaired its hitpoints field is set to this value.
@item->name	[G,S] Alias for @item->descInventory.
@item->owner	[G] The current mobile owner of the item. If the item does not have an owner then `null` is returned.
@item->rentCost	[G,S] The base cost a mobile must pay to rent this item. Rent payments are no longer an active component of the game; however, this value is still used against a player's rent capacity.
@item->sellValue	[G,S] The base value at which the item may be sold to a shop. This value is usually modified by any given shop's trade rates.
@item->shortName	[G,S] Alias for @item->descInventory.
@item->timer	[G] Determines how many ticks until the object goes "poof" from the game. In addition to other custom uses, this field is used to define when corpses are automatically cleaned from the game.
@item->uniqueId	[G] A unique ID assigned to the item when it is created. The lifespan of the ID is until the item is rented or the game reboots.
@item->weight	[G,S] The weight of the item in stones. Unfortunately the game does not support a very fine grained weight system. In general one stone could be considered roughly equivalent to one pound.
@item->materialId	[G] The ID for the material from which this item is primarily made.
@item->materialPtr	[G] A pointer to the material structure that can be used with material resolutions.
@item->material	[G] The name of the material from which this item is primarily made.
@item->continentId	[G] The ID of the continent in which the item resides. Continents at this time have an influence over summon and gate spells since you can't jump between them using these spells. You should never store the continent ID or compare against a a literal integer value since it could change. It is better to store/compare against the key value.
@item->continentPtr	[G] A unique pointer to the continent data structure that can be used with continent specific resolutions.
@item->continentKey	[G] The simplified name of the continent which will consist of only alphabetic characters and underscores. If you need to store a continent identifier of compare against an explicit value then you should use this value. Example: western_islands
@item->continent	[G] The name of the continent as might be displayed to a player. Example: Western Islands
@item->areaId	[G] The ID of the area in which the item resides. You should never store the area ID or compare against a a literal integer value since it could change. It is better to store/compare against the key value.
@item->areaPtr	[G] A unique pointer to the area data structure that can be used with area specific resolutions.
@item->areaKey	[G] The simplified name of the area which will consist of only alphanumeric characters and underscores. If you need to store a area identifier of compare against an explicit value then you should use this value. Example: esa_isle
@item->area	[G] The name of the area as might be displayed to a player. Example: Esa Isle
@item->zoneId	[G] The ID of the zone in which the item resides.
@item->zonePtr	[G] A unique pointer to the zone data structure that can be used with zone specific resolutions.
@item->zone	[G] The name of the zone as shown when a zone resets or is loaded.
@item->roomId	[G] The ID of the room in which the item resides.
@item->roomPtr	[G] A unique pointer to the room data structure that can be used with room specific resolutions.
@item->room	[G] The name of the room as shown when a player looks at a room.

Variables
You can use these fields to retrieve and set entity, player, and saved variables for the item.
@item->evars->varName	[G,S] Sets or retrieves the value for the item's entity variable name "varName".
@item->pvars->varName	[G,S] Sets or retrieves the value for the item's player variable name "varName".
@item->svars->varName	[G,S] Sets or retrieves the value for the item's saved variable name "varName".

Inventory
These fields can be used to retrieve and move items into the item's inventory. This is generally only desireable when the item is a container.
@item->inventory	[G] Returns an array consisting of the items' contents.
@item->inventory->first	[G,S] Returns the first item contained by the item. If assigned a value then the assigned item is moved to the first position of the container's contents
@item->inventory->head	[G,S] An alias for @item->inventory->first.
@item->inventory->last	[G,S] Returns the last item contained by the item. If assigned a value then the assigned item is moved to the last position of the container's contents
@item->inventory->tail	[G,S] Alias for @item->inventory->last.

Inventory (short aliases)
Exactly the same as the inventory field counterparts except less typing is involved :)
@item->inv	[G] Alias for @item->inventory.
@item->inv->first	[G,S] Alias for @item->inventory->first.
@item->inv->head	[G,S] Alias for @item->inventory->head.
@item->inv->last	[G,S] Alias for @item->inventory->last.
@item->inv->tail	[G,S] Alias for @item->inventory->tail.

Buffs
Fields for retrieving information about any buffs on the item.
@item->buffs	[G] Returns an array of buff pointers currently on the item. Entries are indexed sequentially from 1 onward.
@item->buffs->first	[G,S] Returns a pointer to the first buff on the item.
@item->buffs->last	[G,S] Returns a pointer to the last buff on the item.
@item->buffs->head	[G,S] An alias for @item->buffs->first
@item->buffs->tail	[G,S] An alias for @item->buffs->last
@item->buffs->add	[G,S] An alias for @item->buffs->last

Extras
Fields for retrieving information about any extras on the item.
@item->extras	[G] Returns an array of extra pointers currently on the item. Entries are indexed sequentially from 1 onward.
@item->extras->first	[G,S] Returns a pointer to the first extra on the item.
@item->extras->last	[G,S] Returns a pointer to the last extra on the item.
@item->extras->head	[G,S] An alias for @item->extras->first
@item->extras->tail	[G,S] An alias for @item->extras->last

Wear Flags
These flags determine on which body locations the item can be worn by a mobile. Additionally, in a perverse abuse of the "wear" concept, the ability to pick the item up off the ground is also included in this list. This perversion is maintained for historical reasons. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@item->canGet	[G,S] Determines whether the item can be picked up from the ground or floor.
@item->canTake	[G,S] Alias for @item->canGet
@item->hold	[G,S] Determines whether the item can be held such as for wands, staves, and weapons.
@item->wearAbout	[G,S] Determines whether the item can be worn about the body such as for cloaks.
@item->wearArm	[G,S] Alias for @item->wearArms.
@item->wearArms	[G,S] Determines whether the item can be worn on the arms such as for armbands.
@item->wearBody	[G,S] Determines whether the item can be worn on the body such as for vests and body armour.
@item->wearFeet	[G,S] Determines whether the item can be worn on the feet such as for boots.
@item->wearFinger	[G,S] Alias for @item->wearFingers.
@item->wearFingers	[G,S] Determines whether the item can be worn on the fingers such as for rings.
@item->wearFoot	[G,S] Alias for @item->wearFeet.
@item->wearHand	[G,S] Alias for @item->wearHands.
@item->wearHands	[G,S] Determines whether the item can be worn on the hands such as for gloves and gauntlets.
@item->wearHead	[G,S] Determines whether the item can be worn on the head such as for helms and crowns.
@item->wearLeg	[G,S] Alias for @item->wearLegs.
@item->wearLegs	[G,S] Determines whether the item can be worn on the legs such as for leg plates and pants.
@item->wearNeck	[G,S] Determines whether the item can be worn on the neck such as for necklaces and pendants.
@item->wearShield	[G,S] Determines whether the item can be worn as a shield.
@item->wearWaist	[G,S] Determines whether the item can be worn around the waist such as for belts.
@item->wearWrist	[G,S] Alias for @item->wearWrists.
@item->wearWrists	[G,S] Determines whether the item can be worn on the wrists such as for bracers.
@item->wield	[G,S] Determines whether the item can be wielded such as for swords and clubs.

Flags
Flags are boolean values that enable or disable features for the object. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@item->flags->canGet	[G,S] Alias for @item->canGet.
@item->flags->canTake	[G,S] Alias for @item->canGet.
@item->flags->expires	[G,S] Determines whether the item expires or not. This is used in conjunction with @item->timer. If this flag is set then the timer is reduced by 1 each tick that the item is in a PC mobiles inventory or equipment.
@item->flags->expiresAnywhere	[G,S] Determines whether the item expires or not. This is used in conjunction with @item->timer. If this flag is set then the timer is reduced by 1 each tick regardless of the item's location.
@item->flags->expiresWhenWorn	[G,S] Determines whether the item expires or not. This is used in conjunction with @item->timer. If this flag is set then the timer is reduced by 1 each tick that the item is worn by a PC mobile.
@item->flags->isAntiEvil	[G,S] if this flag is set then evil mobiles cannot wear the item.
@item->flags->isAntiGood	[G,S] If this flag is set then goodly mobiles cannot wear the item.
@item->flags->isAntiNeutral	[G,S] If this flag is set then neutral mobiles cannot wear the item.
@item->flags->isBlessed	[G,S] Flags the item as blessed. This also has the effect of augmenting the item's description with "... It glows softly!".
@item->flags->isCursed	[G,S] Flags the item as cursed. A cursed item cannot be dropped until the curse has been removed. Cursed items can also be stolen.
@item->flags->isDark	[G,S] This flag has no known usage at this time.
@item->flags->isEquipped	[G] Returns 1 if the item is currenty equipped by a mobile.
@item->flags->isEvil	[G,S] Flags the item as being evil. Evil items cannot be blessed.
@item->flags->isGlowing	[G,S] Flags the item as glowing. This has the effect of augmenting the item's description with "... It glows softly!".
@item->flags->isHumming	[G,S] Flags the item as humming. This has the effect of augmenting the item's description with "... It hums quietly!".
@item->flags->isInAffects	[G] Returns 1 if the item is currenty in a mobile's special affects inventory; 0 oitherwise.
@item->flags->isInContainer	[G] Returns 1 if the item is currenty in a container item; 0 otherwise.
@item->flags->isInInventory	[G] Returns 1 if the item is currenty in a mobile's regular inventory; 0 otherwise.
@item->flags->isInRoom	[G] Returns 1 if the item is currenty in a room; 0 otherwise.
@item->flags->isInvisible	[G,S] Flags the item as being invisible. To see it the viewer must be affected by detect invisible.
@item->flags->isMagical	[G,S] Flags the item as magical. This flags has different uses in the game. One use is that weapons having this flag enabled cannot be enchanted.
@item->flags->isNicknamed	[G,S] When enabled it indicates that the item has a nickname.
@item->flags->isNoDrop	[G,S] Alias for @item->flags->isCursed.
@item->flags->isNoDamage	[G,S] Item cannot be damage when this flag is set.
@item->flags->isNoDestroy	[G,S] Item cannot be destroyed when this flag is set. This differs from the `isNoDamage` flag because it can be damaged to near destruction but not actually destroyed.
@item->flags->isNoExtract	[G,S] Prevents the item from being removed from play when an owning mobile is killed or purged. In other words, the item should be a permanent part of the character. This flag is most often used in conjunction with special affect items such as Vampirism.
@item->flags->isNoGive	[G,S] When enabled it prevents the item from being given to another mobile.
@item->flags->isNoLocate	[G,S] When enabled it prevents the item from being located using the locate object spell.
@item->flags->isNoRemove	[G,S] When enabled it prevents the item from being removed if worn.
@item->flags->isNoZoneUnload	[G,S] When enabled it indicates to the game engine not to unload the item when the zone resets.
@item->flags->isTwoHanded	[G,S] Flags the item as requiring two hands to wield.

Affect Specific
Fields relevant to items that have had been assigned the "affect" type.
@item->affect->owner	[G,S] A pointer to the owner of the affect (if set). Setting the value of this field is optional.
@item->affect->skillName	[G,S] The name of the skill with which this affect is associated. This field is optional.
@item->affect->antidotes	[G,S] An array of values that define antidotes for the affect. Generally antidotes will match the names of skills than can be used to neutralize the affect; however, custom quest oriented names can be used also. The internal mobile AI engine uses this list to determine if the mobile can neutralize the affect if it is negative.
@item->affect->antidotes->add	[S] Meta field for adding new antidotes to the list of possible antidotes for the affect.
@item->affect->antidotes->delete	[S] Meta field for deleting antidotes from the list of possible antidotes for the affect.

Armour Specific
Fields relevant to items that have had been assigned the "armour" type.
@item->armour->acFactor	[G,S] The factor by which this item increases a mobile's armour class when worn. This is denoted as a factor since the exact armour class modification depends on the worn location. For more details see "help armour types".
@item->armor->acFactor	[G,S] An alias for @item->armour->acFactor.

Arrow Specific
Fields relevant to items that have had been assigned the "arrow" type.
@item->arrow->damageString	[G,S] The amount of damage the arrow contributes to the overall damage calculation from combining the arrow's damage and the bow's damage when a successful hit occurs. This is not generally a rote value but rather a simple mathematical formula that is evaluated during damage calculation. For instance one might assign the following value: `"10 + 1d5"`
@item->arrow->damageType	[G,S] The type of damage the arrow will inflict. The following values are possible: acid, bite, bludgeon, breath, claw, cold, crush, deadlyPoison, drainLife, electric, fire, hit, mental, negativeEnergy, pierce, poison, positiveEnergy, pound, slash, smash, sting, whip

Body Part Specific
Fields relevant to items that have had been assigned the "body part" type.
@item->bodyPart	[S] A meta field to which a corpse pointer can be assigned such that relevant body part fields can be automatically derived.
@item->bodyPart->mobId	[G,S] The ID of the mobile to which the body part belongs. This wil be 0 when the body part is from a PC mobile.
@item->bodyPart->name	[G,S] The name of the mobile to which the body part belongs. In the case of NPCs this will be set to the mobile's `@mob->descShort` field. In the case of a PC mobile this will be set to their name.
@item->bodyPart->race	[G,S] The race of the creature to which the body part belongs (eg. elf, gnome, troll, human).
@item->bodyPart->level	[G,S] The level of the creature to which the body part belongs.
@item->bodyPart->flags->isPc	[G,S] Flags the body part as having belonged to a PC mobile.
@item->bodyPart->flags->isNpc	[G,S] Flags the body part as having belonged to an NPC mobile.
@item->bodyPart->flags->isDust	[G,S] Flags the body part as being dust.
@item->bodyPart->flags->isSlime	[G,S] Flags the body part as being slime.
@item->bodyPart->flags->isGelatin	[G,S] Flags the body part as being gelatin.
@item->bodyPart->flags->isHusk	[G,S] Flags the body part as being a husk.

Bow Specific
Fields relevant to items that have had been assigned the "bow" type.
@item->bow->nockFactor	[G,S] This field determines how long it takes to pull an arrow using the bow. A higher nockFactor means longer pull time, but also means that the arrow will inflict more damage upon hitting the target.
@item->bow->damageString	[G,S] The amount of damage the bow contributes to the overall damage calculation from combining the arrow's damage and the bow's damage when a successful hit occurs. This is not generally a rote value but rather a simple mathematical formula that is evaluated during damage calculation. For instance one might assign the following value: `"10 + 1d5"`

Container Specific
Fields relevant to items that have had been assigned the "container" type.
@item->container->maxCapacity	[G,S] The maximum capacity of the container. This determines how much the container can hold. It is a measure of the weight of items that may be placed inside the container.
@item->container->usedCapacity	[G,S] The current capacity of the container being consumed by contents. It is a measure of the weight of itemscurrently in the container.
@item->container->pickResilience	[G,S] Not currently implemented.
@item->container->forceResilience	[G,S] Not currently implemented.
@item->container->keys	[G,S] Returns an array consisting of the IDs of objects that may be used as keys to unlock this container. An array of IDs may also be assigned that will determine what items can unlock the container.
@item->container->keys->add	[S] A meta field to which an item ID can be assigned and which will then be added to the list of valid key IDs.
@item->container->keys->delete	[S] A meta field to which an item ID can be assigned and which will result in that ID being removed from the list of valid key IDs.
@item->container->flags->canClose	[G,S] Determines whether the container can be closed or not.
@item->container->flags->isCloseable	[G,S] Alias for @item->container->flags->canClose.
@item->container->flags->isClosed	[G,S] Flags the container as currently closed.
@item->container->flags->hasLock	[G,S] Determines whether the container has a lock.
@item->container->flags->isLocked	[G,S] Flags the container as currently locked.
@item->container->flags->isPickproof	[G,S] Flags the container as not being pickable (a la pick skill).
@item->container->flags->isFreeStorage	[G,S] Flags the container as providing free storage. Items placed within a container with this flag enabled will not count against a players rent capacity.
@item->container->flags->isInverted	[G,S] Flags the container as inverted. An inverted container will display its contents when viewed. For instance the belt of heads worn by Groulth in Elkin is an inverted container and displays the heads as though attached to the outside.

Corpse Specific
Fields relevant to items that have had been assigned the "corpse" type.
@item->corpse->mobId	[G,S] The ID of the mobile to which the corpse belongs. This wil be 0 when the corpse is from a PC mobile. The monster zombie uses this field to load an appropriate zombie for the corpse.
@item->corpse->name	[G,S] The name of the mobile to which the corpse belongs. In the case of NPCs this will be set to the mobile's `@mob->descShort` field. In the case of a PC mobile this will be set to their name. The monster zombie spell uses this field to re-assign the exact name to the zombie.
@item->corpse->race	[G,S] The race of the creature to which the corpse belongs (eg. elf, gnome, troll, human).
@item->corpse->level	[G,S] The level of the creature to which the corpse belongs.
@item->corpse->lifeforce	[G,S] A value assigned to the corpse (currently based on level) which at the current time is used to determine vampire bloodlust satiation.
@item->corpse->flags->isPc	[G,S] Flags the corpse as having belonged to a PC mobile.
@item->corpse->flags->isNpc	[G,S] Flags the corpse as having belonged to an NPC mobile.
@item->corpse->flags->isDecapitated	[G,S] Flags the corpse as having been decapitated.
@item->corpse->flags->isDisguiseUsed	[G,S] Flags the corpse as having been plundered for a disguise.
@item->corpse->flags->isSkinnable	[G,S] Determines whether the corpse can have a skin removed.
@item->corpse->flags->isSkinned	[G,S] Flags the corpse as having been skinned.
@item->corpse->flags->isDust	[G,S] Flags the corpse as being dust (such as for vampires).
@item->corpse->flags->isSlime	[G,S] Flags the corpse as being slime (such as for slimes).
@item->corpse->flags->isGelatin	[G,S] Flags the corpse as being gelatin (such as for gelatins ;)
@item->corpse->flags->isHusk	[G,S] Flags the corpse as being a husk (such as for dopplegangers).

Drink Specific
Fields relevant to items that have had been assigned the "drink" type.
@item->drink->name	[G,S] The name of the drink (eg. beer, water, wine).
@item->drink->colour	[G,S] The colour of the drink's liquid (eg. brown, clear, red).
@item->drink->color	[G,S] An alias for @item->drink->colour.
@item->drink->maxCapacity	[G,S] The maximum drink units that the item may contain.
@item->drink->usedCapacity	[G,S] The current number of drink units being used (filled up amount).
@item->drink->affectDrunk	[G,S] The amount by which a drink of the liquid affects a mobile's drunkeness (negative values can be used to make the mobile less drunk).
@item->drink->affectHunger	[G,S] The amount by which a drink of the liquid affects a mobile's fullness (negative values can be used to make the mobile hungrier).
@item->drink->affectThirst	[G,S] The amount by which a drink of the liquid affects a mobile's thirst fullness (negative values can be used to make the mobile thirstier).
@item->drink->flags->isPoisoned	[G,S] Flags the drink is poisoned.
@item->drink->flags->isEmpty	[G,S] Meta flag that returns 1 if there is nothing left to drink; otherwise returns 0.

Herb Specific
Fields relevant to items that have had been assigned the "herb" type.
@item->herb->maxUses	[G,S] The maximum number of times the herb may be used.
@item->herb->usesLeft	[G,S] The current number of uses remaining.
@item->herb->quality	[G,S] The quality of the herb. This influences it's potency in the same way quality of spells/skills influence their potency.
@item->herb->chanceFind	[G,S] The chance that the herb can be found while foraging.
@item->herb->chanceWorks	[G,S] The chance that the herb will work when used.
@item->herb->prepTime	[G,S] The amount of time required to prep the herb for use.
@item->herb->preppedValueFactor	[G,S] I don't remember.
@item->herb->preppedTypes	[G,S] Returns an array of prep types supported by the herb. The following values are currently supported: salve, liquid, dried, potion, spellComponent. Similarly an array may be assigned to this field to set the supported prep types.
@item->herb->preppedTypes->add	[S] A meta field for adding support for a prep type to the herb.
@item->herb->preppedTypes->delete	[S] A meta field for removing support for a prep type form the herb.
@item->herb->harvestTerrains	[G,S] Returns an array of terrains where the herb may be found via forage. Similarly an array of terrains may be assigned to the field to set the supported harvest terrains. See the list of terrain types for rooms for possible values.
@item->herb->harvestTerrains->add	[S] A meta field for adding support for a harvest terrain.
@item->herb->harvestTerrains->delete	[S] A meta field for removing support for a harvest terrain.
@item->herb->harvestMonths	[G,S] Returns an array of months during which the herb may be found via forage. Similarly an array of months may be assigned to the field to set the supported harvest months. The month values should be enumerated value of the month (eg. month of nature == 7).
@item->herb->harvestMonths->add	[S] A meta field for adding support for a harvest month.
@item->herb->harvestMonths->delete	[S] A meta field for removing support for a harvest month.

Food Specific
Fields relevant to items that have had been assigned the "food" type.
@item->food->portionSize	[G,S] The amount the food satiates a mobile's hunger.
@item->food->flags->isPoisoned	[G,S] Flags the food as poisoned.

Key Specific
Fields relevant to items that have had been assigned the "key" type.
@item->key->locks	[G,S] Returns an array consisting of the IDs of rooms/containers that the key can lock and unlock. An array of IDs may also be assigned that describe what rooms/containers the key can lock and unlock. The actual lock and unlock functionality is defined by the container or room and this value merely serves to show the reverse mapping without having any functional ability.
@item->key->locks->add	[S] A meta field to which a room or container ID can be assigned and which will then be added to the list of rooms/containers that this key can lock and unlock.
@item->key->locks->delete	[S] A meta field to which a room or container ID can be assigned and which will then cause the removal of that id from the list of lock IDs.

Light Specific
Fields relevant to items that have had been assigned the "light" type.
@item->light->duration	[G,S] The maxmum duration of the light source as measured in ticks.
@item->light->timeLeft	[G,S] The current remaining duration of the light source. For each tick that the light source is found equipped, the time left is reduced by 1.
@item->light->brightness	[G,S] The brightness of the light source. Light sources most commonly emit a brightness of 100. Brightness range can be from -1000 to 1000 with negative values inducing darkness.
@item->light->flags->isEternal	[G,S] Flags the light source as being eternal.
@item->light->flags->isExpired	[G,S] Flags the light source as having expired.

Missile Specific
Fields relevant to items that have had been assigned the "missile" type.
@item->missile->damageString	[G,S] The amount of damage the missile inflicts when a successful hit occurs. This is not generally a rote value but rather a simple mathematical formula that is evaluated during damage calculation. For instance one might assign the following value: `"10 + 1d5"`
@item->missile->damageType	[G,S] The type of damage the missile will inflict. The following values are possible: acid, bite, bludgeon, breath, claw, cold, crush, deadlyPoison, drainLife, electric, fire, hit, mental, negativeEnergy, pierce, poison, positiveEnergy, pound, slash, smash, sting, whip

Money Specific
Fields relevant to items that have had been assigned the "money" type.
@item->money->amount	[G,S] The amount of gold by which to raise the player's on hand gold when the item is picked up.

Note Specific
Fields relevant to items that have had been assigned the "note" type.
@item->note->content	[G,S] The content of the note.
@item->note->language	[G,S] The language in which the note's content is written. The content is always stored verbatim as typed (usually english). When a mobile attempts to read the note if they do not understand the language that this field denotes, then the message is scrambled in such a way as to be unreadable.

Potion Specific
Fields relevant to items that have had been assigned the "potion" type.
@item->potion->spells	[G,S] Returns an array of all the spells that will be applied to a mobile when it quaffs the potion. Each entry in the array will itself be an array consisting of the following fields: name, level, quality. A similar array may be assigned to the this field that will set the spells.
@item->potion->spells->add	[S] This is a meta field that enables individual spells to be added to the potion. Two formats are accepted. A string consisting of the name of a spell can be assigned in which case the spell's quality defaults to 100 and the spell's level defaults to the level of the item. Alternatively an array may be assigned to this field consisting of the following fields to explicitly set the associate spell criteria: name, level, quality.
@item->potion->spells->delete	[S] This is a meta field that enables spells of the given name to be removed from the potion's list of spells.

Resource Specific
Fields relevant to items that have had been assigned the "resource" type.
@item->resource->race	[G,S] For resources of organic origin, this field can be set to the name of the associated race.

Rod Specific
Fields relevant to items that have had been assigned the "rod" type.
@item->rod->charges	[G,S] The number of charges remaining in the rod.
@item->rod->maxCharges	[G,S] The maximum number of charges the rod contains.
@item->rod->spells	[G,S] Returns an array of all the spells that will be applied to a mobile when it is targetted by the rod. Each entry in the array will itself be an array consisting of the following fields: name, level, quality. A similar array may be assigned to the this field that will set the spells.
@item->rod->spells->add	[S] This is a meta field that enables individual spells to be added to the rod. Two formats are accepted. A string consisting of the name of a spell can be assigned in which case the spell's quality defaults to 100 and the spell's level defaults to the level of the item. Alternatively an array may be assigned to this field consisting of the following fields to explicitly set the associate spell criteria: name, level, quality.
@item->rod->spells->delete	[S] This is a meta field that enables spells of the given name to be removed from the rod's list of spells.

Scroll Specific
Fields relevant to items that have had been assigned the "scroll" type.
@item->scroll->spells	[G,S] Returns an array of all the spells that will be applied to the target of the scroll. Each entry in the array will itself be an array consisting of the following fields: name, level, quality. A similar array may be assigned to the this field that will set the spells.
@item->scroll->spells->add	[S] This is a meta field that enables individual spells to be added to the scroll. Two formats are accepted. A string consisting of the name of a spell can be assigned in which case the spell's quality defaults to 100 and the spell's level defaults to the level of the item. Alternatively an array may be assigned to this field consisting of the following fields to explicitly set the associate spell criteria: name, level, quality.
@item->scroll->spells->delete	[S] This is a meta field that enables spells of the given name to be removed from the scroll's list of spells.

Staff Specific
Fields relevant to items that have had been assigned the "staff" type.
@item->staff->charges	[G,S] The number of charges remaining in the staff.
@item->staff->maxCharges	[G,S] The maximum number of charges the staff contains.
@item->staff->spells	[G,S] Returns an array of all the spells that will be applied to the targets of the staff when it is used. Each entry in the array will itself be an array consisting of the following fields: name, level, quality. A similar array may be assigned to the this field that will set the spells.
@item->staff->spells->add	[S] This is a meta field that enables individual spells to be added to the staff. Two formats are accepted. A string consisting of the name of a spell can be assigned in which case the spell's quality defaults to 100 and the spell's level defaults to the level of the item. Alternatively an array may be assigned to this field consisting of the following fields to explicitly set the associate spell criteria: name, level, quality.
@item->staff->spells->delete	[S] This is a meta field that enables spells of the given name to be removed from the staff's list of spells.

Tome Specific
Fields relevant to items that have had been assigned the "tome" type.
@item->tome->skillName	[G,S] The name of the skill that the tome allows a player to learn.
@item->tome->level	[G,S] Not currently implemented.
@item->tome->flags->isCursed	[G,S] Not currently implemented.
@item->tome->flags->isExploding	[G,S] Not currently implemented.

Trap Specific
Fields relevant to items that have had been assigned the "trap" type.
@item->trap->damageString	[G,S] The amount of damage the trap inflicts when a successful hit occurs. This is not generally a rote value but rather a simple mathematical formula that is evaluated during damage calculation. For instance one might assign the following value: `"10 + 1d5"`
@item->trap->damageType	[G,S] The type of damage the trap will inflict. The following values are possible: acid, bite, bludgeon, breath, claw, cold, crush, deadlyPoison, drainLife, electric, fire, hit, mental, negativeEnergy, pierce, poison, positiveEnergy, pound, slash, smash, sting, whip

Wand Specific
Fields relevant to items that have had been assigned the "wand" type.
@item->wand->charges	[G,S] The number of charges remaining in the wand.
@item->wand->maxCharges	[G,S] The maximum number of charges the wand contains.
@item->wand->spells	[G,S] Returns an array of all the spells that will be applied to the target of the wand's effects. Each entry in the array will itself be an array consisting of the following fields: name, level, quality. A similar array may be assigned to the this field that will set the spells.
@item->wand->spells->add	[S] This is a meta field that enables individual spells to be added to the wand. Two formats are accepted. A string consisting of the name of a spell can be assigned in which case the spell's quality defaults to 100 and the spell's level defaults to the level of the item. Alternatively an array may be assigned to this field consisting of the following fields to explicitly set the associate spell criteria: name, level, quality.
@item->wand->spells->delete	[S] This is a meta field that enables spells of the given name to be removed from the wand's list of spells.

Weapon Specific
Fields relevant to items that have had been assigned the "weapon" type.
@item->weapon->damageString	[G,S] The amount of damage the weapon inflicts when a successful hit occurs. This is not generally a rote value but rather a simple mathematical formula that is evaluated during damage calculation. For instance one might assign the following value: `"10 + 1d5"`
@item->weapon->damageType	[G,S] The type of damage the weapon will inflict. The following values are possible: acid, bite, bludgeon, breath, claw, cold, crush, deadlyPoison, drainLife, electric, fire, hit, mental, negativeEnergy, pierce, poison, positiveEnergy, pound, slash, smash, sting, whip

Resolutions: Races

Using %getRacePtr() you can retrieve a pointer for the given race ID or name that will allow you to retrieve information via the resolutions defined here. Each description is prefixed with either [G] gettable, [S] settable, or [G,S] gettable and settable. Resolutions are case sensitive.

General Information
General racial fields for working with race information.
@race->id	[G] ...
@race->name	[G] ...
@race->tagName	[G] ...
@race->utters	[G] ...

Initialization Basepoints
These determine to what values the associated field is initialized when a mobile of the given race is created. Initialization values are constants but the engine will add a +/-10% fuzziness factor.
@race->initArmourClass	[G] ...
@race->initHitpoints	[G] ...
@race->initMana	[G] ...
@race->initMoves	[G] ...
@race->initPractices	[G] ...

Primary Stat Minimums
These define a lower bound on the primary stats for a mobile of the given race. This primarily determines the starting values for PC members of the race. NPC members will be assigned a value within the min/max range if the value for the primary stat is not explicitly set by the builder.
@race->minCharisma	[G] ...
@race->minConstitution	[G] ...
@race->minDexterity	[G] ...
@race->minIntelligence	[G] ...
@race->minStrength	[G] ...
@race->minWisdom	[G] ...

Primary Stat Maximums
These define an upper bound on the primary stats for a mobile of the given race. This primarily determines the maximum values for PC members of the race when stats make gains during gameplay. NPC members will be assigned a value within the min/max range if the value for the primary stat is not explicitly set by the builder.
@race->maxCharisma	[G] ...
@race->maxConstitution	[G] ...
@race->maxDexterity	[G] ...
@race->maxIntelligence	[G] ...
@race->maxStrength	[G] ...
@race->maxWisdom	[G] ...

Miscellaneous Stat Minimums
The semantics for these fields follow that of the primary stat minimums.
@race->minFemaleHeight	[G] ...
@race->minFemaleWeight	[G] ...
@race->minMaleHeight	[G] ...
@race->minMaleWeight	[G] ...
@race->minNightVision	[G] ...

Miscellaenous Stat Maximums
The semantics for these fields follow that of the primary stat maximums.
@race->maxFemaleHeight	[G] ...
@race->maxFemaleWeight	[G] ...
@race->maxMaleHeight	[G] ...
@race->maxMaleWeight	[G] ...
@race->maxNightVision	[G] ...
@race->castingConcentration	[G] ...
@race->castingCost	[G] ...
@race->castingTime	[G] ...

Stat Gain Rates
These determine the speed at which the relevant stat makes gains. Given that some basepoint is set to 100% these can be set to increase or decrease the odds that a player will make a successful roll for a stat gain.
@race->gainRateHitpoints	[G] ...
@race->gainRateMana	[G] ...
@race->gainRateMoves	[G] ...
@race->gainRatePractices	[G] ...

Regen Rates
These determine the rate at which the mobile regenerates its supply of the associated stat. For instance trolls have a regenRateHitpoints value of 200 which means they regenerate their hitpoints at 200% of normal. In layman's terms, they regen at twice the speed of most races.
@race->regenRateHitpoints	[G] ...
@race->regenRateMana	[G] ...
@race->regenRateMoves	[G] ...

Flags
Miscellaneous race specific flags. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@race->flags->isPcRace	[G] ...
@race->flags->isTrainable	[G] ...
@race->flags->isSkinnable	[G] ...

Wear Locations
The following flags denote flags that determine whether a mobile of the given race can wear equipment in the associated equipment slot. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@race->wear->fingers	[G] ...
@race->wear->neck	[G] ...
@race->wear->body	[G] ...
@race->wear->head	[G] ...
@race->wear->legs	[G] ...
@race->wear->feet	[G] ...
@race->wear->hands	[G] ...
@race->wear->arms	[G] ...
@race->wear->shield	[G] ...
@race->wear->about	[G] ...
@race->wear->waist	[G] ...
@race->wear->wrist	[G] ...
@race->wear->wield	[G] ...
@race->wear->hold	[G] ...

Innate Abilities/Affects
The following fields determine innate abilities and effects that a mobile of the given race is automatically and permanently granted when it is created. In some cases (such as vampires) a merging of the racial flags takes place. Hence a reptilian vampire can both fly and breathe water.
@race->affects->antiMagic	[G] ...
@race->affects->blind	[G] ...
@race->affects->chillTouch	[G] ...
@race->affects->comprehension	[G] ...
@race->affects->cursed	[G] ...
@race->affects->darkRegenBonus15	[G] ...
@race->affects->darkRegenBonus30	[G] ...
@race->affects->deadlyPoison	[G] ...
@race->affects->deathsDoor	[G] ...
@race->affects->depravity	[G] ...
@race->affects->detectAura	[G] ...
@race->affects->detectInvisible	[G] ...
@race->affects->detectMagic	[G] ...
@race->affects->dodge	[G] ...
@race->affects->evilOrigin	[G] ...
@race->affects->fear	[G] ...
@race->affects->feebleMind	[G] ...
@race->affects->fieryVortex	[G] ...
@race->affects->fistsOfFury	[G] ...
@race->affects->fly	[G] ...
@race->affects->footParalysis	[G] ...
@race->affects->forestRegenBonus25	[G] ...
@race->affects->forestRegenBonus50	[G] ...
@race->affects->goodOrigin	[G] ...
@race->affects->handParalysis	[G] ...
@race->affects->hide	[G] ...
@race->affects->hitpointsRegenBonus100	[G] ...
@race->affects->hitpointsRegenPenalty50	[G] ...
@race->affects->infravision	[G] ...
@race->affects->insanity	[G] ...
@race->affects->invisible	[G] ...
@race->affects->invulnerable	[G] ...
@race->affects->lichTouch	[G] ...
@race->affects->manaRegenBonus100	[G] ...
@race->affects->manaRegenPenalty50	[G] ...
@race->affects->manaShield	[G] ...
@race->affects->moveImpaired	[G] ...
@race->affects->movesRegenBonus100	[G] ...
@race->affects->movesRegenPenalty50	[G] ...
@race->affects->paralysis	[G] ...
@race->affects->parry	[G] ...
@race->affects->poisoned	[G] ...
@race->affects->protectFromEvil	[G] ...
@race->affects->regenerate	[G] ...
@race->affects->sanctuary	[G] ...
@race->affects->senseLife	[G] ...
@race->affects->shide	[G] ...
@race->affects->shockingGrasp	[G] ...
@race->affects->sickness	[G] ...
@race->affects->silenced	[G] ...
@race->affects->sneak	[G] ...
@race->affects->summoned	[G] ...
@race->affects->superFlee	[G] ...
@race->affects->superHunt	[G] ...
@race->affects->vampireDaywalk	[G] ...
@race->affects->waterBreath	[G] ...
@race->affects->waterRegenBonus25	[G] ...
@race->affects->waterRegenBonus50	[G] ...
@race->affects->waterWalk	[G] ...

Resolutions: Rooms

Rooms define the locations available geographically within the mud. Linking of rooms creates routes, and groups of rooms define areas, and groups of areas define continents. Following are the room fields that can currently be retrieved and set via the resolution operator. Each description is prefixed with either [G] gettable, [S] settable, or [G,S] gettable and settable. Resolutions are case sensitive.

General Information
Various fields to retrieve and set room information.
@room->id	[G] The ID (vnum) of the room as assigned by the builder.
@room->uniqueId	[G] The unique ID of the room. This will change when the area reloads or the MUD reboots.
@room->level	[G,S] The level of the room. This is used for magical effects invoked by the room.
@room->terrainType	[G,S] The terrain type. This will be one of the following textual identifiers (the preferred way to test for a terrain type): inside, city, field, forest, hills, mountain, swimWater, noSwimWater, underwater, desert, air, jungle, tundra, plain, swamp
@room->terrainName	[G] The name of the terrain. This is a user friendly name for the terrain, and can be embedded in output intended to be read.
@room->terrainTypeId	[G,S] The integer ID of the terrain type. This should not be used in comparisons against explicit integer values.
@room->sizeType	[G,S] The size of the room. This will be one of the following textual identifiers (the preferred way to test for a room's size): micro, tiny, small, medium, large, huge, enormous, gargantuan, unlimited
@room->sizeTypeId	[G,S] The integer ID of the room's size type. This should not be used in comparisons against explicit integer values.
@room->name	[G,S] The name (or title) of the room.
@room->description	[G,S] The room's description when a player types "look".
@room->brightness	[G] The ambient brightness. Players can see in brightness of 101 (this can differ to some degree based on race).
@room->continentId	[G] The ID of the continent in which the room resides. Continents at this time have an influence over summon and gate spells since you can't jump between them using these spells. You should never store the continent ID or compare against a a literal integer value since it could change. It is better to store/compare against the key value.
@room->continentPtr	[G] A unique pointer to the continent data structure that can be used with continent specific resolutions.
@room->continentKey	[G] The simplified name of the continent which will consist of only alphabetic characters and underscores. If you need to store a continent identifier of compare against an explicit value then you should use this value. Example: western_islands
@room->continent	[G] The name of the continent as might be displayed to a player. Example: Western Islands
@room->areaId	[G] The ID of the area in which the room resides. You should never store the area ID or compare against a a literal integer value since it could change. It is better to store/compare against the key value.
@room->areaPtr	[G] A unique pointer to the area data structure that can be used with area specific resolutions.
@room->areaKey	[G] The simplified name of the area which will consist of only alphanumeric characters and underscores. If you need to store a area identifier of compare against an explicit value then you should use this value. Example: esa_isle
@room->area	[G] The name of the area as might be displayed to a player. Example: Esa Isle
@room->zoneId	[G] The ID of the zone in which the room resides.
@room->zonePtr	[G] A unique pointer to the zone data structure that can be used with zone specific resolutions.
@room->zone	[G] The name of the zone as shown when a zone resets or is loaded.

Variables
You can use these fields to retrieve and set entity, player, and saved variables for the room.
@room->evars->varName	[G,S] Sets or retrieves the value for the room's entity variable name "varName".
@room->pvars->varName	[G,S] Sets or retrieves the value for the room's player variable name "varName".
@room->svars->varName	[G,S] Sets or retrieves the value for the room's saved variable name "varName".

Exits
You can use these fields to retrieve and set exits for the room. Assigning a room pointer or ID to an exit field will cause the room to re-link that exit to the assigned room.
@room->exits	[G] Returns an array of exits indexed by the associated cardinal direction's name. The following indexes may be set: north, south, east, west, up, down.
@room->exits->north	[G] Returns a pointer to the exit leading north; otherwise null.
@room->exits->east	[G] Returns a pointer to the exit leading east; otherwise null.
@room->exits->south	[G] Returns a pointer to the exit leading south; otherwise null.
@room->exits->west	[G] Returns a pointer to the exit leading west; otherwise null.
@room->exits->up	[G] Returns a pointer to the exit leading up; otherwise null.
@room->exits->down	[G] Returns a pointer to the exit leading down; otherwise null.

Mobiles
Fields for retrieving information about any mobiles in the room.
@room->mobiles	[G] Returns an array of mobile pointers currently in the room. Entries are indexed sequentially from 1 onward.
@room->mobiles->total	[G] Returns the number of mobiles in the room.
@room->mobiles->count	[G] An alias for @room->mobiles->total
@room->mobiles->first	[G,S] Returns a pointer to the first mobile in the room. If assigned a pointer to a mobile then the mobile is moved to the first position in the room.
@room->mobiles->last	[G,S] Returns a pointer to the last mobile in the room. If assigned a pointer to a mobile then the mobile is moved to the last position in the room.
@room->mobiles->head	[G] An alias for @room->mobiles->first
@room->mobiles->tail	[G] An alias for @room->mobiles->last

Mobiles (PC)
Fields for retrieving information about any PCs in the room.
@room->pcs	[G] Returns an array of PC pointers currently in the room. Entries are indexed sequentially from 1 onward.
@room->pcs->total	[G] Returns the number of PCs in the room.
@room->pcs->count	[G] An alias for @room->pcs->total
@room->pcs->first	[G] Returns a pointer to the first PC in the room.
@room->pcs->last	[G] Returns a pointer to the last PC in the room.
@room->pcs->head	[G] An alias for @room->pcs->first
@room->pcs->tail	[G] An alias for @room->pcs->last

Mobiles (NPC)
Fields for retrieving information about any NPCs in the room.
@room->npcs	[G] Returns an array of NPC pointers currently in the room. Entries are indexed sequentially from 1 onward.
@room->npcs->total	[G] Returns the number of NPCs in the room.
@room->npcs->count	[G] An alias for @room->npcs->total
@room->npcs->first	[G] Returns a pointer to the first NPC in the room.
@room->npcs->last	[G] Returns a pointer to the last NPC in the room.
@room->npcs->head	[G] An alias for @room->npcs->first
@room->npcs->tail	[G] An alias for @room->npcs->last

Items
Fields for retrieving information about any items in the room.
@room->items	[G] Returns an array of item pointers currently in the room. Entries are indexed sequentially from 1 onward.
@room->items->total	[G] Returns the number of items in the room.
@room->items->count	[G] An alias for @room->items->total
@room->items->first	[G,S] Returns a pointer to the first item in the room. If assigned a pointer to an item then the item is moved to the first position in the room.
@room->items->last	[G,S] Returns a pointer to the last item in the room. If assigned a pointer to an item then the item is moved to the last position in the room.
@room->items->head	[G] Alias for @room->items->first
@room->items->tail	[G] Alias for @room->items->last

Items (deprecated aliases)
Fields for retrieving information about any items in the room. This style is deprecated since the term "object" can be confused with object oriented programming terminology.
@room->objects	[G] DEPRECATED. Alias for @room->items
@room->objects->total	[G] DEPRECATED. Alias for @room->items->total
@room->objects->count	[G] DEPRECATED. Alias for @room->items->count
@room->objects->first	[G] DEPRECATED. Alias for @room->items->first
@room->objects->last	[G] DEPRECATED. Alias for @room->items->last
@room->objects->head	[G] DEPRECATED. Alias for @room->items->head
@room->objects->tail	[G] DEPRECATED. Alias for @room->items->tail

Inventory (mobiles and objects)
These fields are used to retrieve the room's contents with respect to mobiles and objects. Using these fields for retrieval provides an aggregation of the mobiles and objects found in the room with mobiles taking precedence in any returned results. Additionally, using these meta fields allows indiscriminate movement of items and mobiles into the room.
@room->inventory	[G] Returns an aggregate array of mobile and item pointers currently in the room. Entries are indexed sequentially from 1 onward. mobiles are listed first.
@room->inventory->total	[G] Returns the combined total number of mobiles and items in the room.
@room->inventory->count	[G] An alias for @room->inventory->total
@room->inventory->first	[G,S] Returns the first mobile in the room, or if there are none, then the first object. If assigned a pointer to a mobile then the mobile is moved to the first mobile position in the room. If assigned a pointer to an item then the item is moved to the first item position in the room.
@room->inventory->last	[G,S] Returns the last object in the room, or if there are none, then the last mobile. If assigned a pointer to a mobile then the mobile is moved to the last mobile position in the room. If assigned a pointer to an item then the item is moved to the last item position in the room.
@room->inventory->head	[G] Alias for @room->inventory->first
@room->inventory->tail	[G] Alias for @room->inventory->last

Inventory (mobiles and objects -- short alias)
Exactly the same as the inventory field counterparts except less typing is involved :)
@room->inv	[G] Alias for @room->inventory
@room->inv->total	[G] An alias for @room->inventory->total
@room->inv->count	[G] An alias for @room->inventory->count
@room->inv->first	[G] Alias for @room->inventory->first
@room->inv->last	[G] Alias for @room->inventory->last
@room->inv->head	[G] Alias for @room->inventory->head
@room->inv->tail	[G] Alias for @room->inventory->tail

Flags
Flags are boolean values that enable or disable features for the room. To set a flag you can assign the value 1, to disable a flag you can assign the value 0.
@room->flags->isDark	[G] Whether or not the room is dark.
@room->flags->isLight	[G] Whether or not the room is light.
@room->flags->isDeathtrap	[G,S] Deathtrap status.
@room->flags->isNoMobs	[G,S] No mobiles allowed status.
@room->flags->isInside	[G,S] Inside status (eg. not outside).
@room->flags->isIndoors	[G,S] Alias for @room->flags->isInside
@room->flags->isNoAggro	[G,S] No aggression status.
@room->flags->isGladiator	[G,S] Gladiator combat status. When enabled deaths in the room will be treated as gladiatorial deaths.
@room->flags->isFreeDeath	[G,S] Free death status. When enabled deaths in the room will not generate the usual penalty of exp loss and corpse creation.
@room->flags->isNoMagic	[G,S] No magic status.
@room->flags->isTunnel	[G,S] Room is a tunnel status.
@room->flags->isPrivate	[G,S] Private status. When enabled only two players may be in the room at once (immortals are immune to this check).
@room->flags->isNoSummon	[G,S] No summon status. When enabled mobiles cannot be summoned to the room. Additionally mobiles cannot gate out of the room.
@room->flags->isNoTeleport	[G] No teleport status. When enabled mobiles cannot teleport into this room.
@room->flags->isNoNegativeAffects	[G,S] No negative affects flag. When enabled negative affects in the room will expire prematurely.
@room->flags->isShop	[G] Shop status. Set at load time if a shop corresponds to the room.
@room->flags->isLawful	[G,S] NOT CURRENTLY SUPPORTED.
@room->flags->isNeutral	[G,S] NOT CURRENTLY SUPPORTED.
@room->flags->isChaotic	[G,S] NOT CURRENTLY SUPPORTED.

BlobbieScript Manual

Flaws in the Easyact Engine

Flaws in the Easyact Engine

Expressions

Expression - for

Expression - foreach

Operators

Variables

Triggers

Functions

Resolutions

Appendix A - Examples

Appendix B - Triggers

Trigger: adj_sound

Trigger: catch_act_act

Trigger: catch_ask_act

Trigger: catch_ask_text

Trigger: catch_attack_act

Trigger: catch_combat_start_act

Trigger: catch_death_act

Trigger: catch_dispel

Trigger: catch_drop_act

Trigger: catch_enter_game

Trigger: catch_entry_act

Trigger: catch_examine_act

Trigger: catch_exit_act

Trigger: catch_get_act

Trigger: catch_get_from_act

Trigger: catch_give_act

Trigger: catch_identify_act

Trigger: catch_level_up

Trigger: catch_list_affect

Trigger: catch_practice_act

Trigger: catch_put_into_act

Trigger: catch_remove_act

Trigger: catch_room_affect_show

Trigger: catch_say_act

Trigger: catch_say_text

Trigger: catch_script_call

Trigger: catch_affect_show

Trigger: catch_signal_act

Trigger: catch_speech_act

Trigger: catch_speech_text

Trigger: catch_talk

Trigger: catch_tell_act

Trigger: catch_use_act

Trigger: catch_weapon_strike

Trigger: catch_wear_act

Trigger: check_board_permissions_act

Trigger: check_can_enter

Trigger: check_can_exit

Trigger: custom_command_act

Trigger: custom_mobile_examine_info

Trigger: custom_mobile_prompt

Trigger: custom_mobile_status

Trigger: dream_for_area

Trigger: dream_for_continent

Trigger: dream_for_room

Trigger: dream_for_world

Trigger: dream_for_zone

Trigger: fight_act

Trigger: if_inroom

Trigger: on_area_load

Trigger: on_eaten

Trigger: on_entry

Trigger: on_exit

Trigger: on_expire

Trigger: on_hour_of_day

Trigger: on_immortal_goto_enter

Trigger: on_immortal_goto_exit

Trigger: on_immortal_qsave

Trigger: on_load

Trigger: on_location_change

Trigger: on_real_hour_of_day

Trigger: on_tick

Trigger: on_weapon_strike

Trigger: on_zone_load

Trigger: on_zone_unload

Trigger: preempt_death_act

Trigger: random_act