The UO function module defines the following functions:
(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:
|
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:
|
||||
Parameters: |
|
||||
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: |
|
||||
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: |
|
||||
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. |
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. |
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. |
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. |
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. |
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. |
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) |
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. |
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 |
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 |
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 |