# UOX3 Script Engine

### API and Event handling

### Miscellaneous Functions

RollDice
Prototype |
    int RollDice( numDie, faces, addition );
Purpose | Rolls a faces sided die numDie times and adds addition. The example is for a DnD style dice like: 2d3+1
Example of Usage |
    var mDie = RollDice( 2, 3, 1 );

ScriptPrintNumber
Prototype |
    ScriptPrintNumber( number );
Purpose | Prints out a number to the console
Example of Usage |
    ScriptPrintNumber( 5 );

SetShowLayer
Prototype |
    SetShowLayer( number );
Purpose | Sets showlayer true (if number == 1) or false
Example of Usage |
    SetShowLayer( 1 );

GetShowLayer
Prototype |
    int GetShowLayer();
Purpose | Returns value of showlayer
Example of Usage |
    var iLayer = GetShowLayer();

RandomNumber
Prototype |
    int RandomNumber( loNum, hiNum );
Purpose | Returns a random number between loNum and hiNum
Example of Usage |
    var iNum = RandomNumber( 0, 10 );

CalcCharFromSer
Prototype |
    CHARACTER CalcCharFromSer( cSerial );
Purpose | Returns the item with serial cSerial. Returns null if it doesn't exist
Example of Usage |
    var trgChar = CalcCharFromSer( cSerial );

CalcTargetedChar
Prototype |
    CHAR CalcTargetedChar( cSerial );
Purpose | Returns targeted character stored on socket
Example of Usage |
    var trgItem = CalcTargetedChar( cSerial );

CalcItemFromSer
Prototype |
    ITEM CalcItemFromSer( iSerial );
Purpose | Returns the item with serial iSerial. Returns null if it doesn't exist
Example of Usage |
    var trgItem = CalcItemFromSer( iSerial );

CalcTargetedItem
Prototype |
    ITEM CalcTargetedItem( iSerial );
Purpose | Returns targeted item stored on socket
Example of Usage |
    var trgItem = CalcTargetedItem( iSerial );

RegisterKey
Prototype |
Purpose |
Example of Usage |

UnregisterKey
Prototype |
Purpose |
Example of Usage |

GetMurderThreshold
Prototype |
    int GetMurderThreshold();
Purpose | Returns the number of kills needed to go red.
Example of Usage |
    if( GetMurderThreshold() > GetMurderCount( pTalking ) )

    {

    	TextMessage( pTalkingTo, "Surely sir, you must be a murderer.  I bid you adieu" );

    	EmoteMessage( pTalkingTo, "*scampers off*" );

    }

GetTileIDAtMapCoord
Prototype |
    int GetTileIDAtMapCoord( xLoc, yLoc, worldNumber );
Purpose | Returns ID of the tile at xLoc and yLoc in world worldNumber
Example of Usage |
    var MapTile = GetTileIDAtMapCoord( 0, 0, 0 ); // gets tile at 0,0 in Britannia

StaticInRange
Prototype |
    bool StaticInRange( xLoc, yLoc, worldNumber, radius, tileID );
Purpose | Checks for static within specified range of given location
Example of Usage |
    // Checks if there's a static tile with ID 0x04a9 (wooden floor) within a radius of 3 from pUser's location
    var staticFound = StaticInRange( pUser.x, pUser.y, pUser.worldnumber, 3, 0x04a9 );

StaticAt
Prototype |
    bool StaticAt( xLoc, yLoc, worldNumber, tileID );
Purpose | Checks for static at specified location. If no tileID parameter is specified, will match ANY static at said location
Example of Usage |
    // Checks if there's a static tile with ID 0x04a9 (wooden floor) at a specific location
    var staticFound = StaticAt( pUser.x, pUser.y, pUser.worldnumber, 0x04a9 );

    // Checks if there's ANY static tile at specific location
    var staticFound = StaticAt( pUser.x, pUser.y, pUser.worldnumber );

TriggerEvent
Prototype |
    TriggerEvent( scriptID, "functionName", argument1, argument2 );
Purpose | Calls the JScript that uses scriptID, runs function which is called "functionName", along with the arguments defined afterwards, seperated by commas.
Example of Usage |
    TriggerEvent( 8000, "onUseChecked", pUser, pItem );

AreaCharacterFunction
Prototype |
    AreaCharacterFunction( "myAreaFunc", radiusObject, radius, socket );
Purpose | Allows script to work with every character that is found in the radius of the radiusObject (item or character), for the purpose of area-effects.
Example of Usage |
    function onUseChecked( pUser, pSock );
    {
    	AreaCharacterFunction( "myAreaFunc", pUser, 10, pSock );
    }
    function myAreaFunc( srcChar, trgChar, pSock )
    {
    	trgChar.TextMessage( "Oh no I've been found!" );
    	pSock.SysMessage( "Found " + trgChar.name );
    }

AreaItemFunction
Prototype |
    AreaItemFunction( "myAreaFunc", radiusObject, radius, socket );
Purpose | Allows script to work with every item that is found in the radius of the radiusObject (item or character), for the purpose of area-effects.
Example of Usage |
    function onUseChecked( pUser, pSock );
    {
    	AreaItemFunction( "myAreaFunc", pUser, 10, pSock );
    }
    function myAreaFunc( srcChar, trgItem, pSock )
    {
    	trgItem.TextMessage( "Oh no I've been found!" );
    	pSock.SysMessage( "Found " + trgItem.name );
    }

UseItem
Prototype |
    UseItem( iSock/mChar, iToUse );
Purpose | Current character of iSock/mChar passed in uses the item iToUse.
Example of Usage |
    if( iUsed.type == 12 )

    {

    	mChar.TextMessage( "I just LURV using doors" );

    	UseItem( mChar, iToUse );

    }

TriggerTrap
Prototype |
    TriggerTrap( pChar/pSock, iTrap );
Purpose | pChar/pSock triggers trap on iTrap object (if any trap is present)
Extra Info | Trap will only trigger if both first two parts of MOREZ value is set on object; first part needs to be set to 1 to indicate object is trapped, second part needs to specify damage amount to apply.
Example of Usage |
    // Setup trap on iTrap object
    // First part of value (01) indicates object is trapped
    // Second part of value (32) defines damage dealt (32 = 0x32 = 50 damage)
    iTrap.morez = 0x01320000;

    // Trigger the trap
    TriggerTrap( pChar, iTrap );

SendStaticStats
Prototype |
    void SendStaticStats( socket );
Purpose | Builds a gump with map and tile information on the targeted location.
Example of Usage |
    SendStaticStats( mSock );

GetTileHeight
Prototype |
    signed char GetTileHeight( tileID );
Purpose | Returns the map height of the specified tile.
Example of Usage |
    object.z = GetTileHeight( targTile );

IterateOver
Prototype |
    unsigned int IterateOver( objectType );
Purpose | Iterates over all objects of specified type in the world.
Extra Info | For every object it comes across, the iterator will call onIterate( object ) in the calling script.
Example of Usage |
    var count = IterateOver( "ITEM" );
    function onIterate( toCheck )
    {
    	toCheck.TextMessage( "I'm an item!" );
    	return true;
    }

WorldBrightLevel
Prototype |
    unsigned char WorldBrightLevel( [lightlevel] );
Purpose | Sets and returns the bright light level of the world.
Example of Usage |
    WorldBrightLevel( 1 );

WorldDarkLevel
Prototype |
    unsigned char WorldDarkLevel( [lightlevel] );
Purpose | Sets and returns the dark light level of the world.
Example of Usage |
    var darkLight = WorldDarkLevel();

WorldDungeonLevel
Prototype |
    unsigned char WorldDungeonLevel( [lightlevel] );
Purpose | Sets and returns the dungeon light level of the world.
Example of Usage |
    WorldDungeonLevel( 1 );

ValidateObject
Prototype |
    bool ValidateObject( object );
Purpose | Returns true if argument is validated as an object
Example of Usage |
    if( !ValidateObject( pUser ) )
    	return;

ReloadJSFile
Prototype |
    void ReloadJSFile( scriptID );
Purpose | Reloads a specified JavaScript file depending on scriptID from jse_fileassociations.scp
Example of Usage |
    function CommandRegistration()
    {
    	RegisterCommand( "reloadjsfile", 3, true ); //Reload JavaScript file
    }

    function command_RELOADJSFILE( socket, cmdString )
    {
    	var scriptID = parseInt( cmdString );
    	socket.SysMessage( "Attempting Reload of JavaScript (ScriptID " + cmdString + ")" );
    	ReloadJSFile( scriptID );
    }

GetTimer
Prototype |
    bool GetTimer( timerID );
Purpose | Returns the specified timer value for a Character or Socket object
Example of Usage |
    myObj.GetTimer( 3 );

SetTimer
Prototype |
    bool SetTimer( timerID, numMilliSeconds )
Purpose | Sets specified timer for a Character or Socket object, with amount of miliseconds until it expires
Example of Usage |
    mySock.SetTimer( 3, 1000 );

Moon
Prototype |
    bool Moon( moonNum, newVal );
    bool Moon( moonNum )
Purpose | Get and set the server moon values for the two moons Felucca (0) and Trammel (1)
Example of Usage |
    var feluccaMoonphase = Moon( 0 );
    var TrammelMoonphase = Moon( 1 );
    Moon( 0, 7 ); //Set the moon Felucca to moonphase 7
    Moon( 1, 3 ); //Set the moon Trammel to moonphase 3

CreateParty
Prototype |
    bool CreateParty( partyleader );
Purpose | Create a new party/group with the specified character as leader
Example of Usage |
    var myParty = CreateParty( pUser ); //create a new party (myParty) with pUser as the leader

GetSocketFromIndex
Prototype |
    bool GetSocketFromIndex( socketIndex );
Purpose | Create a socket-object based on the specified socketIndex
Example of Usage |
    var socket = GetSocketFromIndex( 0 ); //fetch whatever socket is connected to the server as socket/connection 0

GetClientFeature
Prototype |
    bool GetClientFeature( ClientFeaturesBitNum );
Purpose | Check if a specific client features is enabled. For a list of features that can be checked this way, see [settings]->clientFeatures List in the UOX.INI Settings section of the UOX3 Documentation.
Example of Usage |
    var aosFeaturesEnabled = GetClientFeature( 0x10 ); // AoS bit from list of client features

GetServerFeature
Prototype |
    bool GetServerFeature( ServerFeaturesBitNum );
Purpose | Check if a specific server features is enabled. For a list of features that can be checked this way, see [settings]->serverFeatures List in the UOX.INI Settings section of the UOX3 Documentation.
Example of Usage |
    var contextMenusEnabled = GetServerFeature( 0x08 ); // ContextMenus bit from list of server features

GetServerSetting
Prototype |
    string GetServerSetting( serverSettingString );
Purpose | Fetches the value of a specified server setting and returns it as a string. Wrap in parseInt() if expected value returned is an int.
Example of Usage |
    var guardsActive = GetServerSetting( "GUARDSACTIVE" ); // Returns 1 if GUARDSACTIVE is set to 1 in UOX.INI, or 0 if set to 0.

CheckTileFlag
Prototype |
    bool CheckTileFlag( tileID, tileflag );
Purpose | Check if a specific tile ID has given flag
Example of Usage |
    var doesTileBlock = CheckTileFlag( iUsed.id, 6 ); //6 = TF_BLOCKING

GetMapElevation
Prototype |
    bool GetMapElevation( x, y, z, world );
Purpose | Returns the map elevation at specified coordinates
Example of Usage |
    var mapElev = GetMapElevation( pUser.x, pUser.y, pUser.z, pUser.worldnumber );

IsInBuilding
Prototype |
    bool IsInBuilding( x, y, z, world, instance, checkHeight );
Purpose | Returns true if specified location is inside a static building (underneath static items), or if player is inside a multi. If checkHeight argument is true, player is only deemed inside a multi if there are multi-items above the player's head. If player is in a courtyard/on a rooftop, they will be deemed to be NOT in the building. checkHeight is not used for the static part of the function, only for multis.
Example of Usage |
    var isCharInBuilding = IsInBuilding( myChar.x, myChar.y, myChar.z, myChar.worldnumber, myChar.instanceID, true );

CheckStaticFlag
Prototype |
    bool CheckStaticFlag( x, y, z, world, tileFlagID );
Purpose | Check if any statics at given coordinates has specified tile flag. Parameters: x, y, z, world = coordinates and worldnumber tileFlagID = tileFlag from sourceCode
    	TF_FLOORLEVEL	= 0,
    	TF_HOLDABLE = 1,
    	TF_TRANSPARENT = 2,
    	TF_TRANSLUCENT = 3,
    	TF_WALL = 4,
    	TF_DAMAGING = 5,
    	TF_BLOCKING = 6 ,
    	TF_WET = 7,
    	TF_UNKNOWN1 = 8,
    	TF_SURFACE = 9,
    	TF_CLIMBABLE = 10,
    	TF_STACKABLE = 11,
    	TF_WINDOW = 12,
    	TF_NOSHOOT = 13,
    	TF_DISPLAYA = 14,
    	TF_DISPLAYAN = 15,
    	TF_DESCRIPTION = 16,
    	TF_FOLIAGE = 17,
    	TF_PARTIALHUE = 18,
    	TF_UNKNOWN2 = 19,
    	TF_MAP = 20,
    	TF_CONTAINER = 21,
    	TF_WEARABLE = 22,
    	TF_LIGHT = 23,
    	TF_ANIMATED = 24,
    	TF_NODIAGONAL = 25, //HOVEROVER in SA clients and later, to determine if tiles can be moved on by flying gargoyles
    	TF_UNKNOWN3 = 26,
    	TF_ARMOR = 27,
    	TF_ROOF = 28,
    	TF_DOOR = 29,
    	TF_STAIRBACK = 30,
    	TF_STAIRRIGHT = 31
Example of Usage |
    var tileFlagFound = CheckStaticFlag( pUser.x, pUser.y, pUser.z, pUser.worldnumber, 10 ); // Is there a tile with TF_CLIMBABLE flag?

CheckDynamicFlag
Prototype |
    bool CheckDynamicFlag( x, y, z, worldNumber, instanceID, tileFlagID );
Purpose | Check if any dynamics at given coordinates has specified tile flag. Parameters: x, y, z, world, instanceID = coordinates, worldnumber and instanceID tileFlagID = tileFlag from sourceCode
    	TF_FLOORLEVEL	= 0,
    	TF_HOLDABLE = 1,
    	TF_TRANSPARENT = 2,
    	TF_TRANSLUCENT = 3,
    	TF_WALL = 4,
    	TF_DAMAGING = 5,
    	TF_BLOCKING = 6 ,
    	TF_WET = 7,
    	TF_UNKNOWN1 = 8,
    	TF_SURFACE = 9,
    	TF_CLIMBABLE = 10,
    	TF_STACKABLE = 11,
    	TF_WINDOW = 12,
    	TF_NOSHOOT = 13,
    	TF_DISPLAYA = 14,
    	TF_DISPLAYAN = 15,
    	TF_DESCRIPTION = 16,
    	TF_FOLIAGE = 17,
    	TF_PARTIALHUE = 18,
    	TF_UNKNOWN2 = 19,
    	TF_MAP = 20,
    	TF_CONTAINER = 21,
    	TF_WEARABLE = 22,
    	TF_LIGHT = 23,
    	TF_ANIMATED = 24,
    	TF_NODIAGONAL = 25, //HOVEROVER in SA clients and later, to determine if tiles can be moved on by flying gargoyles
    	TF_UNKNOWN3 = 26,
    	TF_ARMOR = 27,
    	TF_ROOF = 28,
    	TF_DOOR = 29,
    	TF_STAIRBACK = 30,
    	TF_STAIRRIGHT = 31
Example of Usage |
    var tileFlagFound = CheckDynamicFlag( pUser.x, pUser.y, pUser.z, pUser.worldNumber, pUser.instanceID, 6 ); // Is there a tile with TF_BLOCKING flag?

DoesStaticBlock
Prototype |
    bool DoesStaticBlock( x, y, z, world, checkWater );
Purpose | Check if statics at/above given location blocks character movement Parameters: x, y, z, world = coordinates and worldnumber checkWater = true if water should block, false if not (for creatures that can swim, for instance)
Example of Usage |
    var doesStaticBlock = DoesStaticBlock( pUser.x + 1, pUser.y, pUser.z, pUser.worldnumber, false );

DoesDynamicBlock
Prototype |
    bool DoesDynamicBlock( x, y, z, world, instance, checkWater, waterWalk, checkOnlyMultis, checkOnlyNonMultis );
Purpose | Checks if dynamics at/above given location blocks character movement. Parameters: x, y, z, world, instance = coordinates, worldnumber and instanceID checkWater = true if water should block, false if not (for creatures that can swim, for instance) waterWalk = true if creature can move on water surfaces, false if not checkOnlyMultis = only multis will be checked, other dynamic items are ignored checkOnlyNonMultis = multis are ignored, all other dynamic items are checked
Example of Usage |
    var doesDynamicBlock = DoesDynamicBlock( pUser.x + 1, pUser.y, pUser.z, pUser.worldnumber, pUser.instanceID, false, false, false, false );

DoesMapBlock
Prototype |
    bool DoesMapBlock( x, y, z, world, checkWater, waterWalk, checkMultiPlacement, checkForRoad );
Purpose | Checks if map tile at given coordinates would block character movement. Parameters: x, y, z, world = coordinates and worldnumber checkWater = true if water should block, false if not (for creatures that can swim, for instance) waterWalk = true if creature can move on water surfaces, false if not checkMultiPlacement = if true, map tile has to be at exact same Z as provided coordinate, or it will count as blocked checkForRoad = true if roads and paths should count as blocking. checkMultiPlacement must be true for this to be checked
Example of Usage |
    var doesMapBlock = DoesMapBlock( pUser.x + 1, pUser.y, pUser.z, pUser.worldnumber, false, false, true, true );

DistanceBetween
Prototype |
    bool DistanceBetween( x1, y1, x2, y2 );
    bool DistanceBetween( x1, y1, z1, x2, y2, z2 );
    bool DistanceBetween( objA, objB );
    bool DistanceBetween( objA, objB, checkZ );
Purpose | Get the distance between two sets of coordinates or objects on either 2D or 3D plane Parameters: x1, y1, z1, x2, y2, z2 = coordinates checkZ = true if distance between two objects should take into account Z axis
Example of Usage |
    // Get distance between two sets of x, y coordinates
    var distance1 = DistanceBetween( pUser.x, pUser.y, iUsed.x, iUsed.y );

    // Get distance between two sets of x, y, z coordinates
    var distance2 = DistanceBetween( pUser.x, pUser.y, pUser.z, iUsed.x, iUsed.y, iUsed.z );

    // Get distance between pUser and iUsed using 2D coordinates
    var distance2 = DistanceBetween( pUser, iUsed );

    // Get distance between pUser and iUsed using 3D coordinates
    var distance2 = DistanceBetween( pUser, iUsed, true );

GetAccountCount
Prototype |
    int GetAccountCount();
Purpose | Gets the total amount of accounts on the server
Example of Usage |
    var totalAccounts = GetAccountCount();

GetPlayerCount
Prototype |
    int GetPlayerCount();
Purpose | Gets the total amount of players online on the server
Example of Usage |
    var totalPlayers = GetPlayerCount();

BASEITEMSERIAL
Prototype |
    int BASEITEMSERIAL();
Purpose | Gets the constant that defines the base value used as starting point for item serials. If an object serial is lower than this, it probably belongs to a character. If it's higher, it belongs to an item.
Example of Usage |
    var baseItemSerial = BASEITEMSERIAL();

INVALIDSERIAL
Prototype |
    int INVALIDSERIAL();
Purpose | Gets the constant defining an invalid serial. If an object serial matches this, it's invalid!
Example of Usage |
    var invalidSerial = INVALIDSERIAL();

INVALIDID
Prototype |
    int INVALIDID();
Purpose | Gets the constant defining an invalid ID. If an object's ID matches this, it's probably not a valid ID!
Example of Usage |
    var invalidID = INVALIDID();

INVALIDCOLOUR
Prototype |
    int INVALIDCOLOUR();
Purpose | Gets the constant defining an invalid colour. If an object's colour is equal or higher than this, it's probably not a valid colour!
Example of Usage |
    var invalidColour = INVALIDCOLOUR();

©Copyright 2000-2001 WWW.UOX3.NET (Daniel Stratton/Matthew Randall)