Documentation › Modules › UO.em

File: UO.em

Functions that interact with and alter UO game world data, including server-client messages.

Last modified: 09/20/2026

Functions

Modules

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
const VENDOR_BUYABLE_CONTAINER_FILTER := 0x02; // filter items in the SendSellWindow() by what is in the buyable container
 
const SENDDIALOGMENU_FORCE_OLD  := 0x01;    // send UnCompressed Gump
 
// RegisterForSpeechEvents flags
const LISTENPT_HEAR_GHOSTS      := 0x01;    // hear ghost speech in addition to living speech
const LISTENPT_HEAR_TOKENS      := 0x02;    // hear also speechtokens (only with ssopt.SeperateSpeechTokens)
const LISTENPT_NO_SPEECH        := 0x04;    // hear no normal speech (only with ssopt.SeperateSpeechTokens)
 
// 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;
const LISTEX_FLAG_PLAYERS_ONLY := 0x10;
const LISTEX_FLAG_NPC_ONLY := 0x20;
 
// 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_HOVEROVER   := 0x02000000; //HoverOver (gargoyle flying tiles)
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 (gargoyle flying)
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;        // Implicit.  Will move if able.
const MOVEITEM_IGNOREMOVABLE   := 0x20000000; // Will ignore the movable property on items.
const MOVEOBJECT_FORCELOCATION := 0x40000000; // Force Z location
 
// Constants for PrintTextAbove*
const JOURNAL_PRINT_NAME    := 0x00;  // Implicit.  Print's the object's description / npc's name in the journal.
const JOURNAL_PRINT_YOU_SEE := 0x01;  // Will print "You see:" in the journal.
 
// 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.
 
// FindSubstance constants
const FINDSUBSTANCE_IGNORE_LOCKED := 0x1; // Find matches in locked containers
const FINDSUBSTANCE_ROOT_ONLY     := 0x2; // Do not find matches in sub-containers.
const FINDSUBSTANCE_FIND_ALL      := 0x4; // Find all matches ignoring given amount
 
// FindObjtypeInContainer constants
const FINDOBJTYPE_RECURSIVE     := 0x0; // Search in sub-containers (DEFAULT).
const FINDOBJTYPE_IGNORE_LOCKED := 0x1; // Find matches in locked containers.
const FINDOBJTYPE_ROOT_ONLY     := 0x2; // Do not find matches in 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;
 
//  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;
const TGTOPT_ALLOW_NONLOCAL := 0x0008;
 
// 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;
const RACE_GARGOYLE := 2;
 
// 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    := 946;
const _DEFAULT_TEXT_REQUIREDCMD    := 0;
 
// Realms
const _DEFAULT_REALM  := "britannia";
const REALM_BRITANNIA := _DEFAULT_REALM;
const REALM_BRITANNIA_ALT	:= "britannia_alt";
const REALM_ILSHENAR  := "ilshenar";
const REALM_MALAS     := "malas";
const REALM_TOKUNO    := "tokuno";
const REALM_TERMUR    := "termur";
 
//PerformAction
const ACTION_DIR_FORWARD  := 0;
const ACTION_DIR_BACKWARD := 1;
const ACTION_NOREPEAT     := 0;
const ACTION_REPEAT       := 1;
// Masks for EnableEvents()
const EVMASK_ALL      := 0;
const EVMASK_ONLY_PC  := 1;
const EVMASK_ONLY_NPC := 2;
//CanWalk
const CANWALK_DIR := -1;
//UpdateMobile
const UPDATEMOBILE_RECREATE := 1;
const UPDATEMOBILE_UPDATE   := 0;
//CloseWindow
const CLOSE_PAPERDOLL := 1;
const CLOSE_STATUS    := 2;
const CLOSE_PROFILE   := 8;
const CLOSE_CONTAINER := 12;
//SendCharProfile
const CHARPROFILE_NO_UNEDITABLE_TEXT := array;
const CHARPROFILE_NO_EDITABLE_TEXT := array;
//Accessible
const ACCESSIBLE_DEFAULT := -1; // uses the default from ssopt
const ACCESSIBLE_IGNOREDISTANCE := -2; // ignores the range check

Accessible( by_character, item, range := ACCESSIBLE_DEFAULT )#

Parameters

by_character Character Reference
item Item Reference
range Integer

Explanation

Function: Determines if an item falls into one of the following categories for a character:
An item on the ground, within "range" squares (defaults to "DefaultAccessibleRange" from servspecopt). Use ACCESSIBLE_IGNOREDISTANCE to avoid this check.
An item equipped by the character
An item inside the character's backpack
A temporarily accessible item: one inside a container the character was shown with SendOpenSpecialContainer(), a bank box for instance. Such a container stands nowhere, so no distance is measured against it - having been shown it is what puts its contents in reach, and that ends as soon as the character moves.
Note 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

AddAmount( item, amount )#

Parameters

item 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

ItemRef on success or error on failure

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

AddMenuItem( menu, objtype, text, color:=0 )#

Parameters

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.
Note 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

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.
Note 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

AssignRectToWeatherRegion( region, xwest, ynorth, xeast, ysouth, realm := _DEFAULT_REALM )#

Parameters

region string. An empty string puts the rect back to the region that covered it when the shard loaded
xwest integer
ynorth integer
xeast integer
ysouth integer
realm String - case-sensitive name of the realm

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 config

Attach( character )#

Parameters

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

Broadcast( text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR, required_cmdlevel := _DEFAULT_TEXT_REQUIREDCMD )#

Parameters

text String
font Integer (optional)
color Integer (optional)
required_cmdlevel Integer (optional)

Explanation

Sends text as a System Message to every online player whos cmd level is above required_cmdlevel.
See client.inc for font and color values.

Return values

1 on success

Errors

  • none (returns 0 on invalid parameter)

CanWalk(movemode, x1, y1, z1, x2_or_dir, y2 := CANWALK_DIR, realm := _DEFAULT_REALM )#

Parameters

movemode String
x1 Integer world coordinates
y1 Integer world coordinates
z1 Integer world coordinates
x2_or_dir Integer world coordinates
y2 Integer world coordinates
realm String - case-sensitive name of the realm

Explanation

Checks if a mobile can walk with given movemode into given direction and returns the new z value or error.
Note if y2 is CANWALK_DIR x2 is considered as direction. if x2 and y2 is given it calculates the needed direction
uo.em constants:
const CANWALK_DIR := -1;

Return values

new z value on success

Errors

  • "Invalid Parameters"
  • "Realm not found."
  • "Invalid coordinates for realm."
  • "Cannot walk there"

Related

CancelTarget( of_whom )#

Parameters

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

CheckLineOfSight( object1, object2 )#

Parameters

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

CheckLosAt( character, x, y, z )#

Parameters

character Character Reference
x Integer world coordinates
y Integer world coordinates
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

  • (returns 0 on invalid parameter)
  • "Invalid Coordinates for realm"

Related

CheckLosBetween( x1, y1, z1, x2, y2, z2, realm := _DEFAULT_REALM )#

Parameters

x1 Integer world coordinates for coordinate 1
y1 Integer world coordinates for coordinate 1
z1 Integer world coordinates for coordinate 1
x2 Integer world coordinates for coordinate 2
y2 Integer world coordinates for coordinate 2
z2 Integer world coordinates for coordinate 2
realm String - case-sensitive name of the realm

Explanation

Tests if coordinate 1 has Line-of-sight to coordinate 2

Return values

1 if coordinate 1 has line-of-sight to coordinate 2
0 if coordinate 1 does not have line-of-sight to coordinate 2

Errors

  • (returns 0 on invalid parameter)
  • "Invalid Coordinates for realm"
  • "Realm not found"

Related

CloseGump( character_or_array, gumpid, response := 0 )#

Parameters

character_or_array Character or Array of Characters
gumpid Integer
response UObject - what is going to be returned to the gump script

Explanation

If the gump was sent using a custom gumpid, then the same gumpid must be used here. If the gump was sent without specifying a gumpid, then use the sender script's pid.
Closes the gump, returning 'response' to the script that called SendDialogGump(), or SYSEVENT_GUMP_RESPONSE with 'response' to the script that called DisplayDialogGump.

Return values

1 on success

Errors

  • "Invalid Parameters"
  • "No client attached"
  • "Couldnt find script"

CloseTradeWindow( character )#

Parameters

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

CloseWindow( character, type, object )#

Parameters

character Character
type Integer
object UObject Reference

Explanation

if ( type == CLOSE_CONTAINER ) object has to be a ContainerRef, to close the open container gump. else object has to be a MobRef to close paperdoll, status or profile of the chosen mob.
uo.em constants for type:
const CLOSE_PAPERDOLL := 1;
const CLOSE_STATUS    := 2;
const CLOSE_PROFILE   := 8;
const CLOSE_CONTAINER := 12;

Return values

1 on success

Errors

  • "Invalid Parameters"
  • "No client attached"
  • "Invalid object, has to be a containerRef"
  • "Invalid object, has to be a mobRef"
  • "Invalid type"

Related

ConsumeReagents( who, spellid )#

Parameters

who 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

Related config

ConsumeSubstance( container, objtype, amount )#

Parameters

container Container reference
objtype Integer objtype to find and consume
amount An integer

Explanation

Subtracts "amount" of type "objtype", 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

CoordinateDistance(x1, y1, x2, y2 )#

Parameters

x1 Integer world coordinates
y1 Integer world coordinates
x2 Integer world coordinates
y2 Integer world coordinates

Explanation

Calculates the distance between two coordinates.

Return values

The distance between two coordinates.

Errors

  • "Invalid parameter type"

Related

CoordinateDistanceEuclidean(x1, y1, x2, y2 )#

Parameters

x1 Integer world coordinates
y1 Integer world coordinates
x2 Integer world coordinates
y2 Integer world coordinates

Explanation

Calculates the distance between two coordinates.
Note This distance is defined as sqrt(pow(x1-x2,2)+pow(y1-y2,2))

Return values

Double - calculated distance on success

Errors

  • "Invalid parameter type"

Related

CreateAccount( acctname, password, enabled )#

Parameters

acctname string
password string
enabled integer (0 or 1)

Explanation

Creates a new player account with the specified account name, password.
Note If enabled == 0, player cannot log in.
Only accepts Alphanumeric characters for account name. Control characters, '{' '}', and spaces not allowed.
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

CreateItemAtLocation( x, y, z, objtype, amount := 1, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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

Related config

CreateItemCopyAtLocation(x, y, z, item, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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

Related config

CreateItemInBackpack( of_character, objtype, amount := 1, x := -1, y := -1 )#

Parameters

of_character Character Reference
objtype Integer objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amount Integer (optional, 0..60000)
x Integer coords inside container gump (optional)
y Integer coords inside container gump (optional)

Explanation

Creates an item in a character's backpack.
Note 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

Related config

CreateItemInContainer( container, objtype, amount := 1, x := -1, y := -1 )#

Parameters

container Container Reference
objtype Integer objtype, OR String ObjtypeName, OR GetItemDescriptor struct.
amount Integer (optional, 0..60000)
x Integer coords inside container gump (optional)
y Integer coords inside container gump (optional)

Explanation

Creates an item in a container.
Note 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

Related config

CreateItemInInventory( container, objtype, amount := 1, x := -1, y := -1 )#

Parameters

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
x Integer coords inside container gump (optional)
y Integer coords inside container gump (optional)

Explanation

Creates a stack of items in the specified container. As usual, objtype must be valid and amount must be 1..60000. FORCES STACKING: If the specified obytpe is not stackable by default (i.e. most weapons), this function WILL CREATE A STACK! This will cause a client crash if container is a player's pack! Therefore, this function SHOULD ONLY BE USED WITH NPC MERCHANTS' STORAGE AREA INVENTORIES! For normal containers, use CreateItemInContainer().
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

Related config

CreateMenu( title )#

Parameters

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

x Integer world coordinates
y Integer world coordinates
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.
Note 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 (or the ControlScript specified in the boat's item descriptor) 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

CreateNpcFromTemplate( template, x, y, z, override_properties := 0, realm := _DEFAULT_REALM )#

Parameters

template String
x Integer world coordinates
y Integer world coordinates
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)
forcelocation Integer (0/1)

Explanation

Creates an NPC from a template (found in NPCDESC.CFG).
Note override_properties: a structure containing members to override values in the NPC template. This can be used to override built-in properties (facing, color, gender etc) and custom properties ("CProps" = dictionary {key=cpropname value=cpropvalue})
forcelocation: if true, the NPC will be created even in an invalid location.

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

Related config

DestroyItem( Item )#

Parameters

Explanation

Removes an item from the world. Transmits commands to each client in range of item to reflect this.
Note 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."
  • "That item is a multi. Use uo::DestroyMulti instead."
  • "Invalid parameter type"

Related

DestroyMulti( multi )#

Parameters

Explanation

Deletes a Multi item from the world.
Note 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

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

DisableEvents( eventtype )#

Parameters

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

Explanation

Disconnects the character's client.
Note Fun!

Return values

1 on success

Errors

  • "Invalid parameter"
  • "No client is attached"

Related

DisplayDialogGump( chr_or_array, layout, textlines, x := 0, y := 0, flags := 0, gumpid := 0 )#

Parameters

chr_or_array Character Reference or Array of Character References
layout String Array
textlines String Array
x Integer-Offset
y Integer-Offset
flags Integer
gumpid Integer, 0 to 0xFFFFFF

Explanation

Non-blocking version of SendDialogGump, instead of blocking the script to return the player response it sends SYSEVENT_GUMP_RESPONSE event instead.
Check documentation of uo::SendDialogGump return value for an explanation of the response member of the event.
Sends a generic gump window to a given char or to all given chars in array.
If no gumpid is given, the script's pid will be sent as gumpid.
Note "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.
Based on clientversion core will send compressed or uncompressed version
Note uo.em constants for this function:
const SENDDIALOGMENU_FORCE_OLD  := 0x01;

Return values

1 on sucess or error

Errors

  • "Invalid parameter"
  • "No client attached"
  • "Buffer length exceeded" (64K byte)
  • "GumpID out of range"

Distance( obj1, obj2 )#

Parameters

Explanation

Determines the distance between two objects. If either object is in a container, uses the world-position of its ultimate-parent container.
Note 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)
Note Two objects with nothing to measure between them are 65535 apart - different realms, or one of them standing nowhere at all, such as in a storage area. Objects sharing a holder are 0 apart, and an item on a cursor is measured from the character holding it.
Note The contents of a container shown with SendOpenSpecialContainer(), a bank box for instance, are 0 away from that character until they move, as Accessible() also reports. A container standing in the world is measured normally.

Return values

Integer - calculated distance on success

Errors

  • "Invalid parameter type"

Related

DistanceEuclidean( obj1, obj2 )#

Parameters

Explanation

Determines the distance between two objects. If either object is in a container, uses the world-position of its ultimate-parent container.
Note This distance is the straight line between the two positions, so it agrees with Distance() only along the axes.
Note The special cases are the same as Distance().

Return values

Double - calculated distance on success

Errors

  • "Invalid parameter type"

Related

EnableEvents( eventtype, range := -1, evmask := EVMASK_ALL )#

Parameters

eventtype Integer
range Integer (optional, 0..32)
evmask Integer

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.
Note 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)
Evmask is used to receive entered/leftarea caused only by PCs, NPCs, or both (the default)

Return values

Integer new event "mask" on success

Errors

  • "Invalid parameter"

EnumerateItemsInContainer( container, flags := 0 )#

Parameters

container Container Reference
flags Integer

Explanation

Returns an array of the contents of a container.
Note If 'container' is itself locked, its contents will still be enumerated.
Note uo.em constant for this function:
const ENUMERATE_IGNORE_LOCKED := 0x1; // List content of locked container
const ENUMERATE_ROOT_ONLY     := 0x2; // Do not list contents of sub-containers.

Return values

An Array of Item References on success

Errors

  • "Invalid parameter type"
  • none (returns 0 on different errors)

Related

EnumerateOnlineCharacters()#

Explanation

Gets a list of all online player characters.

Return values

An Array of Character References on success

Errors

  • none

Related

EquipFromTemplate( character, template )#

Parameters

character Character Reference
template String

Explanation

Creates equipment for a character, using EQUIP.CFG.
Note Element properties in EQUIP.CFG have the format Equip [item name or objtype] [colors] with 'Armor' and 'Weapon' meaning the same as 'Equip'. Objtypes and colors may be decimal or hex (0xHHHH).
The color is optional, and may be a single value, an inclusive range written low-high, or a comma separated list whose entries are either of those. A list entry is picked at random, and a picked range gives a value anywhere between its ends, so the same template can dress two characters differently.
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 config

EquipItem( mobile, item )#

Parameters

Explanation

Equips an item on a mobile.
Note 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

EraseGlobalProperty( propname )#

Parameters

propname 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, propname )#

Parameters

object UObject Reference
propname 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

FindAccount( acctname )#

Parameters

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

FindObjtypeInContainer( container, objtype, flags:=FINDOBJTYPE_RECURSIVE )#

Parameters

container Container reference
objtype integer objtype to find
flags Integer

Explanation

Returns an Item Reference to the first found item matching objtype starting in "container".
uo.em constants for flags:
// FindObjtype constants
const FINDOBJTYPE_RECURSIVE     := 0x0; // Search in sub-containers (DEFAULT).
const FINDOBJTYPE_IGNORE_LOCKED := 0x1; // Find matches in locked containers
const FINDOBJTYPE_ROOT_ONLY     := 0x2; // Do not find matches in sub-containers.

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

FindPath( x1, y1, z1, x2, y2, z2, realm := _DEFAULT_REALM, flags := FP_IGNORE_MOBILES, searchskirt := 5, movemode := "L" )#

Parameters

x1 Integer world coordinates - start of the path
y1 Integer world coordinates - start of the path
z1 Integer world coordinates - start of the path
x2 Integer world coordinates - destination
y2 Integer world coordinates - destination
z2 Integer world coordinates - destination
realm String - case-sensitive name of the realm
flags Integer
searchskirt Integer
movemode String - default 'L'

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.
Note 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.
Note 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."
  • "Wrong movemode parameter"

Related

FindSubstance( container, objtype, amount, makeinuse := 0, flags := 0 )#

Parameters

container Container reference
objtype Integer objtype to find
amount Integer
makeinuse Integer (0/1)
flags Integer

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.
uo.em constants for flags:
// FindSubstance constants
const FINDSUBSTANCE_IGNORE_LOCKED := 0x1; // Find matches in locked containers
const FINDSUBSTANCE_ROOT_ONLY     := 0x2; // Do not find matches in sub-containers.
const FINDSUBSTANCE_FIND_ALL      := 0x4; // Find all matches ignoring given amount

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

GetAmount( item )#

Parameters

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

GetCommandHelp( character, command )#

Parameters

character Character Reference
command string

Explanation

Gets a help message for a textcommand, if one is defined.
Note 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

GetCoordsInLine(x1, y1, x2, y2 )#

Parameters

x1 Integer world coordinates
y1 Integer world coordinates
x2 Integer world coordinates
y2 Integer world coordinates

Explanation

Calculates every coordinate between the two points.

Return values

Array of Structs {.x, .y}

Errors

  • "Invalid parameter type"

Related

GetEquipmentByLayer( character, layer )#

Parameters

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

GetFacing(from_x, from_y, to_x, to_y )#

Parameters

from_x Integer world coordinates
from_y Integer world coordinates
to_x Integer world coordinates
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"

GetGlobalProperty( propname )#

Parameters

propname 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"

GetGlobalPropertyNames()#

Explanation

Gets all the global property names. Use GetGlobalProperty(returned_array[i]) to get the property value.

Return values

Array of strings

GetHarvestDifficulty( resource, x, y, tiletype, realm := _DEFAULT_REALM )#

Parameters

resource String
x Integer world coordinates
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).
Note 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.
Formula: random_int( (90 - (units * 80 / units_per_area_)) * 2 )

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 config

GetMapInfo( x, y, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
realm String - case-sensitive name of the realm

Explanation

Gets information about map data at a location.
Note 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

menuname static or dynamic menu

Explanation

Gets all the objtypes contained in the menu.
Note see CreateMenu(), AddMenuItem()

Return values

Array of objtypes contained in the given menu.

Errors

  • none (instead returns 0 on failure)

Related

GetMidpointCircleCoords(xcenter, ycenter, radius )#

Parameters

xcenter Integer center of the circle coordinate
ycenter Integer center of the circle coordinate
radius Integer circle radius

Explanation

based on given center coordinates and radius returns array of x,y structs which represent a circle
The array of coordinates is sorted, which means that its easily possible to only use every second point

Return values

Error or Array

Related

GetMultiDimensions( multiid )#

Parameters

multiid 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

GetObjProperty( object, property_name )#

Parameters

object UObject Reference
property_name 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

GetObjPropertyNames( object )#

Parameters

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

GetObjType( object )#

Parameters

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

Related config

GetObjtypeByName( name )#

Parameters

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 config

GetRegionLightLevelAtLocation( x, y, realm := _DEFAULT_REALM )#

Parameters

x x location
y y location
realm String - case-sensitive name of the realm

Explanation

Get lightlevel of [light] region for coordinates.

Return values

Integer value of lightlevel on success

Errors

  • "Invalid Parameter"
  • "Realm not found"
  • "Invalid Coordinates for realm"

Related config

GetRegionName( object )#

Parameters

object top level UObject (item/character/npc/etc)

Explanation

Get name of [justice] region that Object is in. An item is resolved through whatever holds it, and one on a cursor through the character holding it.
Note An object standing in no realm, in a storage area for instance, has no region and gets an error.

Return values

String value of "Region Name" on success

Errors

  • "Invalid Parameter"
  • "Object has no position in the world"
  • "No Region defined at this Location"

Related config

GetRegionNameAtLocation( x, y, realm := _DEFAULT_REALM )#

Parameters

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 config

GetRegionString( resource, x, y, propertyname, realm := _DEFAULT_REALM )#

Parameters

resource string
x Integer world coordinates
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 config

GetSpellDifficulty( spellid )#

Parameters

spellid Integer

Explanation

Gets spell "difficulty" based on spell circle number (config/circles.cfg).
Note 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 config

GetStandingCoordinates( x, y, radius := 0, minz := -128, maxz := 127, realm := _DEFAULT_REALM, movemode := "L", doors_block := 0 )#

Parameters

x Integer world coordinates
y Integer world coordinates
radius Integer
minz Integer
maxz Integer
realm String - case-sensitive name of the realm
movemode String - case-sensitive movemode (e.g. "LS")
doors_block Integer (0/1)

Explanation

Returns an Array of coordinates that a creature can stand on within "radius". This is a square radius (so really, the apothem).
"minz" and "maxz" may be used to specify the minimum and maximum height of the returned coordinates.

Return values

Array of Structs with members "x", "y", "z" and possibly "multi" (containing multi reference if the coordinate is on a multi).

Errors

  • "Invalid parameter type"
  • "Realm not found"
  • "Invalid Coordinates for Realm"

GetStandingHeight( x, y, startz, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
startz Integer
realm String - case-sensitive name of the realm

Explanation

Gets the lowest z height value one could stand at x,y starting at "startz".
Note 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, includeitems := 1 )#

Parameters

x Integer world coordinates
y Integer world coordinates
realm String - case-sensitive name of the realm
flags Integer
includeitems Integer (0/1) - whether to include items, or only map statics

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 (gargoyle flying)
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"

GetWorldHeight( x, y, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
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

character Character Reference
privilege String

Explanation

Grants a privilege to a character.
Note 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

HarvestResource( resource, x, y, b, n, realm := _DEFAULT_REALM )#

Parameters

resource String
x Integer world coordinates
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.
Note 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 config

IsStackable( item1, item2 )#

Parameters

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

ListAccounts()#

Explanation

Gets a list of all account names.

Return values

Array of Strings of account names.

Related

ListEquippedItems( who )#

Parameters

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

ListGhostsNearLocation( x, y, z, range, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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).
Note 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

ListHostiles( attackable, range := 20, flags := 0 )#

Parameters

attackable Character Reference/Attackable Item
range integer (optional, default=20)
flags integer (optional, default=0)

Explanation

Gets a list of Character/Item References that are hostile (i.e. attacking) "character"
Note 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/Item References hostile to "character"

Errors

  • "Invalid parameter"

Related

ListItemsAtLocation( x, y, z, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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.
Note 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

ListItemsInBoxOfObjType( objtype, x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )#

Parameters

objtype An integer value. The ObjType to search for.
x1 integer, for north west upper corner of box
y1 integer, for north west upper corner of box
z1 integer, for north west upper corner of box
x2 integer, for south east lower corner of box
y2 integer, for south east lower corner of box
z2 integer, for south east lower corner of box
realm String - case-sensitive name of the realm

Explanation

Lists all items inside an imaginary box. Finds items with ObjType numbers matching objtype.
Note This function will not generate "Invalid Coordinates for realm" Error, because some Scripter "loves" this "bug" :o/

Return values

Error or Array of items found inside the specified box with the matching ObjType.

Errors

  • "Invalid parameter"
  • "Realm not found"

Related

ListItemsNearLocation( x, y, z, range, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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).
Note 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.
Note 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

ListItemsNearLocationOfType( x, y, z, range, objtype, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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.
Note 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.
Note 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

ListItemsNearLocationWithFlag( x, y, z, range, flags, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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_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_HOVEROVER   := 0x02000000; //HoverOver (gargoyle flying tiles)
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
Note 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.
Note 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

ListMobilesInBox( x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )#

Parameters

x1 integer, for north west upper corner of box
y1 integer, for north west upper corner of box
z1 integer, for north west upper corner of box
x2 integer, for south east lower corner of box
y2 integer, for south east lower corner of box
z2 integer, for south east lower corner of box
realm String - case-sensitive name of the realm

Explanation

like ListObjectsInBox but returns only mobiles

Return values

Error or Array of all characters found inside the specified box.

Errors

  • "Invalid parameter"
  • "Realm not found"

Related

ListMobilesInLineOfSight( object, range )#

Parameters

object UObject Reference
range Integer

Explanation

Gets list of mobiles in line of sight of "object", maximum "range" tiles away.
Note 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

ListMobilesNearLocation( x, y, z, range, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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).
Note Finds living, non-hidden mobiles found near the location.
Note 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.
Note 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

ListMobilesNearLocationEx( x, y, z, range, flags, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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).
Note 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;
Note 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.
Note 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

ListMultisInBox( x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )#

Parameters

x1 integer, for north west upper corner of box
y1 integer, for north west upper corner of box
z1 integer, for north west upper corner of box
x2 integer, for south east lower corner of box
y2 integer, for south east lower corner of box
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)
Note 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

ListObjectsInBox( x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )#

Parameters

x1 integer, for north west upper corner of box
y1 integer, for north west upper corner of box
z1 integer, for north west upper corner of box
x2 integer, for south east lower corner of box
y2 integer, for south east lower corner of box
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
Note 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

ListObjectsInBoxOfClass( POL_Class, x1,y1,z1, x2,y2,z2, realm := _DEFAULT_REALM )#

Parameters

POL_Class A POL class to search for eg. POLCLASS_
x1 integer, for north west upper corner of box
y1 integer, for north west upper corner of box
z1 integer, for north west upper corner of box
x2 integer, for south east lower corner of box
y2 integer, for south east lower corner of box
z2 integer, for south east lower corner of box
realm String - case-sensitive name of the realm

Explanation

Lists all items inside an imaginary box. Finds items matching the POL_Class.
Note This function will not generate "Invalid Coordinates for realm" Error, because some Scripter "loves" this "bug" :o/

Return values

Error or Array of items found inside the specified box with the matching POL_Class.

Errors

  • "Invalid parameter"
  • "Realm not found"

Related

ListOfflineMobilesInRealm( realm := _DEFAULT_REALM )#

Parameters

realm String - case-sensitive name of the realm

Explanation

returns the list of offline mobiles in a specific realm.
Useful for moving the offline mobiles out of a shadow realm before deleting it.

Return values

An Array of Character References of mobiles found.

Errors

  • "Invalid parameter"
  • "Realm not found"

Related

ListStaticsAtLocation( x, y, z, flags := 0, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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.
Note 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", "objtype" and "hue" or Error.

Errors

  • "Invalid parameter"
  • "Realm not found"
  • "Invalid Coordinates for Realm"

Related

ListStaticsInBox( x1,y1,z1, x2,y2,z2, flags := 0, realm := _DEFAULT_REALM )#

Parameters

x1 integer, for north west upper corner of box
y1 integer, for north west upper corner of box
z1 integer, for north west upper corner of box
x2 integer, for south east lower corner of box
y2 integer, for south east lower corner of box
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.
Note This function will not generate "Invalid Coordinates for realm" Error, because some Scripter "loves" this "bug" :o/
Note 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

ListStaticsNearLocation( x, y, z, range, flags := 0, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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).
Note 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.
Note 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", "objtype" and "hue" or Error.

Errors

  • "Invalid parameter"
  • "Realm not found"
  • "Invalid Coordinates for Realm"

Related

ListStaticsNearLocationOfType( x, y, z, range, objtype, flags := 0, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
z Integer world coordinates
range Integer
objtype Integer
flags Integer
realm String - case-sensitive name of the realm

Explanation

Searches the world for static items within range squares of (x,y,z) of type objtype.
Note 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.
Note 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", "objtype" and "hue" or Error.

Errors

  • "Realm not found"
  • "Invalid Coordinates for Realm"

Related

ListStaticsNearLocationWithFlag( x, y, z, range, flags, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
z Integer world coordinates
realm String - case-sensitive name of the realm
range Integer
flags Integer

Explanation

Gets an array of items 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_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_HOVEROVER   := 0x02000000; //HoverOver (gargoyle flying tiles)
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
Note 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.
Note 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 Structs with members "x", "y", "z", "objtype" and "hue" or Error.

Errors

  • "Invalid parameter"
  • "Realm not found"
  • "Invalid Coordinates for Realm"

Related

MoveItemToContainer( item, container, x := -1, y := -1, add_to_existing_stack := 0 )#

Parameters

item Item Reference
container Container Reference
x Integer coords inside container gump (optional)
y Integer coords inside container gump (optional)
add_to_existing_stack Defines if the items moved to the container will look for an existing stack and add to it or just add as a new item ( old behaviour )

Explanation

Moves an item into a container.
Note 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.
If add_to_existing_stack == 1 and there is no stack in the container, it will return Error "There is no existing stack", so its up to scripts to check this.
If add_to_existing_stack == 2 and there is no stack in the container, it will just add as a new item like when add_to_existing_stack == 0.

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"
  • "There is no existing stack"

Related

MoveItemToSecureTradeWin( item, character )#

Parameters

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

MoveObjectToLocation( object, x, y, z, realm := _DEFAULT_REALM, flags := MOVEOBJECT_NORMAL )#

Parameters

object Object Reference
x Integer world coordinates
y Integer world coordinates
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.
Note 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.
Note If MOVEITEM_IGNOREMOVABLE is set movable member is ignored.
Note If item is equipped, its unequiptest and unequip scripts are run, if any.
Note 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 MOVEITEM_IGNOREMOVABLE := 0x20000000;
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"
  • "That character is piloting a boat and cannot be moved"

OpenPaperdoll( towhom, forwhom )#

Parameters

Explanation

Sends the paperdoll gump to a character.
Note "towhom" gets the paperdoll for character "forwhom"

Return values

1 on success

Errors

  • "Invalid parameter type"
  • "No client attached"

Related

POLCore()#

Explanation

Returns a Polcore object. See object reference for object methods.

Return values

Polcore object reference

Related

PerformAction( character, action, framecount := 5, repeatcount := 1, backward := ACTION_DIR_FORWARD, repeatflag := ACTION_NOREPEAT, delay := 1 )#

Parameters

character Character Reference
action Integer
framecount Integer (Optional)
repeatcount Integer (Optional)
backward Integer (Optional)
repeatflag Integer (Optional)
delay Integer (Optional)

Explanation

Causes character to perform an action, such as Bow or Salute.
Note see client.inc for valid action IDs
const ACTION_DIR_FORWARD  := 0;
const ACTION_DIR_BACKWARD := 1;
const ACTION_NOREPEAT     := 0;
const ACTION_REPEAT       := 1;

Return values

1 on success

Errors

  • "Invalid parameter"

Related

PlayLightningBoltEffect( center_object )#

Parameters

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

PlayMovingEffect( source, target, effect, speed, loop := 0, explode := 0 )#

Parameters

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
Note 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

PlayMovingEffectEx( source, target, effect, speed, duration := 0, hue := 0, render := 0, fixeddirection := 0, explode := 0, effect3d := 0, effect3dexplode := 0, effect3dsound := 0 )#

Parameters

source UObject Reference
target UObject Reference
effect Integer
speed Integer (0..255)
duration Integer (Optional, 0..255)
hue Integer
render Integer (Optional, 0..255)
fixeddirection Integer (Optional, 0..1)
explode Integer (Optional, 0..1)
effect3d Integer
effect3dexplode Integer (Optional, 0..255)
effect3dsound Integer (Optional, 0..255)

Explanation

Causes a moving effect to be played, travelling from source to destination
effect3d,effect3dexplode,effect3dsound are only interpreted by the 3D client
effect3dexplode and effect3dsound are only interpreted if explode is set, effect3d and effect3dexplode values can be found in client/particles dir.
Note effect = an item graphic number (the first in a series if an animation) speed = how fast the effect should travel. explode = 0/1 show an explosion at destination at the end of the effect? hue = which color should the effect have? fixeddirection = 0/1 should the effect change his facing?
render values are:
0 no change
1 It becomes dark
2 It becomes bright
3 Bright color is emphasized and dark color is converted transparently
4 The translucency (transparency is high)
5 The translucency (it is close to primary color)
6 Negative positive reversal
7 The background which is transparent negative positive reversal

Return values

1 on success

Errors

  • "Realms must match"

Related

PlayMovingEffectXYZ( srcx, srcy, srcz, dstx, dsty, dstz, effect, speed, loop := 0, explode := 0, realm := _DEFAULT_REALM )#

Parameters

srcx Integer Source world coordinates
srcy Integer Source world coordinates
srcz Integer Source world coordinates
dstx Integer Destination world coordinates
dsty Integer Destination world coordinates
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.
Note "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"

PlayMovingEffectXYZEx( srcx, srcy, srcz, dstx, dsty, dstz, realm := _DEFAULT_REALM, effect, speed, duration := 0, hue := 0, render := 0, fixeddirection := 0, explode := 0, effect3d := 0, effect3dexplode := 0, effect3dsound := 0 )#

Parameters

srcx Integer Source world coordinates
srcy Integer Source world coordinates
srcz Integer Source world coordinates
dstx Integer Destination world coordinates
dsty Integer Destination world coordinates
dstz Integer Destination world coordinates
realm String - case-sensitive name of the realm
effect Integer
speed Integer (0..255)
duration Integer (Optional, 0..255)
hue Integer
render Integer (Optional, 0..255)
fixeddirection Integer (Optional, 0..1)
explode Integer (Optional, 0..1)
effect3d Integer
effect3dexplode Integer (Optional, 0..255)
effect3dsound Integer (Optional, 0..255)

Explanation

Causes a moving effect to be played, travelling from source to destination
effect3d,effect3dexplode,effect3dsound are only interpreted by the 3D client
effect3dexplode and effect3dsound are only interpreted if explode is set, effect3d and effect3dexplode values can be found in client/particles dir.
Note effect = an item graphic number (the first in a series if an animation) speed = how fast the effect should travel. explode = 0/1 show an explosion at destination at the end of the effect? hue = which color should the effect have? fixeddirection = 0/1 should the effect change his facing?
render values are:
0 no change
1 It becomes dark
2 It becomes bright
3 Bright color is emphasized and dark color is converted transparently
4 The translucency (transparency is high)
5 The translucency (it is close to primary color)
6 Negative positive reversal
7 The background which is transparent negative positive reversal

Return values

1 on success

Errors

  • "Realm not found"
  • "Invalid Coordinates for realm"
  • "Realm not found"

Related

PlayMusic( chr, music_id := 0 )#

Parameters

chr Character
music_id Integer - ID of the music to be played on client

Explanation

Plays music on client, as if it had just entered a new region

Return values

1 on success

Errors

  • "Invalid Parameters"

Related

PlayObjectCenteredEffect( center, effect, speed, loop := 0 )#

Parameters

center 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.
Note 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

PlayObjectCenteredEffectEx( center, effect, speed, duration := 0, hue := 0, render := 0, layer := 0, effect3d := 0 )#

Parameters

center UObject Reference
effect Integer
speed Integer (0..255)
duration Integer (Optional, 0..255)
hue Integer
render Integer (Optional, 0..255)
layer Integer (Optional, 0..255)
effect3d Integer

Explanation

Causes an effect to be played, centered on uobject, which follows uobject if it moves.
layer, effect3d are only interpreted by the 3D client
effect3d values can be found in client/particles dir.
Note effect = an item graphic number (the first in a series if an animation) speed = how fast the effect should travel. duration = controls the number of total frames to play in the animation (loops if greater than the length of the animation). 0 = play once. hue = which color should the effect have?
render values are:
0 no change
1 It becomes dark
2 It becomes bright
3 Bright color is emphasized and dark color is converted transparently
4 The translucency (transparency is high)
5 The translucency (it is close to primary color)
6 Negative positive reversal
7 The background which is transparent negative positive reversal
layer values are:
0 Head
1 RightHand
2 LeftHand
3 Waist
4 LeftFoot
5 RightFoot
7 CenterFeet

Return values

1 on success

Errors

  • none (returns 0 on invalid parameter)

Related

PlaySoundEffect( object, effect )#

Parameters

object UObject Reference
effect Integer

Explanation

Causes a sound effect to be played, centered on object.
Note 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

PlaySoundEffectPrivate( object, effect, playfor )#

Parameters

object UObject Reference
effect Integer
playfor Character Reference

Explanation

Plays a sound effect only heard by "playfor", centered around "object"
Note see client.inc for sound IDs (or InsideUO)

Return values

1 on success

Errors

  • "Invalid parameter"

Related

PlaySoundEffectXYZ( x, y, z, effect, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
z Integer world coordinates
effect Integer
realm String - case-sensitive name of the realm

Explanation

Causes a sound effect to be played, centered on Location.
Note 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"
  • "Realm not found"
  • "Invalid Coordinates for realm"

Related

PlayStationaryEffect( x, y, z, effect, speed, loop := 0, explode := 0, realm := _DEFAULT_REALM )#

Parameters

x Integer world coordinates
y Integer world coordinates
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.
Note "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"

PlayStationaryEffectEx( x, y, z, realm := _DEFAULT_REALM, effect, speed, duration := 0, hue := 0, render := 0, effect3d := 0 )#

Parameters

x Integer world coordinates
y Integer world coordinates
z Integer world coordinates
realm String - case-sensitive name of the realm
effect Integer
speed Integer (to 255)
duration Integer (Optional, 0..255)
hue Integer
render Integer (Optional, 0..255)
effect3d Integer

Explanation

Starts a stationary graphic effect at x,y,z.
effect3d is only interpreted by the 3D client
effect3d values can be found in client/particles dir.
Note effect= is a UO graphic number (the first graphic in a series for an animated effect) speed = controls the time between frames of animation duration = controls the number of total frames to play in the animation (loops if greater than the length of the animation). 0 = play once.
render values are:
0 no change
1 It becomes dark
2 It becomes bright
3 Bright color is emphasized and dark color is converted transparently
4 The translucency (transparency is high)
5 The translucency (it is close to primary color)
6 Negative positive reversal
7 The background which is transparent negative positive reversal
layer values are:
0 Head
1 RightHand
2 LeftHand
3 Waist
4 LeftFoot
5 RightFoot
7 CenterFeet

Return values

1 on success

Errors

  • "Realm not found"
  • "Invalid Coordinates for realm"

Related

PrintTextAbove( above_object, text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR, journal_print := JOURNAL_PRINT_NAME )#

Parameters

above_object UObject Reference
text String
font Integer (optional)
color Integer (optional)
journal_print Integer (optional)

Explanation

Prints text above an object, as if spoken.
Note see client.inc for suitable values for font and color
Note journal_print flags:
const JOURNAL_PRINT_NAME  := 0x00; // Implicit.  Print's the object's description / npc's name in the journal.
const JOURNAL_PRINT_YOU_SEE := 0x01; // Will print "You see:" in the journal.

Return values

0 if text was too long (>200 characters)
1 on success

Errors

  • "A parameter was invalid"

Related

PrintTextAbovePrivate( above_object, text, character, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR, journal_print := JOURNAL_PRINT_NAME )#

Parameters

above_object UObject Reference
text String
character Character Reference
font Integer (optional)
color Integer (optional)
journal_print 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"
Note see client.inc for suitable values for font and color
Note journal_print flags:
const JOURNAL_PRINT_NAME  := 0x00; // Implicit.  Print's the object's description / npc's name in the journal.
const JOURNAL_PRINT_YOU_SEE := 0x01; // Will print "You see:" in the journal.

Return values

0 if text was too long (>200 characters)
1 on success

Errors

  • "A parameter was invalid"

Related

ReadGameClock()#

Explanation

Returns the total number of seconds the server has been active.
Note 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

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"

ReleaseItem( item )#

Parameters

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

RequestInput(character, item, prompt )#

Parameters

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.
Note "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

ReserveItem( item )#

Parameters

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

RestartScript( npc_or_item )#

Parameters

npc_or_item Reference to Character (must be an NPC) or Item

Explanation

Stops the current master script for an NPC or control script for an Item, 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 and Items"

Related

Resurrect( mobile, flags := 0 )#

Parameters

mobile 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

RevokePrivilege( character, privilege )#

Parameters

character Character Reference
privilege 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

SaveWorldState()#

Explanation

Saves the current world state. If the script is currently not critical or eg run via run_script_to_completition its suspended until the complete worldsave is over. Returning also in the struct ElapsedMillisecondsTotal.
ElapsedMilliseconds is the part the world was stopped for, and ElapsedMillisecondsWriting how much of that went on writing the files. ElapsedMillisecondsFlush and ElapsedMillisecondsCommit cover finishing the last writes and putting the data files in place, both of which happen with the shard already running again.
Files is a struct of bytes written per data file ("storage", "items", "pcs", ...). Tasks is a struct of what each part of the save cost in milliseconds ("storage", "items", "character", ...); the parts are worked on at the same time, so read the biggest entry rather than the sum. pol.cfg LogWorldSaveDetails logs the same breakdown.

Return values

struct { CleanObjects, DirtyObjects, ElapsedMilliseconds, ElapsedMillisecondsWriting, ElapsedMillisecondsFlush, ElapsedMillisecondsCommit, Files, Tasks, [ElapsedMillisecondsTotal] }

Errors

  • "Failed to save world"
  • "pol.cfg has InhibitSaves=1"

SecureTradeWin( character, character2 )#

Parameters

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

SelectColor( character, item )#

Parameters

Explanation

Sends a color chooser gump to character.
Note 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

SelectMenuItem2( character, menuname )#

Parameters

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.
Note 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

Related config

SendBuyWindow( character, container, vendor, items, flags := 0 )#

Parameters

character Character Reference to player
container Container Reference ( vendor 'for sale items' container )
vendor Character Reference to NPC vendor
items Container Reference (vendor 'player bought items' container)
flags Integer

Explanation

Sends the "buy scroll" gump to a player to choose items to buy.
Note Pretty nasty function. Containers should be in storage areas.
Note 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...
Note 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)

SendCharProfile( character, of_who, title, uneditable_text := CHARPROFILE_NO_UNEDITABLE_TEXT, editable_text := CHARPROFILE_NO_EDITABLE_TEXT )#

Parameters

character Character
of_who Character
title String
uneditable_text unicode arrays
editable_text unicode arrays

Explanation

will send the serverside charprofile packet back to client and display it for the player.
uo.em constants for type:
const CHARPROFILE_NO_UNEDITABLE_TEXT := array;
const CHARPROFILE_NO_EDITABLE_TEXT := array;

Return values

1 on success

Errors

  • "Invalid Parameters"
  • "Mobile must be online."
  • "Invalid parameter type"

Related

SendCharacterRaceChanger( character )#

Parameters

Explanation

Send Client inside Character Race Changer to change Hair, Beard and Color.

Return values

1 on success or Error

Errors

  • "Invalid parameter"

Related

SendDialogGump( who, layout, textlines, x := 0, y := 0, flags := 0, gumpid := 0 )#

Parameters

who Character Reference
layout String Array
textlines String Array
x Integer-Offset
y Integer-Offset
flags Integer
gumpid Integer, 0 to 0xFFFFFF

Explanation

Sends a generic gump window to "who" and waits for the user's input.
If no gumpid is given, the script's pid will be sent as gumpid.
Note "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.
Based on clientversion core will send compressed or uncompressed version
Note uo.em constants for this function:
const SENDDIALOGMENU_FORCE_OLD  := 0x01;

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)
  • "GumpID out of range"

SendEvent( npc, event )#

Parameters

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

SendHousingTool( who, house )#

Parameters

Explanation

Sends the custom housing tool to Character
house.setcustom(1) is needed before SendHousingTool() works
during editing chr is only allowed to walk inside the house
all components which are not invisible get removed from component list during edit and added to design (not invisible to give the chance to eg protect a house sign from been removed from the editing char)
any item inside the house will be invisible for the chr
any other mobiles get moved outside the house
param houseelemarray in script call is the current list of houseparts, multi.house_parts gives you the last stored list
until no house.acceptcommit() is called and start of commitscript no new SendHousingTool() for this house is allowed

Return values

1 on success

Related

SendInstaResDialog( character )#

Parameters

Explanation

Character's screen fades to black, "You are Dead" appears, Character gets menu choice for Instares.
Note (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

SendOpenBook( character, book )#

Parameters

character Character Reference
book Item Reference (Book object only)

Explanation

Sends a book gump to the character.
The 'book' passed must have a Method Script, exporting the following functions:
exported function IsWritable(book)    // returns 0 or 1 for readonly/writable
exported function GetNumLines(book)   // returns maximum number of lines
exported function GetTitle(book)      // returns title as string
exported function GetAuthor(book)     //returns author as string
exported function GetLine(book, line) // line is 1-based
Writable books must provide the following functions:
exported function SetAuthor(book,author)
exported function SetTitle(book,title)
exported function SetLine(book,line,text)
exported function GetContents(book)   // returns an array of all lines

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

SendOpenSpecialContainer( character, container )#

Parameters

Explanation

Sends an open container gump to the character.
Note 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"

SendOverallSeason( season_id, playsound := 1 )#

Parameters

season_id Integer
playsound Integer

Explanation

Used to send the Season packet 0xBC to all clients logged on.
This function doesnt resend the lightlevel or weather after it sends season, that has to be done by scripts.

Return values

1 on success

Errors

  • "Invalid Parameters"
  • "Invalid season id"

Related

Related config

SendPacket( to_whom, packet_hex_string )#

Parameters

to_whom Character Reference
packet_hex_string String

Explanation

Sends the hex string to the character as a binary packet.
Note 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"
  • "Invalid packet string length."

Related

SendPopUpMenu( to_whom, above, menu )#

Parameters

to_whom Character: who to send the menu to
above Object: Item or Mobile to display the menu above
menu Array: array of menu elements

Explanation

Will show a pop-up context menu above the given object, waits for a reponse and return it (if no response is given, this could hang the script undefinitely)
Every element in the menu array must be an integer specifying a cliloc text for the menu or a struct { cliloc, [disabled,] [arrow,] [color] }
- cliloc: int, this is the only mandatory element in struct, the cliloc text id (min 3000000, max 3065535 if client version below 6)
- disabled: bool, if true, the menu entry will be disabled and shown in gray (default: false)
- arrow: bool, if true, an arrow will be shown (default: false)
- color: an optional rgb 1555 color (ex, 0 = transparent, 0x8000 = solid black, 0x1F = blue, 0x3E0 = green, 0x7C00 = red)

Return values

Error or Array index selected (0 if canceled). No validation is done.

Errors

  • "Invalid parameter"
  • "No client attached"
  • "Can't send empty menu"
  • "Too many entries in menu"
  • "Menu elements must be int or struct"
  • "Cliloc out of range in menu"
  • "Missing cliloc for menu element"
  • "Invalid cliloc for menu element"

SendQuestArrow(to_whom, x := -1, y := -1, arrowid := "" )#

Parameters

to_whom Character reference the arrow shows to
x Integer world coordinates
y Integer world coordinates
arrowid Integer

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.
If the client is HSA (client version > 7.0.9), Multiple arrows can exist at one time. You can specify an id using the arrowid param otherwise one will be generated by the core.
Pass an 'x' and 'y' value of -1 well cancel the arrow, for HSA clients an arrow id is required to clear that specific arrow.

Return values

arrowid on success

Errors

  • "No client attached"
  • "Invalid parameter"
  • "ArrowID out of range"
  • "ArrowID must be supplied for cancelation."

Related

SendSellWindow( character, vendor, i1, i2, i3, flags := 0 )#

Explanation

Sends a sell scroll gump to "character" using "vendor" as the merchant.
Note i1 = vendor's "For sale" item containter. i2 = vendor's "Bought from player" item container. i3 = vendor's "Buyable" item container.
Note the answer can only sell what this window listed, each item once, and only while it can still be sold: at the top of the character's backpack, not newbie, not in use, and, for a container, still empty. The same goes for the shopping list a script gets with servspecopt.cfg ScriptedMerchantHandlers. Opening another sell window replaces the list.
Note 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...
Note 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"
  • "The sell list is too long to send" when what the character could sell does not fit into one packet. No window is opened.

SendSkillWindow( towhom, forwhom )#

Parameters

Explanation

Sends a skills scroll gump to "towhom"
Note The skills belong to "forwhom" and are sent to "towhom"

Return values

1 on success

Errors

  • "Invalid parameter type"
  • "No client attached"

Related

SendStatus( character )#

Parameters

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

SendStringAsTipWindow( character, text )#

Parameters

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

SendSysMessage( character, text, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )#

Parameters

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.
Note 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

SendTextEntryGump( who, line1, cancel := TE_CANCEL_ENABLE, style := TE_STYLE_NORMAL, maximum := 40, line2 := "" )#

Parameters

who Character Reference
line1 String
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.
Note 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

SendViewContainer( character, container )#

Parameters

Explanation

Sends the container's open gump and contents to the character.
Note Use this for normal containers.

Return values

1 on success

Errors

  • "Invalid parameter type"
  • "No client attached"
  • "That isn't a container"

SetGlobalProperty( propname, propval )#

Parameters

propname String
propval 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

object UObject Reference
name String

Explanation

Sets name of item or mobile.

Return values

1 on success

Errors

  • none (returns 0 on failure)

Related

SetObjProperty( object, property_name, property_value )#

Parameters

object UObject Reference
property_name String
property_value 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

SetRegionLightLevel( regionname, lightlevel )#

Parameters

regionname String
lightlevel Integer (0..30)

Explanation

Sets the light level of a region by name.
Note 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 config

SetRegionWeatherLevel( region, type, severity, aux := 0, lightoverride := -1 )#

Parameters

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 config

SetScriptController( who )#

Parameters

Explanation

Set the "controller" of the current script to "who".
Note 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

Shutdown( exit_code := 0 )#

Parameters

exit_code Integer

Explanation

Shuts down the server
Note Disconnects all clients and saves the world state. The POL process will exit with the provided exit_code.

Return values

1 always

SingleClick( who, what )#

Parameters

who Character Reference
what Character or Item reference

Explanation

Emulates a single click of the character "who" on the object or character "what".
Note "what" can be a serial.

Return values

1 on success

Errors

  • "Invalid parameter"
  • "Mobile has no active client"

SpeakPowerWords( who, spellid, font := _DEFAULT_TEXT_FONT, color := _DEFAULT_TEXT_COLOR )#

Parameters

who Character Reference
spellid Integer
font Integer (optional)
color Integer (optional)

Explanation

Forces character "who" to speak the spell power words as defined in spells.cfg.
Note spells.cfg files define spells and spell ids.
See client.inc for font and color values.

Return values

1 on success

Errors

  • "Invalid parameter"
  • "No such spell"
  • "Spell ID out of range"

Related

Related config

StartSpellEffect( who, spellid )#

Parameters

who Character Reference
spellid Integer

Explanation

Starts the spell script as defined in spells.cfg
Note 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

Related config

SubtractAmount( item, amount )#

Parameters

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

SystemFindObjectBySerial( serial, sysfind_flags := 0 )#

Parameters

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.
Note uo.em constants for flags:
const SYSFIND_SEARCH_OFFLINE_MOBILES := 1;

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

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.
Note 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;
const TGTOPT_ALLOW_NONLOCAL :- 0x0008;
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

TargetCoordinates( by_character )#

Parameters

by_character Character Reference

Explanation

Sends a target cursor to a character's client, and waits for the player to target a ground tile.
Note 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.
structure.multi contains Multi Reference if coords are inside a multi
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

TargetMultiPlacement( character, objtype, flags := 0, xoffset := 0, yoffset := 0, hue := 0 )#

Parameters

character Character Reference
objtype Integer
flags Integer (optional)
xoffset Integer offset to 'ghost' target house
yoffset Integer offset to 'ghost' target house
hue Integer

Explanation

Sends character a "ghost" multi to select placement location in the world.
Note 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

UpdateItem( item )#

Parameters

Explanation

updates the item to every client in range, good to use for example after returning 1 in some packethook and the item get invisible

Return values

1 on success or Error

Related

UpdateMobile( mobile, recreate := UPDATEMOBILE_UPDATE )#

Parameters

mobile Character Reference
recreate Integer (Optional, 0..1)

Explanation

if flags set to UPDATEMOBILE_UPDATE sends to mobiles in visual range UpdatePlayer packet of mobile, for example to inform of notority changes
if flags set to UPDATEMOBILE_RECREATE sends ReCreate packet (0x78)
uo.em constants:
const UPDATEMOBILE_RECREATE := 1;
const UPDATEMOBILE_UPDATE   := 0;

Return values

1 on success or Error

Errors

  • "Mobile is offline"

Related

UseItem( item, character )#

Parameters

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