Welcome to PenUltima Online. Click to login or register.

File: UO.em

Description: Functions that interact with and alter UO game world data, including server-client messages.
Last Modified: 10/27/2007

File Constants:

// CreateMulti flags
// only for house creation:
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;
// only for boat creation:
const CRMULTI_FACING_NORTH := 0x0000;
const CRMULTI_FACING_EAST := 0x0100;
const CRMULTI_FACING_SOUTH := 0x0200;
const CRMULTI_FACING_WEST := 0x0300;

// ListHostiles exclusions
const LH_FLAG_LOS := 1; // only include those in LOS
const LH_FLAG_INCLUDE_HIDDEN := 2; // include hidden characters

// FindPath flags
const FP_IGNORE_MOBILES := 0x01; // ignore Mobiles
const FP_IGNORE_DOORS := 0x02; // ignore Doors (you've to open doors by yourself)

// Send*Window flags
const VENDOR_SEND_AOS_TOOLTIP := 0x01; // send Item Description using AoS Tooltips

// RegisterForSpeechEvents flags
const LISTENPT_HEAR_GHOSTS := 0x01; // hear ghost speech in addition to living speech

// List[Statics/Items]* 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

// ListMobilesNearLocationEx exclusions
const LISTEX_FLAG_NORMAL := 0x01;
const LISTEX_FLAG_HIDDEN := 0x02;
const LISTEX_FLAG_GHOST := 0x04;
const LISTEX_FLAG_CONCEALED := 0x08;

// ListItemsNearLocationWithFlag( x,y,z, range, flags ); tiledata flags
// Thanks to Alazane: http://dkbush.cablenet-va.com/alazane/file_formats.html#3.17
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_IMPASSABLE := 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_FOLIAGE := 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

// GetStandingLayers( x, y, flags, realm := _DEFAULT_REALM ); 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

// Constants for MoveObjectToLocation
const MOVEOBJECT_NORMAL := 0x0;
const MOVEOBJECT_FORCELOCATION := 0x40000000;

// Resurrect options
const RESURRECT_FORCELOCATION := 0x01;

// MoveType constants for CanInsert/OnInsert/CanRemove/OnRemove scripts

const MOVETYPE_PLAYER := 0; // Moved by the player
const MOVETYPE_COREMOVE := 1; // Moved with MoveItem*() (or equiv)
const MOVETYPE_CORECREATE := 2; // Created with CreateItemIn*() (or equiv)

// InsertType constants for CanInsert/OnInsert scripts
const INSERT_ADD_ITEM := 1;
const INSERT_INCREASE_STACK := 2;

// DeleteBy constants for CanDelete script
const DELETE_BY_PLAYER := 0;
const DELETE_BY_SCRIPT := 1;

// EnumerateItemsInContainer constants
const ENUMERATE_IGNORE_LOCKED := 0x1; // List content of locked container.
const ENUMERATE_ROOT_ONLY := 0x2; // Do not list contents of sub-containers.

// SendTextEntryGump options
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;

// SystemFindObjectBySerial options:
const SYSFIND_SEARCH_OFFLINE_MOBILES := 1;
const SYSFIND_SEARCH_STORAGE_AREAS := 2;

// Target Options - add these together and pass as second
// param to Target()
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;

// POLCLASS_* constants - use with obj.isa(POLCLASS_*)
const POLCLASS_UOBJECT := 1;
const POLCLASS_ITEM := 2;
const POLCLASS_MOBILE := 3;
const POLCLASS_NPC := 4;
const POLCLASS_LOCKABLE := 5;
const POLCLASS_CONTAINER := 6;
const POLCLASS_CORPSE := 7;
const POLCLASS_DOOR := 8;
const POLCLASS_SPELLBOOK := 9;
const POLCLASS_MAP := 10;
const POLCLASS_MULTI := 11;
const POLCLASS_BOAT := 12;
const POLCLASS_HOUSE := 13;
const POLCLASS_EQUIPMENT := 14;
const POLCLASS_ARMOR := 15;
const POLCLASS_WEAPON := 16;

// mobile.race constants
const RACE_HUMAN := 0;
const RACE_ELF := 1;

// Don't use these outside this file, use FONT_* from client.inc
// (and I don't know what for color)
const _DEFAULT_TEXT_FONT := 3;
const _DEFAULT_TEXT_COLOR := 1000;

// Realms
const _DEFAULT_REALM := "britannia";
const REALM_BRITANNIA := _DEFAULT_REALM;
const REALM_ILSHENAR := "ilshenar";
const REALM_MALAS := "malas";
const REALM_TOKUNO := "tokuno";

Functions:

Accessible( Character, item )
Parameters:
Name Type
Character Character Reference
item Item 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:
Name Type
item_ref Item reference
amount An 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, color=:0 )
Parameters:
Name Type
menu Dynamic Menu Reference (from CreateMenu())
objtype Integer tile graphic to add to menu
text String description
color Integer
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. Color defaults to 0 if no itemdesc.cfg entry exists. Hint: menus.cfg uses the color of the itemdesc entry of the objtype given.
0 for objtype creates a checkbox-style menu
Return values
1 if the item was added successfully
Errors
none (returns 0 on invalid parameters)
ApplyConstraint( objlist, configfile, propertyname, minvalue )
Parameters:
Name Type
objlist array of objtype numbers
configfile config file reference
propertyname string
minvalue integer
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
AssignRectToWeatherRegion( region, xwest, ynorth, xeast, ysouth )
Parameters:
Name Type
region string
xwest integer
ynorth integer
xeast integer
ysouth integer
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:
Name Type
character Character 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
Broadcast( text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )
Parameters:
Name Type
text String
font Integer (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)
CancelTarget( of_whom )
Parameters:
Name Type
of_whom Character Reference
Explanation
If the character has a current Target Reference, it sends the cancel packet. Client response to the original target cursor's script is as if they hit Escape.
Return values
0
Errors
"Invalid parameter type"
"No client connected"
"Client does not have an active target cursor"
Related
Character
CheckLineOfSight( object1, object2 )
Parameters:
Name Type
object1 UObject Reference
object2 UObject 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:
Name Type
character Character Reference
x,y,z Integer 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
CloseTradeWindow( character )
Parameters:
Name Type
character Character Reference
Explanation
Attempts to close the Trade Window a client has open.
Return values
1
Errors
"Invalid parameter type"
"Mobile is not currently trading with anyone."
Related
Character
ConsumeReagents( caster, spellid )
Parameters:
Name Type
caster Character Reference
spellid An 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:
Name Type
container Container reference
objtype Integer objtype to find and consume
amount An 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
CoordinateDistance(x1, y1, x2, y2)
Parameters:
Name Type
x1,y1 Integer world coordinates
x2,y2 Integer 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:
Name Type
acctname string
password string
enabled integer (0 or 1)
Explanation
Creates a new player account with the specified account name, password.
Notes: If enabled == 0, player cannot log in.
Only accepts Alphanumeric characters for account name.
Passwords cannot contain whitespace or control characters.
Return values
Account Reference for the new account on success
Errors
"Account already exists"
"Invalid parameter type"
"Attempted to create account with non-alphanumeric characters."
"Attempted to use password in account creation with non-allowed characters."
Related
Account
CreateItemAtLocation( x, y, z, objtype, amount := 1, realm := _DEFAULT_REALM )
Parameters:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
objtype Integer objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amount Integer (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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
item Item 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:
Name Type
of_character Character Reference
objtype Integer objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amount Integer (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:
Name Type
container Container Reference
objtype Integer objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amount Integer (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:
Name Type
container Container reference
objtype Integer objtype for item to be created, OR String ObjtypeName, OR GetItemDescriptor struct.
amount size 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:
Name Type
title String
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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
objtype Integer objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
flags Integer (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:
Name Type
template String
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
override_properties A 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
DestroyItem( Item )
Parameters:
Name Type
Item Item 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:
Name Type
multi Multi 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
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:
Name Type
eventtype integer 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:
Name Type
character Character 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:
Name Type
object1 UObject Reference
object2 UObject 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:
Name Type
events Integer
range Integer (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:
Name Type
container Container Reference
flags Integer
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:
Name Type
character Character Reference
template String
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:
Name Type
mobile Character Reference
item Item 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:
Name Type
propertyname String
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:
Name Type
object UObject Reference
propertyname String
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:
Name Type
acctname string
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
FindObjtypeInContainer( container, objtype )
Parameters:
Name Type
container Container reference
objtype integer 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:
Name Type
x1,y1,z1 Integer world coordinates - start of the path
x2,y2,z2 Integer world coordinates - destination
realm String - case-sensitive name of the realm
flags Integer
searchskirt Integer
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
FindSubstance( container, objtype, amount, makeinuse := 0 )
Parameters:
Name Type
container Container reference
objtype Integer objtype to find
amount Integer
makeinuse Integer (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:
Name Type
item Item 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
GetCommandHelp( character, command )
Parameters:
Name Type
character Character Reference
command string
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:
Name Type
x1,y1 Integer world coordinates
x2,y2 Integer 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:
Name Type
Character Character reference
layer An 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:
Name Type
from_x,from_y Integer world coordinates
to_x,to_y Integer 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:
Name Type
propertyname String
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:
Name Type
resource String
x,y Integer world coordinates
realm String - case-sensitive name of the realm
tiletype Integer
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:
Name Type
x,y Integer world coordinates
realm String - 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:
Name Type
menuname static 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:
Name Type
graphic Multi 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:
Name Type
object UObject Reference
propertyname String
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
"Invalid parameter type"
"Property not found"
Related
UObject
GetObjPropertyNames( object )
Parameters:
Name Type
object UObject 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
GetObjType( object )
Parameters:
Name Type
object UObject Reference
Explanation
Returns the Objtype of an object. Same as ref.objtype. Works for item root classed and character root classed.
Return values
Integer ObjType or 0
Related
Character
Item
Related Configs
itemdesc.cfg
GetObjtypeByName( name )
Parameters:
Name Type
name string
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:
Name Type
object top 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:
Name Type
x x location
y y location
realm String - 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:
Name Type
resource string
x,y Integer world coordinates
realm String - case-sensitive name of the realm
propertyname string
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:
Name Type
spellid Integer
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:
Name Type
x,y Integer world coordinates
realm String - case-sensitive name of the realm
startx Integer
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:
Name Type
x,y Integer world coordinates
realm String - case-sensitive name of the realm
flags Integer
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
GetWorldHeight( x, y, realm := _DEFAULT_REALM )
Parameters:
Name Type
x,y Integer world coordinates
realm String - 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:
Name Type
character Character Reference
privilege String
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:
Name Type
resource String
x,y Integer world coordinates
realm String - case-sensitive name of the realm
b Integer
n Integer
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
IsStackable( item1, item2 )
Parameters:
Name Type
item1 Item 1
item2 Item 2
Explanation
Compares 2 items to determine if they can be stacked together.
Return values
1 if the 2 items can be stacked, 0 if not or Error
Errors
"Invalid parameter"
Related
Item
ListAccounts()
Explanation
Gets a list of all account names.
Return values
Array of Strings of account names.
Related
Array
Account
ListEquippedItems( who )
Parameters:
Name Type
who Character 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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
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
ListHostiles( character, range := 20, flags := 0 )
Parameters:
Name Type
character Character Reference
range integer (optional, default=20)
flags integer (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:
Name Type
x,y,z Integer world coordinates
realm String - 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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
objtype Integer
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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
flags Integer
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:
Name Type
object UObject Reference
range Integer
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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
flags Integer
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:
Name Type
x1,y1,z1 integer, for north west upper corner of box
x2,y2,z2 integer, for south east lower corner of box
realm String - 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:
Name Type
x1,y1,z1 integer, for north west upper corner of box
x2,y2,z2 integer, for south east lower corner of box
realm String - 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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
flags Integer
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:
Name Type
x1,y1,z1 integer, for north west upper corner of box
x2,y2,z2 integer, for south east lower corner of box
realm String - case-sensitive name of the realm
flags Integer
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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
flags Integer
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
MoveItemToContainer( item, container, x := -1, y := -1 )
Parameters:
Name Type
item Item Reference
container Container Reference
x,y Integer 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
MoveItemToSecureTradeWin( item, character )
Parameters:
Name Type
item Item Reference
character Character 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:
Name Type
object Object Reference
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
flags Integer
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."
Can't move multis at this time.
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
OpenPaperdoll( towhom, forwhom )
Parameters:
Name Type
towhom Character Reference
forwhom Character 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:
Name Type
character Character Reference
action Integer
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:
Name Type
center_object UObject 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:
Name Type
source UObject Reference
target UObject Reference
effect Integer
speed Integer (0..255)
loop Integer (Optional, 0..255)
explode Integer (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:
Name Type
srcx,srcy,srcz Integer Source world coordinates
dstx,dsty,dstz Integer Destination world coordinates
realm String - case-sensitive name of the realm
effect integer
speed integer (to 255)
loop integer (to 255)
explode integer (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:
Name Type
uobject UObject Reference
effect Integer
speed Integer (0..255)
loop Integer (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:
Name Type
object UObject Reference
effect Integer
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:
Name Type
object UObject Reference
effect Integer
playfor Character 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:
Name Type
x,y,z Integer world coordinates
realm String - case-sensitive name of the realm
effect integer
speed integer (to 255)
loop integer (to 255)
explode integer (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:
Name Type
above_object UObject Reference
text String
font Integer (optional)
color Integer (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:
Name Type
above_object UObject Reference
text String
character Character Reference
font Integer (optional)
color Integer (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
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
RegisterForSpeechEvents( at_object, range, flags := 0 )
Parameters:
Name Type
at_object UObject Reference
range Integer
flags Integer (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:
Name Type
item Item 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:
Name Type
character Character Reference
item Item Reference
prompt String
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:
Name Type
item Item 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 Item has been reserved by me. 2 Item was already reserved by me. Or Error
Errors
"That item is already being used."
"Invalid parameter"
Related
Item
RestartScript( npc )
Parameters:
Name Type
npc Character 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:
Name Type
ghost Character Reference
flags integer 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:
Name Type
character Character Reference
privilage String
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:
Name Type
character Character Reference
character2 Character 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:
Name Type
character Character Reference
item Item 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:
Name Type
character Character Reference
menuname String 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:
Name Type
character Character Reference to player
container Container Reference ( vendor 'for sale items' container )
vendor Character Reference to NPC vendor
item Container Reference (vendor 'player bought items' container)
flags Integer
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:
Name Type
character Character 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:
Name Type
who Character Reference
layout String Array
textlines String Array
x,y Integer-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:
Name Type
npc Character Reference to an NPC
event integer
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"
"Event queue is full, discarding event"
Related
NPC
SendInstaResDialog( character )
Parameters:
Name Type
character Character 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:
Name Type
character Character Reference
book Item 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:
Name Type
character Character Reference
container Container 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:
Name Type
to_whom Character Reference
packet_hex_string String
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:
Name Type
to_whom Character reference the arrow shows to
x,y Integer 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:
Name Type
character Character Reference
vendor Character Reference
i1 Container Reference
i2 Container Reference
i3 Container Reference
flags Integer
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:
Name Type
towhom Character Reference
forwhom Character 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:
Name Type
character Character 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:
Name Type
character Character Reference
text String
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:
Name Type
character Character Reference
text String
font Integer (optional)
color Integer (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:
Name Type
who Character Reference
cancel Integer (TE_CANCEL_DISABLE or TE_CANCEL_ENABLE)
style Integer (TE_STYLE_DISABLE or TE_STYLE_NORMAL or TE_STYLE_NUMERICAL)
maximum Integer
line2 String
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:
Name Type
character Character Reference
container Container 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
SetGlobalProperty( propertyname, propertyvalue )
Parameters:
Name Type
propertyname String
propertyvalue a 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:
Name Type
object UObject Reference
name String
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:
Name Type
object UObject Reference
propertyname String
propertyvalue a 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:
Name Type
regionname String
lightlevel Integer (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:
Name Type
region string
type integer
severity integer
aux integer (optional, see above for default values)
lightoverride integer (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:
Name Type
who Character 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
Shutdown()
Explanation
Shuts down the server
Notes: Disconnects all clients and saves the world state.
Return values
1 always
SpeakPowerWords( who, spellid )
Parameters:
Name Type
who Character Reference
spellid Integer
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:
Name Type
who Character Reference
spellid Integer
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:
Name Type
item Item Reference
amount Integer
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:
Name Type
serial Integer
sysfind_flags Integer (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:
Name Type
by_character Character Reference
options Integer (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:
Name Type
Character Character 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,structure.realm - 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
"Client has an active target cursor"
"Mobile has no active client"
"Invalid parameter type"
Related
Character
TargetMultiPlacement( character, objtype, flags := 0, xoffset := 0, yoffset := 0 )
Parameters:
Name Type
character Character Reference
objtype Integer
flags Integer (optional)
xoffset,yoffset Integer 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:
Name Type
item Item Reference
character Character 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