File: UO.em

Description: Functions that interact with and alter UO game world data, including server-client messages.
Last Modified: 6/23/2006

File Constants:

Accessible( Character, item )
Parameters:
NameType
CharacterCharacter Reference
itemItem Reference
Explanation
Function: Determines if an item falls into one of the following categories for a character:
An item on the ground, within two squares
An item equipped by the character
An item inside the character's backpack
A temporarily accessible item
Notes: Does not check that character has line-of-sight to item.
Return values
0 if item does not fall into one of the above categories, 1 if the item does.
Errors
none
Related
Item
Character



AddAmount( item_ref, amount )
Parameters:
NameType
item_refItem reference
amountAn integer 1-60000
Explanation
Adds the specified amount to a stack of items. Amount is between 1 and 60000
Return values
1 or error
Errors
"That item is being used" (if inuse or reserved)
"That item type is not stackable"
"Can't add that much to that stack" (if resulting amount > 60000)
"Invalid Parameter type"
Related
Item



AddMenuItem( menu, objtype, text )
Parameters:
NameType
menuDynamic Menu Reference (from CreateMenu())
objtypeInteger tile graphic to add to menu
textString description
Explanation
Adds a menu item to a dynamic menu.
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.
0 for objtype creates a checkbox-style menu
Return values
1 if the item was added successfully
Errors
none (returns 0 on invalid parameters)



AlterAttributeTemporaryMod( character, attrname, delta_tenths )
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
delta_tenthsInteger
Explanation
Changes the temporary modification value for attribute named "attrname". delta_tenths is in tenths, obviously. So "1" would increase the temp mod by 0.1 points.
Return values
1 on success or Error
Errors
"Invalid parameter type" including if attrname was not found as an attribute
"New modifier value is out of range"
Related
Character
Related Configs
attributes.cfg



ApplyConstraint( objlist, configfile, propertyname, minvalue )
Parameters:
NameType
objlistarray of objtype numbers
configfileconfig file reference
propertynamestring
minvalueinteger
Explanation
Each element's objtype in "objlist" is looked up in the config file referenced by "configfile". if the object's value for "propertyname" is less than "minvalue", its objtype is included in the returned array.
Notes: Example: gets all the bowcraft items you can make given the amount of logs selected.
//Returns all the objtypes in the "BowcraftCarving" entry in menus.cfg:
var objtypes := GetMenuObjTypes( "BowcraftCarving" );
//Returns a subset of the objtypes in the bowcraft item crafting config file that require
//less "material" than the value of targetted_logs.amount.
objtypes := ApplyConstraint(objtypes,bowcraftconfigfile,"material",targetted_logs.amount);
//the return value is in a convienent form to use AddMenuItem()
return objtypes;
Return values
An Array of Object Types that pass the constraint.
Errors
none (instead returns an Uninitialized Object on failure)
Related
UObject
Array



ApplyDamage( Character, Hits )
Parameters:
NameType
CharacterCharacter Reference
HitsReal (0.0 to 30000.0)
Explanation
Decreases a character's hit points, after reducing damage due to armor.
(Old notes:) The steps taken are as follows: A piece of armor is chosen randomly, based on probabilities in ARMRZONE.CFG. Damage is reduced by 50% to 100% of the armor's AR. Remaining damage is halved. "I'm Hit" animation is played. Damage is applied. Mobile is killed if hit points are now zero. Invokes Reputation system effects.
Return values
1 on success
Errors
"Invalid parameter type"
"Damage is out of range"
Related
Character



ApplyRawDamage( Character, Hits )
Parameters:
NameType
CharacterCharacter Reference
HitsInteger (0..255)
Explanation
Decreases a character's hit points. If this causes hit points to drop to zero, kills the character.
Notes: Armor is ignored.
Invokes Reputation system effects.
Return values
1 on success
Errors
none (returns 0 on invalid parameter)
Related
Character



AssignRectToWeatherRegion( region, xwest, ynorth, xeast, ysouth )
Parameters:
NameType
regionstring
xwestinteger
ynorthinteger
xeastinteger
ysouthinteger
Explanation
Sets the range for weather region named "region". Useful for making moving storms. Notes: Weather region strings as defined in regions/weather.cfg
Return values
1 on success
Errors
"Invalid Parameter type"
"Weather region not found"
Related Configs
weather.cfg



Attach( character )
Parameters:
NameType
characterCharacter Reference
Explanation
Associates the current script to the character. See Detach() too.
Return values
1 on success or Error
Errors
"Invalid parameter"
"Another script still attached."
"Another character still attached."
Related
Character



BaseSkillToRawSkill( baseskill )
Parameters:
NameType
baseskillInteger
Explanation
Converts an old-style "base skill" value to old-style "raw skill" value.
Notes: OBSOLETE
Return values
Raw skill value representation
Errors
"Invalid parameter type"



Broadcast( text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )
Parameters:
NameType
textString
fontInteger (optional)
color Integer (optional)
Explanation
Sends text as a System Message to every online player.
See client.inc for font and color values.
Return values
1 on success
Errors
none (returns 0 on invalid parameter)



CheckLineOfSight( object1, object2 )
Parameters:
NameType
object1UObject Reference
object2UObject Reference
Explanation
Tests if object1 has Line-of-sight to object 2
Return values
0 if sight blocked
1 if object1 has LOS to object2
Errors
none (returns 0 on invalid parameter)
Related
UObject



CheckLosAt( character, x, y, z )
Parameters:
NameType
characterCharacter Reference
x,y,zInteger world coordinates
Explanation
Tests if character has Line-of-sight to coordinate
Return values
1 if character has line-of-sight to (x,y,z)
0 if character does not have line-of-sight to (x,y,z)
Errors
none (returns 0 on invalid parameter)
Related
Character



CheckSkill( character, skillid, difficulty, points )
Parameters:
NameType
characterCharacter Ref
skillidInteger skill/attribute ID
difficultyInteger skill use difficulty
pointsInteger skill gain on success
Explanation
NOTE: Calls the Syshook script CheckSkill. If it doesn't exist, always returns false.
Return values
Return value of CheckSkill syshook.
Errors
"Invalid parameter"
"No such skill"
Related
Character



ConsumeMana( who, spellid )
Parameters:
NameType
whoCharacter Reference
spellidInteger
Explanation
Consumes amount of "Mana" for "who" for the spell as defined in spells.cfg
Notes: spells.cfg files define spells and spell ids.
Consumes from "Mana" vital.
Return values
1 on success
Errors
"Invalid parameter"
"No such spell"
"Spell ID out of range"
Related
Character
Related Configs
spells.cfg



ConsumeReagents( caster, spellid )
Parameters:
NameType
casterCharacter Reference
spellidAn integer
Explanation
Removes reagent items from caster's pack according to spellid's definition in spells.cfg. Spells.cfg files define spells & spell ids.
Return values
1 on successful consume, 0 if not enough of defined reagents
Errors
"Spell ID out of range" if !(spellid >= 1 && spellid <= last spellid)
"No such spell" if spellid not found
"Invalid parameter"
Related
Character
Related Configs
spells.cfg



ConsumeSubstance( container, objtype, amount )
Parameters:
NameType
containerContainer reference
objtypeInteger objtype to find and consume
amountAn integer
Explanation
Subtracts "amount" from the first stack of type "objtype" found, starting in container "container"
Return values
1 or Error
Errors
"That is not a container" if container.isa(POLCLASS_CONTAINER) == false
"Amount cannot be negative" if amount < 0
"Not enough of that substance in container"
"Invalid parameter type"
Related
Container



ConsumeVital( who, vital, hundredths )
Parameters:
NameType
whoCharacter Reference
vitalString (vital name)
hundrethsInteger
Explanation
Consumes an amount of vital "vital" in hundreths. for example, ConsumeVital(who, "Stamina", 100) consumes one point of stamina.
Return values
1 on consume success or 0 on failure (insufficient value for the vital)
Errors
"Invalid parameter type" including if vital was not found as a vital name
Related
Character
Related Configs
vitals.cfg



CoordinateDistance(x1, y1, x2, y2)
Parameters:
NameType
x1,y1Integer world coordinates
x2,y2Integer world coordinates
Explanation
Calculates the distance between two coordinates.
Return values
The distance between two coordinates.
Errors
"Invalid parameter type"
Related
UObject



CreateAccount( acctname, password, enabled )
Parameters:
NameType
acctnamestring
passwordstring
enabledinteger (0 or 1)
Explanation
Creates a new player account with the specified account name, password.
Notes: If enabled == 0, player cannot log in.
Return values
Account Reference for the new account on success
Errors
"Account already exists"
"Invalid parameter type"
Related
Account



CreateGuild()
Explanation
Creates a new Guild Object.
Return values
A Guild Reference to the new guild.
Related
Guild



CreateItemAtLocation( x, y, z, objtype, amount := 1, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
objtypeInteger objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amountInteger (0..60000)
Explanation
Creates an item at an arbitrary location.
Amount specifies how large the stack should be.
Runs the item's create script, if any.
Return values
Item Reference on success
Errors
"Invalid parameter type"
"Realm not found"
"Invalid Coordinates for Realm"
"That item is not stackable. Create one at a time."
"Unable to create item of objtype X"
Related
Item
Related Configs
itemdesc.cfg



CreateItemCopyAtLocation(x, y, z, item, realm := _DEFAULT_REALM)
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
itemItem Reference
Explanation
makes a clone of the item referenced with "itemref" at location x,y,z. Copies member variables and CProps. Does not work with Multi objects. Does not copy a container's contents.
Return values
A new Item Reference
Errors
"Invalid parameter type"
"Realm not found"
"Invalid Coordinates for Realm"
"Unable to clone item"
"This function does not work with Multi objects."
Related
Item
Related Configs
itemdesc.cfg



CreateItemInBackpack( of_character, objtype, amount := 1 )
Parameters:
NameType
of_characterCharacter Reference
objtypeInteger objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amountInteger (optional, 0..60000)
Explanation
Creates an item in a character's backpack.
Notes: Adds to an existing stack in the top level of the container, if an appropriate stack can be found (meaning, can hold the new amount, the existing item stack has color equal to its itemdesc.cfg color property AND has equal CProps as its itemdesc.cfg entry (not counting locally and globally ignored cprops). If no appropritate stack is found, creates a new stack.
Runs the item's create script, if any.
Calls the container's canInsert and onInsert scripts, if any.
Return values
Item Reference on success
Errors
"A parameter was invalid."
"Character has no backpack."
"That item is not stackable. Create one at a time."
"That container is full"
"Failed to create that item type"
Related
Character
Item
Related Configs
itemdesc.cfg
stacking.cfg



CreateItemInContainer( container, objtype, amount := 1 )
Parameters:
NameType
containerContainer Reference
objtypeInteger objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amountInteger (optional, 0..60000)
Explanation
Creates an item in a container.
Notes: Adds to an existing stack in the top level of the container, if an appropriate stack can be found (meaning, can hold the new amount, the existing item stack has color equal to its itemdesc.cfg color property AND has equal CProps as its itemdesc.cfg entry (not counting locally and globally ignored cprops). If no appropritate stack is found, creates a new stack.
Runs the item's create script, if any.
Calls the container's canInsert and onInsert scripts, if any.
Return values
Item Reference on success
Errors
"A parameter was invalid"
"That is not a container"
"That item is not stackable. Create one at a time."
"That container is full"
"Failed to create that item type"
Related
Item
Container
Related Configs
itemdesc.cfg
stacking.cfg



CreateItemInInventory( container, objtype, amount := 1 )
Parameters:
NameType
containerContainer reference
objtypeInteger objtype for item to be created, OR String ObjtypeName, OR GetItemDescriptor struct.
amountsize of stack to be created. Default = 1
Explanation
Creates a stack of items in the specified container. As usual, objtype must be valid and amount must be 1..60000.
Note: Will call the container's canInsert and onInsert scripts.
Return values
Item reference or Error
Errors
"A parameter was invalid"
"That is not a container" if container.isa(POLCLASS_CONTAINER) == false
"That container is full" if weight would be > 65535, or if would exceed maximum # of items
"Failed to create that item type"
"Could not insert item into container." if canInsert script returns false
Related
Container
Item
Related Configs
itemdesc.cfg



CreateMenu( title )
Parameters:
NameType
titleString
Explanation
Creates an empty dynamic "old-style item selection" menu.
Return values
A dynamic menu reference if the menu was created successfully
Errors
none (returns 0 on invalid parameter)



CreateMultiAtLocation( x, y, z, objtype, flags := 0, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
objtypeInteger objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
flagsInteger (optional)
Explanation
Creates a "multi" object (house or boat) at a location.
Notes: uo.em constants for flags:
houses only:
const CRMULTI_IGNORE_MULTIS     := 0x0001; //ignore intersecting multis
const CRMULTI_IGNORE_OBJECTS    := 0x0002; //ignore dynamic objects
const CRMULTI_IGNORE_WORLDZ     := 0x0004; //ignore standability,relative Z,world height
const CRMULTI_IGNORE_ALL        := 0x0007; 
objtype must be a multi type as defined in itemdesc.cfg having a type House or Boat.
For Boats: Position must be passable - 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. Runs scripts/misc/boat.ecl on creation.
Return values
Boat Reference or House Reference on success, and adds the multi to the world
Errors
"Invalid parameter type"
"Realm not found"
"Invalid Coordinates for Realm"
"That location is out of bounds"
"That objtype is not a Multi"
"Don't know what kind of multi to make"
Boats:
"Multi definition not found for Boat, objtype=X, graphic=Y"
"No boatshape for Boat in boats.cfg, objtype=X, graphic=Y"
"Position indicated is impassable"
Houses:
"Multi definition not found for House, objtype=X, graphic=Y"
"Location intersects with another structure" (use CRMULTI_IGNORE_MULTIS)
"Something is blocking that location" (use CRMULTI_IGNORE_OBJECTS)
"That location is not suitable" (use CRMULTI_IGNORE_WORLDZ)
Related
House
Boat



CreateNpcFromTemplate( template, x, y, z, override_properties := 0, realm := _DEFAULT_REALM)
Parameters:
NameType
templateString
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
override_propertiesA Struct with keys as String members and values as appropriate (see notes)
Explanation
Creates an NPC from a template (found in NPCDESC.CFG).
Notes: override_properties: a structure containing members to override values in the NPC template. 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.
Return values
Character Reference on success
Errors
"Invalid parameter type"
"Parameter 4 must be a Struct or Integer(0)"
"Realm not found"
"Invalid Coordinates for Realm"
"NPC template 'X' not found"
"Not a valid location for an NPC!"
"Exception detected trying to create npc from template 'X'"
Related
NPC
Related Configs
npcdesc.cfg



CreateRootItemInStorageArea( area, itemname, objtype )
Parameters:
NameType
areaString
itemnameString
objtypeInteger objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
Explanation
Creates the "root" (top-level) item in the storage area "area". "itemname" is the name of this item, and "objtype" is its type.
Notes: The item is normally a container. For example, a bankbox is a storage area and the root item is the chest container. Normal items are then placed in this container.
Return values
Item Reference on success
Errors
"Invalid parameter type"
"Unable to create item"
Related
Item



CreateStorageArea( areaname )
Parameters:
NameType
areanameString
Explanation
Create a new storage area with name "areaname".
Return values
Storage Area reference on success
Errors
Errors: none (returns 0 on invalid parameter)



DestroyGuild( guild )
Parameters:
NameType
guildGuild Reference
Explanation
Destroys an empty guild.
Notes: Must first empty the guild of members, allies, and enemies (see guildref methods)
Return values
1 on success
Errors
"Guild has members"
"Guild has allies"
"Guild has enemies"
"Guild has disbanded"
"Invalid parameter type"
Related
Guild



DestroyItem( Item )
Parameters:
NameType
ItemItem Reference
Explanation
Removes an item from the world. Transmits commands to each client in range of item to reflect this.
Notes: runs the Item's destroy script, if any.
Return values
1 if the item was destroyed
0 if the item's destroy script disallowed destruction
Errors
"That item is being used."
"Invalid parameter type"
Related
Item



DestroyMulti( multi )
Parameters:
NameType
multiMulti Reference
Explanation
Deletes a Multi item from the world.
Notes: House: Moves all characters and items inside multi to ground. Boat: Requires hold be empty, deck be empty, and have no mobiles logged-out on boat.
Return values
1 on success
Errors
"WTF!? Don't know what kind of multi that is!" if not a boat or a house
"Invalid parameter type"
Boat Errors:"There is cargo in the ship's hold"
"There are logged-out characters on the deck"
"The deck is not empty"
Related
House
Boat



DestroyRootItemInStorageArea( area, itemname )
Parameters:
NameType
areaStorage Area Reference
itemnameString
Explanation
Destroys the root item named "itemname" in storage area "area"
Return values
1 on delete success
0 on item not found
Errors
"Invalid parameter type"



Detach()
Explanation
Disassociates the current script from the character that it is attached to. See Attach() too.
If the current script is not attached to a character, does nothing.
Example: a spell script for both doing the spell, implementing a temporary spell effect on an object, and removing the effect after an amount of time:
Program Spell(who)
    // Test, if spell possible (reagents, mana, line of sight, etc..)
    // Do the spell, animations, etc.
    // Now something is changed, a temporary effect is installed to an
object, this effect will expire in n seconds
    // Detach the script from the caster
    Detach(); //this allows other scripts to run on this character during the below sleep()
    sleep(n); //delay until effect time is elapsed
    // End the effect, and return
endprogram
Return values
1 on success (the script was attached to a character, and is no longer.)
Errors
none (returns 0 on failure (character invalid))
Related
Character



DisableEvents( eventtype )
Parameters:
NameType
eventtypeinteger combination (bitwise-OR) of constants from SYSEVENT.INC
Explanation
Disables the system event(s) defined in sysevent.inc for the current NPC or item control script. Do not use for "user" events (see EnableEvents()).
Return values
New event mask on success
Errors
"Invalid parameter"



DisconnectClient( character )
Parameters:
NameType
characterCharacter Reference
Explanation
Disconnects the character's client.
Notes: Fun!
Return values
1 on success
Errors
"Invalid parameter"
"No client is attached"
Related
Character



Distance( object1, object2 )
Parameters:
NameType
object1UObject Reference
object2UObject Reference
Explanation
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)
Return values
Integer - calculated distance on success
Errors
"Invalid parameter type"
Related
UObject



EnableEvents( events, range := -1 )
Parameters:
NameType
eventsInteger
rangeInteger (optional, 0..32)
Explanation
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/sysevent.inc for event type constants. DO NOT use this function for non-system event IDs. For user-created events, just send the event, no need to enable it first.
This function is useful only to NPCs and Items that have called RegisterForSpeechEvents.
Range is only used for certain events (currently speech, and entered/leftarea events)
Return values
Integer new event "mask" on success
Errors
"Invalid parameter"



EnumerateItemsInContainer( container, flags := 0 )
Parameters:
NameType
containerContainer Reference
flagsInteger
Explanation
Returns an array of the contents of a container.
Notes: If 'container' is itself locked, its contents will still be enumerated.
Notes: uo.em constant for this function:
const ENUMERATE_IGNORE_LOCKED := 1; // List content of locked container
Return values
An Array of Item References on success
Errors
"Invalid parameter type"
none (returns 0 on different errors)
Related
Container



EnumerateOnlineCharacters()
Explanation
Gets a list of all online player characters.
Return values
An Array of Character References on success
Errors
none
Related
Character



EquipFromTemplate( character, template )
Parameters:
NameType
characterCharacter Reference
templateString
Explanation
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)
Will not create an item that is not equippable.
Return values
1 on success
Errors
"Invalid parameter"
"Equipment template not found"
"Blech! Can't find '[object name]' named in equip.cfg"
Related
Character
Equipment
Related Configs
equip.cfg



EquipItem( mobile, item )
Parameters:
NameType
mobileCharacter Reference
itemItem Reference
Explanation
Equips an item on a mobile.
Notes: If item 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)
Runs the Item's Equiptest and Equip scripts, if any.
Return values
1 if the item was equipped succesfully
0 if the item's Equip script returned false
Errors
"That is immobile"
"That item is being used."
"That item is not equippable by that character" if equiptest script failed.
"Invalid parameter type"
Related
Character
Item



EraseGlobalProperty( propertyname )
Parameters:
NameType
propertynameString
Explanation
Removes a property from the global property list. propertyname is case-sensative
Return values
1 if the property was erased or did not exist.
Errors
"Invalid parameter type"



EraseObjProperty( object, propertyname )
Parameters:
NameType
objectUObject Reference
propertynameString
Explanation
Removes a property from the custom-property ("cprop") list of an object. propertyname is case-sensative
Return values
1 if the property was erased or did not exist.
Errors
"Invalid parameter type"
Related
UObject



FindAccount( acctname )
Parameters:
NameType
acctnamestring
Explanation
Gets a player Account Reference by the name of the account.
Return values
Account Reference on success
Errors
"Account not found."
"Invalid parameter type"
Related
Account



FindGuild( guildid )
Parameters:
NameType
guildidinteger
Explanation
Gets a Guild Reference for a given Guild ID number
Return values
Guild Reference on success
Errors
"Guild not found"
"Invalid parameter type"
Related
Guild



FindObjtypeInContainer( container, objtype )
Parameters:
NameType
containerContainer reference
objtypeinteger objtype to find
Explanation
Returns an Item Reference to the first found item matching objtype starting in "container".
Return values
Item reference or Error
Errors
"Invalid parameter type"
"That is not a container" if container.isa(POLCLASS_CONTAINER) == false
"No items were found"
Related
Container
Item



FindPath( x1, y1, z1, x2, y2, z2, realm := _DEFAULT_REALM, flags := FP_IGNORE_MOBILES, searchskirt := 5 )
Parameters:
NameType
x1,y1,z1Integer world coordinates - start of the path
x2,y2,z2Integer world coordinates - destination
realmString - case-sensitive name of the realm
flagsInteger
searchskirtInteger
Explanation
Finds a path from start to destination and will return an array of coordinates, representing each step along the path from the next step to take from the start of the path to the actual destination. The coordinates are found in .x, .y, and .z.
Notes: The skirt around the square that is formed around the start of the path to the destination which represents the searchable area is set by searchskirt. Check out MaxPathFindRange in servspecopt.cfg too.
Notes: uo.em constant for this function:
// FindPath flags
const FP_IGNORE_MOBILES         := 0x01;    // ignore Mobiles
const FP_IGNORE_DOORS           := 0x02;    // ignore Doors (you've to open doors by yourself)
Return values
Error or Array of coordinates, representing each step along the path.
Errors
"Invalid parameter"
"Realm not found"
"Start Coordinates Invalid for Realm"
"End Coordinates Invalid for Realm"
"Beyond Max Range."
"Failed to find a path."
"Out of memory."
"Solution Corrupted!"
"Pathfind Error."
Related
NPC
Array



FindRootItemInStorageArea( area, itemname )
Parameters:
NameType
areaStorage Area Reference
itemnameString
Explanation
Finds the root item named "itemname" in the storage area named "area".
Return values
Item Reference on success
Errors
"Invalid parameter type"
"Root item not found."



FindStorageArea( areaname )
Parameters:
NameType
areanameString
Explanation
Gets a reference to the storage area named "areaname"
Return values
Storage Area reference on success
Errors
none (returns 0 on invalid parameter or area not found)



FindSubstance( container, objtype, amount, makeinuse := 0 )
Parameters:
NameType
containerContainer reference
objtypeInteger objtype to find
amountInteger
makeinuseInteger (0/1)
Explanation
Search the given container for items of objtype in an amount equal or greater than the amount given (stackables can return greater than #).
If makeinuse is set to 1, then the items will be reserved.
Return values
If sufficient # of items have been found, those found (and possibly reserved) will be returned in an array.
Errors
"Invalid parameter type"
"That is not a container"
"Amount cannot be negative"
"Not enough of that substance in container"
Related
Container



GetAmount( item )
Parameters:
NameType
itemItem Reference
Explanation
Returns size of item stack.
probably better to use item.amount
Return values
Integer size of item's stack on success
Errors
none (returns 0 on invalid parameter)
Related
Item



GetAttribute( character, attrname )
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
Explanation
Returns the current effective value for the specified attribute on character.
Return values
Integer "Effective" attribute value on success (base + temporary mod + intrinsic mod) or Error
Errors
"Invalid parameter type" including if attrname was not found as an attribute
Related
Character
Related Configs
attributes.cfg



GetAttributeBaseValue( character, attrname )
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
Explanation
Returns the base value for the specified attribute on character.
Return values
Integer "Base" attribute value on success or Error
Errors
"Invalid parameter type" including if attrname was not found as an attribute
Related
Character
Related Configs
attributes.cfg



GetAttributeIntrinsicMod( character, attrname )
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
Explanation
Returns the intrinsic value for the specified attribute on character.
You set intrinsic Mod via exported GetIntrinsicModFunction in attributes.cfg
Return values
Integer "Intrinsic" attribute value on success or Error
Errors
"Invalid parameter type" including if attrname was not found as an attribute
Related
Character
Related Configs
attributes.cfg



GetAttributeTemporaryMod( character, attrname )
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
Explanation
Returns the temporary modification value for the specified attribute on character.
Return values
Integer "temporary" attribute value on success or Error
Errors
"Invalid parameter type" including if attrname was not found as an attribute
Related
Character
Related Configs
attributes.cfg



GetCommandHelp( character, command )
Parameters:
NameType
characterCharacter Reference
commandstring
Explanation
Gets a help message for a textcommand, if one is defined.
Notes: Help files are found in commandname.txt in the same directory as the command script.
Return values
String with help information
Errors
"Invalid parameter type"
"No help for that command found"
Related
Character



GetCoordsInLine(x1, y1, x2, y2)
Parameters:
NameType
x1,y1Integer world coordinates
x2,y2Integer world coordinates
Explanation
Calculates every coordinate between the two points.
Return values
Array of Structs {.x, .y}
Errors
"Invalid parameter type"
Related
UObject



GetEquipmentByLayer( character, layer )
Parameters:
NameType
CharacterCharacter reference
layerAn integer
Explanation
Gets an item reference to an equipped item. For proper layer values, see scripts/include/client.inc
Return values
Itemref or Error
Errors
"Invalid layer"
"Nothing equipped on that layer."
"Invalid parameter"
Related
Character
Item



GetFacing(from_x, from_y, to_x, to_y)
Parameters:
NameType
from_x,from_yInteger world coordinates
to_x,to_yInteger world coordinates
Explanation
Returns the facing number an object must have in order to face to_x and to_y from from_x and from_y.
Return values
Facing number
Errors
"Invalid parameter type"
Related
Character
NPC
UObject



GetGlobalProperty( propertyname )
Parameters:
NameType
propertynameString
Explanation
Retrieves the value of a global property. propertyname is case-sensative
Return values
On success a script object (string, integer, real, array, etc) containing the value of the named property
Errors
"Invalid parameter type"
"Property not found"



GetHarvestDifficulty( resource, x, y, tiletype, realm := _DEFAULT_REALM )
Parameters:
NameType
resourceString
x,yInteger world coordinates
realmString - case-sensitive name of the realm
tiletypeInteger
Explanation
Determines the difficulty of harvesting a resource from location (x,y).
Notes: tiletype will typically be .objtype from TargetCoordinates() Checks the location for an object of type 'tiletype'. This tiletype may be a landtile or an object tile.
"resource" is something like "ore" "wood" "fish", etc. see regions/resource.cfg, regions/ore.cfg, etc.
Return values
An integer difficulty level if resources exist.
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
"No resource by that name"
"No resource-bearing landmark there"
"No resource region at that location"
"Resource is depleted"
Related Configs
resource.cfg



GetMapInfo( x, y, realm := _DEFAULT_REALM )
Parameters:
NameType
x,yInteger world coordinates
realmString - case-sensitive name of the realm
Explanation
Gets information about map data at a location.
Notes: Tells you nothing about Static items! z = map height at x,y. Not necessarily the same as GetStandingHeight() landtile = the land tile type number at x,y (not an item graphic number)
Return values
A Struct with members "z" and "landtile".
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"



GetMenuObjTypes( menuname )
Parameters:
NameType
menunamestatic or dynamic menu
Explanation
Gets all the objtypes contained in the menu.
Notes: see CreateMenu(), AddMenuItem()
Return values
Array of objtypes contained in the given menu.
Errors
none (instead returns 0 on failure)
Related
Array



GetMultiDimensions( graphic )
Parameters:
NameType
graphicMulti Graphic ID
Explanation
Returns struct with coords of _relative_ distances from center. xmin and ymin are _negative_.
Return values
Struct with "xmin", "xmax", "ymin", "ymax".
Errors
"Invalid parameter"
"Multi Graphic not found"
Related
Multi



GetObjProperty( object, propertyname )
Parameters:
NameType
objectUObject Reference
propertynameString
Explanation
Retrieves custom data (a "cprop") associated with an object. propertyname is case-sensative
Return values
On success, the unpacked object that was saved with SetObjProperty. This could be a string, integer, real, array, struct, dictionary, etc.
Errors
"Property not found"
"Invalid parameter type"
Related
UObject



GetObjPropertyNames( object )
Parameters:
NameType
objectUObject reference
Explanation
Gets all the CProp names set on the object. Use GetObjProperty(object, returned_array[i]) to get the CProp value.
Return values
Array of strings or Error
Errors
"Invalid parameter type"
Related
UObject
Array



GetObjtypeByName( name )
Parameters:
NameType
namestring
Explanation
Finds the matching Object Type number for the obejct named "name" Matches on the itemdesc.cfg property "Name".
Return values
Integer ObjType or Error
Errors
"No objtype by that name"
"Invalid parameter"
Related Configs
itemdesc.cfg



GetRegionName( object )
Parameters:
NameType
objecttop level UObject (item/character/npc/etc)
Explanation
Get name of [justice] region that Object is in.
Return values
String value of "Region Name" on success
Errors
"Invalid Parameter"
"No Region defined at this Location"
Related Configs
regions.cfg



GetRegionNameAtLocation( x, y, realm )
Parameters:
NameType
xx location
yy location
realmString - case-sensitive name of the realm
Explanation
Get name of [justice] region for coordinates.
Return values
String value of "Region Name" on success
Errors
"Invalid Parameter"
"Realm not found"
"Invalid Coordinates for realm"
"No Region defined at this Location"
Related Configs
regions.cfg



GetRegionString( resource, x, y, propertyname, realm := _DEFAULT_REALM )
Parameters:
NameType
resourcestring
x,yInteger world coordinates
realmString - case-sensitive name of the realm
propertynamestring
Explanation
Allows you to look up custom properties within a resource region entry.
"resource" is a string that matches a resource type in regions/resource.cfg, i.e. "ore". x,y is the coordinate to look up in the regions defined in resources/ore.cfg (or the filename matching the supplied resource).
"property_name" is the _custom_ property to match (i.e. UnitsPerArea, SecondsPerRegrow, Capacity, Range are NOT matched) in the found region.
Example: in regions/resource.cfg there exists a ResourceType "ore". In ore.cfg 
         there exists a region:
Region Outer Covetous 
{ 
    UnitsPerArea        15 
    SecondsPerRegrow    300 
    Capacity            20000 
    Range        2299 784 2635 967 
    Prop         value_string    -- this is a custom property not used by the core
} 
GetRegionString("ore",2299,785,"Prop"); would return "value_string"
Return values
String value of "propertyname" on success
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
"No resource by that name" if "resource" not found in regions/resource.cfg
"No resource region at that location" if the given x,y is not defined inside any of the regions in regions/[resource string].cfg
"Property not found" if "propertyname" was not found in the matching region.
Related Configs
regions.cfg



GetSpellDifficulty( spellid )
Parameters:
NameType
spellidInteger
Explanation
Gets spell "difficulty" based on spell circle number (config/circles.cfg).
Notes: spells.cfg files define spells and spell ids. "Difficulty" values are used in the function CheckSkill()
Return values
Integer difficulty value
Errors
"Invalid parameter"
"No such spell"
"Spell ID out of range"
Related Configs
circles.cfg



GetStandingHeight( x, y, startz, realm := _DEFAULT_REALM )
Parameters:
NameType
x,yInteger world coordinates
realmString - case-sensitive name of the realm
startxInteger
Explanation
Gets the lowest z height value one could stand at x,y starting at "startz".
Notes: For example, if there is a static tunnel under the map, using a startz value less than the tunnel floor would get you the z of the floor. Above that value would get you the next possible standing height (i.e. on the map above). Also returns a multi reference if a multi exists at that location.
Return values
A Struct with members "z" and possibly "multi" (a Multi Reference)
Errors
"Invalid parameter type"
"Realm not found"
"Invalid Coordinates for Realm"
"Can't stand there" if inaccessible location



GetStandingLayers( x, y, flags := MAPDATA_FLAG_ALL, realm := _DEFAULT_REALM )
Parameters:
NameType
x,yInteger world coordinates
realmString - case-sensitive name of the realm
flagsInteger
Explanation
Returns an Array of standing Layers and blocking Solids.
mapdata flags:
const MAPDATA_FLAG_NONE         := 0x0000;     // Nothing
const MAPDATA_FLAG_MOVELAND     := 0x0001;     // Move Land
const MAPDATA_FLAG_MOVESEA      := 0x0002;     // Move Sea
const MAPDATA_FLAG_BLOCKSIGHT   := 0x0004;     // Block Sight
const MAPDATA_FLAG_OVERFLIGHT   := 0x0008;     // Over Flight
const MAPDATA_FLAG_ALLOWDROPON  := 0x0010;     // Allow DropOn
const MAPDATA_FLAG_GRADUAL      := 0x0020;     // Gradual
const MAPDATA_FLAG_BLOCKING     := 0x0040;     // Blocking
const MAPDATA_FLAG_MORE_SOLIDS  := 0x0080;     // List more Solids

const MAPDATA_FLAG_WALKBLOCK    := 0x0057;     // Move Land, Move Sea, Blocking, Block Sight, Allow DropOn
const MAPDATA_FLAG_MOVE_FLAGS   := 0x0063;     // Move Land, Move Sea, Blocking, Gradual
const MAPDATA_FLAG_DROP_FLAGS   := 0x0050;     // Blocking, Allow DropOn
const MAPDATA_FLAG_ALL          := 0xffffffff; // All
Return values
Array of Structs with members "z", "height" and "flags" at that location or Error.
Errors
"Invalid parameter type"
"Realm not found"
"Invalid Coordinates for Realm"
Related
Character
NPC
Array
Struct



GetVital( character, vitalname )
Parameters:
NameType
characterCharacter Reference
vitalnameString (vital name)
Explanation
Gets the current value of "vitalname" on "character".
Return values
Integer current value of the vital on success or Error
Errors
"Invalid parameter type" including if vitalname was not found as a vital
Related
Character
Related Configs
vitals.cfg



GetVitalMaximumValue( character, vitalname )
Parameters:
NameType
characterCharacter Reference
vitalnameString (vital name)
Explanation
Gets the maximum value of "vitalname" on "character"
Return values
Integer maximum value of the vital on success or Error
Errors
"Invalid parameter type" including if vitalname was not found as a vital
Related
Character
Related Configs
vitals.cfg



GetVitalRegenRate( character, vitalname )
Parameters:
NameType
characterCharacter Reference
vitalnameString (vital name)
Explanation
Returns the regeneration rate for "vitalname" on "character"
Return values
Integer regeneration rate of the vital on success
Errors
"Invalid parameter type" including if vitalname was not found as a vital
Related
Character
String
Related Configs
vitals.cfg



GetWorldHeight( x, y, realm := _DEFAULT_REALM )
Parameters:
NameType
x,yInteger world coordinates
realmString - case-sensitive name of the realm
Explanation
Gets the lowest standing height at x,y
Return values
z value of lowest standing height
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
"Location out of bounds"
"Nowhere" if one could not stand at any z value of x,y



GrantPrivilege( character, privilege )
Parameters:
NameType
characterCharacter Reference
privilegeString
Explanation
Grants a privilege to a character.
Notes: see some other doc for a list of privs and their functions
Return values
1 f the privilege was granted successfully
Errors
"Invalid parameter"
Related
Character



HarvestResource( resource, x, y, b, n, realm := _DEFAULT_REALM )
Parameters:
NameType
resourceString
x,yInteger world coordinates
realmString - case-sensitive name of the realm
bInteger
nInteger
Explanation
Attempts to harvest a resource from a location.
Notes: Harvests a*b resource units, where 0 is less than or equal to 'a' and 'a' is less than or equal to n. Thus you can request 0-40 units in groups of 5, etc.
Return values
Integer number of resource units harvested if resources were harvested, or 0 if no resources were available.
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
"No resource by that name"
"No resource region at that location"
Related Configs
resource.cfg



HealDamage( Character, Hits )
Parameters:
NameType
CharacterCharacter Reference
HitsInteger (0..255)
Explanation
Increases a character's hit points, up to the character's maximum.
Notes: Invokes Reputation system effects.
Return values
1 if some part of the damage could be healed.
Errors
"Invalid parameter"
Related
Character



ListAccounts()
Explanation
Gets a list of all account names.
Return values
Array of Strings of account names.
Related
Array
Account



ListEquippedItems( who )
Parameters:
NameType
whoCharacter Reference
Explanation
Returns a list of items current equipped on character referenced by "who"
Return values
Array of Item References equipped on "who"
Errors
"Invalid parameter"
Related
Character
Item
Array



ListGhostsNearLocation( x, y, z, range, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
Explanation
Searches the world for ghosts within "range" squares of (x,y,z).
Notes: 19 is used for the z-range. Rectangular range is used - x-range and y-range are compared independently This call is equivalent to ListMobilesNearLocationEx( x, y, z, range, LISTEX_GHOST, realm ). For this reason, this function is depreciated.
Return values
An array of Character References of ghosts found near the location on success
Errors
"Invalid parameter"
"Realm not found"
Related
Character



ListGuilds()
Explanation
Gets a list of all guilds.
Return values
An Array of Guild References.
Related
Guild
Array



ListHostiles( character, range := 20, flags := 0 )
Parameters:
NameType
characterCharacter Reference
rangeinteger (optional, default=20)
flagsinteger (optional, default=0)
Explanation
Gets a list of Character References that are hostile (i.e. attacking) "character"
Notes: from uo.em constants:
const LH_FLAG_LOS               := 1;       // only include those in LOS
const LH_FLAG_INCLUDE_HIDDEN    := 2;       // include hidden characters
Will NOT find "concealed" characters.
Return values
Array of Character References hostile to "character"
Errors
"Invalid parameter"
Related
Character
Array



ListItemsAtLocation( x, y, z, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
Explanation
Returns a list of items at the specified x,y,z. test ret != 0
Use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value.
Notes: from uo.em constants:
// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
<uninitialized object> if invalid parameters, or Array of Item References of items at that location.
Errors
"Realm not found"
"Invalid Coordinates for Realm"
Related
Item
Array



ListItemsNearLocation( x, y, z, range, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
Explanation
Searches the world for items within range squares of (x,y,z).
Notes: 19 is used for the Z-Range or use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value. Rectangular range is used - x-range and y-range are compared independently.
Notes: from uo.em constants:
// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
<uninitialized object> if invalid parameters, or Array of Item References of Items found near the location.
Errors
"Realm not found"
"Invalid Coordinates for Realm"
Related
Item
Array



ListItemsNearLocationOfType( x, y, z, range, objtype, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
objtypeInteger
Explanation
Searches the world for items within range squares of (x,y,z) of type objtype.
Notes: 19 is used for the Z-Range or use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value. Rectangular range is used - x-range and y-range are compared independently.
Notes: from uo.em constants:
// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
<uninitialized object> if invalid parameters, or Array of Item References of Items matching "objtype" found near the location.
Errors
"Realm not found"
"Invalid Coordinates for Realm"
Related
Item
Array



ListItemsNearLocationWithFlag( x, y, z, range, flags, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
flagsInteger
Explanation
Gets an array of itemrefs if its graphic matches any of the OR'd flags passed. "flags" here are tiledata.mul flags for the item's graphic.
Tiledata.mul flags:
const TILEDATA_FLAG_BACKGROUND  := 0x00000001; //Background
const TILEDATA_FLAG_WEAPON      := 0x00000002; //Weapon
const TILEDATA_FLAG_TRANSPARENT := 0x00000004; //Transparent
const TILEDATA_FLAG_TRANSLUCENT := 0x00000008; //Translucent
const TILEDATA_FLAG_WALL        := 0x00000010; //Wall
const TILEDATA_FLAG_DAMAGING    := 0x00000020; //Damaging
const TILEDATA_FLAG_IMPASSIBLE  := 0x00000040; //Impassable
const TILEDATA_FLAG_WET         := 0x00000080; //Wet
const TILEDATA_FLAG_UNK         := 0x00000100; //Unknown
const TILEDATA_FLAG_SURFACE     := 0x00000200; //Surface
const TILEDATA_FLAG_BRIDGE      := 0x00000400; //Bridge
const TILEDATA_FLAG_STACKABLE   := 0x00000800; //Generic/Stackable
const TILEDATA_FLAG_WINDOW      := 0x00001000; //Window
const TILEDATA_FLAG_NOSHOOT     := 0x00002000; //No Shoot
const TILEDATA_FLAG_PREFIX_A    := 0x00004000; //Prefix A
const TILEDATA_FLAG_PREFIX_AN   := 0x00008000; //Prefix An
const TILEDATA_FLAG_INTERNAL    := 0x00010000; //Internal (things like hair, beards, etc)
const TILEDATA_FLAG_FOILIAGE    := 0x00020000; //Foliage
const TILEDATA_FLAG_PARTIAL_HUE := 0x00040000; //Partial Hue
const TILEDATA_FLAG_UNK1        := 0x00080000; //Unknown 1
const TILEDATA_FLAG_MAP         := 0x00100000; //Map
const TILEDATA_FLAG_CONTAINER   := 0x00200000; //Container
const TILEDATA_FLAG_WEARABLE    := 0x00400000; //Wearable
const TILEDATA_FLAG_LIGHTSOURCE := 0x00800000; //LightSource
const TILEDATA_FLAG_ANIMATED    := 0x01000000; //Animated
const TILEDATA_FLAG_NODIAGONAL  := 0x02000000; //No Diagonal
const TILEDATA_FLAG_UNK2        := 0x04000000; //Unknown 2
const TILEDATA_FLAG_ARMOR       := 0x08000000; //Armor
const TILEDATA_FLAG_ROOF        := 0x10000000; //Roof
const TILEDATA_FLAG_DOOR        := 0x20000000; //Door
const TILEDATA_FLAG_STAIRBACK   := 0x40000000; //StairBack
const TILEDATA_FLAG_STAIRRIGHT  := 0x80000000; //StairRight
Notes: 19 is used for the Z-Range or use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value. Rectangular range is used - x-range and y-range are compared independently.
Notes: from uo.em constants:
// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
Array of Item References of Items matching "flags" found near the location or Error.
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
Related
Item
Array



ListMobilesInLineOfSight( object, range )
Parameters:
NameType
objectUObject Reference
rangeInteger
Explanation
Gets list of mobiles in line of sight of "object", maximum "range" tiles away.
Notes: Finds living, non-hidden mobiles within range tiles of object, that have LOS with it.
Return values
An Array of Character References on success
Errors
"Invalid parameter"
Related
UObject



ListMobilesNearLocation( x, y, z, range, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
Explanation
Searches the world for mobiles within range squares of (x,y,z).
Notes: Finds living, non-hidden mobiles found near the location.
Notes: 19 is used for the Z-Range or use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value. Rectangular range is used - x-range and y-range are compared independently.
Notes: from uo.em constants:
// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
An Array of Character References
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
Related
Character
Array



ListMobilesNearLocationEx( x, y, z, range, flags, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
flagsInteger
Explanation
Searches the world for mobiles within range squares of (x,y,z).
Notes: uo.em constants for flags - include mobile types:
const LISTEX_FLAG_NORMAL := 0x01;
const LISTEX_FLAG_HIDDEN := 0x02;
const LISTEX_FLAG_GHOST  := 0x04;
const LISTEX_FLAG_CONCEALED  := 0x08;
Notes: 19 is used for the Z-Range or use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value. Rectangular range is used - x-range and y-range are compared independently.
Notes: from uo.em constants:
// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
An Array of Character References of mobiles found matching the search criteria.
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
Related
Character
Array



ListMultisInBox( x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )
Parameters:
NameType
x1,y1,z1integer, for north west upper corner of box
x2,y2,z2integer, for south east lower corner of box
realmString - case-sensitive name of the realm
Explanation
Lists all multis inside an imaginary box (where a multi must have at least one 'static' piece inside the box)
Notes: This function will not generate "Invalid Coordinates for realm" Error, because some Scripter "loves" this "bug" :o/
Return values
Error or Array of all multis found inside the specified box.
Errors
"Invalid parameter"
"Realm not found"
Related
House
Boat
Array



ListObjectsInBox( x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )
Parameters:
NameType
x1,y1,z1integer, for north west upper corner of box
x2,y2,z2integer, for south east lower corner of box
realmString - case-sensitive name of the realm
Explanation
Lists all items & mobiles inside an imaginary box. Finds both characters (PCs & NPCs) and items
Notes: This function will not generate "Invalid Coordinates for realm" Error, because some Scripter "loves" this "bug" :o/
Return values
Error or Array of all characters and items found inside the specified box.
Errors
"Invalid parameter"
"Realm not found"
Related
Item
Character
Array



ListStaticsAtLocation( x, y, z, flags := 0, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
flagsInteger
Explanation
Returns a list of Static or Multi Items at the specified x,y,z.
Use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value.
Notes: from uo.em constants:
// ListStatics* flags
const ITEMS_IGNORE_STATICS      := 0x01;    // Don't list Static Items
const ITEMS_IGNORE_MULTIS       := 0x02;    // Don't list Multi Items

// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
Array of Structs with members "x", "y", "z" and "objtype" or Error.
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
Related
Item
Array



ListStaticsInBox( x1,y1,z1, x2,y2,z2, flags := 0, realm := _DEFAULT_REALM )
Parameters:
NameType
x1,y1,z1integer, for north west upper corner of box
x2,y2,z2integer, for south east lower corner of box
realmString - case-sensitive name of the realm
flagsInteger
Explanation
Lists all Static or Multi Items inside an imaginary box.
Notes: This function will not generate "Invalid Coordinates for realm" Error, because some Scripter "loves" this "bug" :o/
Notes: from uo.em constants:
// ListStatics* flags
const ITEMS_IGNORE_STATICS      := 0x01;    // Don't list Static Items
const ITEMS_IGNORE_MULTIS       := 0x02;    // Don't list Multi Items
Return values
Array of Structs with members "x", "y", "z" and "objtype" or Error.
Errors
"Invalid parameter"
"Realm not found"
Related
Item
Array



ListStaticsNearLocation( x, y, z, range, flags := 0, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
rangeInteger
flagsInteger
Explanation
Searches the world for Static or Multi Items within range squares of (x,y,z).
Notes: 19 is used for the Z-Range or use LIST_IGNORE_Z constant as Z Parameter to list all Items ignoring Z-Value. Rectangular range is used - x-range and y-range are compared independently.
Notes: from uo.em constants:
// ListStatics* flags
const ITEMS_IGNORE_STATICS      := 0x01;    // Don't list Static Items
const ITEMS_IGNORE_MULTIS       := 0x02;    // Don't list Multi Items

// special value for List[Items/Mobiles/Statics]*
const LIST_IGNORE_Z             := 0x40000000; // Ignore Z-Value and list everything
Return values
Array of Structs with members "x", "y", "z" and "objtype" or Error.
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
Related
Item
Array



MoveCharacterToLocation( character, x, y, z, flags := 0 )
Parameters:
NameType
characterCharacter Reference
x,y,zInteger world coordinates
flagsInteger (optional)
Explanation
Moves character to a location in the world.
Notes: The if MOVECHAR_FORCELOCATION is not passed with flags, z-coordinate passed is used as a hint. The character will be placed on the the ground, or on an item, or on a ship, just as if the character had tried to walk there. If it is set, the z location of the character is forced.
uo.em constant for flags: const MOVECHAR_FORCELOCATION := 0x40000000;
Return values
1 on success
Errors
"Invalid parameter"
"Can't go there"
Related
Character



MoveItemToContainer( item, container, x := -1, y := -1 )
Parameters:
NameType
itemItem Reference
containerContainer Reference
x,yInteger coords inside container gump (optional)
Explanation
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.
Calls the item's unequiptest and unequip scripts, if any.
Calls the container's canInsert and onInsert scripts, if any.
Calls the item's original container's (if any) canRemove and onRemove scripts, if any.
Return values
1 on success
Errors
"Invalid parameter type"
"That is immobile"
"That item is being used."
"Non-container selected as target"
"Can't put a container into itself"
"Can't put a container into an item in itself"
"Container is too full to add that"
"Item cannot be unequipped"
Related
Item
Container



MoveItemToLocation( item, x, y, z, flags )
Parameters:
NameType
itemItem Reference
x,y,zInteger world coordinates
flagsInteger
Explanation
Moves an item to a location in the world.
Notes: If item is equipped, its unequiptest and unequip scripts are run, if any.
uo.em constants for flags:
const MOVEITEM_NORMAL        := 0;
const MOVEITEM_FORCELOCATION := 0x40000000;
If FORCELOCATION is not set, the z value is used as a hint, just as if the item was moved there by the cursor. The item will be placed on top of another item, multi, etc. If the flag is set, the z position is forced.
Calls the item's original container's canRemove and onRemove scripts, if any
Return values
1 on success
Errors
"Invalid parameter type"
"Invalid location selected"
"Location specified is out of bounds"
"That item is being used."
"That is immobile"
Related
Item



MoveItemToSecureTradeWin( item, character )
Parameters:
NameType
itemItem Reference
characterCharacter Reference
Explanation
Move item to secure trade window via script.
Return values
1 on success or Error
Errors
"Invalid parameter type"
"That is immobile"
"That item is being used."
"Could not remove item from its container."
"Item was destroyed in CanRemove script"
"Item cannot be unequipped"
"Item was destroyed in Equip Script"
"Item was destroyed in OnRemove script"
"Unable to complete trade"
"That's too heavy to trade."
"Something went wrong with trade window."
Related
Item
Character



MoveObjectToLocation( object, x, y, z, realm := _DEFAULT_REALM, flags := MOVEOBJECT_NORMAL )
Parameters:
NameType
objectObject Reference
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
flagsInteger
Explanation
Moves an Object to a location in the world and/or from one realm to another realm.
Function will replace MoveCharacterToLocation(), MoveItemToLocation(), and MoveObjectToRealm().
Currently moves boats, mobiles, and items.
Notes: If MOVEOBJECT_FORCELOCATION is not passed with flags, z-coordinate passed is used as a hint. The object will be placed on the the ground, or on an item, or on a ship. If it is set, the z location of the object is forced.
Notes: If item is equipped, its unequiptest and unequip scripts are run, if any.
Notes: Calls the item's original container's canRemove and onRemove scripts, if any.
uo.em constants for flags:
// Constants for MoveObjectToLocation
//
const MOVEOBJECT_NORMAL		:= 0x0;
const MOVEOBJECT_FORCELOCATION	:= 0x40000000;
Return values
1 on success
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"
"Can't handle that object type yet."
Mobile:
"Can't go there"
Boat:
"Position indicated is impassable"
Item or Container:
"That is immobile"
"That item is being used."
"Location (x, y, z) is out of bounds"
"Invalid location selected"
"Could not remove item from its container."
"Item was destroyed in CanRemove script"
"Item cannot be unequipped"
"Item was destroyed in Equip script"
"Item was destroyed in OnRemove script"
Related
Boat
Character
Container
Item
UObject



MoveObjectToRealm( object, realm, x, y, z, flags := 0 )
Parameters:
NameType
objectUObject reference
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
flagsinteger (optional, default=0)
Explanation
Moves an Object from one realm to another realm.
This is the only write interface to an object's realm. If you wish an object to reside on another realm, this is the only function available.
Return values
1 on success
Errors
"Invalid parameter type"
"Realm not found"
"Invalid Coordinates for Realm"
"Object is already on that realm."
"Can't handle that type yet"
"Invalid parameter"
Mobile:
"Can't go there"
Boat:
"Position indicated is impassable"
Item or Container:
"That is immobile"
"That item is being used."
"Location (x, y, z) is out of bounds"
"Invalid location selected"
"Could not remove item from its container."
"Item was destroyed in CanRemove script"
"Item cannot be unequipped"
"Item was destroyed in Equip script"
"Item was destroyed in OnRemove script"
Related
UObject



OpenPaperdoll( towhom, forwhom )
Parameters:
NameType
towhomCharacter Reference
forwhomCharacter Reference
Explanation
Sends the paperdoll gump to a character.
Notes: "towhom" gets the paperdoll for character "forwhom"
Return values
1 on success
Errors
"Invalid parameter type"
"No client attached"
Related
Character



PerformAction( character, action )
Parameters:
NameType
characterCharacter Reference
actionInteger
Explanation
Causes character to perform an action, such as Bow or Salute.
Notes: see client.inc for valid action IDs
Return values
1 on success
Errors
"Invalid parameter"
Related
Character



PlayLightningBoltEffect( center_object )
Parameters:
NameType
center_objectUObject Reference
Explanation
Plays a lightning bolt effect centered on the object.
Return values
1 on success
Errors
none (returns 0 if invalid parameter).
Related
UObject



PlayMovingEffect( source, target, effect, speed, loop := 0, explode := 0 )
Parameters:
NameType
sourceUObject Reference
targetUObject Reference
effectInteger
speedInteger (0..255)
loopInteger (Optional, 0..255)
explodeInteger (Optional, 0..255)
Explanation
Causes a moving effect to be played, travelling from source to destination
Notes: effect = an item graphic number (the first in a series if an animation) speed = how fast the effect should travel. loop = 0/1 loop the animation? explode = 0/1 show an explosion at destination at the end of the effect?
Return values
1 on success
Errors
none (returns 0 if invalid parameter)
Related
UObject



PlayMovingEffectXYZ( srcx, srcy, srcz, dstx, dsty, dstz, effect, speed, loop := 0, explode := 0, realm := _DEFAULT_REALM )
Parameters:
NameType
srcx,srcy,srczInteger Source world coordinates
dstx,dsty,dstzInteger Destination world coordinates
realmString - case-sensitive name of the realm
effectinteger
speedinteger (to 255)
loopinteger (to 255)
explodeinteger (to 255)
Explanation
Starts a moving effect between the source and destination coordinates.
Notes: "effect" is a UO graphic number (the first graphic in a series for an animated effect) "speed" controls the time between frames of animation "loop" controls the number of total frames to play in the animation (loops if greater than the length of the animation). 0 = play once. "explode" flags if an explosion effect should be played at the end of the animation
Return values
1 on success, 0 or Error
Errors
"Realm not found"
"Invalid Coordinates for Realm"



PlayObjectCenteredEffect( uobject, effect, speed, loop := 0)
Parameters:
NameType
uobjectUObject Reference
effectInteger
speedInteger (0..255)
loopInteger (Optional, 0..255)
Explanation
Causes an effect to be played, centered on uobject, which follows uobject if it moves.
Notes: see PlayMovingEffect for effect, speed, loop description This is used for effects like flame strike and reactive armor.
Return values
1 on success
Errors
none (returns 0 on invalid parameter)
Related
UObject



PlaySoundEffect( object, effect )
Parameters:
NameType
objectUObject Reference
effectInteger
Explanation
Causes a sound effect to be played, centered on object.
Notes: see client.inc for sound effect constants
All clients within a range of 18 tiles are sent this command. Use PlaySoundEffectPrivate() for private sounds.
Return values
1 on success
Errors
"Invalid parameter"
Related
UObject



PlaySoundEffectPrivate( object, effect, playfor )
Parameters:
NameType
objectUObject Reference
effectInteger
playforCharacter Reference
Explanation
Plays a sound effect only heard by "playfor", centered around "object"
Notes: see client.inc for sound IDs (or InsideUO)
Return values
1 on success
Errors
"Invalid parameter"
Related
Character
UObject



PlayStationaryEffect( x, y, z, effect, speed, loop := 0, explode := 0, realm := _DEFAULT_REALM )
Parameters:
NameType
x,y,zInteger world coordinates
realmString - case-sensitive name of the realm
effectinteger
speedinteger (to 255)
loopinteger (to 255)
explodeinteger (to 255)
Explanation
Starts a stationary graphic effect at x,y,z.
Notes: "effect" is a UO graphic number (the first graphic in a series for an animated effect) "speed" controls the time between frames of animation "loop" controls the number of total frames to play in the animation (loops if greater than the length of the animation). 0 = play once. "explode" flags if an explosion effect should be played at the end of the animation
Return values
1 on success
Errors
"Invalid parameter"
"Realm not found"
"Invalid Coordinates for Realm"



Polcore()
Explanation
Returns a Polcore object. See object reference for object methods.
Return values
Polcore object reference
Related
Polcore



PrintTextAbove( above_object, text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )
Parameters:
NameType
above_objectUObject Reference
textString
fontInteger (optional)
colorInteger (optional)
Explanation
Prints text above an object, as if spoken.
Notes: see client.inc for suitable values for font and color
Return values
0 if text was too long (>200 characters)
1 on success
Errors
"A parameter was invalid"
Related
UObject



PrintTextAbovePrivate( above_object, text, character, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )
Parameters:
NameType
above_objectUObject Reference
textString
characterCharacter Reference
fontInteger (optional)
colorInteger (optional)
Explanation
Causes text to be displayed above "above_object", as if spoken. This text will only be seen by a single character referenced by "character"
Notes: see client.inc for suitable values for font and color
Return values
0 if text was too long (>200 characters)
1 on success
Errors
"A parameter was invalid"
Related
UObject
Character



RawSkillToBaseSkill( rawskill )
Parameters:
NameType
rawskillInteger
Explanation
Converts an old-style "raw skill" value to old-style "base skill" value.
Notes: OBSOLETE
Return values
Base skill value representation
Errors
"Invalid parameter type"



ReadGameClock()
Explanation
Returns the total number of seconds the server has been active.
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.
Return values
Integer - The current value of the game clock.
Errors
none



RecalcVitals( character )
Parameters:
NameType
characterCharacter Reference
vitalnameString (vital name)
Explanation
Recalculates regen rates and maximum values from the exported functions in vitals.cfg for all vitals on a mobile
Call this if you changed the regen rates or maximums for a vital, or the intrinsic modifier exported function for an attribute.
Return values
true
Errors
"Mobile must not be offline"
"Invalid parameter type"
Related
Character
Related Configs
vitals.cfg



RegisterForSpeechEvents( at_object, range, flags := 0 )
Parameters:
NameType
at_objectUObject Reference
rangeInteger
flagsInteger (optional)
Explanation
Player-character speech spoken within "range" tiles of "at_object" will generate speech events, which are sent to "at_object"'s control script (use wait_for_event() to retreive the event).
uo.em constants for flags: const LISTENPT_HEAR_GHOSTS := 0x01;
Return values
1 on success
Errors
"Invalid parameter type"
"Already registered for speech events"
Related
UObject
Item
Character



ReleaseItem( item )
Parameters:
NameType
itemItem Reference
Explanation
Releases an item previously reserved by ReserveItem().
Return values
1 on success or Error
Errors
"That item is not reserved by this script." if item is not reserved (using ReserveItem())
"That item is not reserved." if the item is not "in use"
"Invalid parameter"
Related
Item



RequestInput(character, item, prompt )
Parameters:
NameType
characterCharacter Reference
itemItem Reference
promptString
Explanation
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.
Return values
A String containing the next line of text from the client's keyboard on success. Returns 0 (int) if control characters were found in the string.
Errors
"Invalid parameter"
"No client attached"
"Another script has an active prompt"
Related
Character
Item



ReserveItem( item )
Parameters:
NameType
itemItem Reference
Explanation
Reserves an item so no other script or client may manipulate it until ReleaseItem() is called. Use this function to prevent nasty exploits like this:
if(!ReserveItem(item))
  SendSysMessage(who, "You cannot use that.");
  return;
endif
Return values
1 if already reserved, 1 on success, or Error
Errors
"That item is already being used."
"Invalid parameter"
Related
Item



RestartScript( npc )
Parameters:
NameType
npcCharacter Reference (must be an NPC)
Explanation
Stops the current master script for an NPC, and starts a new one.
npc.script can be assigned before calling this, to change the master script for an NPC.
Return values
1 if the script was started
Errors
"Invalid parameter"
"RestartScript only operates on NPCs"
Related
NPC



Resurrect( ghost, flags := 0 )
Parameters:
NameType
ghostCharacter Reference
flagsinteger flags
Explanation
Resurrects a ghost. Checks to see if the location occupied by the ghost is valid for an alive character first unless flags == RESURRECT_FORCELOCATION. (Be very careful with this unless you like exploits)
flags:
const RESURRECT_FORCELOCATION := 0x01;
Return values
1 if the ghost was resurrected successfully
Errors
"Invalid parameter type"
"That is not dead"
"That location is blocked"
Related
Character



RevokePrivilege( character, privilege )
Parameters:
NameType
characterCharacter Reference
privilageString
Explanation
Revokes a privilege from a character.
Return values
1 if the privilege was revoked, or if it was not previously granted.
Errors
"Invalid parameter"
Related
Character



SaveWorldState()
Explanation
Saves the current world state.
Return values
struct { CleanObjects, DirtyObjects, ElapsedMilliseconds }
Errors
"Exception during world save"
"pol.cfg has InhibitSaves=1"



SecureTradeWin( character, character2 )
Parameters:
NameType
characterCharacter Reference
character2Character Reference
Explanation
Init secure trade via script over long distances.
Return values
1 on success or Error
Errors
"Invalid parameter type"
"You can't trade with yourself."
"No client attached."
"Secure trading is unavailable."
"You cannot trade with someone in war mode."
"You cannot trade while in war mode."
"That person is already involved in a trade."
"You are already involved in a trade."
"Ghosts cannot trade items."
"Something goes wrong."
Related
Character



SelectColor( character, item )
Parameters:
NameType
characterCharacter Reference
itemItem Reference
Explanation
Sends a color chooser gump to character.
Notes: Function blocks until character cancels or selects a color from the chooser gump. No validation is done by the core. Might be useful to check if the color returned is >1001 (out of range for the chooser gump).
Return values
Integer of selected color. use item.color = return_value to set.
Errors
"Invalid parameter type"
"No client attached"
"Client is already selecting a color"
Related
Character
Item



SelectMenuItem2( character, menuname )
Parameters:
NameType
characterCharacter Reference
menunameString name of the static menu in menus.cfg, or a dynamic menu reference
Explanation
Displays an object menu on the character's client for the player to select from.
Notes: Can take a static or dynamic menu.
Return values
0 if the menu was cancelled, or the character's client disconnected.
A Structure on success: .objtype = Integer object type of the selection. .index = 1-based index within the menu of the selection. .graphic = Integer graphic of the object. .color = color of the object.
Errors
"Invalid parameter"
"Client is busy, or menu is empty"
"Menu too large"
Related
Character
Related Configs
menus.cfg



SendBuyWindow( character, container, vendor, items, flags := 0 )
Parameters:
NameType
characterCharacter Reference to player
containerContainer Reference ( vendor 'for sale items' container )
vendorCharacter Reference to NPC vendor
itemContainer Reference (vendor 'player bought items' container)
flagsInteger
Explanation
Sends the "buy scroll" gump to a player to choose items to buy.
Notes: Pretty nasty function. Containers should be in storage areas.
Notes: Core will send Item Description using AoS Tooltips in any case if flag VENDOR_SEND_AOS_TOOLTIP is set. This will correct problems with Item Descriptions in newer Clients, but maybe freeze ancient Clients...
Notes: uo.em constants for this function:
const VENDOR_SEND_AOS_TOOLTIP   := 0x01;
Return values
1 on success
Errors
"A parameter was invalid"
"No client connected to character"
"Parameter 1 invalid"
"Parameter 2 invalid"
"Parameter 3 invalid"
"Too much crap in vendor's inventory!" (message exceeds 2000 byte buffer)
Related
Character
Container



SendCharacterRaceChanger( character )
Parameters:
NameType
characterCharacter Reference
Explanation
Send Client inside Character Race Changer to change Hair, Beard and Color.
Return values
1 on success or Error
Errors
"Invalid parameter"
Related
Character



SendDialogGump( who, layout, textlines, x := 0, y := 0 )
Parameters:
NameType
whoCharacter Reference
layoutString Array
textlinesString Array
x,yInteger-Offset
Explanation
Sends a generic gump window to "who" and waits for the user's input.
Notes: "layout" is an array of strings with each string a gump layout directive. "textlines" is an array of strings with text that is displayed on the gump. "Layout" references this array in a 0-based manner. Creating these arrays is difficult and hard to debug. See the "gumps" package for a more user- friendly interface to gumps.
Return values
the return value is a dictionary. return[0] contains the button ID the user used to close the gump. 0 is returned if the gump was cancelled. return.keys contains the IDs for the radio buttons, checkboxes, and textentries set when the gump was returned. Note control characters are stripped from the text input lines.
Errors
"Invalid parameter"
"No client attached"
"Buffer length exceeded" (64K byte)
Related
Character
Dictionary
Array



SendEvent( npc, event )
Parameters:
NameType
npcCharacter Reference to an NPC
eventinteger
Explanation
Sends the integer event (either a combination of system events, or one user-defined event) to the NPC's control script.
Return values
1 on success
Errors
"Invalid parameter"
"That mobile is not an NPC"
"That NPC doesn't have a control script"
Related
NPC



SendInstaResDialog( character )
Parameters:
NameType
characterCharacter Reference
Explanation
Character's screen fades to black, "You are Dead" appears, Character gets menu choice for Instares.
Notes: (Rac) Could not get menu dialog to appear, "Play as ghost" returned to server no matter what. "AssumePlayAsGhost" in uo.cfg made no difference.
Return values
Integer with choice. 1 = instares, 2 = ghost
Errors
"Invalid parameter type"
"No client attached"
"Client busy with another instares dialog"
Related
Character



SendOpenBook( character, book )
Parameters:
NameType
characterCharacter Reference
bookItem Reference (Book object only)
Explanation
Sends a book gump to the character.
Notes: Need more info on book objects.
Return values
1 on success
Errors
"Invalid parameter type"
"No active client"
"book.GetNumLines() did not return an Integer"
"book.GetContents() must return an array"
"Buffer overflow"
Related
Character
Item
Array



SendOpenSpecialContainer( character, container )
Parameters:
NameType
characterCharacter Reference
containerContainer Reference
Explanation
Sends an open container gump to the character.
Notes: DANGEROUS FUNCTION. Normally only used to show "inaccessable" containers like bankboxes. If used on normal containers, it allows the character to both view and change the contents. See SendViewContainer().
Return values
1 on success
Errors
"Invalid parameter type"
"No client attached"
"That isn't a container"
Related
Character
Container



SendPacket( to_whom, packet_hex_string )
Parameters:
NameType
to_whomCharacter Reference
packet_hex_stringString
Explanation
Sends the hex string to the character as a binary packet.
Notes: Development function, use at your own risk. The string is in a form like: SendPacket(who,"BC0401") would cause the season to change to "desolation"
Return values
1 on success
Errors
"Invalid parameter type"
"No client attached"
Related
Character



SendQuestArrow(to_whom, x := -1, y := -1)
Parameters:
NameType
to_whomCharacter reference the arrow shows to
x,yInteger world coordinates
Explanation
Sends a "quest arrow" to the player that points at x,y
Passing 'x' and 'y' within map bounds will set the Quest Arrow to point at that location.
Passing -1 as 'x' and 'y' (ie. by just called SendQuestArrow(to_whom)) will remove it.
Return values
1 on success
Errors
"No client attached"
"Invalid parameter"
Related
Character



SendSellWindow( character, vendor, i1, i2, i3, flags := 0 )
Parameters:
NameType
characterCharacter Reference
vendorCharacter Reference
i1Container Reference
i2Container Reference
i3Container Reference
flagsInteger
Explanation
Sends a sell scroll gump to "character" using "vendor" as the merchant.
Notes: i1 = vendor's "For sale" item containter. i2 = vendor's "Bought from player" item container. i3 = vendor's "Buyable" item container.
Notes: Core will send Item Description using AoS Tooltips in any case if flag VENDOR_SEND_AOS_TOOLTIP is set. This will correct problems with Item Descriptions in newer Clients, but maybe freeze ancient Clients...
Notes: uo.em constants for this function:
const VENDOR_SEND_AOS_TOOLTIP   := 0x01;
Return values
1 on success
Errors
"A parameter was invalid"
"No client connected to character"
"Parameter 1 invalid" if !(vendor.isa(POLCLASS_NPC))
"Parameter 2 must be a container"
"Character has no backpack"
Related
Character
Container



SendSkillWindow( towhom, forwhom )
Parameters:
NameType
towhomCharacter Reference
forwhomCharacter Reference
Explanation
Sends a skills scroll gump to "towhom"
Notes: The skills belong to "forwhom" and are sent to "towhom"
Return values
1 on success
Errors
"Invalid parameter type"
"No client attached"
Related
Character



SendStatus( character )
Parameters:
NameType
characterCharacter Reference
Explanation
Send full Status Packet to support Extensions like Resistances, if you add'em via Packet Hook. Use SendStatus to update'em.
Return values
1 on success or Error
Errors
"Invalid parameter type"
"No client attached"
"Mobile must not be offline"
Related
Character



SendStringAsTipWindow( character, text )
Parameters:
NameType
characterCharacter Reference
textString
Explanation
Sends "text" to "character" in a tip-window gump.
Text needs to be in "MAC" format: CR at the end of each line.
Return values
1 on success
Errors
"Invalid parameter type"
"No client attached"
Related
Character



SendSysMessage( character, text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )
Parameters:
NameType
characterCharacter Reference
textString
fontInteger (optional)
colorInteger (optional)
Explanation
Displays a System Message in the lower-left corner of character's player's screen.
Notes: see client.inc for suitable values of font and color.
Return values
1 on success
Errors
"Invalid parameter type"
"Mobile has no active client"
Related
Character



SendTextEntryGump( who, line1, cancel := TE_CANCEL_ENABLE, style := TE_STYLE_NORMAL, maximum := 40, line2 := "" )
Parameters:
NameType
whoCharacter Reference
cancelInteger (TE_CANCEL_DISABLE or TE_CANCEL_ENABLE)
styleInteger (TE_STYLE_DISABLE or TE_STYLE_NORMAL or TE_STYLE_NUMERICAL)
maximumInteger
line2String
Explanation
Sends a text-entry gump to "who" with the specified option, style, and informational string.
Notes: uo.em constants for this function:
const TE_CANCEL_DISABLE := 0;
const TE_CANCEL_ENABLE  := 1;
			
const TE_STYLE_DISABLE  := 0;
const TE_STYLE_NORMAL   := 1;
const TE_STYLE_NUMERICAL:= 2;
Return values
A String on success 0 if gump was cancelled.
Errors
"Invalid parameter"
"No client attached"
Related
Character



SendViewContainer( character, container )
Parameters:
NameType
characterCharacter Reference
containerContainer Reference
Explanation
Sends the container's open gump and contents to the character.
Notes: Use this for normal containers.
Return values
1 on success
Errors
"Invalid parameter type"
"No client attached"
"That isn't a container"
Related
Character
Container



SetAttributeBaseValue( character, attrname, basevalue_tenths ); // obsoletes SetRawSkill
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
basevalue_tenthsInteger (0..60000)
Explanation
Sets the "base" value of "attrname" on "character"
Return values
1 on success
Errors
"Invalid parameter type"
Related
Character
Related Configs
attributes.cfg



SetAttributeTemporaryMod( character, attrname, tempmod_tenths ); // obsoletes mob.strength_mod etc
Parameters:
NameType
characterCharacter Reference
attrnameString (attribute name)
tempmod_tenthsInteger (-30000..30000)
Explanation
Sets the "temporary modification" value of "attrname" on "character"
Return values
1 on success
Errors
"Invalid parameter type" including if attrname was not found as an attribute
Related
Character
Related Configs
attributes.cfg



SetGlobalProperty( propertyname, propertyvalue )
Parameters:
NameType
propertynameString
propertyvaluea script object (could be string, int, real, array, etc)
Explanation
Sets the value of a global property. propertyname is case-sensative
Return values
1 on success
Errors
"Invalid parameter type"



SetName( object, name )
Parameters:
NameType
objectUObject Reference
nameString
Explanation
Sets name of item or mobile.
Return values
1 on success
Errors
none (returns 0 on failure)
Related
UObject



SetObjProperty( object, propertyname, propertyvalue )
Parameters:
NameType
objectUObject Reference
propertynameString
propertyvaluea script object (could be string, int, real, array, etc)
Explanation
Sets a custom data property on an object. This data will be saved with the object, for later retrieval with GetObjProperty. propertyname is case-sensative
Return values
1 on success
Errors
"Invalid parameter type"
Related
UObject



SetRegionLightLevel( regionname, lightlevel )
Parameters:
NameType
regionnameString
lightlevelInteger (0..30)
Explanation
Sets the light level of a region by name.
Notes: lightlevel must be a value between 0 and 30 where 0 is daylight and 30 is near-total darkness. regionname must match a region name from REGIONS\LIGHT.CFG.
Return values
1 if the light level was set successfully
Errors
"Invalid Parameter type"
"Light Level is out of range"
"Light region not found"
Related Configs
light.cfg



SetRegionWeatherLevel( region, type, severity, aux := 0, lightoverride := -1)
Parameters:
NameType
regionstring
typeinteger
severityinteger
auxinteger (optional, see above for default values)
lightoverrideinteger (optional, see above for default values)
Explanation
Sets the weather effects for a given weather region.
Notes: Weather values by Tharaxis
type:
    0 - light rain ("It starts to rain")
    1 - rain/thunder ("A fierce storm approaches")
    2 - snow ("It begins to snow")
    3 - brewing storm - ("A storm is brewing")
    255 - None (Turns sound effects off)
			
    severity:is set on a 0-70 scale, 70=torrential rain, 0=light drizzle.		  
    aux: ??? 
    lightoverride: light level amount overrides current level. -1 means no override.
Return values
1 on success
Errors
"Invalid Parameter type"
"Weather region not found" if "region" not found in regions/weather.cfg
Related Configs
weather.cfg



SetScriptController( who )
Parameters:
NameType
whoCharacter Reference
Explanation
Set the "controller" of the current script to "who".
Notes: This is used to know, for instance, who the fire field walk-on script belongs to so that the reputation/criminal system knows who to punish.
pass 0 to clear the script controller.
Return values
Character Reference of the "old" controller of the script.
Errors
none (instead returns 0 on failure)
Related
Character



SetVital( character, vitalname, value )
Parameters:
NameType
characterCharacter Reference
vitalnameString (vital name)
valueInteger (in hundreths)
Explanation
Sets the current value for "vitalname" on "character" in hundreths.
Return values
1 on success
Errors
"Invalid parameter type" including if vitalname was not found as a vital
Related
Character
Related Configs
vitals.cfg



Shutdown()
Explanation
Shuts down the server
Notes: Disconnects all clients and saves the world state.
Return values
1 always



SpeakPowerWords( who, spellid )
Parameters:
NameType
whoCharacter Reference
spellidInteger
Explanation
Forces character "who" to speak the spell power words as defined in spells.cfg.
Notes: spells.cfg files define spells and spell ids.
Return values
1 on success
Errors
"Invalid parameter"
"No such spell"
"Spell ID out of range"
Related
Character
Related Configs
spells.cfg



StartSpellEffect( who, spellid )
Parameters:
NameType
whoCharacter Reference
spellidInteger
Explanation
Starts the spell script as defined in spells.cfg
Notes: spells.cfg files define spells and spell ids.
Return values
1 on success
Errors
"Invalid parameter"
"No such spell"
"Spell ID out of range"
Related
Character
Related Configs
spells.cfg



SubtractAmount( item, amount )
Parameters:
NameType
itemItem Reference
amountInteger
Explanation
Decreases the stack size of an item. If nothing is left, deletes the item.
Return values
1 on success
Errors
"Invalid parameter type"
"That item is being used."
Related
Item



SystemFindObjectBySerial( serial, sysfind_flags := 0 )
Parameters:
NameType
serialInteger
sysfind_flagsInteger (optional, default 0)
Explanation
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.
Notes: uo.em constants for flags:
const SYSFIND_SEARCH_OFFLINE_MOBILES := 1;
const SYSFIND_SEARCH_STORAGE_AREAS   := 2;
Return values
A Character Reference, Item Reference, or Multi reference on success.
Errors
"Invalid parameter type"
"Character not found"
"Item not found."



Target( by_character, options := TGTOPT_CHECK_LOS+TGTOPT_NEUTRAL)
Parameters:
NameType
by_characterCharacter Reference
optionsInteger (Optional)
Explanation
Sends a target cursor to "by_character"'s client, and waits for the player to target something.
Notes: Options control Line-of-sight checking.
0 is returned if the character does not have line-of-sight to the object.
uo.em constants for options, just add together non-mutually exclusive options.
const TGTOPT_CHECK_LOS   := 0x0001;
const TGTOPT_NOCHECK_LOS := 0x0000;	// to be explicit
const TGTOPT_HARMFUL     := 0x0002;
const TGTOPT_NEUTRAL     := 0x0000;	// to be explicit
const TGTOPT_HELPFUL     := 0x0004;
The first 2 options specify if Line-of-sight to the targetting obejct should be checked or not. The last 3 options are involved with the reputation system. Use TGTOPT_HARMFUL if the effect that uses the target is a hostile action (like casting fireball), use _HELPFUL for things like healing and use _NEUTRAL for reputation-neutral actions.
Return values
0 if user cancelled, or nothing targetted, or no LOS to target (if option is selected)
UObject Reference on success (item or character or multi)
Errors
"Invalid parameter type"
"No client connected"
"Client busy with another target cursor"
Related
UObject
Character



TargetCoordinates( Character )
Parameters:
NameType
CharacterCharacter Reference
Explanation
Sends a target cursor to a character's client, and waits for the player to target a ground tile.
Notes: Line-of-sight is not checked.
Return values
A Structure on success: members: structure.x,structure.y,structure.z - containing the location targetted. structure.objtype - containing the objtype of the static object targetted. Not always present members: structure.item contains an Item Reference to a dynamic item targetted. structure.mobile contains a Character Reference to a mobile targetted.
0 if the target cursor was cancelled or the client disconnected.
Errors
"Invalid parameter type"
"Mobile has no active client"
"Client has an active target cursor"
Related
Character



TargetMultiPlacement( character, objtype, flags := 0, xoffset := 0, yoffset := 0 )
Parameters:
NameType
characterCharacter Reference
objtypeInteger
flagsInteger (optional)
xoffset,yoffsetInteger offset to 'ghost' target house
Explanation
Sends character a "ghost" multi to select placement location in the world.
Notes: objtype must be from an itemdesc.cfg entry with a Boat or House type.
boats only constants for flags:
const CRMULTI_FACING_NORTH      := 0x0000;  
const CRMULTI_FACING_EAST       := 0x0100;
const CRMULTI_FACING_SOUTH      := 0x0200;
const CRMULTI_FACING_WEST       := 0x0300;
For House target placement, flags should == 0.
NOTE: the coordinates returned by this are the coordinates of the "target" cursor, not the center of the house if you use x/yoffset! So if you want to have the front steps be under the cursor, you must transform the parameters to CreateMultiAtLocation to include your xoffset and yoffset. Positive offsets move the cursor left/down in relation to the ghost house. An example using the front steps to target:
    var dims := GetMultiDimensions( 0x6071 );
    if(!dims) return; endif
    var loc := TargetMultiPlacement( who, 0x6071, 0, 0, dims.ymax );
    if(!loc) return; endif
    var house := CreateMultiAtLocation( loc.x, loc.y - dims.ymax, loc.z, 0x6071, 0, who.realm );
Return values
A Structure (x,y,z) containing the location targetted on success
Errors
"Invalid parameter type"
"No client attached"
"Client busy with another target cursor"
"Object Type is out of range for Multis"
Related
House
Boat
Character



UseItem( item, character )
Parameters:
NameType
itemItem Reference
characterCharacter Reference
Explanation
This will allow the item specified's use script to be run by the character specified. No checks are done for distance, or check for being a ghost, or anything else.
Warning: This function can also be called with NPC's as the character, but any use script that requires interactivity with it's user that is called on an NPC may have unpredictable results(dependant on the script).
Return values
1 on success, 0 or Error
Errors
"Invalid parameter"
"Character busy."
"Failed to start script!"
Related
Item
Character
NPC




If you know if any information is incorrect on these pages, mail your corrections to shinigami@gmx.net

Copyright ©2003-2011 David Carpman and Shinigami, all rights reserved. DO NOT REPRODUCE, MIRROR, ALTER, SPINDLE, MUTILATE, OR SIT ON.