UO Function Module (UO.EM)

The UO function module defines the following functions:

Unclassified Functions Recently Added
Menu-related Functions: Skill-related functions:
Custom Per-object Properties: Custom Global Properties:
Effects: Object Manipulation:
House/Ship Placement/Creation: Event-Related:
Resource Management  

(These could be organized better, probably.  Suggestions welcome.)

Functions to be probably renamed:


Accessible
Declaration: Accessible( Character, item );
Function: Determines if an item falls into one of the following categories for a character:
  1. An item on the ground, within two squares
  2. An item equipped by the character
  3. An item inside the character's backpack
  4. A temporarily accessible item
Returns: Zero if item does not fall into one of the above categories, nonzero if the item does.
Notes: Does not check that character has line-of-sight to item.

 

ApplyDamage
Declaration: ApplyDamage( Character, Hits : real);
Function: Decreases a character's hit points, after reducing damage due to armor.  The steps taken are as follows:
  1. A piece of armor is chosen randomly, based on probabilities in ARMRZONE.CFG.
  2. Damage is reduced by 50% to 100% of the armor's AR.
  3. Remaining damage is halved.
  4. "I'm Hit" animation is played.
  5. Damage is applied.
  6. Mobile is killed if hit points are now zero.
Parameters:
Character: A mobile
Hits: An real amount of damage to be applied
Returns: Nonzero if the damage could be applied..
An error if damage could not be applied. (Character does not refer to a mobile, Hits is negative);

 

ApplyRawDamage (was: Damage)
Declaration: ApplyRawDamage( Character, Hits );
Function: Decreases a character's hit points.  If this causes hit points to drop to zero, kills the character.
Parameters:
Character: A mobile
Hits: An integer amount of damage to be applied
Returns: Nonzero if the damage could be applied..
An error if damage could not be applied. (Character does not refer to a mobile, Hits is negative);
Notes: Armor is ignored.

 

Broadcast
Declaration: Broadcast( text );
Function: Sends text as a System Message to every online player.
Returns: unimportant

 

CheckLineOfSight
Declaration: CheckLineOfSight( object1, object2 );
Returns: Nonzero if object1 and object2 have line-of-sight to each other.
Zero if object1 and object2 do not have line-of-sight.
An error if parameters are invalid.

 

 

CheckLosAt
Declaration: CheckLosAt( character, x, y, z );
Returns: Nonzero if character has line-of-sight to (x,y,z)
Zero if character does not have line-of-sight to (x,y,z)
An error if parameters are invalid.

 

CreateItemAtLocation
Declaration: CreateItemAtLocation( x, y, z, objtype, amount );
Function: Creates an item at an arbitrary location.
Returns: An Item if the item could be created.
An error if item could not be created (parameters invalid)
Notes: Amount specifies how large the stack should be.

 

CreateItemInBackpack
Declaration: CreateItemInBackpack( Character, ObjType, Amount );
Function: Creates an item in a character's backpack.
Parameters: Amount specifies how large the stack should be.
Returns: An Item if the item could be created.
An error if item could not be created
Errors: That is not a container
That container is full
Failed to create that item type
A parameter was invalid
Notes: Adds to an existing stack in the top level of the container, if an appropriate stack can be found.  If no stack is found that can hold the entire amount, creates a new stack.

 

CreateItemInContainer
Declaration: CreateItemInContainer( Container, ObjType, Amount := 1);
Function: Creates an item in a container.
Parameters: Amount specifies how large the stack should be.
Returns: An Item if the item could be created.
An error if item could not be created (container was full).
Errors: That is not a container
That container is full
Failed to create that item type
A parameter was invalid
Notes: Adds to an existing stack in the top level of the container, if an appropriate stack can be found.  If no stack is found that can hold the entire amount, creates a new stack.

 

CreateNpcFromTemplate
Declaration: CreateNpcFromTemplate( template, x,y,z, override_properties := 0);
Function: Creates an NPC from a template.
Parameters: override_template: a structure containing members to override values in the NPC template (found in NPCDESC.CFG).  This can be used only to override built-in properties (facing, color, gender etc), but not custom properties.  To override custom properties, use SetObjProperty after the NPC has been created.
Returns: A character reference to the NPC if the NPC was created.
An error if unable to create the NPC.

 

Damage
Damage has been renamed to ApplyRawDamage.

 

Detach
Declaration: Detach();
Function: Disassociates the current script from the character that it is attached to.  If the current script is not attached to a character, does nothing.
Returns: Nonzero if the script was attached to a character, and is no longer.
An error if the script was not attached to a character.

 

Distance
Declaration: Distance( object1, object2 );
Function: Determines the distance between two objects.  If either object is in a container, uses the world-position of its ultimate-parent container.
Notes: This distance is defined as the greater of the x-distance and the y-distance.   z-distance is not taken into account.  (This is neither Pythagorean distance nor Manhattan distance)
Returns: The distance if the distance could be calculated.
An error if parameters were invalid.

 

EnumerateItemsInContainer
Declaration: EnumerateItemsInContainer( container );
Function: Enumerates the contents of a container.  Recurses into unlocked subcontainers.   If 'container' is itself locked, its contents will be enumerated.
Returns: An array of object references if container could be found and is a container.
An error if container could not be found or is not a container.

 

EnumerateOnlineCharacters
Declaration: EnumerateOnlineCharacters();
Returns: An array of character references to player characters that are currently logged-in.

 

EquipFromTemplate
Declaration: EquipFromTemplate( character, template )
Function: Creates equipment for a character, using EQUIP.CFG.
Notes: Element properties in EQUIP.CFG can have the following formats:
Equip [hex_objtype] [hex_color]
Armor [armor_template_name]
Weapon [weapon_template_name]
Note that object type and color must be in hex format (0xHHHH)
Returns: Nonzero if equipment was created
Errors: Equipment template not found
Invalid parameter

 

GetAmount
Declaration: GetAmount( item );
Function: Access data in Item
Returns: The size of item's stack.

   

GetPosition
Declaration: GetPosition(object);
Returns: A structure containing the position of the object, relative to its parent.
Format of the structure:
position.x
position.y
position.z

 

GetStats
Declaration: GetStats(character);
Returns: A structure containing the stats of a character:
stats.strength
stats.intelligence
stats.dexterity

 

GetStatus
Declaration: GetStatus( character );
Returns: A structure containing the dynamic status of a character:
status.hp
status.mana
status.stamina
status.ar
Notes: This function name is too close to GetStats().  Any suggestions?

 

GrantPrivilege
Declaration: GrantPrivilege( character, privilege );
Function: Grants a privilege to a character.
Returns: Nonzero if the privilege was granted
Errors: Invalid parameter

 

HealDamage
Declaration: HealDamage( Character, Hits );
Function: Increases a character's hit points, up to the character's maximum.
Parameters:
Character: A mobile
Hits: An integer amount of damage to be applied
Returns: Nonzero if some part of the damage could be healed.
An error if damage could not be healed. (Character does not refer to a mobile, Hits is negative or >65535);

 

ListEquippedItems
Declaration: ListEquippedItems( Character );
Function: // Returns an array of itemrefs of character equipment, including
    // only layers where items are actually equipped. Only includes
    // layers 1 through 24, even if other layers are used internally
    // for other purposes.
Returns:  

 

ListGhostsNearLocation
Declaration: ListGhostsNearLocation( x, y, z, range );
Function: Searches the world for ghosts within range squares of (x,y,z).   19 is used for the z-range.  Rectangular range is used - x-range and y-range are compared independently
Returns: An array of object references of ghosts found near the location.
Errors: Invalid parameter
Notes: This call is equivalent to ListMobilesNearLocationEx( x,y,z, range, LISTEX_GHOST ).  For this reason, this function may be phased out.

 

ListItemsNearLocation
Declaration: ListItemsNearLocation( x, y, z, range );
Function: Searches the world for items within range squares of (x,y,z).   10 is used for the z-range.  Rectangular range is used - x-range and y-range are compared independently
Returns: An array of item references of items found near the location.
An error if parameters are invalid.

 

ListItemsNearLocationOfType
Declaration: ListItemsNearLocationOfType( x, y, z, range, objtype );
Function: Searches the world for items within range squares of (x,y,z) of type objtype.   19 is used for the z-range.  Rectangular range is used: distance is the greater of x-distance and y-distance.
Returns: An array of item references of items found near the location.
Errors: Invalid parameter

 

ListMobilesInLineOfSight
Declaration: ListMobilesInLineOfSight( object, range );
Returns: An array of object references of living, non-hidden mobiles within range tiles of object, that have LOS with it.
Errors: Invalid parameter

 

ListMobilesNearLocation
Declaration: ListMobilesNearLocation( x, y, z, range );
Function: Searches the world for mobiles within range squares of (x,y,z).   19 is used for the z-range.  Rectangular range is used - x-range and y-range are compared independently
Returns: An array of object references of living, non-hidden mobiles found near the location.
Errors: Invalid parameter

 

ListMobilesNearLocationEx
Declaration: ListMobilesNearLocation( x, y, z, range, flags );
Function: Searches the world for mobiles within range squares of (x,y,z).   19 is used for the z-range.  Rectangular range is used - x-range and y-range are compared independently
Parameters: flags is the sum of one or more of the following (found in LISTEX.INC):
LIST_NORMAL: include visible, living mobiles
LIST_HIDDEN: include hidden mobiles
LIST_GHOST: include ghosts
Returns: An array of object references of mobiles found matching the search criteria.
Errors: Invalid parameter

 

MoveCharacterToLocation
Declaration: MoveCharacterToLocation( character, x, y, z );
Function: Transports a character to any location.  Informs all clients of this.
Returns: Nonzero if character could be transported.
An error if parameters are invalid.
Notes: Does not check that the target location is unoccupied, either by mobiles, items, or statics, or that it is in any way a valid place to be.

 

PrintTextAbove
Declaration: PrintTextAbove( above_object, text );
Function: Causes text to be displayed above an object, as if spoken.
Returns: Nonzero if the text was displayed
Zero if text is too long
An error if parameters were invalid.

 

PrintTextAbovePrivate
Declaration: PrintTextAbovePrivate( above_object, text, character );
Function: Causes text to be displayed above an object, as if spoken. This text will only be seen by a single character.
Returns: Nonzero if the text was displayed
Zero if text is too long
An error if parameters were invalid.

 

ReadGameClock
Declaration: ReadGameClock();
Notes: The Game Clock is a seconds-counter.  It is started after all data is read, and is stopped just before writing data.  It has no relationship to real-world calendar time.  It counts real-time seconds - if the system is running slow, it will reliably tell you how many real-time seconds have passed while the game was running.
Returns: The current value of the game clock.

 

RequestInput
Declaration: RequestInput(character, item, prompt );
Function: Prompts a player for input, and waits for the player to type a line of text.
Notes: item is a placeholder - the client needs it, but it is not used internally.  Typically some related item will be passed.
Returns: A string containing the next line of text from the client's keyboard

 

RestartScript
Declaration: RestartScript( npc );
Function: Stops the current master script for an NPC, and starts a new one.
Notes: npc.script can be assigned before calling this, to change the master script for an NPC.
Returns: Nonzero if the script was started. (er, it can fail and return nonzero, at the moment)
An error if unable to restart:
"RestartScript only operates on NPCs"
"Invalid parameter type"

 

Resurrect
Declaration: Resurrect( ghost );
Function: Resurrects a ghost.
Returns: Nonzero if the ghost was resurrected.
An error if unable to resurrect:
"That is not dead"
"Invalid parameter type"

 

RevokePrivilege
Declaration: RevokePrivilege( character, privilege );
Function: Revokes a privilege from a character.
Returns: Nonzero if the privilege was revoked, or if it was not previously granted.
Errors: Invalid parameter

 

SaveWorldState
Declaration: SaveWorldState();
Function: Saves the current world state.
Returns: Nonzero

 

SendSysMessage
Declaration: SendSysMessage( character, text );
Function: Displays a System Message in the lower-left corner of character's player's screen.
Returns: Nonzero if the message was displayed.
Zero if the message could not be displayed (character not found, or no client connected)

 

SetRegionLightLevel
Declaration: SetRegionLightLevel( regionname, lightlevel );
Function: Sets the light level of a region by name.  The name must match a region name from REGIONS\LIGHT.CFG.
Parameters: lightlevel must be a value between 0 and 15, where 0 is daylight and 15 is near-total darkness.
Returns: Nonzero if the light level was set.
An error if the light level could not be set:
"Invalid Parameter type"
"Light Level is out of range"
"Light region not found"

 

SystemFindObjectBySerial
Declaration: SystemFindObjectBySerial( serial );
Function: Searches the world for an item or mobile by serial number. This could be used if the serial number of an object was saved with SetObjProperty, for example.
Returns: A character reference if a character was found.
An item reference if an item was found.
An error if no object count be found.
Errors: Character not found
Item not found
Invalid parameter

 

Target
Declaration: Target( Character, options);
Function: Sends a target cursor to a character's client, and waits for the player to target something.
Returns: The Object targetted if an object was selected.
Zero
if the target cursor was cancelled or the client disconnected.
Notes: Line-of-sight is checked.  Zero is returned if the character does not have line-of-sight to the object.

Options is not yet used.

 

 

TargetCoordinates
Declaration: TargetCoordinates( Character );
Function: Sends a target cursor to a character's client, and waits for the player to target a tile
Returns: A structure (members: x,y,z) containing the location targetted.
Zero
if the target cursor was cancelled or the client disconnected.
Notes: Line-of-sight is not checked.

Menu-Related Functions

AddMenuItem
Declaration: AddMenuItem( menu, objtype, text );
Function: Adds a menu item to a menu.
Returns: Nonzero if the item could be added.
An error if the parameters are invalid.
Notes: The 'objtype' field of a mobile is not appropriate here.  There is special art for mobiles for use in menus.  Human Males (object type: 0x190) use 0x2106, females 0x2107.  Use InsideUO to determine other values.

 

CreateMenu
Declaration: CreateMenu( title : string );
Function: Creates an empty dynamic menu.
Returns: A menu if the menu could be created.
An error if title is not a string.

 

SelectMenuItem2
Declaration: SelectMenuItem2( character, menuname );
Function: Displays an object menu on the character's client for the player to select from.
Returns: Zero if the menu was cancelled, or the character's client disconnected.
A structure containing information on the item selected.  If the variable returned is called 'selection', the structure members are as follows:
selection.objtype: The Object Type of the selection.
selection.index: The 1-based index, within the menu, of the selection.
Notes: This function will be re-re-named to SelectMenuItem in the future.

 

Skill-Related Functions

CheckSkill
Declaration: CheckSkill( character, skillid, difficulty, pointvalue );
Function: Tests a character's skill against a difficulty-based task.  Advances that skill if the test succeeds, proportional to how likely the character was to succeed.
Returns: Zero if the skill check failed.
Greater than zero if the skill check succeeded.
An error if parameters are invalid
Notes: A character has a 100% chance of succeeding at a task with difficulty 20 points below his skill level, which decreases linearly to a 0% chance of succeeding at a task of difficulty 20 points greater than his skill level.  The points awarded will scale from 0% to 100% inverse to this rule.

The return value may be changed in the future to: -100 to 0, failure, more negative indicates worse failure, or 1 to +100, success, higher indicates greater success.

 

GetRawSkill
Declaration: GetRawSkill( character, skillid );
Returns: The Raw Skill of a character, for a skill, as an integer.
Notes: See SKILLS.CFG for skillid values.

 

SetRawSkill
Declaration: SetRawSkill( character, skillid, rawskill );
Function: Sets the Raw Skill  of a character for a given skill. Updates displays on the client if connected.
Returns: Nonzero if the skill could be set.
An error if the skill value could not be set:
"Raw Skill Values must be positive"
"Invalid parameter"
Notes: See SKILLS.CFG for skillid values.

 

GetSkill
Declaration: GetSkill( character, skillid );
Returns: The Effective Skill of a character, for a skill, as an integer.
Notes: See SKILLS.CFG for skillid values.

 

Custom Per-Object Properties

 

EraseObjProperty
Declaration: EraseObjProperty( object, propertyname );
Function: Removes a property from the custom-property list of an object.
Returns: Nonzero if the property was erased or did not exist.
An error if parameters were invalid.

   

GetObjProperty
Declaration: GetObjProperty( object, propertyname );
Function: Retrieves custom data associated with an object.
Returns: A string, integer or real containing the value of the named property
An error if the property could not be found.

   

SetObjProperty
Declaration: SetObjProperty( object, propertyname, propertyvalue );
Function: Associates data with an object.  This data will be saved with the object, for later retrieval with GetObjProperty.
Returns: Nonzero if the value could be associated.
Zero if the value could not be associated (propertyname is not a string, propertyvalue is not a string, integer, or real, or object not found)
Notes: propertyvalue may be a string, an integer, or a real.

 

Custom Global Properties

Global properties are named variables which are saved with game state.  They can be strings, integers, or reals.

No attempt is made to disallow concurrent access to these properties, so it is recommended to set_critical(1) around Get/Modify/Set calls.

EraseGlobalProperty
Declaration: EraseGlobalProperty( propertyname );
Function: Removes a property from the global property list.
Returns: Nonzero if the property was erased or did not exist.
An error if parameters were invalid.

   

GetGlobalProperty
Declaration: GetGlobalProperty( propertyname );
Function: Retrieves the value of a global property.
Returns: A string, integer or real containing the value of the named property
An error if the property could not be found.

   

SetGlobalProperty
Declaration: SetGlobalProperty( propertyname, propertyvalue );
Function: Sets the value of a global property.
Returns: Nonzero if the value could be associated.
Zero if the value could not be associated (propertyname is not a string, propertyvalue is not a string, integer, or real)
Notes: propertyvalue may be a string, an integer, or a real.

 

Effects

 

PerformAction
Declaration: PerformAction( character, action );
Function: Causes character to perform an action, such as Bow or Salute.
Returns: Zero if the action could not be performed.
Nonzero if the action could be performed.

 

PlayLightningBoltEffect
Declaration: PlayLightningBoltEffect( victim );
Function: Plays a lightning bolt effect centered on victim.
Returns: Zero if the effect could not be played.
Nonzero if the effect could be played.

 

PlayMovingEffect
Declaration: PlayMovingEffect( source, destination, effect, speed, loop := 0, explode := 0);
Function: Causes a moving effect to be played, travelling from source to destination
Parameters:   Parameter Description Default
Source source object n/a
Destination destination object n/a
Effect n/a
Speed How fast the effect should travel. n/a
Loop ? 0
Explode Shows an explosion at destination at the end of the effect. 0
Returns: Zero if the effect could not be played.
Nonzero if the effect could be played.
Notes: A list of valid values for effect needs to be catalogued.
Detail is needed on exactly what speed, loop, and explode do.

 

PlayObjectCenteredEffect
Declaration: PlayObjectCenteredEffect( uobject, effect, speed, loop := 0);
Function: Causes an effect to be played, centered on uobject, which follows uocject if it moves.
Parameters:   Parameter Description Default
uobject object to center effect on n/a
Effect n/a
Speed ? n/a
Loop ? 0
Returns: Zero if the effect could not be played.
Nonzero if the effect could be played.
Notes: This is used for effects like flame strike and reactive armor.

A list of valid values for effect needs to be catalogued.
Detail is needed on exactly what speed, loop, and explode do.

 

PlaySoundEffect
Declaration: PlaySoundEffect( character, effect );
Function: Causes a sound effect to be played, centered on a character.
Parameters: The variable effect is an integer value.
Returns: Zero if the effect could not be played.
Nonzero if the effect could be played.
Notes: See sndlist.txt for possible sound effects to play. (All values are in hex; prefix with 0x)

 

Object Manipulation

DestroyItem
Declaration: DestroyItem( Item );
Function: Removes an item from the world.  Transmits commands to each client in range of item to reflect this.
Returns: Nonzero if the item was destroyed
An error if the item could not be destroyed (incorrect parameter, or item has already been destroyed)

 

EquipItem
Declaration: EquipItem( mobile, item );
Function: Equips an item on a mobile.
Notes: If the item is equipped on a character,it will be unequipped.  If it is in a container, it will be removed from the container.

"Equippable" means that the character does not have a similar item equipped, and that the item is an equipment-type item.  Carrying-capacity and strength requirements will fall under this category as well.

To "unequip" an item, move it to another location (typically a backpack)

Returns: Nonzero if the item could be equipped.
Errors: That item is not equippable by that character
Invalid parameter type

 

GetObjType
Declaration: GetObjType( object );
Function:  
Returns: The Object Type of object.

 

MoveItemToContainer
Declaration: MoveItemToContainer( item, container, x := -1, y := -1 )
Function: Moves an item into a container.
Notes: If the default values for x and y are passed, or if x or y does not fall within the legal bounds for a container as found in ITEMDESC.CFG, then a random location within the container will be chosen.
Returns: Nonzero if the item could be placed in the container.
An error if unable to place the item in the container.
Errors: Non-container selected as target
Container is too full to add that
Invalid parameter type
Item cannot be removed from its container
Couldn't find that item

 

MoveItemToLocation
Declaration: MoveItemToLocation( item, x, y, z );
Function: Moves an item to a location on the ground, after removing it from its previous location.
Parameters: z: The z-coordinate passed is used as a hint.  The item will be placed on the the ground, or on another item, or on a ship, just as if a character had tried to walk there.
Notes: If the item is equipped on a character, it will be unequipped.  If it is in a container, it will be removed from the container.
If the location selected is on a ship, the item will henceforth move with the ship.
Returns: Nonzero if the item was moved.
Errors: Invalid location selected
Item cannot be removed from its container
Invalid parameter type

 

SetName
Declaration: SetName( object, name );
Function: Sets the Name of an object.  Single-clicking the object will then return this name.
Returns: Nonzero if the name was set
Zero if the name could not be set (incorrect parameter)
Notes: This can set names of items or mobiles.

 

SubtractAmount
Declaration: SubtractAmount( item, amount );
Function: Decreases the stack size of an item.  If nothing is left, deletes the item.
Returns: Nonzero if the amount could be subtracted.
Zero if the item could not be found.

 

House/Ship Placement/Creation

 

CreateMultiAtLocation
Declaration: CreateMultiAtLocation( x,y,z, objtype );
Function: Creates a "multi" at a location.  Currently the only type of multi supported is that of ships.
Parameters: objtype must be a multi type (0x4000 to 0x4fff - although not all of those are valid)
Returns: A ship reference or multi reference if the object was created.
An error if the object could not be created.
Errors: Object Type out of range for Multis
No known multi definition for that objtype
Unable to create Multi
Position indicated is impassable (ships only)
Invalid parameter type
Notes: A location is "passable" for a ship if every part of the hull sits on water, and no hull location is occupied by the hull of another ship, nor a static or dynamic blocking item.

 

TargetMultiPlacement
Declaration: TargetMultiPlacement( character, objtype );
Function: Requests a character place a multi-gump.
Returns: A structure (x,y,z) containing the location targetted.
Zero if targetting was cancelled.
Errors: No client attached
Client busy with another target cursor
Object Type is out of range for Multis
Invalid parameter type

 

Event-Related:

 

RegisterForSpeechEvents
Declaration: RegisterForSpeechEvents( at_object, range );
Function: Player-character speech spoken within range tiles of at_object will generate speech events, which must be read using wait_for_event.
Returns: Nonzero if registration was successful.
An error if unable to register:
"Already registered for speech events"
"Invalid parameter type"

 

EnableEvents
Declaration: EnableEvents( events, range );
Function: Enables events specified.  When enabled events occur, they will be placed on the script's event queue, and must be read with wait_for_event.  Events that were previously enabled will remain enabled.
Notes: See include/eventid.inc for event type constants. 
"speech" events are by default enabled.  This will change.
This function is useful only to NPCs.
Range is only used for certain events.
Returns: Nonzero if the event type was enabled.
An error if the event type is unknown.
Errors:
Invalid parameter

 

Resource Management

See ../resource.htm for details on resource management and resource pools.

GetHarvestDifficulty
Declaration: GetHarvestDifficulty( x, y, resource, tiletype );
Function: Determines the difficulty of harvesting a resource from location (x,y).
Parameters: tiletype will typically be .objtype from TargetCoordinates()
Notes: Checks the location for an object of type 'tiletype'.  Since this tiletype may be a landtile or an object tile, there may be some room for ambiguity; we'll work on this.
Returns: A difficulty level if resources exist.
An error if the event type is unknown.
Errors: No resource by that name
No resource-bearing landmark there
No resource region at that location
Resource is depleted
Invalid parameter

 

HarvestResource
Declaration: HarvestResource( x, y, resource, b, n );
Function: Attempts to harvest a resource from a location. 
Notes: Harvests a*b resource units, where 0 <= a <= n.  Thus you can request 0-40 units in groups of 5, etc.
Returns: The number of resource units harvested if resources were harvested, or if no resources were available.
An error if an error occurred.
Errors: Invalid parameter