BlobbieScript Manual

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:

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:

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:

0001 if( %getLevel( $n ) < 50 and !%getRandom( 1, 10 ) )
0002 {
0003    damage $n %( (1d10 + 1) * 3 )
0004 }
0005 else-
0006 if( %getAlign( $n ) / 10 > 60 or %getAlign( $n ) < -60 )
0007 {
0008    damage $n %( 1d(1d10) )
0009 }
0010 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.

0001 Example:
0002
0003 //
0004 // Get a list of creatures in the room.
0005 //
0006 @list = %roomGetMobs()     // Creatures are stored in @list
0007
0008 *
0009 * This is a deprecated style, and only works when
0010 * the "*" is the first non-whitespace character on
0011 * a line.
0012 *

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.

0001 Example:
0002
0003 echoto room all
0004 \   You can feel the rush of winds building in strength to
0005 \   a deafening roar. You clasp your ears to mitigate the
0006 \   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.

0001 Example:
0002
0003 if( @n->name == "The Overlord" )
0004 {
0005    echoto notc @n Grovel before your master heathens!
0006 }
0007 else
0008 {{{{
0009    spit @n
0010 }}}}
0011 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.

0001 Example:
0002
0003 @i = 20;
0004 while( (@i -= 1) > 0 )
0005 {
0006    echoto room all A fireball suddenly explodes before you.
0007    damage room all %( 20 + 1d15 ) fire
0008
0009    wait 20 secs;
0010 }
0011 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.

0001 static @foo
0002 static @foo = @fee = (60 * 60) / 14
0003
0004 Strange Behaviour:
0005
0006 //
0007 // Normal variable.
0008 //
0009 @foo = 3
0010
0011 //
0012 // Static declaration, the original @foo has been clobbered and it's
0013 // value forgotten.
0014 //
0015 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:

0001 %setVar( foo, 1 )       is identical to     %setEntityVar( @i, foo, 1 )
0002 %getVar( foo )          is identical to     %getEntityVar( @i, foo )
0003 %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:

0001 %setSavedVar()
0002 %getSavedVar()
0003 %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:

0001 %setPlayerVar()
0002 %getPlayerVar()
0003 %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_attack_act
catch_bash_door
catch_close_door
catch_combat_start_act
catch_death_act
catch_destroy_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_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

Details  |  World  |  Continents  |  Areas  |  Zones  |  Rooms  |  Mobiles  |  Items  |  Exits  |  Extras  |  Buffs  |  Races

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.


0001 'fun fun fun'->5
0002 @string->3
0003 @array->index
0004 @n->hitpoints
0005 @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.


0001 Examples:
0002
0003 @text = "Blobbie was here."         // Set up the @text variable
0004
0005 @text->6                            // Returns the string "i"
0006
0007 @text->3 = u                        // Sets the 3rd character to "u"
0008                                     // and returns "u"
0009
0010 @text                               // Returns "Blubbie was here."
0011
0012 @text->10 = 105                     // Sets the 10th character to the
0013                                     // character represented by ascii
0014                                     // value 105 ("i") and returns 105
0015
0016 @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.


0001 Example:
0002
0003 //
0004 // Set up a multi-level associative array
0005 // of immortals.
0006 //
0007
0008 @immortals->name->1 = Blobule
0009 @immortals->name->2 = Galimatazo
0010 @immortals->name->3 = Pazam
0011 @immortals->name->4 = Sang
0012 @immortals->name->5 = DevilDoll
0013 @immortals->name->6 = Brack
0014
0015 @immortals->race->1 = Slime
0016 @immortals->race->2 = Reptile
0017 @immortals->race->3 = Gnome
0018 @immortals->race->4 = Draconian
0019 @immortals->race->5 = Demon
0020 @immortals->race->6 = Doppleganger
0021
0022 //
0023 // Method 1...
0024 //
0025
0026 @immortals->name->1 " the " @immortals->race->1  // Blobule the Slime
0027 @immortals->name->2 " the " @immortals->race->2  // Galimatazo the Reptile
0028 @immortals->name->3 " the " @immortals->race->3  // Pazam the Gnome
0029 @immortals->name->4 " the " @immortals->race->4  // Sang the Draconian
0030 @immortals->name->5 " the " @immortals->race->5  // DevilDoll the Demon
0031 @immortals->name->6 " the " @immortals->race->6  // Brack the Doppleganger
0032
0033 //
0034 // Method 2...
0035 //
0036
0037 @names = @immortals->name                   // Get list of immortal names
0038 @races = @immortals->race                   // Get list of immortal races
0039
0040 @names->1 " the " @races->1                 // Blobule the Slime
0041 @names->2 " the " @races->2                 // Galimatazo the Reptile
0042 @names->3 " the " @races->3                 // Pazam the Gnome
0043 @names->4 " the " @races->4                 // Sang the Draconian
0044 @names->5 " the " @races->5                 // DevilDoll the Demon
0045 @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:


0001 foreach( @room->mobiles as @target )
0002 {
0003    if( (@target->hitpoints += 1d5) > @target->maxHitpoints )
0004    {
0005        @target->hitpoints = @target->maxHitpoints
0006    }
0007    endif
0008 }
0009 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
0001 @message->1 = "emote looks around to get her bearings."
0002 @message->2 = "emote pulls out a map, looks at it, and makes a few markings."
0003 @message->3 = "talk" @r "Travelling is fun, I can tell you"
0004 \             "how to get just about anywhere!"
0005
0006 << @message->(1d3)

The Repair Gnome
0001 protect
0002 {
0003    if( !%canSee( @this, @o ) )
0004    {
0005        echoto char @n @I doesn't seem to notice the @O.
0006        break
0007    }
0008    endif
0009
0010    if( !%canSee( @this, @n ) )
0011    {
0012         say Hmmm? Where did this come from?
0013         drop @o
0014         break
0015    }
0016    endif
0017
0018    if( @o->hitpoints >= @o->maxHitpoints ) )
0019    {
0020         talk @n This is already in perfect condition!
0021         give @o @n
0022         drop @o
0023         break
0024    }
0025    endif
0026
0027    @repairCost =
0028    \   @o->sellValue * (@o->maxHitpoints - @o->hitpoints) / @o->maxHitpoints
0029
0030    @repairCost = %asInteger( @repairCost )
0031
0032    if( @n->gold < @repairCost )
0033    {
0034        talk @n You need @repairCost gold pieces to get that fixed.
0035        talk @n Please come back when you have more gold.
0036        give @o @n
0037        drop @o
0038        break
0039    }
0040    endif
0041
0042    @o->hitpoints = @o->maxHitpoints
0043    emote rapidly fiddles with @O, %sexPossess( @this ) hands moving
0044    \   faster than the eye can follow.
0045    say There we go, right as rain!
0046    give @o @n
0047    drop @o
0048
0049    echoto char @n You give @repairCost gold coins to @I.
0050    echoto notc @n gives some gold to @I.
0051
0052    @n->gold = @n->gold - @repairCost
0053    @this->gold = @this->gold + %asInt( @repairCost / 25 )
0054 }
0055 endprotect

Greedy the Giant
0001 if( !%isAwake( @this ) )
0002 {
0003    return
0004 }
0005 endif
0006
0007 foreach( %getRoomObects() as @object )
0008 {
0009    if( %canTake( @object )
0010    \   &&
0011    \   (%isObjectTypeKey( @object )
0012    \    ||
0013    \    %isObjectTypeWand( @object )
0014    \    ||
0015    \    %isObjectTypeStaff( @object )
0016    \    ||
0017    \    %isObjectTypePotion( @object )
0018    \    ||
0019    \    %isObjectTypeScroll( @object )
0020    \    ||
0021    \    %isObjectTypeWeapon( @object )
0022    \    ||
0023    \    %getObjStat( @object, "sellValue" ) >= 50000) )
0024    {
0025        say Oh goodie goodie...
0026        get @object
0027        return
0028    }
0029    endif
0030 }
0031 endwhile

Appendix B - Triggers

Trigger: adj_sound

Response Typeplaintext
EntitiesRooms, 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 Typescript
EntitiesRooms, Mobiles, Objects
Parameterssubstring

    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 Typescript
EntitiesMobiles
Parameterskeyword1 [, 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 Typeplaintext
EntitiesMobiles
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 Typescript
EntitiesMobiles, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesObjects (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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, Mobiles, Objects
Parameterskeyword1 [, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesObjects
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 Typescript
EntitiesObjects
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 Typescript
EntitiesMobiles
Parameterscoins 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 Typescript
EntitiesMobiles, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesObjects (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 Typescript
EntitiesMobiles
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 Typescript
EntitiesObjects
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 Typescript
EntitiesObjects
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 Typescript
EntitiesObjects (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 Typescript
EntitiesRooms, Mobiles, Objects
Parameterskeyword1 [, 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 Typeplaintext
EntitiesMobiles
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 Typescript
EntitiesRooms, Mobiles, Objects
Parametersname [, 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 Typescript
EntitiesObjects (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 Typescript
EntitiesRooms, Mobiles, Objects
Parametersname

    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 Typescript
EntitiesRooms, Mobiles, Objects
Parameterskeyword1 [, 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 Typeplaintext
EntitiesMobiles
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 Typescript
EntitiesRooms, Mobiles, Objects
Parameterstype, 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 Typescript
EntitiesMobiles
Parameterskeyword1 [, 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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, 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 Typescript
EntitiesObjects
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 Typescript
EntitiesObjects (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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, Mobiles, Objects
Parameterscommand [, 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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms
Parametersarea1 [, 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 Typescript
EntitiesRooms
Parameterscontinent1 [, 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 Typescript
EntitiesRooms
Parametersroom1 [, 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 Typescript
EntitiesRooms
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 Typescript
EntitiesRooms
Parameterszone1 [, 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 Typescript
EntitiesRooms, Mobiles, Objects
Parametersthreshold

    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 Typescript
EntitiesRooms, Mobiles, Objects
Parametersthreshold

    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 Typescript
EntitiesRooms, Mobiles, Objects
ParametersareaId1 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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, 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 Typescript
EntitiesMobiles, 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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, Mobiles, Objects
Parametershour | 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 Typescript
EntitiesMobiles, 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 Typescript
EntitiesMobiles, 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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, 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 Typescript
EntitiesMobiles, 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 Typescript
EntitiesRooms, Mobiles, Objects
Parametershour | 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 Typescript
EntitiesRooms, Mobiles, Objects
Parametersthreshold

    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 Typescript
EntitiesObjects
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 Typescript
EntitiesRooms, Mobiles, Objects
ParameterszoneId1 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 Typescript
EntitiesRooms, Mobiles, Objects
ParameterszoneId1 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 Typescript
EntitiesRooms, 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 Typescript
EntitiesRooms, Mobiles, Objects
Parametersthreshold

    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 Typespecial
EntitiesMobiles
ParametersbitInteger

    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 Typespecial
EntitiesMobiles
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 Typespecial
EntitiesMobiles
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 Typespecial
EntitiesRooms, Mobiles, Objects
ParametersprocName

    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 Typespecial
EntitiesRooms, 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:

::

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( )
Parametersstring @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersmixed @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( )
Parametersarray @data

    Returns the first value in the passed array.

Function: %arrayGetKeyForValue()

Aliases%arrayGetKeyForValue( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @data

    Returns the number of elements in the passed array.

Function: %arrayGetTail()

Aliases%arrayGetTail( )
Parametersarray @data

    Returns the last value in the passed array.

Function: %arrayGetValues()

Aliases%arrayGetValues( )
Parametersarray @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( )
Parametersarray @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()
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @value

    Returns null. This function is mostly available for completeness.

Function: %asString()

Aliases%asString( )
Parametersmixed @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( )
Parametersentity @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parametersmobile @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( )
Parametersobject @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( )
Parametersmobile @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( )
Parametersmixed @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( )
Parameterscharacter @entity

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

Example:

%combatClear( @n )

Function: %combatStart()

Aliases%combatStart( ), %setFighting( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersinteger @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( )
Parametersstring @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( )
Parametersinteger @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersobject @entity

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

Function: %corpseGetName()

Aliases%corpseGetName( ), %corpseGetName( )
Parametersobject @entity

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

Function: %corpseGetStat()

Aliases%corpseGetStat( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersstring @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( )
Parametersinteger @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( )
Parametersstring @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersstring @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( )
Parametersstring @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( )
Parameterscharacter @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( )
Parameterscharacter @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()
Parametersstring @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()
Parametersstring @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( )
Parameterscharacter @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( )
Parametersexit @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( )
Parametersexit @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersarray @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parameterscharacter @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( )
Parametersfloat @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( )
Parameterscharacter @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( )
Parametersobject @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( )
Parametersmixed @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( )
Parametersentity @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmobile @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( ),
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersinteger @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersinteger @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersobject @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersobject @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( )
Parametersmixed @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( )
Parameterscharacter 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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parametersstring @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parameterscharacter @entity

    Returns the weight of the given character. Character entity may be a
character pointer or keyword.

Function: %hasAffectItem()

Aliases%hasAffectItem( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @entity

    Returns the height of the given character. Character entity may be a
character pointer or keyword.

Function: %hitsCond()

Aliases%hitsCond( ), %hitCond( ), %getHitsCondition( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parametersmobile @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( )
Parametersmixed @entity

    Returns 1 if @entity is a text pointer to a mobile; otherwise 0 is
returned.

Function: %isDark()

Aliases%isDark( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmixed @entity

    Returns 1 if @entity is a text pointer to an exit; otherwise 0 is
returned.

Function: %isExtra()

Aliases%isExtra( )
Parametersmixed @entity

    Returns 1 if @entity is a text pointer to an extra; otherwise 0 is
returned.

Function: %isFighting()

Aliases%isFight( ), %isFighting( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmobile @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( )
Parametersmixed @value

    Returns 1 if the given value is of type integer, otherwise 0 is returned.

Function: %isItemHere()

Aliases%isItemHere( ), %isItemHere( ), %isItemHere( ), %isItemHere( )
Parametersobject @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( )
Parametersinteger @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( )
Parametersmixed @entity

    Returns 1 if @entity is a text pointer to an object; otherwise 0 is
returned.

Function: %isJailed()

Aliases%isJailed( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmixed @data

    Returns 1 if the given data is null, otherwise returns 0.

Function: %isOutside()

Aliases%isOutside( ), %isOutside( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersinteger @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersobject @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( )
Parametersinteger @objectId

    Returns the total number of objects currently in the game with the given
objectId (vnum).

Function: %itemGetStat()

Aliases%itemGetStat( ), %itemGetStat( ), %itemGetStat( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersobject @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()
Parametersstring @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( )
Parametersstring @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( )
Parametersinteger @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parameterscharacter @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( )
Parametersmobile @entity

    Returns 1 if the mobile is an undead race; otherwise returns 0. Mobile
@entity must be a pointer.

Function: %mobPulseActivity()

Aliases%mobPulseActivity( )
Parametersmobile @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parametersstring @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( )
Parametersobject @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( )
Parametersobject @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parametersmobile @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersinteger @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( )
Parametersinteger @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( )
Parametersarray @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( )
Parametersroom @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( )
Parametersroom @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( )
Parametersmixed @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parametersinteger @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( )
Parameterschacracter @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parametersinteger @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( )
Parameterscharacter @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersstring @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( )
Parametersmixed @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( )
Parametersmobile @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( )
Parametersmixed @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( )
Parametersmixed @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( )
Parametersstring @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parameterscharacter @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( )
Parametersmobile @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( )
Parameterscharacter @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( )
Parametersstring @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( )
Parametersmobile @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( )
Parametersmixed @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( )
Parametersstring @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()
Parametersstring @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()
Parametersstring @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()
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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()
Parametersstring @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()
Parametersstring @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( )
Parametersstring @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()
Parametersstring @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()
Parametersstring @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()
Parametersstring @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()
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parametersstring @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( )
Parameterscharacter @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( )
Parametersentity @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( )
Parametersstring @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( )
Parameterscharacter @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( )
Parametersobject @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

Details  |  World  |  Continents  |  Areas  |  Zones  |  Rooms  |  Mobiles  |  Items  |  Exits  |  Extras  |  Buffs  |  Races

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

Details  |  World  |  Continents  |  Areas  |  Zones  |  Rooms  |  Mobiles  |  Items  |  Exits  |  Extras  |  Buffs  |  Races

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

Details  |  World  |  Continents  |  Areas  |  Zones  |  Rooms  |  Mobiles  |  Items  |  Exits  |  Extras  |  Buffs  |  Races

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

Details  |  World  |  Continents  |  Areas  |  Zones  |  Rooms  |  Mobiles  |  Items  |  Exits  |  Extras  |  Buffs  |  Races

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.