Last Updated: 25. August, 2022
Written for UOX3 Version: v0.99.5b-6
In this document you will find details on how to write scripts for the embedded scripting engine in UOX3, with details about the JS Events, Functions, Methods and Properties available for use, examples on how to use them in your scripts, as well as basic tips and tricks for getting stuff done in JS.
A copy of this document specific to your downloaded version of UOX3 is included in the UOX3/docs/ folder, though the latest up-to-date version can always be found at https://www.uox3.org/docs/jsdocs.html!
UOX3's JavaScript Engine is based on an embedded version of SpiderMonkey 1.7. This provides a similar feature-set to JavaScript 1.7 or ECMAScript 5, minus any web/browser-specific stuff.
UOX3's JS engine does not protect against global object pollution, which means care should be taken when using global variables - variables declared outside functions - as a change to one of these variables in one instance of a particular script will also be reflected in any other instances of the same script. General rule of thumb - only use global variables for constants, unchanging arrays/flags, etc.
You can download JS scripts written and shared by other UOX3 users from The JScript Vault section of the UOX3.org forums. Each such script should come with its own setup instructions.
If you're having trouble with your scripts, or even just feel the need to bounce ideas off of someone, feel free to post in the Scripting Department section of the UOX3.org forums, or join us on the UOX3 Discord!
You can either post your suggestion/request in the Feature Requests - Wishes - Suggestions section of the UOX3.org forums, giving other users the chance to chime in and potentially back up your suggestion, or you can hop on to the UOX3 Discord and air your idea in the chat!
The first and most obvious way to resolve this problem is to start learning how to script! Read the documentation, follow the examples, check out existing scripts and try out tweaks. You can either post your suggestion/request in the Feature Requests - Wishes - Suggestions section of the UOX3.org forums, giving other users the chance to chime in and potentially back up your suggestion, or you can hop on to the UOX3 Discord and air your idea in the chat!
Prototype
function [Script]Registration()
Purpose
Registers specific types of global scripts with the JS engine
When Triggered
These events are triggered on UOX3 startup, and on reloads of the script-engine
Notes
The name of the event depends on the type of script being registered. Supported types:
Scripts from each type need to be assigned scriptIDs in specific sections of jse_fileassociations.scp:
Access levels (or command levels) are specified in dfndata/command/commands.dfn, and the default setup goes like this:
Example of usage
// --------COMMAND SCRIPTS----------- //
function CommandRegistration()
{
// Register a command with name "myCustomCommand",
// usable by characters with access level 3 or higher
RegisterCommand( "myCustomCommand", 3, true );
}
function command_MYCUSTOMCOMMAND( socket, cmdString )
{
// ...handle command functionality here
}
// --------CONSOLE SCRIPTS----------- //
function ConsoleRegistration()
{
// Register a few different keys/keycodes as global listeners for keypresses in UOX3 console
RegisterKey( 'q', "shutdown" );
RegisterKey( 'Q', "shutdown" );
RegisterKey( 27, "shutdown" ); // escape
}
function shutdown()
{
Console.BeginShutdown();
}
// --------PACKET SCRIPTS----------- //
function PacketRegistration()
{
// Register script as global listener for packet 0x7F
RegisterPacket( 0x7F, 0x0 );
}
function onPacketReceive( pSocket, packetNum, subCommand )
{
// ...handle packet hook functionality here
}
// --------SKILL SCRIPTS----------- //
function SkillRegistration()
{
// Register script as a global listener for skill 35 (Animal Taming)
RegisterSkill( 35, true );
}
function onSkill( pUser, objType, skillUsed )
{
// ...handle sksill functionality here
}
// --------SPELL SCRIPTS----------- //
function SpellRegistration()
{
// Register script as global listener for spell 1 from spells.dfn
RegisterSpell( 1, true );
}
function onSpellCast( socket, character, directCast, spellNum )
{
// ...handle spell functionality here
}
Prototype
function inRange( pChar, objInRange )
Purpose
Useful for when you want to do something when a certain thing comes into range. You could yell out guards when a murderer comes into range, for instance, if you're in a guarded region.
When Triggered
objInRange comes into visible range of pChar. pChar's script is activated
Usable in Global script? No
Notes
Only triggers once per object that comes within range, and will not trigger for that object again unless it goes out of range and then comes in range again. The range is dependent on pChar's update range, which for players is partially controlled by the client and can be up to 24 tiles away depending on the client version (before 7.0.55.27 max range is 18, after it's 24).
Example of usage
function inRange( pChar, objInRange )
{
if( objInRange.isItem ) // An item came into range
{
pChar.DoStaticEffect( 0x376A, 9, 0, ); // Make some sparkles!
if( objInRange.id == 0x1416 ) // Ooh, it's a purty piece of armour
{
pChar.EmoteMessage( "*ooooooooooooo*" );
}
}
}Prototype
function outOfRange( pChar, objVanish )
Purpose
To take actions based on when things go out of range. For instance, if you ran out of range of your attacker, you might decide to automatically try and hide.
When Triggered
When objVanish goes out of range of pChar, pChar's script is activated
Notes
Only triggers once per object that goes out of range, and will not trigger for that object again unless it comes back into range and then goes out of range again. The range is dependent on pChar's update range, which for players is partially controlled by the client and can be up to 24 tiles away depending on the client version (before 7.0.55.27 max range is 18, after it's 24).
Example of usage
function outOfRange( pChar, objVanish )
{
if( objVanish.isChar ) // A character went out of range
{
pChar.DoStaticEffect( 0x376A, 9, 0, ); // Make some sparkles!
if( objVanish.id == 0x0017 ) // it's a direwolf!
{
pChar.TextMessage( "Phew, I escaped the wolf!" );
}
}
}Prototype
function onAISliver( npcChar )
Purpose
Great for creating custom AI behaviours, while being mindful of the fact that the event runs every single AI when attached to an NPC. Optimization of how much work the script does per cycle can be important to keep performance up if having many NPCs with the event active.
When Triggered
Every AI loop, during their AI slice
Return Values
Example of usage
// This example would probably be better handled using the onStatChange event, but is included here to show how it'd work with the onAISliver event
function onAISliver( aiChar )
{
// If RandomNumber equals 0, and aiChar is still alive...
if( !RandomNumber( 0, 49 ) && !aiChar.dead )
{
// If health is below 25%...
if((( aiChar.health * 100 ) / aiChar.maxhp ) < 25 )
{
// ... and aiChar is not already in "berserk mode"...
if( !aiChar.GetTag( "zerkMode" ))
{
// ... enter berserk mode!
aiChar.EmoteMessage( "*enters berserk mode*" );
aiChar.SetTag( "zerkMode", true );
// Set temp buff stats to equal real stats in order to temporarily boost that stat by 2x
aiChar.tempdex = aiChar.dexterity;
aiChar.tempint = aiChar.intelligence;
aiChar.tempstr = aiChar.strength;
}
}
else
{
// If health is above or equal to 25%...
if( aiChar.GetTag( "zerkMode" ))
{
// ... exit berserk mode!
aiChar.EmoteMessage( "*exits berserk mode*" );
aiChar.SetTag( "zerkMode", false );
// Revert temp buff stats
aiChar.tempdex -= aiChar.actualDexterity;
aiChar.tempint -= aiChar.actualIntelligence;
aiChar.tempstr -= aiChar.actualStrength;
}
}
}
return false;
}Prototype
function onAttack( pAttacker, pDefender )
Purpose
Flesh out attacking code/add additional effects to attacks.
When Triggered
After pAttacker has attacked pDefender in each "round" of combat
Notes
After pAttacker's script has been triggered, pDefender's onDefense event also triggers. Note that these events run in addition to hard-coded combat (and/or other combat events), after everything else is done, and do not replace these.
Example of usage
function onAttack( pAttacker, pDefender )
{
pAttacker.TextMessage( "Who lives in that castle?" );
pDefender.TextMessage( "Help! Help! I'm being repressed!" );
}Prototype
function onBuy( pSock, Vendor )
Purpose
To allow more control over who can access NPC vendors.
When Triggered
Runs on NPC vendor before trade gump opens
Return Values
Notes
Can be used to completely block access to a vendor based on criteria of one's choosing!
Example of usage
function onBuy( pSock, Vendor )
{
// If player does not belong to the undead race, vendor wants nothing to do with him!
if( pSock.currentChar.raceID != 11 )
{
Vendor.TextMessage( "Sorry, I don't sell to the likes of you!" );
return false;
}
return true;
}Prototype
function onBuyFromVendor( pSock, npcVendor, iBought )
Purpose
To allow restricting the purchase of specific items
When Triggered
Runs on item after player verifies purchase, but before purchase has gone through
Return Values
Example of usage
function onBuyFromVendor( pSock, npcVendor, iBought )
{
var pUser = pSock.currentChar;
pUser.TextMessage( "I am buying an item ("+iBought.name+") from a vendor!" );
npcVendor.TextMessage( "I am selling an item!" );
return true;
}Prototype
function onBoughtFromVendor( pSock, npcVendor, iBought )
Purpose
To allow manipulating the item that has been bought, immediately after it reaches the player's backpack.
When Triggered
Runs on item after purchase has gone through and item has reached player's backpack.
Return Values
Notes
Used, amongst other things, for automatically turning pet-statues bought from animal-trainers into actual pets.
Example of usage
function onBoughtFromVendor( pSock, npcVendor, iBought )
{
var pUser = pSock.currentChar;
pUser.TextMessage( "I bought an item ("+iBought.name+") from a vendor!" );
npcVendor.TextMessage( "I just sold an item to some random dude!" );
return true;
}Prototype
function onCallback#( socket, target )
Purpose
To handle callbacks from targeting cursors
When Triggered
Triggered for player who selects a target initiated from a CustomTarget method
Notes
# behind onCallback function-name in prototype is linked to the ID used in the CustomTarget method that initiated the targeting cursor, and should use the same value
Example of usage
// The following example includes the registration and handling of a 'disconnect GM command, which then prompts the GM to select a target, but note that CustomTarget + onCallback event combination an also be used in any other scripts/events.
function CommandRegistration()
{
// Register a new GM command
RegisterCommand( "disconnect", 2, true );
}
function command_DISCONNECT( socket, cmdString )
{
// Fetch system message 196 from dictionary files
var targMsg = GetDictionaryEntry( 196, socket.Language );
// Prompt GM to select a target
socket.CustomTarget( 0, targMsg );
}
// This onCallback event is called for a target selected with a target cursor initiated with CustomTarget ID 0
function onCallback0( socket, ourObj )
{
// Ensure a valid target has been selected before continuing
if( !socket.GetWord( 1 ) && ValidateObject( ourObj ) && ourObj.isChar && ourObj.online )
{
var targSock = ourObj.socket;
if( targSock && targSock != socket )
{
socket.SysMessage( GetDictionaryEntry( 1029, socket.Language ) );
targSock.SysMessage( GetDictionaryEntry( 1030, targSock.Language ) );
// Disconnect the target player
targSock.Disconnect();
}
}
}Prototype
function onCharDoubleClick( pUser, targChar )
Purpose
To allow greater customization of double-clicking on characters.
When Triggered
When pUser double-clicks targChar, targChar's script is activated
Return Values
Example of usage
function onCharDoubleClick( pUser, targChar )
{
targChar.TextMessage( "If you think you'll be allowed to see my paperdoll, think again!" );
return false;
}Prototype
function onClick( pSock, objClicked )
Purpose
To allow greater customization on clicking on items.
When Triggered
When a player single-clicks objClicked, objClicked's script is activated
Return Values
Notes
This event will also trigger for characters with script attached if AllNames client macro is used, and for incoming character names showing at edge of screen. Note that depending on client version, this event might not trigger when clicking certain types of objects, because clients more recent than X (?) won't send requests on click, but will instead send requests for details (including names) for all objects in range ahead of time, with name being displayed client-side on hover/click.
Example of usage
function onClick( pSock, objClicked )
{
pSock.SysMessage( "You have clicked on: "+objClicked.name );
objClicked.TextMessage( "Zug, zug!" );
return true;
}Prototype
function onCollide( targSock, pColliding, objCollidedWith )
Purpose
Replacement of collision based triggers, increase teleporter abilities, custom behaviour when pushing past other characters
When Triggered
When pColliding collides with objCollidedWith (stepped on basically)
Usable in Global script? No
Return Values
Notes
targSock is -1 if pColliding is an NPC
Example of usage
function onCollide( trgSock, srcChar, trgItem )
{
srcChar.Teleport( srcChar.x + 5, srcChar.y +5, srcChar.z, 0 );
srcChar.EmoteMessage( "*Eegads, I am teleported!*" );
return false;
}Prototype
function onAICombatTarget( pAttacker, pTarget )
Purpose
To allow overriding target selection for combat that normally takes place in hard-coded AI behaviours
When Triggered
When pAttacker loops through nearby characters as part of their AI behaviour, this event triggers once for every character found (pTarget) - or until event returns true
Usable in Global script? No
Return Values
Example of usage
function onAICombatTarget( pAttacker, pTarget )
{
// Don't attack NPCs with ai AI_HEALER_G (good aligned healers)
if( pTarget.aitype == 1 )
return false;
else
return true;
}
// See js/npc/ai/orcs.js for a more elaborate examplePrototype
function onCombatStart( pAttacker, pDefender )
Purpose
To allow overriding combat functionality
When Triggered
When pAttacker attacks someone, pAttacker's script is triggered.
Usable in Global script? No
Return Values
Example of usage
function onCombatStart( pAttacker, pDefender )
{
pAttacker.TextMessage( "I'm attacking!" );
pDefender.TextMessage( "I'm being attacked!" );
return true;
}Prototype
function onCombatEnd( currChar, targChar )
Purpose
Allow to override what happens when combat between two characters ends.
When Triggered
When either currChar or targChar dies or goes out of range, the script is fired for currChar
Usable in Global script? No
Return Values
Example of usage
function onCombatEnd( currChar, targChar )
{
if( currChar.health != 0 )
currChar.TextMessage( "Whee! I survived combat!" );
if( targChar.health != 0 )
targChar.TextMessage( "Yay! I survived combat!" );
return true;
}Prototype
function onCombatDamageCalc( attacker, defender, getFightSkill, hitLoc )
Purpose
Allow to override the combat damage calculation
When Triggered
Every time combat damage calculation occurs this event is fired for attacker
Usable in Global script? No
Return Values
Example of usage
function onCombatDamageCalc( pAttacker, pDefender, fightSkill, hitLoc )
{
// Get attacker's base damage
var baseDamage = pAttacker.attack;
if( baseDamage == -1 ) // No damage if weapon breaks
return 0;
// Apply hard-coded damage bonuses based on race weakness, character skills and stats, etc
var damage = ApplyDamageBonuses( 1, pAttacker, pDefender, fightSkill, hitLoc, baseDamage );
if( damage < 1 )
return 0;
// Apply hard-coded defense modifiers based on armor, resistances etc
damage = ApplyDefenseModifiers( 1, pAttacker, pDefender, fightSkill, hitLoc, damage, true);
// If damage after defense modifiers is below 0, do a small random amount of damage still
if( damage <= 0 )
damage = RandomNumber( 0, 4 );
// Half remaining damage by 2 if PUB15 or earlier
damage /= 2;
// If defender is a player, damage is divided by this modifier from uox.ini (modifier defaults to 1)
if( !pDefender.npc )
damage /= GetServerSetting( "NPCDAMAGERATE" );
return damage;
}Prototype
onCommand( mySock, cmdString )
Purpose
Can be used as a "catch-all" event for handling unknown commands (suggest other similar commands that actually exists, for instance?), or to implement multiple custom commands in the same script.
When Triggered
When player executes a command that's not otherwise handled by code or dedicated command scripts
Usable in Global script? No
Return Values
Example of usage
//Example 1
function onCommand( mySock, cmdString )
{
mySock.SysMessage( "Command entered: " + cmdString );
return false;
}
// Example 2
function onCommand( mySock, cmdString )
{
mySock.SysMessage( "Unknown command (" + cmdString + "). Try 'validcmd for a list of commands available to you, or 'howto for more info on specific commands." );
return true;
}Prototype
function onContRemoveItem( iCont, objRemoved, pChar )
Purpose
To allow reactions to items being removed from a container
When Triggered
When an item has already been removed from a container, script activates on container
Usable in Global script? No
Return Values
No return values supported
Example of usage
function onContRemoveItem( iCont, objRemoved, pChar )
{
// ... do something when an item has been removed from container
}
// For additional examples of how to use this event, check the following scripts in your UOX3 folder:
// js/server/misc/dungeon_treasure_decay.jsPrototype
function onCreateDFN( objMade, objType )
Purpose
Used for customization of players at creation, or tinkering with newly created items/NPCs
When Triggered
Usable in Global script (scriptID 0)? For NPCs/Items, No. For Players, Yes
Notes
Example of usage
// When this script is setup as "global id" (0) in JSE_FILEASSOCIATIONS.SCP,
// it will send the sysmessage to all NEW characters that enters the world.
function onCreateDFN( objMade, objType )
{
if( objType == 1 && !objMade.npc )
objMade.SysMessage( "Welcome to Our Unique World(TM)!" );
}Prototype
function onCreateTile( objMade, objType )
Purpose
Used for customization of non-DFN based items at creation.
When Triggered
When a non-DFN based item is created.
Usable in Global script (scriptID 0)? No
Notes
Example of usage
// Only scripts using script-id 0 or ones assigned through harditems.dfn will work with this event.
function onCreate( objMade, objType )/
{
objMade.name = "A renamed item";
}Prototype
function onDamage( damaged, attacker, damageValue, damageType )
Purpose
Custom reactions to damage, or to prevent damage from taking place
When Triggered
When the char "damaged" gets damaged
Usable in Global script? No
Return Values
Notes
The attacker can be a char or NULL, damageType is the type of damage being dealt. Supported damageTypes: 1 (Physical), 2 (Light), 3 (Rain), 4 (Cold/Ice), 5 (Heat/Fire), 6 (Lightning/Magic/Energy), 7 (Poison), 8 (Snow)
Example of usage
function onDamage( damaged, attacker, damageValue, damageType )
{
var dmgTypeString = "";
switch( damageType )
{
case 1:
dmgTypeString = "Physical";
break;
case 2:
dmgTypeString = "Light";
break;
case 3:
dmgTypeString = "Rain";
break;
case 4:
dmgTypeString = "Cold";
break;
case 5:
dmgTypeString = "Heat";
break;
case 6:
dmgTypeString = "Lightning/Magic";
return false; // Character is immune to Lightning/Magic damage!
case 7:
dmgTypeString = "Poison";
break;
case 8:
dmgTypeString = "Snow";
break;
}
damaged.TextMessage( "Ouch, those "+damageValue+" points of " + dmgTypeString + " damage really hurt." );
return true;
}Prototype
function onDeath( pDead, iCorpse )
Purpose
Add custom effect/behaviour after default death sequence
When Triggered
After the player or NPC pDead dies
Usable in Global script? No
Return Values
Notes
iCorpse is the newly created corpse of pDead (the character who died)
Example of usage
function onDeath( pDead, iCorpse )
{
// If pDead is a player, teleport them to a specific location after dying
if( !pDead.npc )
pDead.Teleport( 1000, 1000, 0 );
// Prevent other scripts with onDeath event from running
return true;
}Prototype
function onDeathBlow( pKilled, pKiller )
Purpose
Custom reactions after a killing blow has been made
When Triggered
When a killing blow has been made, this event triggers for pKilled
Usable in Global script? No
Return Values
Example of usage
function onDeathBlow( pDead, pKiller )
{
pDead.health = pDead.health + 10;
pDead.TextMessage( "But I'm not dead!" );
return false;
}Prototype
function onDecay( iDecayed )
Purpose
To interrupt the decay of items to do something special before it's deleted - or prevent the decay of certain items under any circumstance
When Triggered
When iDecayed is about to decay, the event triggers for iDecayed
Return Values
Notes
Note that if event returns false, yet never disabled decay for item, the event will keep triggering every time UOX3 checks item decay
Example of usage
function onDecay( iDecaying )
{
// Disable decay for the item so the event doesn't trigger again on next check!
iDecaying.decay = false;
iDecaying.decaytime = 10;
// Do something with the item and start a timer to delete it
iDecaying.TextMessage( "I don't feel so good..." );
iDecaying.StartTimer( 5000, 1, true );
// Return false to prevent code from actually decaying the item!
return false;
}
function onTimer( timerObj, timerID )
{
// Timer is up, go through with deletion of the item
timerObj.Delete();
}Prototype
function onDefense( pAttacker, pDefender )
Purpose
To allow customization/fleshing out of combat mechanics
When Triggered
When pAttacker attacks pDefender (in each "round" of combat), event triggers for pDefender, right after onAttack event is triggered for pAttacker
Notes
The event runs at the end of each hard-coded combat "round"
Example of usage
function onDefense( pAttacker, pDefender )
{
pAttacker.TextMessage( "Who lives in that castle?" );
pDefender.TextMessage( "Help! Help! I'm being repressed!" );
}Prototype
function onDelete( objDestroyed, objType )
Purpose
Add custom behaviour when certain items/NPCs are deleted via logging, world broadcasts, spawn new items, etc.
When Triggered
Right before an item or character is deleted from the server
Notes
Example of usage
function onDelete( objDestroyed, objType )
{
if( objType == 0 )
Console.Print( objDestroyed.name + " has been deleted from the world.\n" );
}Prototype
function onDispel( objDispelled, objType )
Purpose
Add custom behaviour for when an object is dispelled (such as letting NPCs resist being dispelled)
When Triggered
When objDispelled is dispelled, event in objDispelled's script is activated
Return Values
Notes
Example of usage
// Example 1
function onDispel( objDispelled, objType )
{
Console.Print( objDispelled.name + " has been dispelled.\n" );
}
// Example 2
function onDispel( objDispelled, objType )
{
// Check magic resistance of objDispelled
if( objType == 0 )
{
if(( objDispelled.skills.magicresistance / 10 ) > RandomNumber( 0, 100 ))
{
Console.Print( objDispelled.name + " resisted being dispelled!\n" );
return true;
}
}
return false;
}Prototype
function onDrop( iDropped, pDropper )
Purpose
Allowing control over dropping items from cursor
When Triggered
When pDropper drops iDropped, event in iDropped's script is activated
Return Values
Example of usage
function onDrop( iDropped, pDropper )
{
var pSock = pDropper.socket;
//Lets fetch the serial of the target-location
var temp1 = pSock.GetByte( 10 );
var temp2 = pSock.GetByte( 11 );
var temp3 = pSock.GetByte( 12 );
var temp4 = pSock.GetByte( 13 );
//Check the value of Byte 10 to determine if the target is ground, character or container
if( temp1 == 0 ) //Target is a character
{
var targetChar = CalcCharFromSer( temp1, temp2, temp3, temp4 )
pDropper.TextMessage( "I've dropped this item on a character named "+targetChar.name+", let's bounce it back." );
return false;
}
if( temp1 == 0xFF ) //Target is ground or another item
{
pDropper.TextMessage( "I've dropped this item on the ground or on another item." );
return true;
}
if( temp1 <= 0x40 ) //Target is a container
{
var targetItem = CalcItemFromItem( temp1, temp2, temp3, temp4 );
pDropper.TextMessage( "I've dropped this item in/on a container with ID "+targetItem.id+"." );
return true;
}
}Prototype
function onDropItemOnItem( iDropped, cDropper, iDroppedOn )
Purpose
Adding custom behaviour when dropping items on other items
When Triggered
When iDropped is dropped by cDropper on iDroppedOn, first event in iDropped's script is triggered, then if it doesn't bounce, same event is triggered for iDroppedOn
Return Values
Example of usage
function onDropItemOnItem( iDropped, cDropper, iDroppedOn )
{
if( iDropped.id == 0x1f14 ) //If the item being dropped is a recall rune
{
if( iDroppedOn.id == 0x0efa ) //If the item being dropped on is a spellbook
{
cDropper.TextMessage("I am dropping "+iDropped.name+" on a "+iDroppedOn.name );
return true;
}
}
else
{
cDropper.TextMessage( "Generic error message!" );
return false;
}
}Prototype
function onDropItemOnNpc( pDropper, pDroppedOn, iDropped )
Purpose
Adding custom behaviour when dropping items on NPCs
When Triggered
When iDropped is dropped on pDroppedOn, first event in iDropped's script is triggered, then if it doesn't bounce, same event is triggered for pDroppedOn
Return Values
Example of usage
function onDropItemOnNpc( pDropper, pDroppedOn, iDropped )
{
pDropper.TextMessage( "Here, I offer you my this object as a gift of friendship." );
// Move item to NPC's backpack, if he has one
var targPack = pDroppedOn.pack;
if( ValidateObject( targPack ))
{
pDroppedOn.TextMessage( "Wow! Exactly what I wanted, that's amazing!" );
iDropped.container = targPack;
return 2;
}
// Otherwise, reject the item drop and bounce it back where it came from
return false;
}Prototype
function onEnterEvadeState( mNPC, enemyChar )
Purpose
To allow custom reactions when NPCs enter evasion state. Could for instance have the NPC lash out in panic and destroy nearby dynamic, non-locked down and blocking items...
When Triggered
When mNPC enters evasion state in combat due to being unable to reach enemyChar, event triggers in mNPC's script
Return Values
Notes
As part of entering evasion state, the NPC's health will automatically be reset to maximum
Example of usage
function onEnterEvadeState( mNPC, enemyChar )
{
mChar.TextMessage( "I've entered the Evade state! My HP will be replenished..." );
enemyChar.TextMessage( "Oops, I caused the NPC to enter Evade state!" );
return true;
}Prototype
function onEnterRegion( pEntering, regionEntered )
Purpose
To allow custom reactions when players enter regions
When Triggered
When pEntering enters regionEntered, event is triggered in pEntering's script, before same event is triggered in regionEntered's script
Notes
Region-scripts can be attached to regions through regions.dfn, using one or more script=# tags
Example of usage
function onEnterRegion( pEntering, regionEntered )
{
if( pEntering.raceID != 11 )
{
//sound the alarm! non-undead intruder to region
//spawn undead guards
}
}Prototype
function onEntrance( iEntered, objEntering, objType )
Purpose
To allow custom behaviour/reactions when objects enter a multi
When Triggered
When objEntering enters the multi object iEntered, event triggers in iEntered's script, then same event triggers in objEntering's script
Return Values
Notes
Example of usage
function onEntrance( iEntered, objEntering, objType )
{
if( objType == 0 && !objEntering.npc )
objEntering.SysMessage("You have entered "+iEntered.name);
return false;
}Prototype
function onEquip( pEquipper, iEquipped )
Purpose
Can be used to apply special effects (stat changes, skill changes, VFX) when players equip certain items
When Triggered
When pEquipper equips iEquipped, event triggers in iEquipped's script
Return Values
Notes
Event will only ever trigger for items that can actually be equipped!
Example of usage
function onEquip( pEquipper, iEquipped )
{
pEquipper.StaticEffect( 0x376A, 9, 6 );
return false;
}Prototype
function onEquipAttempt( pEquipper, iEquipped )
Purpose
To allow overriding what happens when a player attempts to equip an item
When Triggered
When pEquipper attempts to equip iEquipped, event triggers in iEquipped's script
Return Values
Notes
This event runs before the onEquip event, and if script returns false, onEquip event will never run
Example of usage
function onEquipAttempt( pEquipper, iEquipped )
{
if( pEquipper.race == 0 )
{
pEquipper.TextMessage( "This item cannot be equipped by humans!" );
return false;
}
return true;
}Prototype
function onFall( pFall, fallDistance )
Purpose
Can be used to apply custom effects/behaviour (like taking damage) when character takes a fall (as determined by client!)
When Triggered
When pFall is determined by server to be falling, event triggers in pFall's script
Notes
pFall can be either an NPC or PC, will only trigger (by the client) if fallDistance is over 20, so it does not trigger whenever a character walks down steps/off small ledges/down hills, etc.
Example of usage
function onFall( pFall, fallDistance )
{
if( fallDistance > 20 )
pFall.SysMessage("Yikes! That was a long fall! I fell " + fallDistance + " meters!" );
}Prototype
function onFlagChange( pChanging, newStatus, oldStatus )
Purpose
To allow detecting and acting on flag changes, such as performing a special action when a player becomes a criminal or murderer.
When Triggered
When pChanging's flag (criminal system, innocent, criminal, murderer, etc) changes, event triggers in pChanging's script
Return Values
Notes
Might take a few seconds to trigger for NPCs after a flag update has taken place, based on what NPCFLAGUPDATETIMER in UOX.INI is set to.
Example of usage
function onFlagChange( pChanging, newStatus, oldStatus )
{
if( newStatus == 0x01 ) // Murderer
BroadcastMessage( "Announcement! " + pChanging.name + " has been declared a murderer, and may be killed on sight! Bounty available!" );
else if( newStatus == 0x02 ) // Criminal
BroadcastMessage( "Rumor has it that " + pChanging.name + " has fallen afoul of the law! Keep those coin purses safe!" );
else if( newStatus == 0x04 ) // Innocent
BroadcastMessage( "Good news, everyone! " + pChanging.name + " has returned to the straight and narrow path!" );
else if( newStatus == 0x08 ) // Neutral
BroadcastMessage( "Filthy neutrals like " + pChanging.name + "... you never know where you stand with them. It sickens me!" );
return false;
}Prototype
function onGumpInput( pSock, pButtonID, gumpText )
Purpose
To allow customizing behaviour from player input via old-school gump text entry dialogues
When Triggered
When text is entered and submitted via the old-school gump text entry dialogue
Notes
Gump text entry dialogue sent from server via packet 0xAB, response sent from client via packet 0xAC. Primarily used for stuff like entering gold donation amount in townstone menus, entering guild-name when creating/renaming guild, guild-abbreviation, guild master's title, guild-charter
Example of usage
function onGumpInput( pSock, pButtonID, gumpText )
{
var pUser = pSock.currentChar;
pUser.TextMessage( "I pressed a button with ID " + pButtonID );
pUser.TextMessage( "The text entry gump contained this text: " + gumpText );
}Prototype
function onGumpPress( pSock, pButton, gumpData )
Purpose
To allow reactions to button presses in gumps
When Triggered
When a player presses a button in a Gump from the same script
Notes
pButton is the button-ids for normal gump-buttons, while gumpData handles radiobutton-ids, checkbox-ids, and text-entry-ids(and the text-entries).
Example of usage
function onGumpPress( pSock, pButton, gumpData )
{
var pUser = pSock.currentChar;
switch(pButton)
{
case 0:
// abort and do nothing
break;
case 1:
var Text1 = gumpData.getEdit(0);
pUser.SysMessage( "The first TextEntry was: "+Text1 );
var Text2 = gumpData.getEdit(1);
pUser.SysMessage( "The second TextEntry was: "+Text2 )
var OtherButton = gumpData.getButton(0);
switch(RadioButton)
{
case 0:
pUser.SysMessage( "You selected RadioButton number: "+OtherButton );
pUser.DoAction( 15 );
break;
case 1:
pUser.SysMessage( "You selected RadioButton number: "+OtherButton );
pUser.DoAction( 11 );
break;
case 2:
pUser.SysMessage( "The Checkbox with ID "+OtherButton+" was checked." );
pUser.DoAction( 18 );
break;
}
break;
}
}Prototype
function onHelpButton( pChar )
Purpose
To allow overriding the behaviour of the Help button in the player paperdoll, for instance to do custom Help gumps
When Triggered
When a player clicks the Help button in their character paperdoll
Return Values
Example of usage
function onHelpButton( pChar )
{
pChar.TextMessage( "I pressed the Help button! Let's override the menu." );
// Do custom Help gump here
// ...
return false;
}Prototype
function onHouseCommand( pSocket, iMulti, cmdID )
Purpose
To bring house command handling from hard code to JS engine, making it easier to adjust and extend the housing system in the future.
When Triggered
When a player speaks a house command while inside a house, event triggers in iMulti's script
Return Values
Notes
cmdID is the ID of a triggerword uttered by the player. These triggerwords are defined client-side, and depending on the client version range from 0 to 255. See Speech tab in UOFiddler for a complete list!
Example of usage
function onHouseCommand( pSocket, iMulti, cmdID )
{
if( ValidateObject( iMulti ) && iMulti.IsInMulti( pSocket.currentChar ))
{
switch( cmdID )
{
case 34: // Remove Thyself
pSocket.CustomTarget( 0, "Who do you want to remove from your house?" );
break;
default:
Console.Log( "Unhandled house command detected with cmdID: " + cmdID );
return false;
}
}
return true;
}Prototype
function onHungerChange( pChanging, newStatus )
Purpose
To allow customization of behaviour when a character's hunger level changes. Could be used for wilding of pets, or for changing AI of monsters.
When Triggered
When a player's hunger level changes, event triggers in pChanging's script
Return Values
Notes
If overridden, the normal hunger messages are not displayed.
Example of usage
function onHungerChange( pChanging, newStatus )
{
pChanging.TextMessage( "ooooo, I feel more hungry" );
if( newStatus == 0 )
{
TextMessage( pChanging, "I'm melting, I'm melting!" );
}
return true;
}Prototype
function onIterate( object )
Purpose
To perform checks or make changes to each object iterated over by the IterateOver() function
When Triggered
When IterateOver() function is called from a script, event will trigger (in the same script) for every object the iterator comes across
Return Values
Notes
The IterateOver() function will return a count of all objects that onIterate returned true for.
Example of usage
function doStuff( socket, pUser )
{
socket.SysMessage( "Killing all NPCs (including invulnerable ones!)" );
var numKilled = IterateOver( "CHARACTER" );
socket.SysMessage( "Killed " + NumToString( numKilled ) + " NPCs " );
}
function onIterate( charCheck )
{
if( ValidateObject( charCheck ) && charCheck.npc )
{
charCheck.Kill();
return true;
}
return false;
}Prototype
function onLeaveRegion( pLeaver, regionLeft )
Purpose
To allow reactions when characters leave regions
When Triggered
When pLeaver leaves regionLeft, event first triggers in pLeaver's script, then triggers in regionLeft's script
Notes
Region-scripts can be attached to regions through on or more script=# tags in regions.dfn
Example of usage
function onLeaveRegion( pLeaver, regionLeft )
{
// if pLeaver is not allowed to leave the region
// turn him into a criminal and spawn guards to go after him!
}Prototype
function onLeaving( iMultiLeft, objLeaving, objType )
Purpose
To allow reaction to/custom behaviour for when an object leaves a multi
When Triggered
when objLeaving leaves iMultiLeft, event triggers in iMultiLeft's script, then event triggers in objLeaving's script
Return Values
Notes
Example of usage
function onLeaving( iLeft, objLeaving, objType )
{
if( objType == 0 && !objType.npc )
objLeaving.SysMessage( "You have left " + iLeft.name );
return false;
}Prototype
function onLightChange( myObject, lightLevel )
Purpose
To allow custom behaviour on objects when light level changes. Could for instance be used to automatically turn on lights/lamps when it becomes dark out, and turn them off when it becomes bright
When Triggered
Event triggers in script of myObject (char or item) when lightLevel changes
Return Values
Notes
Can also be put in global script (scriptID 0) to trigger for all objects
Example of usage
function onLightChange( myObject, lightLevel )
{
// (pseudo-code)
if( ValidateObject( myObject ) && myObject.isItem )
{
if( myObject.id == [insert_unlit_lamppost_id] )
{
if( lightLevel > 10 ) //high light levels = dark, low light levels = bright
{
myObject.id = [insert_lit_lamppost_id];
return true;
}
}
else if( myObject.id == [insert_lit_lamppost_id] )
{
if( lightLevel < 10 )
{
myObject.id = [insert_unlit_lamppost_id]
return true;
}
}
}
return false;
}Prototype
function onLogin( sockPlayer, pChar )
Purpose
To allow customization of what happens when a player logs in. Could pop up custom gumps, or do certain things (say everyone ALWAYS starts in one spot, no matter where they logged out. Diabloesque hall logins).
When Triggered
Event triggers for pChar's script when pChar logs in to the world
Notes
sockPlayer is never -1
Example of usage
function onLogin( sockPlayer, pChar )
{
pChar.Teleport( 1000, 1000, 0, 0 );
}Prototype
function onLogout( sockPlayer, pChar )
Purpose
To allow customization of what happens when a player logs out, like do certain things with the character (teleport them to a specific location, set some properties, etc)
When Triggered
Event triggers for pChar's script when pChar logs out of the world. Event can also be put in global script (with scriptID 0) to trigger for all player characters
Notes
sockPlayer is never -1
Example of usage
function onLogin( sockPlayer, pChar )
{
sockPlayer.SysMessage( "Farewell! Come back soon." );
}Prototype
function onMakeItem( socket, crafter, craftedItem, createEntryID )
Purpose
To allow special handling of newly crafted items.
When Triggered
Immediately after a character has attempted to craft an item, the even triggers in scripts attached to the character.
Notes
If character failed to create an item, the event still triggers, but craftedItem be null
Example of usage
function onMakeItem( socket, crafter, craftedItem, createEntryID )
{
// Have crafter say a message
if( ValidateObject( crafter ))
{
if( ValidateObject( craftedItem ))
{
crafter.TextMessage( "I crafted an item based on createEntryID " + createEntryID );
}
else
{
crafter.TextMessage( "I failed to craft an item with createEntryID " + createEntryID );
}
}
if( ValidateObject( craftedItem ))
{
// ... Do something with craftedItem
}
}Prototype
function onMoveDetect( srcObj, pChar, rangeToChar, oldCharX, oldCharY )
Purpose
To allow detection of movement near an object (items only, for now). Distance at which it triggers determined by part 1 of the item's MORE property.
When Triggered
When an object detects movement by a character nearby, based on range defined in item's MORE property
Notes
Use long ranges with care!
Example of usage
function onMoveDetect( srcObj, pChar, rangeToChar, oldCharX, oldCharY )
{
// .. do something when character is in range of object
}
// For examples of how this can be used, check out the following scripts in your UOX3 folder:
// js/server/misc/warning_trigger.js
// js/server/misc/dungeon_trap.jsPrototype
function onNameRequest( myObj, requestedBy )
Purpose
To allow better control of what names are sent to the client for a given object, by making it possible to override the object's name when it's requested. Can be used to create systems where players have to learn the names of other characters, or "incognito" systems, or even a setup where players can know each other by different names!
When Triggered
Event triggers for myObj whenever their name is retrieved by UOX3, if they have a script attached with the event present - or if the event is present in the global script (ID 0), in which case it would trigger for _all_ characters and items.
Return Values
Notes
Example of usage
function onNameRequest( myObj, requestedBy )
{
if( myObj.isChar )
{
if( ValidateObject( requestedBy ))
{
// Return "Unknown" as name when name is requested by another character who doesn't "know" myObj
if( requestedBy.serial != myObj.serial && !myObj.GetTag( "knowsMe" + requestedBy.serial ))
{
return "Unknown";
}
}
// Return an empty string (or true/false) to have UOX3 use/send the object's default name
return "";
}
}Prototype
function onPacketReceive( socket, packetNum, subCommand )
Purpose
Similar to "packet-hooks" in other emulators - allows overriding the handling of incoming network packets without modifying the server source-code
When Triggered
When receiving a network packet
Notes
OVERLOADPACKETS needs to be enabled in UOX.INI and each specific packet script must be registered in jse_fileassociations.scp and registered with UOX3 via the PacketRegistration/RegisterPacket functions. Note that subCommand is currently not supported; can be left as 0.
IMPORTANT: Once a packet has been registered this way, it needs to be handled in its entirety through the script, including any and all responses expected by the client. Not sending the correct response to a packet, or reading the wrong amount of bytes for the packet can result in unexpected behaviour in client/server.
Example of usage
function PacketRegistration()
{
RegisterPacket( [packetID], [subCommand] );
}
function onPacketReceive( pSocket, packetNum, subCommand )
{
var cmd = pSocket.GetByte( 0 );
if( cmd != packetNum )
return;
... // Read packet data here, using ReadBytes, GetByte, GetWord, GetDWord, GetSByte, GetSWord, GetSDWord and GetString socket methods
return;
}Prototype
function onPathfindEnd( tChar, pathfindResult )
Purpose
Can be used to detect and/or do something when NPC pathfinding comes to an end
When Triggered
When NPC pathfinding after JS methods WalkTo()/RunTo() comes to an end, event triggers in tChar's script
Return Values
Notes
pathfindResult parameter contains...
Example of usage
function onPathfindEnd( tChar, pathfindResult )
{
if( ValidateObject( tChar ))
{
tChar.TextMessage( "Pathfinding ended! Result of pathfinding was... ");
switch( pathfindResult )
{
case -1: // Pathfinding failed
tChar.TextMessage( "...a failure! I couldn't move at all." );
break;
case 0: // Pathfinding partially succeeded, but didn't make it all the way to target destination
tChar.TextMessage( "...a partial success! I made it part of the way there." );
break;
case 1: // Reached end of the path
tChar.TextMessage( "...a success! I reached my target location." );
break;
default:
tChar.TextMessage( "...a success? A failure? I have no idea. Result unknown!" );
break;
}
}
return true;
}Prototype
function onPickup( iPickedUp, pGrabber )
Purpose
To allow controlling whether characters are allowed to pickup certain items, or what happens if they do
When Triggered
When pGrabber picks up iPickedUp, the event triggers in iPickedUp's script
Return Values
Example of usage
function onPickup( iPickedUp, pGrabber )
{
var pSock = pGrabber.socket;
//Check the value of pSock.pickupSpot to determine where the item was picked up from
switch( pSock.pickupSpot )
{
case 0: //nowhere
pGrabber.TextMessage( "I picked up this item from... NOWHERE!" );
break;
case 1: //ground
pGrabber.TextMessage( "I picked up this item from the ground." );
break;
case 2: //ownpack
pGrabber.TextMessage( "I picked up this item from my own backpack." );
break;
case 3: //otherpack
pGrabber.TextMessage( "I picked up this item from a container." );
break;
case 4: //paperdoll
pGrabber.TextMessage( "I picked up this item from my paperdoll." );
break;
case 5: //bank
pGrabber.TextMessage( "I picked up this item from my bank box." );
break;
default:
pGrabber.TextMessage( "Error. Redo from Start." );
break;
}
//Use return false to disallow the pickup and bounce item
//return false;
}Prototype
function onQuestGump( pUser )
Purpose
To allow providing a response to players who click the Quest button in paperdoll, for instance by showing a custom quest gump?
When Triggered
Event triggers in pUser's script when quest button in paperdoll is pressed
Return Values
Example of usage
function onQuestGump( pUser )
{
pUser.TextMessage( "I pressed the Quest button in paperdoll!" );
return true;
}Prototype
function onRessurect( pAlive )
Purpose
To allow control over what happens when a player is returned to life
When Triggered
When a player pAlive is being resurrected, event triggers in pAlive's script
Return Values
Notes
Only applies to PCs, since NPCs cannot currently be in a state of "death" (they're either alive, or don't exist)
Example of usage
function onResurrect( pAlive )
{
var ResAmount = pAlive.GetTag( "ResAmount" );
if( ResAmount && ResAmount < 5 )
{
pAlive.SysMessage( "You still have some spirit left... have a good one!" );
return true;
}
else
{
pAlive.SysMessage( "You've resurrected too many times already! Have fun in the gray world... FOREVER!" );
return false;
}
}Prototype
function onScrollCast( pUser, spellID )
Purpose
To allow overriding spellcasting from magic scrolls
When Triggered
When a spell is cast using a magic scroll, event triggers in pUser's script
Return Values
Example of usage
function onScrollCast( pUser, spellID )
{
if( spellID == 18 )
{
pUser.TextMessage( "I'm casting a fireball from a fireball-scroll!" );
return -2;
}
}Prototype
function onScrollingGumpPress( pSock, gumpID, buttonID )
Purpose
To allow handling gump presses from old-school horizontally scrolling T2A gumps displayed in client via packet 0x76
When Triggered
When player clicks an entry in the old-school horizontally scrolling T2A gump displayed in client via packet 0x76, as long as said gump uses a gumpID between 0x4000 and 0xFFFF, and the event itself is present in the global script (script ID 0)
Example of usage
// The below example sends instructions to the client to open
// a horizontally scrolling gump with 4 options - one for Repair, one to craft Shields, one to craft
// Armor, and one to craft Weapons. Note that this example does not handle submenus sent after player press an
// initial option.
// For testing purposes, we double-click an item to open the gump
function onUseChecked( pUser, iUsed )
{
var socket = pUser.socket;
var pStream = new Packet; // Create new packet stream and reserve a size of 83 bytes
pStream.ReserveSize( 83 );
// Register packet ID 0x7c
pStream.WriteByte( 0, 0x7C );
// Send size of packet
pStream.WriteShort( 1, 0x0053 ); // 83 bytes
pStream.WriteLong( 3, 0x00000000 ); // Irrelevant?
pStream.WriteShort( 7, 0x5000 ); // ID of gump, must be between 0x4000 and 0xffff
// Register text at top of menu window
pStream.WriteByte( 9, 0x1d );
pStream.WriteString( 10, "What would you like to make?", 0x1d );
// Inform client we want to show 4 menu options
pStream.WriteByte( 39, 4 );
// Register menu option 1
pStream.WriteShort( 40, 0x0faf );
pStream.WriteShort( 42, 0x0000 );
pStream.WriteByte( 44, 6 );
pStream.WriteString( 45, "Repair", 6 );
// Register menu option 2
pStream.WriteShort( 51, 0x1b72 );
pStream.WriteShort( 53, 0x0000 );
pStream.WriteByte( 55, 6 );
pStream.WriteString( 56, "Shield", 6 );
// Register menu option 3
pStream.WriteShort( 62, 0x1415 );
pStream.WriteShort( 64, 0x0000 );
pStream.WriteByte( 66, 5 );
pStream.WriteString( 67, "Armor", 5 );
// Register menu option 4
pStream.WriteShort( 72, 0x13b9 );
pStream.WriteShort( 74, 0x0000 );
pStream.WriteByte( 76, 6 );
pStream.WriteString( 77, "Weapon", 6 );
// Send menu to player
socket.Send( pStream );
pStream.Free();
return false;
}
// Let's handle the player's clicks in the gump
function onScrollingGumpPress( pSock, gumpID, buttonID )
{
pSock.SysMessage( "I pressed button: " + buttonID + " in gump with ID " + gumpID );
// ... craft additional packets with submenu content etc. based on which button player clicked
}
Prototype
function onSell( pSock, Vendor )
Purpose
To allow greater control over who can sell stuff to specific vendors.
When Triggered
Event triggers for Vendor's script before trade gump opens
Return Values
Example of usage
function onSell( pSock, Vendor )
{
// If player does not belong to the undead race, vendor wants nothing to do with him!
if( pSock.currentChar.raceID != 11 )
{
Vendor.TextMessage( "RIGHT! As if I would buy from you..." );
return false;
}
else
return true;
}Prototype
function onSellToVendor( pSock, Vendor, iSold )
Purpose
To allow greater control over the selling of specific items to vendors
When Triggered
Event triggers for iSold's script after player verifies sale, but before sale has actually gone through
Return Values
Example of usage
function onSellToVendor( pSock, Vendor, iSold )
{
var pUser = pSock.currentChar;
pUser.TextMessage( "I am selling an item (" + iSold.name + ") to a vendor!" );
Vendor.TextMessage( "I am buying an item!" );
return true;
}Prototype
function onSoldToVendor( pSock, Vendor, iSold )
Purpose
To allow greater control over what happens after specific items have been sold to NPCs
When Triggered
Event triggers for iSold's script after the item has already been sold and has reached the NPC vendor's "bought items"-backpack
Return Values
Notes
If the item sold to the vendor stacks with items already there, the script will run on the entire stack, not just the one item specifically sold!
Example of usage
function onSoldToVendor( pSock, Vendor, iSold )
{
var pUser = pSock.currentChar;
pUser.TextMessage( "I sold an item (" + iSold.name + ") to a vendor!" );
Vendor.TextMessage( "I just bought an item from some random dude!" );
return true;
}Prototype
function onSkill( objUsing, skillUsed, objType )
Purpose
Complements the use of current skill code
When Triggered
When objUsing uses skill skillUsed, event triggers for objUsing's script. If no event is found, event directly attached to skill triggers instead. Fires before any existing skill usage code kicks in
Notes
If used with RegisterSkill() in a script listed under SKILLUSE_SCRIPTS in jse_fileassociations.scp, event will trigger for only the registered skill. If used in a stand-alone script listed under SCRIPT_LIST section instead, event will be a global listener for all skills used.
Example of usage
function onSkill( objUsing, skillUsed, objType )
{
switch( skillUsed )
{
case 0:
objUsing.TextMessage("Time to do some alchemy work!");
break;
case 1:
objUsing.TextMessage("Now using Anatomy skill!");
break;
case 2:
objUsing.TextMessage("Animal Lore usage Enabled!");
break;
//case etc.:
}
}Prototype
function onSkillChange( pPlayer, skill, skillChangeAmount )
Purpose
Allows you to take action when your skill level changes (positively or negatively)
When Triggered
This event is fired if onSkillLoss or onSkillGain return true, or if those events are not defined. If the events returned false, onSkillChange will not trigger
Example of usage
function onSkillChange( pPlayer, skill, skillChangeAmount )
{
if( skillChangeAmount > 0 )
pPlayer.TextMessage( "Oh wow, I've gained some points in skill number " + skill + "!" );
else
pPlayer.TextMessage( "Oh noes, I've lost some points in skill number " + skill + "!" );
}Prototype
function onSkillCheck( pUser, skillID, lowSkill, highSkill )
Purpose
For taking additional action when skillchecks are performed
When Triggered
Event triggers for pUser's script when a skillcheck is performed
Return Values
Notes
Runs just prior to skillcheck. lowSkill is minimum skill requirement for successful use of the skill (as passed into the skill check), while highSkill is the maximum skill the player can reach (as passed into the skill check)
Example of usage
function onSkillCheck( pUser, skillID, lowSkill, highSkill )
{
pUser.TextMessage( "A skillcheck is being done for skill with ID " + skillID + "!" );
return false;
}Prototype
function onSkillGain( pPlayer, skill, skillGainAmount )
Purpose
Allow preventing or taking special action before skill gain takes place
When Triggered
When pPlayer gains in skill skill
Return Values
Example of usage
function onSkillGain( pPlayer, skill, skillGainAmount )
{
pPlayer.TextMessage( "Aww, I was about to gain " + ( skillGainAmount / 10 ) + " points in skill number " + skill + ", but got denied!" );
return false;
}Prototype
function onSkillLoss( pPlayer, skill, skillLossAmount )
Purpose
Allow preventing or taking special action before skill loss takes place
When Triggered
Just before pPlayer loses skillLossAmount in skill skill
Return Values
Example of usage
function onSkillLoss( pPlayer, skill, skillLossAmount )
{
pPlayer.TextMessage( "Phew, I was about to lose " + ( skillLossAmount / 10 ) + " points in skill number " + skill + ", but it didn't happen!" );
return false;
}Prototype
function onSkillGump( pUser )
Purpose
For overriding the client's request to open the default skillgump
When Triggered
When pUser tries opening the skill-gump
Return Values
Example of usage
function onSkillGump( pUser )
{
pUser.SysMessage( "Overriding default skillgump, opening custom one instead..." );
// Insert custom skillgump here!
return false;
}Prototype
function onSnooped( pSnooped, pSnooping, bSuccess )
Purpose
To allow for behavioural change on snooping behaviour
When Triggered
After pSnooped snoops into pSnooping's pack
Return Values
Notes
bSuccess is true if snooping succeeded, false if it failed. If false, the script must handle things that would otherwise be handled by hard code, like turning snooper criminal, handling loss of karma, calling for guards, sending messages snooper/snooped, etc.
Example of usage
function onSnooped( pSnooped, pSnooping, bSuccess )
{
if( !bSuccess && !pSnooping.criminal )
{
pSnooped.TextMessage( "Oi! You! Stop snooping, or I'll call the guards!" );
pSnooping.criminal = true;
}
else if( !bSuccess && pSnopping.criminal )
{
pSnooped.TextMessage( "That's it, you've crossed the line! GUARDS!" );
}
}Prototype
function onSnoopAttempt( pSnooped, pSnooping )
Purpose
To allow for custom behaviour when players attempt to snoop into other characters' backpacks
When Triggered
When pSnooping attempts to snoop into pSnooped's pack
Return Values
Example of usage
function onSnoopAttempt( pSnooped, pSnooping )
{
pSnooping.SysMessage( "The target is protected and cannot be snooped!" );
return true;
}Prototype
function onSpeech( strSaid, pTalking, pTalkingTo )
Purpose
Greatly improve the speech handling capabilities
When Triggered
When pTalking says strSaid to pTalkingTo. pTalkingTo's script is activated. Can also trigger in item scripts, if ITEMSDETECTSPEECH is enabled in UOX.INI.
Return Values
Example of usage
function onSpeech( strSaid, pTalking, pTalkingTo )
{
// This is a simple mimic NPC. Everything that someone says to it is quoted back verbatim<
pTalkingTo.TextMessage( strSaid );
// Return value of 1 means NPC "absorbs" strSaid and doesn't allow other NPCs to see and react to it - though other PCs can still see it
return 1;
}Prototype
function onSpeechInput( pUser, pItem, pSpeech, pSpeechID )
Purpose
To allow action after speech-input has been requested
When Triggered
When the SpeechInput method is executed
Example of usage
function onUseChecked( pUser, iUsed )
{
pUser.SysMessage( "What do you want to rename this item to:" );
pUser.SpeechInput( 1, iUsed );
}
function onSpeechInput( pUser, iUsed, pSpeech, pSpeechID )
{
if( pSpeech == null || pSpeech == " ")
{
pUser.SysMessage( "You didn't type anything!" );
return;
}
switch( pSpeechID )
{
case 1:
pUser.SysMessage( "You rename the item to: "+pSpeech );
iUsed.name = pSpeech;
break;
}
}Prototype
function onSpecialMove( pUser, abilityID )
Purpose
To allow implementation of special abilities used during combat (or otherwise) when players toggle these from client.
When Triggered
Event triggers for pUser's script when player toggles a special move from a combat book in client
Return Values
Notes
Can be used in global scripts, or individual scripts attached to player characters. Lookup packet 0xD7, subCmd 0x19 in packet guides for updated details on special moves that are available, whose IDs range from 0x00 to 0x1D, or see list below (might be out of date):
0x00 = Cancel Ability Attempt
0x01 = Armor Ignore
0x02 = Bleed Attack
0x03 = Concusion Blow
0x04 = Crushing Blow
0x05 = Disarm
0x06 = Dismount
0x07 = Double Strike
0x08 = Infecting
0x09 = Mortal Strike
0x0A = Moving Shot
0x0B = Paralyzing Blow
0x0C = Shadow Strike
0x0D = Whirlwind Attack
0x0E = Riding Swipe
0x0F = Frenzied Whirlwind
0x10 = Block
0x11 = Defense Mastery
0x12 = Nerve Strike
0x13 = Talon Strike
0x14 = Feint
0x15 = Dual Wield
0x16 = Double shot
0x17 = Armor Peirce
0x18 = Bladeweave
0x19 = Force Arrow
0x1A = Lightning Arrow
0x1B = Psychic Attack
0x1C = Serpent Arrow
0x1D = Force of Nature
Server can send packet 0xBF, subCommand 0x21 to cancel the red highlighted state of the ability icon in the client, and reset the status of them.
Example of usage
// Example where a timer is used to disable special move after two seconds
function onSpecialMove( pUser, abilityID )
{
pUser.TextMessage( "I'm activating ability #" + abilityID );
pUser.StartTimer( 2000, abilityID, true );
return true;
}
function onTimer( timerObj, timerID )
{
// Toggle ability off after 2 second timer has elapsed
var toSend = new Packet;
toSend.ReserveSize( 7 )
toSend.WriteByte( 0, 0xbf ); // Packet
toSend.WriteShort( 1, 0x07 ); // Length
toSend.WriteShort( 3, 0x21 ); // SubCmd
toSend.WriteByte( 5, timerID ); // Ability ID
toSend.WriteByte( 6, 0 ); // On/off
timerObj.socket.Send( toSend );
toSend.Free();
}Prototype
function onSpellCast( pUser, spellID )
Purpose
To allow overriding spellcasting on a spell-per-spell basis
When Triggered
When any spell is cast
Return Values
Example of usage
function onSpellCast( pUser, spellID )
{
if( spellID == 18 )
{
pUser.CustomTarget( 0, "What do you want to target with your fireball?" );
return -1;
}
}Prototype
function onSpellGain( spellBook, spellNum )
Purpose
To allow doing something whenever spells are added to spellbooks
When Triggered
Triggered for spellbooks when spells are added to them
Notes
This event runs before the spell is actually added to the spellBook, and won't have any effect on whether this succeeds
Example of usage
function onSpellGain( spellBook, spellNum )
{
Console.Log( "Spell number " + spellNum + " was added to spellBook with serial " + spellBook.serial, "server.log" );
}Prototype
function onSpellLoss( spellBook, spellNum )
Purpose
To allow doing something whenever spells are removed from spellbooks
When Triggered
Triggered for spellbooks when spells are removed from them
Notes
This event runs before the spell is actually removed from the spellBook, and won't have any effect on whether this succeeds
Example of usage
function onSpellLoss( spellBook, spellNum )
{
Console.Log( "Spell number " + spellNum + " was removed from spellBook with serial " + spellBook.serial, "server.log" );
}Prototype
function onSpellSuccess( pCaster, spellID )
Purpose
To allow custom behaviour (or effects) after a spell has successfully been cast
When Triggered
When successfully casting a spell, event triggers in scripts attached to pCaster
Return Values
Example of usage
function onSpellSuccess( pCaster, spellID )
{
if( spellID == 18 )
{
pCaster.TextMessage( "Yes! I managed to cast a fireball!" );
}
return true;
}Prototype
function onSpellTarget( myTarget, myTargetType, pCaster, spellID )
Purpose
To allow custom behaviour when targeting specific objects with spells
When Triggered
When targeting something/someone with a spell, event triggers in myTarget's script
Notes
myTarget can be both items and characters. myTargetType will be 0 if myTarget is a char, and 1 if myTarget is an item
Return Values
Example of usage
// Script attached to an NPC that's immune to magic, where event returns 2 to reject spell being cast
function onSpellTarget( myTarget, myTargetType, pCaster, spellID )
{
var socket = pCaster.socket;
if( socket != null )
pCaster.SysMessage( GetDictionaryEntry( 9056, socket.language )); // That target is immune to magic!
return 2;
}Prototype
function onStatChange( pPlayer, stat, statChangeAmount )
Purpose
Allows taking action when a character's base stat changes (positively or negatively)
When Triggered
This event is fired if onStatLoss or onStatGained return true, or if those events are not defined. If the events returned false, onStatChange will not trigger. Stat numbers: Strength - 59, Dexterity - 60, Intelligence - 61
Example of usage
function onStatChange( pPlayer, stat, statChangeAmount )
{
if( statChangeAmount > 0 )
pPlayer.TextMessage( "Oh wow, I've gained some points in stat number " + stat + "!" );
else
pPlayer.TextMessage( "Oh noes, I've lost some points in stat number " + stat + "!" );
}Prototype
function onStatGained( pPlayer, stat, statGainedAmount )
Purpose
Allows taking action when a character's base stat is about to increase
When Triggered
When pPlayer gains statGainedAmount points in stat. Stat numbers: Strength - 59, Dexterity - 60, Intelligence - 61
Return Values
Example of usage
function onStatGained( pPlayer, stat, statGainedAmount )
{
pPlayer.TextMessage( "Aww, I was about to gain " + statGainedAmount + " points in stat number " + tat + ", but got denied!" );
return false;
}Prototype
function onStatLoss( pPlayer, stat, statLossAmount )
Purpose
For taking action when a person loses points in a stat
When Triggered
When pPlayer loses statLossAmount points in stat. Stat numbers: Strength - 59, Dexterity - 60, Intelligence - 61
Return Values
Example of usage
function onStatLoss( pPlayer, stat, statLossAmount )
{
pPlayer.TextMessage( "Phew, I was about to lose " + statLossAmount + " points in stat number " + stat + ", but it didn't happen!" );
return false;
}Prototype
function onSteal( pThief, iStolen, pVictim )
Purpose
Specialization of stealing
When Triggered
When iStolen is stolen from pVictim, iStolen's script is activated
Notes
Works, but gives a console error: ERROR: Chars[-1] referenced is invalid. Crash averted!
Return Values
Example of usage
function onSteal( pThief, iStolen, pVictim )
{
pThief.SysMessage( "You attempt to steal the "+iStolen.name );
pVictim.TextMessage( "Who does this hand in my pocket belong to???" );
ConsoleMessage( iStolen.name+" has been attempted stolen!" );
return false; // allow stealing code to run like normal
}Prototype
function onStolenFrom( pThief, pVictim, iStolen )
Purpose
To allow for response when items are stolen from a player/npc
When Triggered
When the player pThief steals the item iStolen from the character pVictim, the event in pVictim's script is triggered
Return Values
Example of usage
function onStolenFrom( pThief, pVictim, iStolen )
{
pVictim.TextMessage( "Hey you, get your hands off my banana!" );
pVictim.YellMessage( "GUARDS!!!!!!!" );
// Have pVictim attack pThief
pVictim.target = pThief;
pVictim.attackFirst = false;
pVictim.attacker = pThief;
pVictim.atWar = true;
// Prevent other scripts with event and/or hard-code from running
return true;
}Prototype
function onSwing( iSwung, pSwinging, pSwingAt )
Purpose
To allow more control over what happens when one character takes a swing at another in combat
When Triggered
When pSwinging swings iSwung at pSwingAt
Notes
Event can trigger for either pSwinging character or iSwung item, depending on which object script is attached to
Return Values
Example of usage
function onSwing( iSwung, pSwinging, pSwingAt )
{
pSwinging.TextMessage( "Have at thee, knave!" );
return true;
}Prototype
function onTalk( pTalking, strSaid )
Purpose
Greatly improve the speech handling capabilities
When Triggered
When pTalking says strSaid, pTalking's script is activated
Return Values
Example of usage
function onTalk( myChar, mySpeech )
{
// This is a simple script that will make the character talking perform the digging animation upon saying "'dig".
// (Note: 'DIG won't be displayed as speech, since script intercepts the text before it is spoken out loud)
// If anything else is said, the script returns true so speech can proceed as normal.
if( mySpeech == "'dig")
myChar.DoAction(11);
else
return true;
}Prototype
function onTempChange( myObject, temperature )
Purpose
To allow reactions for characters/items when temperature changes
When Triggered
Triggers for myObject (char/item) when temperature changes
Notes
Can also be put in a global script (script ID 0) to run for all objects
Example of usage
function onTempChange( myObject, temperature )
{
myObject.TextMessage( "I detected a temperature change! The temperature is now " + temperature + " degrees." );
}Prototype
function onTimer( timerObj, timerID )
Purpose
To be used for custom timer information for objects
When Triggered
When tempeffect 40 (StartTimer) duration has elapsed for timer timerID
Example of usage
function onTimer( timerObj, timerID )
{
if( timerID == 0 )
{
timerObj.StaticEffect( 0x376A, 9, 6 ); // Make some sparkles!
}
}Prototype
function onTooltip( myObject )
Purpose
To allow adding new/custom object properties for objects when server sends tooltip data to client
When Triggered
Triggers for object (char/item) when server is about to send tooltip data to client
Example of usage
// Display remaining uses left in a tooltip, based on item's UsesLeft tag
function onTooltip( myObj )
{
var tooltipText = "";
var usesLeft = myObj.GetTag( "UsesLeft" );
if( usesLeft > 0 )
{
tooltipText = GetDictionaryEntry( 9403 ); // uses remaining: %i
tooltipText = ( tooltipText.replace(/%i/gi, (usesLeft).toString()) );
// Set a temporary tag on item to tell server which cliloc ID to use for the tooltip
myObj.SetTempTag( "clilocTooltip", 1042971 ); // ~1_NOTHING~
}
return tooltipText;
}Prototype
function onUnequip( pEquipper, iUnequipped )
Purpose
To allow something to happen when player has finished unequipping an item
When Triggered
When pEquipper has unequipped iUnequipped, event is triggered in iUnequipped's script
Return Values
Example of usage
function onUnequip( pUnequipper, iUnequipped )
{
pUnequipper.StaticEffect( 0x376A, 9, 6 );
return false;
}Prototype
function onUnequipAttempt( pEquipper, iUnequipped )
Purpose
To allow overriding what happens when player attempts to unequip an item
When Triggered
When pEquipper attempts to unequip iUnequipped, event is triggered in iUnequipped's script
Return Values
Example of usage
function onUnequipAttempt( pUnequipper, iUnequipped )
{
if( /* check if item is cursed */ )
{
pUnequipper.TextMessage( "The item is cursed! You cannot unequip it..." );
return false;
}
return true;
}Prototype
function onUseBandageMacro( pSock, targChar, iUsed )
Purpose
To allow greater control of bandage self macro
When Triggered
When pSock uses iUsed on targChar
Notes
This can be put in the global script (scriptID 0) to handle what should happen when a player attempts to use the Bandage Self macro in the client
Return Values
Example of usage
function onUseBandageMacro( pSock, targChar, bandageItem )
{
if( pSock && bandageItem && bandageItem.amount >= 1 )
{
var pUser = pSock.currentChar;
TriggerEvent( 4000, "onUseCheckedTriggered", pUser, targChar, bandageItem );
}
return true;
}
// ...then, in scriptID 4000 - skill\healing.js, add this at the top of the file:
function onUseCheckedTriggered( pUser, targChar, iUsed )
{
if( pUser && iUsed && iUsed.isItem )
{
var socket = pUser.socket;
if( socket )
{
if( pUser.skillsused.healing || pUser.skillsused.veterinary )
{
socket.SysMessage( "You are too busy to do that." );
}
else if( socket.GetTimer( 0 ) <= GetCurrentClock() )
{
socket.tempObj = iUsed;
socket.SetTimer( 0, 5000 );
onCallback1( socket, targChar );
}
else
{
socket.SysMessage( GetDictionaryEntry( 473, socket.Language ) );
}
}
}
return true;
}Prototype
function onUseChecked( pUser, iUsed )
Purpose
To allow greater customization on using items
When Triggered
When pUser uses iUsed, iUsed's script is triggered
Return Values
Example of usage
function onUseChecked( pUser, iUsed )
{
// Open player's bank box, if they're within range of the item being used
var trgSock = pUser.socket;
if( pUser.InRange( iUsed, 8 ))
pUser.OpenBank( trgSock );
// Prevent hard-code from running
return false;
}Prototype
function onUseUnChecked( pUser, iUsed )
Purpose
To allow greater customization on using items
When Triggered
When pUser uses iUsed, iUsed's script is triggered
Notes
Unlike the onUseChecked event this one runs without any hardcoded checks like distance-check, LoS-check, etc. These will need to be handled in the script as needed!
Return Values
Example of usage
function onUseUnChecked( pUser, iUsed )
{
// Open player's bank box, if they're within range of the item being used
var trgSock = pUser.socket;
if(pUser.InRange( iUsed, 8 ))
pUser.OpenBank( trgSock );
// Prevent hard-code from running
return false;
}Prototype
function onVirtueGumpPress( mChar, tChar, buttonID )
Purpose
To allow a custom response/custom behaviour when player clicks Virtue Gump button in client paperdoll
When Triggered
When the Virtue Gump is pressed in the client's paperdoll
Notes
Can also be put in global script (scriptID 0) to trigger for all characters
Return Values
Example of usage
function onVirtueGumpPress( mChar, tChar, buttonID )
{
// .. open custom gump here
return true;
}Prototype
function onWarModeToggle( pChar )
Purpose
To allow reactions for characters/items when weather changes
When Triggered
Triggers for player pChar when they attempt to toggle war mode on/off
Notes
Can be put in global script (scriptID 0) to trigger for all player characters
Return Values
Example of usage
function onWarModeToggle( pChar )
{
pChar.TextMessage( "I tried toggling my war mode via the button in paperdoll, but was denied!" );
return false;
}Prototype
function onWeatherChange( myObject, weatherType )
Purpose
To allow reactions for characters/items when weather changes
When Triggered
Triggers for myObject (char/item) when weather changes
Notes
Can also be put in global script (scriptID 0) to trigger for all objects. Weather types: 0 = NONE, 1 = Physical (used for weapons/armor only), 2 = Light, 3 = Rain, 4 = Cold, 5 = Heat/Fire, 6 = Lightning/Energy, 7 = Poison, 8 = Snow, 9 = Storm, 10 = Storm Brewing
Example of usage
function onWeatherChange( myObject, weatherType )
{
myObject.TextMessage( "I detected a weather change! New weather-type: " + weatherType );
}Prototype
int AreaCharacterFunction( "myAreaFunc", radiusObject, radius, socket );
Purpose
Allows script to look for characters within specified radius of the defined radiusObject (Item or Character), and run a custom function for each Character found.
Notes
The custom script run for each Character found can return true or false to allow AreaCharacterFunction to return a value indicating how many characters were found (if all return true) or how many were altered in some way (if function only returns true when altering a character)
Example of usage
function onUseChecked( pUser, pSock );
{
var numCharsFound = AreaCharacterFunction( "myAreaFunc", pUser, 10, pSock );
pUser.SysMessage( "Number of characters found: " + numCharsFound );
}
function myAreaFunc( srcChar, trgChar, pSock )
{
trgChar.TextMessage( "Oh no I've been found!" );
pSock.SysMessage( "Found character: " + trgChar.name );
return true;
}
Prototype
CHARACTER CalcCharFromSer( serial );
Purpose
Returns the character object associated with the specified serial, or null if no character is found
Example of usage
var myChar = CalcCharFromSer( serial );Prototype
CHARACTER CalcTargetedChar( socket );
Purpose
Returns character object if target serial stored on socket is a character
Notes
Essentially a shortcut for doing this: var targetChar = CalcCharFromSer( socket.GetDWord( 7 ));
Example of usage
var targetChar = CalcTargetedChar( socket );Prototype
CHARACTER SpawnNPC( sectionName/npclist, x, y, z, worldNumber, instanceID, useNpcList )
Purpose
Spawns a character from a DFN entry or NPCLIST (sectionName)
Notes
sectionName can be an section ID from NPC DFNs to spawn from, or the name of an NPCLIST. useNpcList is a boolean to indicate if sectionName is a NPCLIST (true) or not (false). Defaults to false if not specified.
Example of usage
// Spawn a horse when an item is double-clicked
function onUseChecked( pUser, iUsed )
{
var nSpawned = SpawnNPC( "brownhorse", pUser.x, pUser.y, pUser.z, pUser.worldnumber, pUser.instanceID );
if( nSpawned != null )
pUser.SysMessage( "Wheee - a brown horse just spawned at my location!" );
}Prototype
int ApplyDefenseModifiers( dmgType, pAtt, pDef, skillNum, hitLoc, baseDmg, armorDmg );
Purpose
Returns a netDmg value after applying defense modifiers to baseDmg, with a boolean at the end deciding whether or not armor gets damaged.
Example of usage
var netDmg = ApplyDefenseModifiers( dmgType, pAtt, pDef, fightSkill, hitLoc, baseDmg, true );Prototype
int ApplyDamageBonuses( dmgType, pAttacker, pDefender, fightSkill, hitLoc, baseDmg );
Purpose
Returns a newDmg value after applying combat bonus modifiers to baseDmg
Example of usage
var newDmg = ApplyDamageBonuses( dmgType, pAttacker, pDefender, fightSkill, hitLoc, baseDmg );Prototype
int CommandLevelReq( cmdName );
Purpose
Returns the command level required to execute cmdName
Example of usage
if( CommandLevelReq( "add" ) <= pUser.commandlevel )
{
pUser.TextMessage( "I can execute the add command!" );
}Prototype
bool CommandExists( cmdName );
Purpose
Returns true if the command cmdName exists
Example of usage
if( !CommandExists( "fllerugh" ))
{
pUser.TextMessage( "No such command exists!" );
}Prototype
void CommandRegistration();
Purpose
Registers one or more scripted commands (using RegisterCommand function) in the JS command table
Notes
Each command registered using RegisterCommand( commandName, accessLevel, isEnabled ) within the CommandRegistration function will look for a function within the same script, the name of which is based on the command in question, using the syntax function command_[COMMANDNAME]( socket, cmdString )
Access levels (or command levels) are specified in dfndata/command/commands.dfn, and the default setup goes like this:
Example of usage
// Register two test commands in the same script
// First command is called "testcommand1", and can be accessed by GMs (command level 2) or above
// Second command is called "testcommand2", and can be accessed by Counselors (command level 1) or above
function CommandRegistration()
{
RegisterCommand( "testcommand1", 2, true );
RegisterCommand( "testcommand2", 1, true );
}
function command_TESTCOMMAND1( socket, cmdString )
{
socket.SysMessage( "You've successfully executed testcommand1!" );
}
function command_TESTCOMMAND2( socket, cmdString )
{
socket.SysMessage( "You've successfully executed testcommand2!" );
}Prototype
void DisableCommand( cmdName );
Purpose
Disables specified command on server
Example of usage
DisableCommand( "istats" );Prototype
void EnableCommand( cmdName );
Purpose
Enables specified command on server
Example of usage
EnableCommand( "istats" );Prototype
string FinishedCommandList();
Purpose
Returns true if there are no more commands left in the (hard-coded) command table
Example of usage
// Print first name of first command in the hard-coded command table
var cmdName = FirstCommand();
Console.Print( cmdName + "\n" );
// As long as there's commands left in the command table, print the next command name
while( !FinishedCommandList() )
{
cmdName = NextCommand();
Console.Print( cmdName + "\n" );
}Prototype
string FirstCommand();
Purpose
Returns the name of the first command in the (hard-coded) command table, or an empty string if there are no commands
Example of usage
var cmdName = FirstCommand();Prototype
string NextCommand();
Purpose
Returns the name of the next command in the (hard-coded) command table, or an empty string if there are no commands
Example of usage
var cmdName = NextCommand();Prototype
void RegisterCommand( commandName, commandLevel, isEnabled );
Purpose
Registers a scripted command in the JS command table, usually as part of the CommandRegistration function
Example of usage
RegisterCommand( "testcommand1", 2, true );Prototype
void DisableKey( keyCode );
Purpose
Disables specified key in console
Example of usage
DisableKey( 27 ); // Disables Esc key in UOX3 consolePrototype
void EnableKey( keyCode );
Purpose
Enables specified key in console
Example of usage
EnableKey( 27 ); // Enables Esc key in UOX3 consolePrototype
void RegisterKey( key/keyCode, functionName );
Purpose
When used in conjunction with the ConsoleRegistration event, it registers the current JS script as a global listener for a specific keypress in the UOX3 console, and triggers the specified function in the same script when that key is pressed.
Notes
Script must be added under the [CONSOLE_SCRIPTS] section of jse_fileassocations.scp to work.
Example of usage
// Example from js/console/shutdown.js
function ConsoleRegistration()
{
RegisterKey( 'q', "shutdown" );
RegisterKey( 'Q', "shutdown" );
RegisterKey( 27, "shutdown" ); // escape
}
function shutdown()
{
Console.BeginShutdown();
}Prototype
DoMovingEffect( srcObject, trgObject, effect, speed, loop, explode, [hue], [renderMode] );
DoMovingEffect( srcObject, targX, targY, targZ, effect, speed, loop, explode, [hue], [renderMode] );
DoMovingEffect( srcX, srcY, srcZ, targX, targY, targZ, effect, speed, loop, explode, [hue], [renderMode] );
Purpose
Does a moving effect (eg fireball) from srcObject to trgObject, from srcObject to targ location or from src location to targ location!
Notes
effect = the ID of the art effect to play
speed = the speed of the effect?
loop = ???
explode = 0 no explosion, 1 explodes
hue = the colour of the effect
rendermode = how to render the effect. Available options: 0 - normal, 1 - transparent, 2 - additive, 3 - dark colors transparent, 4 - bright colors transparent, 5 - semi transparent, 6 - subtractive/negative colors, 7 - inverted colors?
hue and renderMode are OPTIONAL, none, one or both can be left out, but if setting renderMode, hue MUST be specified. Hue for effects also seems to be offset by 1 compared to hues for items; if you have a staff with hue 0x0480 and you want an effect with same hue, try 0x047f for the effect (in some cases combined with a different renderMode - like 0xa for 0x047f)
Example of usage
DoMovingEffect( pUser, pUser, 0x36D5, 0x07, 0x00, true, 0x1EC );Prototype
void DoStaticEffect( targX, targY, targZ, effectID, speed, loop, explode );
Purpose
Plays a static effect at a target location
Notes
effectID = the ID of the art effect to play
speed = the speed of the effect?
loop = ???
explode = 0 no explosion, 1 explodes
Example of usage
DoStaticEffect( pUser.x, pUser.y, pUser.z, 0x352D, 0x3, 0x10, false );Prototype
void DoTempEffect( iType, srcObj, trgObj, tempEffectID, more1, more2, more3, [itemPtr] );
Purpose
Adds a temporary effect (things like protection, night sight, agility, etc.) to trgObj
Notes
Depending on the type of effect, the strength and/or duration can be derived from srcObj's skills or provided more# values. If iType = 0, then it's a character, otherwise it's an item
Note: Effect ID corresponds to tempEffectID in DoTempEffect function parameter
1 = Paralyze - duration either srcObj's Magery skill / 10, or more2 param if no srcObj
2 = NightSight - duration either srcObj's Magery skill / 2, or more2 param if no srcObj
3 = Clumsy - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect duration halved if resisted. Effect strength from more1 param
4 = Feeblemind - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect duration halved if resisted. Effect strength from more1 param
5 = Weaken - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect duration halved if resisted. Effect strength from more1 param
6 = Agility - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect strength from more1 param
7 = Cunning - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect strength from more1 param
8 = Strength - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect strength from more1 param
9 = Grind Necro Reagent - more2 is time it takes to finish grinding
10 = Craft Potion - ???
11 = Bless - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect strength from more1 param
12 = Curse - duration either srcObj's Magery skill / 10, or more2 param if no srcObj. Effect duration halved if resisted. Effect strength from more1 param
15 = Reactive Armor - duration either srcObj's Magery skill / 10, or 6 seconds if no srcObj
16 = Explosion Potion message - Used by JS script potion.js to show countdown for explosion potions. more1 is serial of potion, more2 is time until explosion, more3 is countdown #
18 = Polymorph - more1 is first part of polymorph ID, more2 is second part(?). Duration dependent on UOX.INI setting POLYDURATION (defaults to 90 seconds)
19 = Incognito - params not used, lasts 90 seconds
21 = Protection - duration either 120 seconds if srcObj exists, otherwise uses more2 param. Boosts trgObj's Parrying skill by value in more1 param for duration of effect
25 = Disable Item - disables item for duration specified in more1 param
26 = Temporarily Disable Potion Usage - disables usage of potions for a duration of 10 seconds
27 = Explosion - if srcObj is provided, will deal fire damage after delay set in Explosion spell definition, base amount of damage provided by more1 param, with srcObj as caster
28 = Magic Arrow - if srcObj is provided, will deal fire damage after delay set in Magic Arrow spell definition, base amount of damage provided by more1 param, with srcObj as caster
29 = Harm - if srcObj is provided, will deal cold damage after delay set in Harm spell definition, base amount of damage provided by more1 param, with srcObj as caster
30 = Fireball - if srcObj is provided, will deal fire damage after delay set in Fireball spell definition, base amount of damage provided by more1 param, with srcObj as caster
31 = Lightning - if srcObj is provided, will deal lightning damage after delay set in Lightning spell definition, base amount of damage provided by more1 param, with srcObj as caster
32 = Mind Blast - if srcObj is provided, will deal cold damage after delay set in Mind Blast spell definition, base amount of damage provided by more1 param, with srcObj as caster
33 = Energy Bolt - if srcObj is provided, will deal lightning damage after delay set in Energy Bolt spell definition, base amount of damage provided by more1 param, with srcObj as caster
34 = Chain Lightning - if srcObj is provided, will deal lightning damage after delay set in Chain Lightning spell definition, base amount of damage provided by more1 param, with srcObj as caster
35 = Flamestrike - if srcObj is provided, will deal fire damage after delay set in Flamestrike spell definition, base amount of damage provided by more1 param, with srcObj as caster
36 = Meteor Swarm - if srcObj is provided, will deal fire damage after delay set in Meteor Swarm spell definition, base amount of damage provided by more1 param, with srcObj as caster
40 = JS Timers - Special case. JS timers are added via the obj.StartTimer() function rather than DoTempEffect, and will not work correctly if added via DoTempEffect
41 = Crafting - crafting duration provided by more1 param (100 = 1.00 second), ID of item to craft via more2, crafter via srcObj
42 = Crafting Sound - delay for crafting sound effect provided via more1 param (100 = 1.00 second), sound FX to play provided via more2 param
43 = Regrow Sheep Wool - delay in seconds for when wool will regrow on a sheep provided via more1 param
Example of usage
// Add effect of a lesser Agility potion to pUser (copied from js/items/potion.js)
DoTempEffect( 0, pUser, pUser, 6, RandomNumber( 6, 15 ), 0, 0 );Prototype
int CompareGuildByGuild( srcGuild, trgGuild );
Purpose
Compares the relations between two guilds
Notes
Potential relationships:
Example of usage
var pUserGuild = pUser.guild;
var pCharGuild = pChar.guild;
if( pUserGuild && pCharGuild && CompareGuildByGuild( pUserGuild, pCharGuild ) == 2 )
{
pUser.TextMessage( "Oh hey, we're allied!" );
}Prototype
int AreaItemFunction( "myAreaFunc", radiusObject, radius, socket );
Purpose
Allows script to look for dynamic items within specified radius of the defined radiusObject (Item or Character), and run a custom function for each Item found.
Notes
The custom script run for each Item found can return true or false to allow AreaItemFunction to return a value indicating how many Items were found (if all return true) or how many were altered in some way (if function only returns true when altering an Item)
Example of usage
function onUseChecked( pUser, pSock );
{
var numItemsFound = AreaItemFunction( "myAreaFunc", pUser, 10, pSock );
pUser.SysMessage( "Number of characters found: " + numItemsFound );
}
function myAreaFunc( srcChar, trgItem, pSock )
{
trgItem.TextMessage( "Oh no I've been found!" );
pSock.SysMessage( "Found item: " + trgItem.name );
return true;
}
Prototype
ITEM CalcItemFromSer( serial );
Purpose
Returns the Item object associated with the specified serial, or null if no Item is found
Example of usage
var myItem = CalcItemFromSer( serial );Prototype
ITEM CalcTargetedItem( socket );
Purpose
Returns Item object if target serial stored on socket is a Item
Notes
Essentially a shortcut for doing this: var targetItem = CalcItemFromSer( socket.GetDWord( 7 ));
Example of usage
var targetItem = CalcTargetedItem( socket );Prototype
ITEM CreateBlankItem( socket, character, amount, itemName, itemID, colour, objectType, inPack );
Purpose
Spawns a "blank" item with values from the UO client's tiledata file.
Notes
Parameters:
Example of usage
function onUseChecked( pUser, iUsed )
{
var myItem = CreateBlankItem( pUser.socket, pUser, 10, "apple", 0x09d0, 0x0, "ITEM", true );
pUser.SysMessage( "Oh my, 10 apples just appeared in my backpack! Magic!" );
}Prototype
ITEM CreateDFNItem( socket, character, sectionToMake[, [int Amount], [objectType], [bool inPack] );
ITEM CreateDFNItem( null, null, sectionToMake, [int Amount], [objectType], [bool inPack], [int Color], [worldNumber], [instanceID] );
Purpose
Spawns an item from a DFN section number/id.
Notes
Parameters (check Prototype for correct order):
Example of usage
function onUseChecked( pUser, iUsed )
{
var myItem = CreateDFNItem( pUser.socket, pUser, "0x09d0", 10, "ITEM", true );
pUser.SysMessage( "Oh my, 10 apples just appeared in my backpack! Magic!" );
}
function onUseChecked( pUser, iUsed )
{
var myItem = CreateDFNItem( pUser.socket, pUser, "0x09d0", 10, "ITEM", false, 0x0001 );
iUsed.TextMessage( "Oh my, 10 black apples just spawned on top of me! Magic!" );
}
function onUseChecked( pUser, iUsed )
{
var myItem = CreateDFNItem( null, null, "0x09d0", 10, "ITEM", false, 0, iUsed.worldnumber, iUsed.instanceID );
iUsed.TextMessage( "Oh my, 10 apples just spawned on top of me! Magic!" );
}Prototype
ITEM FindItem( xLoc, yLoc, zLoc, world, idToCheck[, instanceID] );
Purpose
Returns item reference to item of given ID that is closest (within immediate nearby internal map regions) to specified coordinates
Example of usage
// Fetch item reference for item with id 0x04a9 closest to player's location
var closestItem = FindItem( pUser.x, pUser.y, pUser.z, pUser.worldnumber, 0x04a9 );Prototype
ITEM FindRootContainer( iObj );
ITEM FindRootContainer( iObjSerial );
Purpose
Finds the root container of a provided item object, or item object serial - if any
Notes
Parameters:
Example of usage
function onUseChecked( pUser, iUsed )
{
var rootContainer = FindRootContainer( iUsed );
if( ValidateObject( rootContainer ))
pUser.TextMessage( "The item is in a container! The root container's name is " + rootContainer.name );
else
pUser.TextMessage( "The item has no root container." );
}Prototype
ITEM GetItem( xLoc, yLoc, zLoc, world );
Purpose
Returns item closest to specified coordinates
Example of usage
// Find closest item to player's location
var closestItem = GetItem( pUser.x, pUser.y, pUser.z, pUser.worldnumber );Prototype
CHARACTER GetPackOwner( item/serial, argType );
Purpose
Returns owner of container item is contained in (if any)
Notes
If the first argument is an Item, argType should be 0. If first argument is an item serial, argType should be 1!
Example of usage
// Fetch owner of object based on object
var objOwner = GetPackOwner( myItem, 0 );
// Fetch owner of object based on object's serial
var objOwner = GetPackOwner( myItemSerial, 1 );Prototype
void DisableSpell( spellID );
Purpose
Disables specified spell on server
Example of usage
DisableSpell( 1 );Prototype
void EnableSpell( spellID );
Purpose
Enables specified spell on server
Example of usage
EnableSpell( 1 );Prototype
void RegisterSpell( spellID, enabledBool );
Purpose
If called from within SpellRegistration() function in a script registered under the [MAGIC_SCRIPTS] section of jse_fileassociations.scp, will register the onSpellCast() event in the same script as a global listener for use of the specified magic spell.
Example of usage
function SpellRegistration()
{
// Register script as global listener for spell 1 from spells.dfn
RegisterSpell( 1, true );
}
function onSpellCast( socket, character, directCast, spellNum )
{
// ...handle spell functionality here
}Prototype
bool CheckDynamicFlag( x, y, z, world, instanceID, tileFlagID );
Purpose
Check if any dynamic tile at given coordinates has specified tile flag.
Notes
Supported tileFlags:
0 - TF_FLOORLEVEL // "Background"
1 - TF_HOLDABLE // "Weapon"
2 - TF_TRANSPARENT // "SignGuildBanner"
3 - TF_TRANSLUCENT // "WebDirtBlood"
4 - TF_WALL // "WallVertTile"
5 - TF_DAMAGING // ??
6 - TF_BLOCKING // "Impassable"
7 - TF_WET // "LiquidWet"
8 - TF_UNKNOWN1 // "Ignored"
9 - TF_SURFACE // "Standable"
10 - TF_CLIMBABLE // "Bridge"
11 - TF_STACKABLE // "Generic"
12 - TF_WINDOW // "WindowArchDoor"
13 - TF_NOSHOOT // "CannotShootThru"
14 - TF_DISPLAYA // "Prefix A"
15 - TF_DISPLAYAN // "Prefix An"
16 - TF_DESCRIPTION// "Internal"
17 - TF_FOLIAGE // "FadeWithTrans"
18 - TF_PARTIALHUE // Partial hue can be applied to item (0x8000 + regular hue)
19 - TF_UNKNOWN2 // ??
20 - TF_MAP // ??
21 - TF_CONTAINER // ??
22 - TF_WEARABLE // "Equipable"
23 - TF_LIGHT // "LightSource"
24 - TF_ANIMATED // ??
25 - TF_NODIAGONAL // "HoverOver" in SA clients and later, to determine if tiles can be moved on by flying gargoyles
26 - TF_UNKNOWN3 // "NoDiagonal" in SA clients and later?
27 - TF_ARMOR // "WholeBodyItem"
28 - TF_ROOF // "WallRoofWeap"
29 - TF_DOOR // "Door"
30 - TF_STAIRBACK // "ClimbableBit1"
31 - TF_STAIRRIGHT // "ClimbableBit2"
// Following flags were added in HS expansion? Purpose unknown
32 - TF_ALPHABLEND
33 - TF_USENEWART
34 - TF_ARTUSED
35 - TF_NOSHADOW
36 - TF_PIXELBLEED
37 - TF_PLAYANIMONCE
38 - TF_MULTIMOVABLE
Example of usage
// Is there a tile with TF_BLOCKING flag at user's location?
var tileFlagFound = CheckDynamicFlag( pUser.x, pUser.y, pUser.z, pUser.worldnumber, pUser.instanceID, 6 );Prototype
bool CheckStaticFlag( x, y, z, world, tileFlagID );
Purpose
Check if any static tile at given coordinates has specified tile flag.
Notes
Supported tileFlags:
0 - TF_FLOORLEVEL // "Background"
1 - TF_HOLDABLE // "Weapon"
2 - TF_TRANSPARENT // "SignGuildBanner"
3 - TF_TRANSLUCENT // "WebDirtBlood"
4 - TF_WALL // "WallVertTile"
5 - TF_DAMAGING // ??
6 - TF_BLOCKING // "Impassable"
7 - TF_WET // "LiquidWet"
8 - TF_UNKNOWN1 // "Ignored"
9 - TF_SURFACE // "Standable"
10 - TF_CLIMBABLE // "Bridge"
11 - TF_STACKABLE // "Generic"
12 - TF_WINDOW // "WindowArchDoor"
13 - TF_NOSHOOT // "CannotShootThru"
14 - TF_DISPLAYA // "Prefix A"
15 - TF_DISPLAYAN // "Prefix An"
16 - TF_DESCRIPTION// "Internal"
17 - TF_FOLIAGE // "FadeWithTrans"
18 - TF_PARTIALHUE // Partial hue can be applied to item (0x8000 + regular hue)
19 - TF_UNKNOWN2 // ??
20 - TF_MAP // ??
21 - TF_CONTAINER // ??
22 - TF_WEARABLE // "Equipable"
23 - TF_LIGHT // "LightSource"
24 - TF_ANIMATED // ??
25 - TF_NODIAGONAL // "HoverOver" in SA clients and later, to determine if tiles can be moved on by flying gargoyles
26 - TF_UNKNOWN3 // "NoDiagonal" in SA clients and later?
27 - TF_ARMOR // "WholeBodyItem"
28 - TF_ROOF // "WallRoofWeap"
29 - TF_DOOR // "Door"
30 - TF_STAIRBACK // "ClimbableBit1"
31 - TF_STAIRRIGHT // "ClimbableBit2"
// Following flags were added in HS expansion? Purpose unknown
32 - TF_ALPHABLEND
33 - TF_USENEWART
34 - TF_ARTUSED
35 - TF_NOSHADOW
36 - TF_PIXELBLEED
37 - TF_PLAYANIMONCE
38 - TF_MULTIMOVABLE
Example of usage
// Is there a tile with TF_CLIMBABLE flag at user's location?
var tileFlagFound = CheckStaticFlag( pUser.x, pUser.y, pUser.z, pUser.worldnumber, 10 );Prototype
bool CheckTileFlag( tileID, tileFlag );
Purpose
Check if a specific tile ID has given flag
Notes
Supported tileFlags:
0 - TF_FLOORLEVEL // "Background"
1 - TF_HOLDABLE // "Weapon"
2 - TF_TRANSPARENT // "SignGuildBanner"
3 - TF_TRANSLUCENT // "WebDirtBlood"
4 - TF_WALL // "WallVertTile"
5 - TF_DAMAGING // ??
6 - TF_BLOCKING // "Impassable"
7 - TF_WET // "LiquidWet"
8 - TF_UNKNOWN1 // "Ignored"
9 - TF_SURFACE // "Standable"
10 - TF_CLIMBABLE // "Bridge"
11 - TF_STACKABLE // "Generic"
12 - TF_WINDOW // "WindowArchDoor"
13 - TF_NOSHOOT // "CannotShootThru"
14 - TF_DISPLAYA // "Prefix A"
15 - TF_DISPLAYAN // "Prefix An"
16 - TF_DESCRIPTION// "Internal"
17 - TF_FOLIAGE // "FadeWithTrans"
18 - TF_PARTIALHUE // Partial hue can be applied to item (0x8000 + regular hue)
19 - TF_UNKNOWN2 // ??
20 - TF_MAP // ??
21 - TF_CONTAINER // ??
22 - TF_WEARABLE // "Equipable"
23 - TF_LIGHT // "LightSource"
24 - TF_ANIMATED // ??
25 - TF_NODIAGONAL // "HoverOver" in SA clients and later, to determine if tiles can be moved on by flying gargoyles
26 - TF_UNKNOWN3 // "NoDiagonal" in SA clients and later?
27 - TF_ARMOR // "WholeBodyItem"
28 - TF_ROOF // "WallRoofWeap"
29 - TF_DOOR // "Door"
30 - TF_STAIRBACK // "ClimbableBit1"
31 - TF_STAIRRIGHT // "ClimbableBit2"
// Following flags were added in HS expansion? Purpose unknown
32 - TF_ALPHABLEND
33 - TF_USENEWART
34 - TF_ARTUSED
35 - TF_NOSHADOW
36 - TF_PIXELBLEED
37 - TF_PLAYANIMONCE
38 - TF_MULTIMOVABLE
Example of usage
// Checks if tile ID for iUsed has the TF_BLOCKING (6) flag
var doesTileBlock = CheckTileFlag( iUsed.id, 6 );Prototype
bool DoesDynamicBlock( x, y, z, world, instance, checkWater, waterWalk, checkOnlyMultis, checkOnlyNonMultis );
Purpose
Checks if dynamics at/above given location blocks character movement.
Notes
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 );Prototype
bool DoesMapBlock( x, y, z, world, checkWater, waterWalk, checkMultiPlacement, checkForRoad );
Purpose
Checks if map tile at given coordinates would block character movement.
Notes
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 );Prototype
bool DoesStaticBlock( x, y, z, world, checkWater );
Purpose
Check if statics at/above given location blocks character movement
Notes
Parameters: x, y, z, world = coordinates and worldnumber, checkWater = true if water should count as blocking, 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 );Prototype
int GetMapElevation( x, y, world );
Purpose
Returns the map elevation at specified coordinates
Example of usage
var mapElev = GetMapElevation( pUser.x, pUser.y, pUser.worldnumber );Prototype
int GetTileHeight( tileID );
Purpose
Returns the height of the static tile with specified ID.
Notes
Among other things, useful for getting the surface Z of targeted statics in client version 7.0.8.2 or lower, as these don't automatically include this in the target Z for socket as more recent clients do.
Example of usage
var tileHeight = GetTileHeight( tileID );Prototype
int GetTileIDAtMapCoord( xLoc, yLoc, worldNumber );
Purpose
Returns ID of the map tile at xLoc and yLoc in world worldNumber
Example of usage
// Get map tile ID at 0,0 in Felucca
var mapTileID = GetTileIDAtMapCoord( 0, 0, 0 );Prototype
void SendStaticStats( socket );
Purpose
Builds a gump with map or tile information for recently targeted location.
Example of usage
SendStaticStats( mSock );Prototype
bool StaticAt( xLoc, yLoc, worldNumber, tileID );
Purpose
Checks for static at specified location.
Notes
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 );
Prototype
bool StaticInRange( xLoc, yLoc, worldNumber, radius, tileID );
Purpose
Checks for static item within specified range of given location
Example of usage
// Checks for a static tile with ID 0x04a9 (wooden floor) within a 3 tile radius from pUser's location
var staticFound = StaticInRange( pUser.x, pUser.y, pUser.worldnumber, 3, 0x04a9 );
Prototype
int BASEITEMSERIAL();
int INVALIDSERIAL();
int INVALIDID();
int INVALIDCOLOUR();
Purpose
BASEITEMSERIAL() - 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.
INVALIDSERIAL() - Gets the constant defining an invalid serial. If an object serial matches this, it's invalid!
INVALIDID() - Gets the constant defining an invalid ID. If an object's ID matches this, it's probably not a valid ID!
INVALIDCOLOUR() - 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 baseItemSerial = BASEITEMSERIAL();
var invalidSerial = INVALIDSERIAL();
var invalidID = INVALIDID();
var invalidColour = INVALIDCOLOUR();
Prototype
PARTY CreateParty( partyleader );
Purpose
Create a new party/group with the specified character as leader
Example of usage
// Create a new party (myParty) with pUser as the leader
var myParty = CreateParty( pUser );Prototype
int DistanceBetween( x1, y1, x2, y2 );
int DistanceBetween( x1, y1, z1, x2, y2, z2 );
int DistanceBetween( objA, objB );
int DistanceBetween( objA, objB, checkZ );
Purpose
Get the distance between two sets of coordinates or objects on either 2D or 3D plane
Notes
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 );Prototype
int GetAccountCount();
Purpose
Gets the total amount of accounts on the server
Example of usage
var totalAccounts = GetAccountCount();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
// AoS bit from list of client features
var aosFeaturesEnabled = GetClientFeature( 0x10 );Prototype
string GetDictionaryEntry( entryNum [, language ] );
Purpose
Pulls entry from the dictionary file based on language (or server default, if no language parameter is ).
Example of usage
var textString = GetDictionaryEntry( 1, socket.language );Prototype
int GetMurderThreshold();
Purpose
Returns the number of kills needed to be branded as a murderer and turn red.
Notes
See also: Character .murderCount and .murderer properties
Example of usage
if( GetMurderThreshold() > pTalking.murderCount )
{
TextMessage( pTalkingTo, "Surely sir, you must be a murderer. I bid you adieu" );
EmoteMessage( pTalkingTo, "*scampers off*" );
}Prototype
int GetPlayerCount();
Purpose
Gets the total amount of players online on the server
Example of usage
var totalOnlinePlayers = GetPlayerCount();Prototype
SOSObject GetRandomSOSArea( worldNum, instanceID );
Purpose
Gets a random SOS area from list of such areas loaded from [SOSAREAS] section of regions.dfn
Example of usage
// Fetch reference to a random SOS area
var sosArea = GetRandomSOSArea( pUser.worldNum, pUser.instanceID );
// Pick a random location within the selected sosArea
var rndX = RandomNumber( sosArea[0], sosArea[2] );
var rndY = RandomNumber( sosArea[1], sosArea[3] );
// Add location to sos message item
sosMsg.morex = rndX;
sosMsg.morey = rndY;
sosMsg.morez = worldNum;
sosMsg.more = sosMsg.instanceID;
// See UOX3/js/item/waterstainedsos.js for full example, including validation for whether the chosen location is suitable, and not blocked by dynamic items, static items or map tilesPrototype
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
// ContextMenus bit from list of server features
var contextMenusEnabled = GetServerFeature( 0x08 );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
// Returns 1 if GUARDSACTIVE is set to 1 in UOX.INI, or 0 if set to 0.
var guardsActive = GetServerSetting( "GUARDSACTIVE" );Prototype
SOCKET GetSocketFromIndex( socketIndex );
Purpose
Create a socket-object based on the specified socketIndex
Example of usage
// Fetch whichever socket is connected to the server as socket/connection 0
var socket = GetSocketFromIndex( 0 );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.
Notes
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 );Prototype
int IterateOver( objectType );
Purpose
Iterates over all objects of specified type in the world.
Notes
For every object it comes across, the iterator will call a function onIterate( object ) in the same script. Supported object types: "BASEOBJ", "CHARACTER", "ITEM", "SPAWNER", "MULTI", "BOAT"
Example of usage
var itemCount = IterateOver( "ITEM" );
Console.log( itemCount + " items found!" );
...
function onIterate( myObject )
{
myObject.TextMessage( "I'm an item!" );
// ... optionally do something here
return true;
}Prototype
int Moon( moonNum );
void Moon( moonNum, newVal );
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 3Prototype
int RandomNumber( loNum, hiNum );
Purpose
Returns a random number between loNum (inclusive) and hiNum (inclusive)
Example of usage
var iNum = RandomNumber( 0, 10 );Prototype
void Reload( subSystemID );
Purpose
Dynamically reloads one (or all) of UOX3's subsystems without having to restart UOX3
Notes
Supported subSystemIDs:
Example of usage
// Reload all DFNs (and Skill system)
Reload( 4 );
// Reload INI file
Reload( 7 );Prototype
void ReloadJSFile( scriptID );
Purpose
Dynamically reloads script with specified scriptID from jse_fileassociations.scp without having to restart UOX3
Notes
Cannot be used to validate sockets
Example of usage
// Example of how this is used by 'reloadjsfile command
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 );
}
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
// Roll a DnD style dice of type 2d3+1 (2 dice with 3 faces, add 1 to result)
var mDie = RollDice( 2, 3, 1 );Prototype
bool/int/string/object TriggerEvent( scriptID, "functionName", argument1, argument2 );
Purpose
Calls script with specified scriptID, runs function in said script that matches "functionName", with the defined function arguments. The called upon script can return a value in the form of a boolean, int, string or an object
Example of usage
// Calls script with ID 8000 and runs function "onUseChecked" with function parameters pUser and iUsed
var returnVal = TriggerEvent( 8000, "onUseChecked", pUser, iUsed );
Prototype
TriggerTrap( pChar/pSock, iTrap );
Purpose
pChar/pSock triggers trap on iTrap object (if any trap is present on object)
Notes
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)
// Third (00) and Fourth (00) parts, unused here, normally indicate the min/max skill required to disarm trap
iTrap.morez = 0x01320000;
// Trigger the trap
TriggerTrap( pChar, iTrap );
Prototype
void UseItem( pSock/mChar, iToUse );
Purpose
To allow characters (and NPCs in particular) to trigger item-use functionality of items
Notes
Either a socket or a character can be passed in as a parameter of the UseItem function. If a socket is passed in, UOX3 will derive the character using the item from said socket.
Example of usage
// If an item has type 12, make NPC use the door to open it
if( myItem.type == 12 )
{
mChar.TextMessage( "A door! What's on the other side?" );
UseItem( mChar, iToUse );
}
Prototype
bool ValidateObject( object );
Purpose
Returns true if argument is a valid object (Item, Character, Multi, Boat, Spawner)
Notes
Cannot be used to validate sockets
Example of usage
if( !ValidateObject( iUsed ))
return;Prototype
[int] WorldBrightLevel( [lightlevel] );
Purpose
Get/Set the "maximum brightness" light-level for daytime across the entire world
Notes
If no parameter is provided, function will return current "maximum brightness" light-level for daytime instead.
Example of usage
// Set maximum world brightness level to 1
WorldBrightLevel( 1 );
// Get current maximum world brightness level
var lightLevel = WorldBrightLevel();
Prototype
[int] WorldDarkLevel( [lightlevel] );
Purpose
Get/Set the "minimum brightness" light-level for night-time across the entire world
Notes
If no parameter is provided, function will return current "minimum brightness" light-level for night-time instead.
Example of usage
// Set minimum world brightness level to 15
WorldDarkLevel( 15 );
// Get current maximum world brightness level
var lightLevel = WorldDarkLevel();
Prototype
[int] WorldDungeonLevel( [lightlevel] );
Purpose
Get/Set the fixed light-level for any regions marked as dungeons
Notes
If no parameter is provided, function will return current fixed light-level for dungeons instead.
Example of usage
// Set fixed dungeon light level to 12
WorldDungeonLevel( 12 );
// Get current fixed light level of dungeons
var lightLevel = WorldDungeonLevel();
Prototype
MULTI CalcMultiFromSer( serial );
Purpose
Calculates a multi object from a serial
Example of usage
var iMultiSerial = parseInt(pUser.GetTag( "iMultiSerial" ));
var iMultiSerial1 = ( iMultiSerial >> 24 );
var iMultiSerial2 = ( iMultiSerial >> 16 );
var iMultiSerial3 = ( iMultiSerial >> 8 );
var iMultiSerial4 = ( iMultiSerial % 256 );
var iMulti = CalcMultiFromSer( iMultiSerial1, iMultiSerial2, iMultiSerial3, iMultiSerial4 );Prototype
MULTI FindMulti( ourObj );
MULTI FindMulti( x, y, z, worldNumber[, instanceID] );
Purpose
Finds the multi that is in the area of the coordinates x, y, z, worldNumber (and optionally, instanceID), or in the area of the specified object
Notes
WorldNumbers: 0 = Felucca, 1 = Trammel, 2 = Ilshenar, 3 = Malas, 4 = Tokuno, 5 = Ter-mur
Example of usage
// Find Multi at pChar's location
var iMulti = FindMulti( pChar );
if( iMulti )
{
pChar.TextMessage( "You know, I'm standing in the same spot as a multi!" );
}
// Find Multi at specific set of coordinates (or in this case, myItem's location)
var iMulti = FindMulti( myItem.x, myItem.y, myItem.z, myItem.worldnumber );
if( iMulti )
{
myItem.TextMessage( "I am an item, in the same spot as a multi!" );
}Prototype
void RegisterPacket( packetID, subCommand );
Purpose
Register JS script as a global listener for a specific network packet
Notes
Triggers onPacketReceive() event in same script when this network packet is sent - IF script is added under the PACKET_SCRIPTS section of jse_fileassociations.scp, and the RegisterPacket() function is called from a PacketRegistration() function.
See also: [Script]Registration() and onPacketReceive() events
Example of usage
function PacketRegistration()
{
RegisterPacket( 0x05, subCommand );
}
function onPacketReceive( socket, packetNum, subCommand )
{
switch( packetNum )
{
case 0x05: //Request Attack sent from client
{
//do stuff??
break;
}
default:
break;
}
}Prototype
bool WillResultInCriminal( srcChar, targChar );
Purpose
Checks if hostile action done by one character versus another will result in criminal flag
Notes
Function compares flagging, race, guilds, aggressor flags, owners of each character to determine if a hostile action towards targChar would result in a criminal flag for srcChar
Example of usage
var willBeCriminal = WillResultInCriminal( srcChar, targChar );Prototype
int ResourceAmount( resourceType );
void ResourceAmount( resourceType, int );
Purpose
Used to get/set the maximum amount of resources per area of a specific resourceType ("ORE", "LOGS" or "FISH").
Example of usage
var maxLogAmount = ResourceAmount( "LOGS" );
//or...
ResourceAmount( "LOGS", 10 );Prototype
int ResourceArea( resourceType );
void ResourceArea( resourceType, int );
Purpose
Used to get/set the amount of resource areas to split the world into for a specific resourceType ("ORE", "LOGS" or "FISH").
Example of usage
var resourceAreas = ResourceArea( "ORE" );
//or...
ResourceArea( "ORE", 10 );Prototype
RESOURCEOBJ ResourceRegion( x, y, worldnumber );
Purpose
Returns a resource object allowing JS to modify resource data
Example of usage
var mResource = ResourceRegion( pUser.x, pUser.y, pUser.worldnumber );Prototype
int ResourceTime( resourceType );
void ResourceTime( resourceType, int );
Purpose
Used to get/set the spawn timer of a resourceType ("ORE", "LOGS" or "FISH").
Example of usage
var logTimer = ResourceTime( "LOGS" );
//or...
ResourceTime( "LOGS", 600 );Prototype
int GetRaceCount();
Purpose
Counts all Races available on the Server.
Example of usage
var totalRaceCount = GetRaceCount();Prototype
bool IsRaceWeakToWeather( raceID, weatherType );
Purpose
Returns true if race is weak to weatherType
Notes
The list of weather types are:
Example of usage
var myRace = pUser.race;
if( IsRaceWeakToWeather( myRace.id, 0 ))
{
pUser.TextMessage( "Eee, bright light!" );
}Prototype
int GetRaceSkillAdjustment( raceID, skillNum );
Purpose
Returns the % increase (or penalty) that raceID gets for skillNum.
Example of usage
var myRace = pUser.race;
if( GetRaceSkillAdjustment( myRace.id, 32 ) > 10 )
{
pUser.TextMessage( "Woah, that's a big increase to Spirit Speak you've got there!" );
}Prototype
int RaceCompareByRace( srcRaceID, trgRaceID );
Purpose
Returns the relationship of the two specified races.
Notes
If the relationship is 0, then they're neutral. If it's greater than 0 and less than 100, then they're allies. If it's less than 0 and greater than -100, then they're enemies.
Example of usage
if( RaceCompareByRace( pUser.race.id, pChar.race.id ) < 0 )
{
pUser.TextMessage( "Ahhh we hate each other, for some reason! Fight me!" );
}Prototype
MakeItem( socket, player, itemNum );
Purpose
Player makes the item itemNum. itemNum points to a create.dfn (SECTION ITEM itemNum) entry. Socket can be -1
Example of usage
MakeItem( socket, player, 1 );Prototype
MakeMenu( socket, menuID );
Purpose
Opens up make menu with specified ID and sends it to socket
Example of usage
MakeMenu( sock, 1 );Prototype
void BroadcastMessage( messageToSend );
Purpose
Sends messageToSend string to every client in the world
Example of usage
BroadcastMessage( "You're all going to die a hideous and painful death... j/k!" );Prototype
void Yell( socket, messageToYell, commandLevel );
Purpose
Globally sends the message to anyone matching the provided command level
Notes
Supported commandLevel values: 0 - Players, 1 - Counselors, 2 - GMs, 3 - Admins
Example of usage
Yell( pSock, "Isn't the world great?", 2 );Prototype
SpawnRegion GetSpawnRegion( spawnRegionNum );
Purpose
Returns SpawnRegion object for specified spawnRegionNum.
Example of usage
// Returns SpawnRegion object for spawn region #1 from spawns.dfn
var spawnRegion = GetSpawnRegion( 1 );
pUser.TextMessage( "The name of this SpawnRegion is: " + spawnRegion.name );Prototype
int GetSpawnRegionCount()
Purpose
Returns amount of SpawnRegions that exist.
Example of usage
// Get count of all spawn regions on the server
var spawnRegionCount = GetSpawnRegionCount();
pUser.TextMessage( "There are " + spawnRegionCount + " SpawnRegions on this server!" );
// Iterate through all spawn regions on the server
var spawnRegion;
for( var i = 0; i < spawnRegionCount; i++ )
{
spawnRegion = GetSpawnRegion( i );
Console.Print( "SpawnRegion Name: " + spawnRegion.name + "\n" );
}Prototype
int GetSpawnRegionFacetStatus( facetNum );
Purpose
Returns enabled state for Spawn Regions in specified facet (controlled by SPAWNREGIONSFACETS setting in UOX.INI, or SetSpawnRegionFacetStatus() method)
Notes
Function returns 0 if Spawn Regions are disabled for a given facet, or 1 if they're enabled
Example of usage
// Get enabled state for Spawn Regions in Felucca
var feluccaSpawnStatus = GetSpawnRegionFacetStatus( 0 );Prototype
void IterateOverSpawnRegions();
Purpose
Iterates over all SpawnRegions on the server.
Notes
For every object it comes across, the iterator will call onIterateSpawnRegions( SpawnRegionObject ) in the calling script.
Example of usage
var count = IterateOverSpawnRegions();
..
function onIterateSpawnRegions( toCheck )
{
Console.Print( "Spawn Region Number: " + toCheck.regionNum + "\n" );
Console.Print( "Spawn Region Name: " + toCheck.name + "\n" );
Console.Print( "Spawn Region World: " + toCheck.world + "\n" );
return true;
}Prototype
void SetSpawnRegionFacetStatus( spawnRegionFacetStatus );
void SetSpawnRegionFacetStatus( facetNum, newSpawnRegionStatus );
Purpose
Sets enabled state of spawn regions in a given facet (2 arguments) - or across all facets (1 argument)
Notes
The single-argument spawnRegionFacetStatus should be a bitmask with combined settings for which facets Spawn Regions should be enabled for:
Example of usage
// Enable Spawn Regions for Felucca specifically
SetSpawnRegionFacetStatus( 1, true );
// Enable Spawn Regions in Felucca, Ilshenar and Malas at the same time
SetSpawnRegionFacetStatus( 13 );Prototype
int GetCurrentClock();
Purpose
Returns a timestamp for current time
Example of usage
var iTime = GetCurrentClock();Prototype
int GetDay();
Purpose
Returns the day number of the server (UO days since server start)
Example of usage
var iDay = GetDay();Prototype
int GetHour();
Purpose
Returns the hour of the current UO day
Example of usage
var iHour = GetHour();Prototype
int GetMinute();
Purpose
Returns the minute of the current UO day
Example of usage
var iMin = GetMinute();Prototype
int GetStartTime();
Purpose
Returns a timestamp from when server was initially started up
Example of usage
var startupTime = GetStartTime();Prototype
int SecondsPerUOMinute();
void SecondsPerUOMinute( newNumSecs );
Purpose
Gets and sets the amount of real life seconds associated with a minute in the game
Example of usage
var iNumSecs = SecondsPerUOMinute();Prototype
REGION GetTownRegion( regionID );
Purpose
Returns a Region JS Object reference for specified region ID
Example of usage
// Fetch reference to a region (region ID from regions.dfn)
var townRegion = GetTownRegion( regionID );Prototype
void PossessTown( targetTown, sourceTown );
Purpose
Source town takes control over target town
Notes
???
Example of usage
// Fetch reference to source Town Region
var sourceTownRegion = GetTownRegion( sourceRegionID );
// Fetch reference to target Town Region
var targetTownRegion = GetTownRegion( targetRegionID );
// Have sourceTownRegion possess targetTownRegion
PossessTown( targetTownRegion, sourceTownRegion );Prototype
void AddScriptTrigger( scriptID )
Purpose
Adds a scriptTrigger to an object's list of scriptTriggers
Example of usage
myObject.AddScriptTrigger( 8000 );Prototype
void ApplySection( scriptSection )
Purpose
Applies a DFN section to an item/character
Example of usage
object.ApplySection( "orcishlord" );Prototype
void Delete()
Purpose
Deletes the object
Example of usage
myObject.Delete();Prototype
int DistanceTo( object )
Purpose
Returns the distance between two objects
Example of usage
objectOne.DistanceTo( objectTwo );Prototype
bool FinishedItems()
Purpose
Returns true if there are no more items left to look through in the container, character or multi
Example of usage
See FirstItem Method!Prototype
void FirstItem()
Purpose
Returns a handle to the first item in the container, character or multi. If it's null, then there are no items.
Example of usage
// Looping through all items equipped on character
// (including backpack, bankbox, hair, etc) upon clicking an item with script attached
function onUseChecked( pUser, iUsed )
{
var mItem;
for( mItem = pUser.FirstItem(); !pUser.FinishedItems(); mItem = pUser.NextItem() )
{
if( ValidateObject( mItem ))
{
pUser.SysMessage( "Item found on my character: " + mItem.name + " (" + mItem.id + ")" );
}
}
return false;
}// Looping through all items in character's backpack upon clicking an item with script attached
function onUseChecked( pUser, iUsed )
{
var mItem;
for( mItem = pUser.pack.FirstItem(); !pUser.pack.FinishedItems(); mItem = pUser.pack.NextItem() )
{
if( ValidateObject( mItem ))
{
pUser.SysMessage( "Item found in my backpack: " + mItem.name + " (" + mItem.id + ")" );
}
}
return false;
}// Looping through all items in a container upon using a container with script attached
function onUseChecked( pUser, iUsed )
{
var mItem;
for( mItem = iUsed.FirstItem(); !iUsed.FinishedItems(); mItem = iUsed.NextItem() )
{
if( ValidateObject( mItem ))
{
pUser.SysMessage( "Item found in container: " + mItem.name + " (" + mItem.id + ")" );
}
}
return false;
}Prototype
int GetJSTimer( timerID, scriptID );
bool SetJSTimer( timerID, timeInMilliseconds, scriptID );
bool KillJSTimer( timerID, scriptID );
Purpose
Gets or sets expiry timestamp for JS timer with specified timerID associated with specified scriptID, or kills timer completely
Notes
Example of usage
// (GetJSTimer) Fetches expiry timestamp for timer (ID 0) associated with a script (ID 4500, doors.js) on an object (an open door, in this example)
var expiryTimestamp = myDoor.GetJSTimer( 0, 4500 );
var currentTimestamp = GetCurrentClock();
pSock.SysMessage( "Timer expires in " + ((expiryTime - currentTime)/1000).toString() + " seconds." );
// (SetJSTimer) Sets expiry time (15 seconds from now) for an active timer (ID 0) associated with a script (ID 4500, doors.js) on object (an open door, in this example)
myDoor.SetJSTimer( 0, 15000, 4500 );
// (KillJSTimer) Kills a specific timer (ID 0) associated with a script (ID 4500, doors.js) on an object (an open door, in this example)
myDoor.KillJSTimer( 0, 4500 );
Prototype
int GetNumTags()
Purpose
Returns the number of Tags assigned to an Object.
Example of usage
pUser.SysMessage( "Number of Tags on targeted object: " + myTarget.GetNumTags() );Prototype
int GetSerial( part )
Purpose
Gets part (1-4) of an object's serial. An alternative is to use .serial object property instead, which fetches whole serial of object instead of just one part.
Example of usage
var iSerialPart1 = myItem.GetSerial( 1 );Prototype
boolean/int/string GetTag( "TagName" );
void SetTag( "TagName", value );
Purpose
Gets/Sets a persistent value (boolean/int/string) for the tag with name "TagName" on Object
Notes
The tags you store on Objects are persistent, which means they're stored in the worldsave.
Example of usage
// Store the value 42 in a tag called "myTag" on myObject
myObject.SetTag( "myTag", 42 );
// Spit out a system message with the value of "myTag" tag on myObject
pUser.SysMessage( "Value of persistent tag myTag on object: " + myObject.GetTag( "myTag" ));Prototype
boolean/int/string GetTempTag( "TagName" );
void SetTempTag( "TagName", value );
Purpose
Gets/Sets a temporary value (boolean/int/string) for the tag with name "TagName" on Object
Notes
Temporary tags are not persistent, and will not be stored in worldsaves. Good for tags that don't need to last past a server restart!
Example of usage
// Store the value 42 in a temporary tag called "myTag" on myObject
myObject.SetTempTag( "myTag", 42 );
// Spit out a system message with the value of "myTag" tag on myObject
pUser.SysMessage( "Value of temporary tag myTag on object: " + myObject.GetTempTag( "myTag" ));Prototype
bool HasSpell( spellNum )
Purpose
If used with a character, scans through player's backpack and looks for spell with ID spellNum in first spellbook found. If used with an item (such as a spellbook), looks for spell with ID spellNum in item.
Example of usage
// Check if player (pUser) has spell with ID 3
if( pUser.HasSpell( 3 ))
{
// Do something here...
}
// Check if a spellbook item (iUsed) has spell with ID 7
if( iUsed.HasSpell( 7 ))
{
// Do something here...
}Prototype
bool InRange( trgObj, distance )
Purpose
Returns true if the distance to trgObj is less than distance
Example of usage
if( myItem.InRange( trgObj, 18 ))
{
myItem.TextMessage( "trgObj is within range; it's closer than 18 tiles!" );
}Prototype
bool Killtimers( [timerID] );
Purpose
If no timerID is specified, kills all JS timers on the object. If timerID is specified, kills only specified JS timer on object regardless of script(!)
Example of usage
// Kills all JS timers on myObject
myObject.KillTimers();
// Kills JS timer(s) with ID 1 on myObject
myObject.KillTimers( 1 );Prototype
void NextItem()
Purpose
Returns the next item found in the container, character or multi
Example of usage
See FirstItem Method!Prototype
void Refresh();
Purpose
Causes the Character/Item to be refreshed for nearby sockets in range to see it
Example of usage
// Refreshes myObj by sending it to all nearby sockets
myObj.Refresh();Prototype
void RemoveScriptTrigger( scriptID )
Purpose
Removes a scriptTrigger from an object's list of scriptTriggers
Example of usage
myObject.RemoveScriptTrigger( 8000 );Prototype
void RemoveSpell( spellNum );
Purpose
Removes spellNum from spellbook (if method is run on a spellbook Item), or from first spellbook found in player's backpack (if run on a Character)
Example of usage
// Remove spellNum from first spellbook found in myChar's inventory
myChar.RemoveSpell( 0 );
// Remove spellNum from a specific spellbook Item
spellbookItem.RemoveSpell( 0 );Prototype
int Resist( type );
void Resist( type, value );
Purpose
Gets and sets the resistance values of a char or item.
Notes
Available item types:
Example of usage
// Set the Armor value of an item to 25:
mItem.Resist( 1, 25 );
// Get the armor value of an item:
value = mItem.Resist( 1 );Alias of Teleport Method
Prototype
void SoundEffect( soundID, bAllHear );
Purpose
Plays a sound originating from Character or Item.
Notes
Example of usage
// Play sound effect originating from myChar, which only myChar can hear
myChar.SoundEffect( 568, false );
// Play sound effect originating from myItem, which all other nearby characters can also hear
myItem.SoundEffect( 568, true );Prototype
void StartTimer( numMiliSec, timerID, callback );
Purpose
Starts a timer on Character/Item that will elapse after numMiliSec milliseconds pass.
Notes
timerID must be between 0 and 100. Resulting onTimer event will be triggered. Which script it triggers in depends on the (optional, defaults to false) third parameter, which can be true (calls back to existing script), false (calls back into object's script) or an int (scriptID to call back to). See also: onTimer event and KillTimers() BaseObject method.
Example of usage
// Timer calls back to myObj's script. myObj can be a Char or an Item
myObj.StartTimer( 600, 0, true );
// Timer calls back to current script
myObj.StartTimer( 1200, 0, false );
// Timer calls back to script with ID 2012
myObj.StartTimer( 1200, 0, 2012 );Prototype
void StaticEffect( effectID, speed, loop );
Purpose
Plays a static effect on Character/Item
Example of usage
myObj.StaticEffect( 0x376A, 9, 6 );Prototype
void Teleport();
void Teleport( object );
void Teleport( location );
void Teleport( x, y );
void Teleport( x, y, z );
void Teleport( x, y, z, world );
void Teleport( x, y, z, world, instanceID );
Purpose
Teleports Character/Item to specified location
Notes
If no parameter is provided, object is teleported to their current location and resent to all nearby players. location parameter refers to a location ID from dfndata/location/location.dfn
Example of usage
// Teleports object to Moonglow
myObj.Teleport( 4467, 1284, 5 );
// Teleports object to Lord British Castle Entrance location
myObj.Teleport( 21 );
// Teleports object to the location of an item iUsed
myObj.Teleport( iUsed );
Prototype
void TextMessage( message );
void TextMessage( message, allHear, txtHue )
void TextMessage( message, allHear, txtHue, speechTarget, speechTargetSerial, speechFontType );
void TextMessage( message, allHear, txtHue, speechTarget, speechTargetSerial, speechFontType, speechType );
Purpose
Sends a TextMessage for the Character/Item, which is displayed as speech, either to Character only or all nearby characters - depending on parameters
Notes
The function has 5 extra optional arguments (if including an optional parameter, make sure to also include the preceding argument):
Example of usage
myObj.TextMessage( "Hello world!" );
myChar.TextMessage( "Public, ice-coloured message sent to everyone as if I said it.", true, 0x0480 );
myChar.TextMessage( "Private, ice-coloured message just for me!", false, 0x0480 );
myItem.TextMessage( "This is a private message from an item to a character!", false, 0, 0, myChar.serial );
myItem.TextMessage( "THIS IS A MESSAGE IN RUNIC LETTERS VISIBLE TO ALL", true, 0, 3, null, 8 );Prototype
void UpdateStats( statType );
Purpose
Sends update to client with specified stat (health, mana or stamina) for object
Notes
Can be used with any character, as well as with items/multis with damageable flag enabled. Supported stat types:
Example of usage
// Update health stat for character or damageable object
myObj.UpdateStats( 0 );
// Update mana stat for character
myChar.UpdateStats( 1 );
// Update stamina stat for character
myChar.UpdateStats( 2 );Prototype
void AddFriend( pChar )
Purpose
Adds a player to an NPC pet/follower's friend list
Example of usage
myPet.AddFriend( pChar );Prototype
void AddSpell( spellNum )
Purpose
Adds specified spell to the first spellbook in character's pack
Example of usage
myChar.AddSpell( 3 ); //adds Feeblemind spell to myChar's spellbook (if he has one)Prototype
void BoltEffect()
Purpose
Plays the lightning bolt effect on specified character to all nearby players
Example of usage
myChar.BoltEffect();Prototype
void BreakConcentration()
void BreakConcentration( socket )
Purpose
Break a caster's concentration
Example of usage
myNPC.BreakConcentration(); //for NPCs, who have no sockets
myPlayer.BreakConcentration( mSocket ); //for players, who DO have socketsPrototype
void BuyFrom( targNPC )
Purpose
Brings up targNPC's shopkeeper gump or player vendor backpack for buying
Example of usage
myChar.BuyFrom( myNPC );Prototype
int CalculateControlChance( pChar );
Purpose
Returns chance (in values ranging from 0 to 1000) of pChar (player) successfully controlling a pet
Example of usage
var controlChance = myPet.CalculateControlChance( pChar );Prototype
bool CanSee( object );
bool CanSee( x, y, z );
Purpose
LineOfSight-checking; check if character/socket can see a specified object/target location
Example of usage
if( !myChar.CanSee( targetChar ))
return;
if( myChar.CanSee( targetChar.x, targetChar.y, targetChar.z )
{
// ...Do stuff here
}Prototype
void CastSpell( spellNum [, directCast])
Purpose
Causes character to cast spellNum. Character can be an NPC or PC, and spellNum can be any valid spell number from 0 to 65. The optional boolean parameter directCast can be used to make the character automatically cast the spell at their current target (if spell is targeted)
Example of usage
// Player casts recall spell
pUser.CastSpell( 32 );
// NPC casts lightning bolt at their current target
myNPC.CastSpell( 30, true );Prototype
bool CheckSkill( skillNum, minSkill, maxSkill )
bool CheckSkill( skillNum, minSkill, maxSkill, isCraftSkill )
Purpose
Returns true if the result of a skillcheck for skill skillNum is between minSkill and maxSkill
Notes
If the optional parameter isCraftSkill is set to true, UOX3 uses an alternate skill check formula that provides a minimum 50% chance of success if player at least meets minimum requirements for crafting an item
Example of usage
// If result of skill check for myChar's skill #1 (alchemy) is between 20.0 and 100.0
if( myChar.CheckSkill( 1, 200, 1000 ))
{
...
}Prototype
void ClearFriendList();
Purpose
Clears an NPC pet/follower's friend list
Example of usage
myPet.ClearFriendList();Prototype
void CustomTarget( targetNum, toSay )
Purpose
Very similar to PopUpTarget. It's a callback situation instead. targetNum must be between 0 and 255. Character says toSay, and is shown a cursor. Re-enters the script associated with the socket's player (i.e. player who gets the cursor). Enters function name based on the value of tNum. if tNum is 0, then the function would be onCallback0. Prototype of callback is:
function onCallback0( pSock, myTarget )
Example of usage
// User double-clicks an item, which brings up a custom target cursor
function onUseChecked( pUser, iUsed )
{
pUser.CustomTarget( 0, "Select your custom target:" );
}
// After player targets something, onCallback0 is called
function onCallback0( pSock, myTarget )
{
// ... do something with target here
}Prototype
void Damage( amount )
void Damage( amount, damageType )
void Damage( amount, damageType, attacker )
void Damage( amount, damageType, attacker, doRepSys )
Purpose
Cause damage to a character.
Notes
damageType represents the type of damage done (1 = Physical, 2 = Light, 3 = Rain, 4 = Cold, 5 = Heat, 6 = Lightning/Energy, 7 = Poison, 8 = Snow). doRepSys true/false defines whether a criminal check should be done for attacker
Example of usage
// Deal 15 damage to myChar (defaults to Physical damage)
myChar.Damage( 15 );
// Deal 15 Heat/Fire damage to myChar, with attackerChar as source
myChar.Damage( 15, 5, attackerChar );
// Deal 15 Lightning damage to myChar, with attackerChar as source, and flag set to do rep check for criminal flag
myChar.Damage( 15, 6, attackerChar, true );Prototype
int Defense( hitLoc, damageType, doArmorDamage )
Purpose
Returns the defense value against damageType of the armor item at the location hitLoc and does armor damage if needed
Notes
hit locations:0 = whole char, 1 = body, 2 = arms, 3 = head, 4 = legs, 5 = neck, 6 = the rest
damage types: 0 = None, 1 = Physical, 2 = Light, 3 = Rain, 4 = Cold, 5 = Heat, 6 = Lightning, 7 = Poison, 8 = Snow, 9 = Storm
Example of usage
// Get the defense value of the head armor against Physical damage and damage the armor:
value = mChar.Defense( 3, 1, true);Prototype
int DirectionTo( trgObj )
int DirectionTo( x, y );
Purpose
Returns the direction (0 = North, 1 = North-East, 2 = East, 3 = South-East, 4 = South, 5 = South-West, 6 = West, 7 = North-West) from character to trgObj/location
Example of usage
var dir = myChar.DirectionTo( trgChar );
var dir = myChar.DirectionTo( trgChar.x, trgChar.y );Prototype
void Dismount()
Purpose
Dismounts character
Example of usage
myChar.Dismount()Prototype
void DoAction( trgAction subAction )
Purpose
Makes character play the action trgAction. If subAction is specified, will play action using the "new" animation packet 0xE2, which supports subActions. This is also required for any gargoyle-specific animations.
Notes
Pre-v7.0.0.0:
Human/Elf actions range from 0x01 to 0x22.
Animals have animations in 0x00 to 0x0c range.
Monsters have animations in 0x00 to 0x15 range, though not all monsters support all these animations.
v7.0.0.0+:
All character actions range from 0x00 to 0x0f, with some animations registered as sub-actions
Example of usage
myChar.DoAction( 0x0B );
// or a gargoyle action & subAction
myChar.DoAction( 0x00, 0x03 );Prototype
CHARACTER Dupe();
Purpose
Dupes specified character
Notes
Location of duped character must be manually set
Example of usage
// Create a duplicate of myChar
var dupedChar = myChar.Dupe();
// Teleport the duped character to the same location as myChar
dupedChar.Teleport( myChar );Prototype
void EmoteMessage( message )
Purpose
Causes the Char to emote message. You have to put the start and end * manually in!
Example of usage
myChar.EmoteMessage( "*looks around*" );Prototype
void ExecuteCommand( cmdString )
Purpose
Executes the command cmdString (should include any params)
Example of usage
myChar.ExecuteCommand( "add 0x04a9" );Prototype
void ExplodeItem( myItem, damage, damageType, explodeNearby )
Purpose
Deletes specified item by exploding it, dealing damage to the character and potentially nearby characters
Example of usage
// Explode item and deal damage only to myChar
myChar.ExplodeItem( myItem, 25, 5, false );
// Explode item and deal damage to all characters within a radius of 2 tiles (hardcoded range)
myChar.ExplodeItem( myItem, 25, 5, true );Prototype
Item FindItemLayer( layer )
Purpose
A return value of -1 indicates there was no item at that particular layer. A common list of layers follow:
0x01 - Single-Hand item/weapon
0x02 - Two-Hand item/weapon (including Shield)
0x03 - Foot Covering/Armor
0x04 - Leg Covering (including Pants, Shorts, Bone/Chain/Ring legs)
0x05 - Chest Clothing/Female Chest Armor
0x06 - Head Covering/Armor
0x07 - Hand Covering/Armor
0x08 - Ring
0x09 - N/A (not used)
0x0A - Neck Covering/Armor
0x0B - Hair
0x0C - Waist (Half-Apron)
0x0D - Torso (inner)(Chest Armor)
0x0E - Bracelet
0x0F - N/A (no info)
0x10 - Facial Hair
0x11 - Torso (Middle)(Surcoat, Tunic, Full Apron, Sash)
0x12 - Earrings
0x13 - Arm Covering/Armor
0x14 - Back (Cloak)
0x15 - BackPack
0x16 - Torso (outer)(Robe)
0x17 - Legs (outer)(Skirt/Kilt)
0x18 - Legs (inner)(Leg Armor)
0x19 - Mount (Horse, Ostard, etc.)
0x1A - NPC Buy Restock Container
0x1B - NPC Buy No Restock Container
0x1C - NPC Sell Container
0x1D - Bank Box
Example of usage
var leftHand = myChar.FindItemLayer( 1 );Prototype
Item FindItemType( itemType )
Purpose
Look for items of a certain type in character's pack
Example of usage
var spellBook = myPlayer.FindItemType( 9 ); //does the player have a spellbook?Prototype
void Follow( followTarget )
Purpose
Forces NPC to follow specified target
Example of usage
myNPC.Follow( followTarget );Prototype
void Gate( item )
void Gate( x, y, z, world )
Purpose
Opens a gate to the location marked on an item, or to a specific set of coordinates
Example of usage
// Opens a gate to coordinates from a recall rune (targItem)
myChar.Gate( targItem );
// Opens a gate to Lord British's throne room
myChar.Gate( 1329, 1624, 50 );Prototype
FRIENDLIST GetFriendList();
Purpose
Gets an NPC pet/follower's friend list
Example of usage
// Get pet's friend list
var friendList = myPet.GetFriendList();
for( var i = 0; i < friendList.length; i++ )
{
if( ValidateObject( friendList[i] ))
{
myPet.TextMessage( friendList[i].name + " is my friend!" );
}
}Prototype
PETLIST GetPetList();
Purpose
Gets list of character's pets/followers
Example of usage
// Get myChar's pet/follower list
var petList = myChar.GetPetList();
for( var i = 0; i < petList.length; i++ )
{
if( ValidateObject( petList[i] ))
{
myChar.TextMessage( petList[i].name + " is my pet and/or follower!" );
}
}Prototype
int GetTimer( timerID )
int SetTimer( timerID, numMilliSeconds )
Purpose
Get/Set the time in milliseconds until specified timer expires for a Character object
Notes
Supported timerIDs for Characters
Timer.TIMEOUT // Time until next attack can be done in combat
Timer.INVIS // Time until invisible character becomes visible
Timer.HUNGER // Time until character grows more hungry
Timer.THIRST // Time until character grows more thirsty
Timer.POISONTIME // Time until next tick of poison damage
Timer.POISONTEXT // Time until next message about suffering from poison
Timer.POISONWEAROFF // Time until poison wears off
Timer.SPELLTIME // Time until spell cast is completed. Can be set to 0 to interrupt
Timer.SPELLRECOVERYTIME // Time until player has recovered from casting a spell
Timer.ANTISPAM // Time until next speech message can be sent (for anti spam purposes)
Timer.CRIMFLAG // Time until criminal flag runs out
Timer.MURDERRATE // Time until next murder count decay
Timer.PEACETIMER // Time until character can re-enter combat after being affected by peacemaking
Timer.FLYINGTOGGLE // Time until next time flying ability can be toggled for gargoyles
Timer.FIREFIELDTICK // Time until next fire field tick
Timer.POISONFIELDTICK // Time until next poison field tick
Timer.PARAFIELDTICK // Time until next paralyze field tick
Timer.MOVETIME // Time until NPC can move again
Timer.SPATIMER // Time until next time NPC can cast a spell
Timer.SUMMONTIME // Time until a summoned NPC will vanish
Timer.EVADETIME // Time until an NPC will exit evade state
Timer.LOYALTYTIME // Time until next time pet loyalty drops
Timer.LOGOUT // Time it takes for a player char to vanish after logoutSee also: GetTimer()/SetTimer() Socket Methods.
Example of usage
// Get remaining time in milliseconds before criminal flag expires
var criminalTimer = myChar.GetTimer( Timer.CRIMFLAG );
// Set time from now in milliseconds that criminal flag will last
myChar.SetTimer( timer.CRIMFLAG, 3000 );Prototype
bool HasBeenOwner( pChar );
Purpose
Returns whether character pChar has previously owned the pet (is on pet's owner list)
Example of usage
// Get myChar's pet/follower list
if( myPet.HasBeenOwner( pChar ))
{
myPet.TextMessage( "Hey, you owned me earlier, I'll let you tame me easier this time around!" );
}Prototype
void Heal( amount ); void Heal( amount, pHealer );
Purpose
Heals a character for specified amount, with optional argument to provide character who healed
Example of usage
myChar.Heal( 15 );
myChar.Heal( 15, healerChar );Prototype
bool InitiateCombat( targetChar );
Purpose
Attempts to initiate combat with target character
Example of usage
if( myNPC.InitiateCombat( otherChar ))
{
myNPC.TextMessage( "Yes! I managed to initiate combat with " + otherChar.name + "!" );
}Prototype
void InvalidateAttacker();
Purpose
Resets the attacker attack so that it cancels attack setup.
Example of usage
myNPC.InvalidateAttacker();Prototype
void InitWanderArea()
Purpose
Initialize a WanderArea (10x10 box, or 10 radius circle) for the specified NPC. Will only work if their wander-mode is already set to box or circle.
Example of usage
myNPC.InitWanderArea();Prototype
void Jail()
void Jail( numSecsToJail )
Purpose
Jails character for n seconds if specified. If no duration is specified, defaults to 24 hours.
Example of usage
myChar.Jail( 1000 );Prototype
void Kill()
Purpose
Kills the character. If onDeathBlow JS event is present for character's script, it triggers
Example of usage
myChar.Kill();Prototype
void MagicEffect( spellID )
Purpose
Applies spell effects of specified spell to character
Example of usage
myChar.MagicEffect( 43 );Prototype
void MakeMenu( menu )
Purpose
Opens up make menu menu and sends it to character's socket
Example of usage
// Can be used with a character
myChar.MakeMenu( 1 );
// Or with a socket
mySocket.MakeMenu( 1 );Prototype
void Mark( item )
Purpose
Marks an item with the characters current location to be used later for recall or gate
Example of usage
myChar.Mark( targItem );Prototype
void OpenBank( trgSock )
Purpose
Opens character's bank, sending it to trgSock
Example of usage
myPlayer.OpenBank( trgSock );Prototype
void OpenLayer( socket, layerToOpen )
Purpose
Opens the specified layer of the character for the specified socket
Example of usage
myChar.OpenLayer( socket, 0x15 );Prototype
void PopUpTarget( tNum, toSay )
Purpose
Provides a call to hard-coded targeting cursors.
Notes
tNum must be between 0 and 255 inclusive. Says toSay, and shows a cursor. Note that some of these might depend on factors in code to actually work, and might not have much effect when ran through a script - or could grant access to functionality that a player would normally not have access to.
Example of usage
// Can be used with a character object
myChar.PopUpTarget( 1, "Where do you wish to teleport to?" );1 - TELEPORT (teleports character to target location)
2 - DYE (will reset targeted item to default colour)
4 - REPAIRMETAL (Targeted metal item will be repaired. Checks Blacksmithing skill)
5 - DYEALL (used to give color to dyetubs)
6 - DVAT (Used for dying objects with the colour of the used dye tub)
9 - ITEMID (Select item to identify. Checks Item Identification skill)
10 - FISH (Select fishing location. Checks Fishing skill)
11 - INFO (Get info on targeted tile)
13 - SMITH (Blacksmithing skill usage via tools)
14 - MINE (Mining skill usage via tools)
15 - SMELTORE (Ore smelting targeting cursor)
16 - WSTATS (Show wander/movement details for targeted NPC)
17 - NPCRESURRECT (Used by NPC healers to resurrect dead players. In this context only works if target is identical to popuptarget user. Self-resurrection item?)
(To be continued)
Prototype
void ReactOnDamage( damageType, attackerChar );
Purpose
Lets a character react to damage by an attacker
Notes
In practical terms, this is what happens when a character reacts to damage:
Example of usage
myChar.ReactOnDamage( 2, attackerChar );Prototype
void Recall( item )
Purpose
Recalls character to the location marked on specified item (if any).
Example of usage
myChar.Recall( targItem );Prototype
void Release()
Purpose
Releases character from jail.
Example of usage
myChar.Release();Prototype
void RemoveFriend( pChar )
Purpose
Removes a player from an NPC pet/follower's friend list
Example of usage
myPet.RemoveFriend( pChar );Prototype
int Resist( resistanceType );
void Resist( resistanceType, amount );
Purpose
Used to get/set the resistance type and amount of a character
Notes
Supported resistanceTypes:
Example of usage
pUser.Resist( 1, 20 );
//or...
var coldResist = pUser.Resist( 4 );Prototype
int ResourceCount( realItemID );
int ResourceCount( realItemID, colour );
int ResourceCount( realItemID, colour, moreVal );
Purpose
Returns the amount of items with specified ID realItemID, colour (optional) and MORE value (optional) from character's backpack
Notes
A colour value of -1 will make UOX3 count ANY item of the specified realItemID regardless of colour. If moreVal is specified, UOX3 will only count items with a matching MORE value.
Example of usage
// Count all items in character's backpack with specified ID (0x1bf2) and colour (0)
var iCount = myChar.ResourceCount( 0x1bf2, 0 );
// Count all items in character's backpack with specified ID (0x1bf2), of ANY colour
var iCount = myChar.ResourceCount( 0x1bf2, -1 );
// Count all items in character's backpack with specified ID (0x1bf2), colour (0x0482) and MORE value (1)
var iCount = myChar.ResourceCount( 0x1bf2, 0x0482, 1 );Prototype
void Resurrect()
Purpose
Resurrects the deceased character.
Example of usage
myChar.Resurrect();Prototype
void RunTo( object, maxSteps );
void RunTo( x, y, maxSteps );
Purpose
Makes the (NPC only) character run to a specific object/location, halting if it takes too many steps.
Example of usage
myNPC.RunTo( pUser, 10 );Prototype
void SellTo( myNPC );
Purpose
Brings up the shopkeeper gump for selling to vendor myNPC.
Example of usage
myChar.SellTo( myNPC );Prototype
void SetInvisible( visibility, timeLength );
Purpose
Sets character to the specified visibility level for the specified amount of time (in milliseconds).
Notes
Supported visibility levels:
Example of usage
myChar.SetInvisible( 1, 1000 );Prototype
void SetPoisoned( poisonLevel, duration )
Purpose
Applies a specified level of poison to a character for a specified amount of time (in milliseconds).
Example of usage
// Gives myChar a level 2 poison for 10 seconds.
myChar.SetPoisoned( 2, 10000 );Prototype
void SetSkillByName( "skillName", value );
Purpose
Sets the skill specified by name to the specified value.
Notes
Name must be the same as in skills.dfn, or "ALLSKILLS" to set all skills at once.
Example of usage
myChar.SetSkillByName( "alchemy", 1000 );Prototype
void SpeechInput( speechID [, speechItem] );
Purpose
Calls up the onSpeechInput event using specified ID, with the text the user types. Also supports an optional speechItem parameter, which allows passing along an object to the onSPeechInput event.
Example of usage
// Example 1, in some function, we call upon user to enter some text:
myChar.SpeechInput( 1 );
// When user enters their text, the onSpeechInput() event gets triggered
function onSpeechInput( pUser, iUsed, pSpeech, pSpeechID )
{
// In this case, iUsed is null, because no item was passed along with SpeechInput
}
// Example 2, this time we pass along an item object called iUsed
myChar.SpeechInput( 1, iUsed );
function onSpeechInput( pUser, iUsed, pSpeech, pSpeechID )
{
// After checking to make sure iUsed is valid, we assign the text the user entered as the new name of iUsed
if( ValidateObject( iUsed ))
{
iUsed.name = pSpeech;
}
}Prototype
void SpellFail();
Purpose
Does the actions associated in code with spell failure. Use after character fails to cast a spell, will play fail-effect, sound and give player default fail-message
Notes
SoundID is the ID of the sound to play. If bAllHear is true, then everyone nearby hears it. If it's false, then only the Character hears it.
Example of usage
myChar.SpellFail();Prototype
void SpellMoveEffect( targetChar, mSpell );
Purpose
Plays the MOVEFX effect of the specified spell in SPELLS.DFN, going from the character to the target
Example of usage
// Get ID of spell being cast
var spellNum = mChar.spellCast;
// Get Spell object based on ID
var mSpell = Spells[spellNum];
// Play mSpell's MOVEFX from mChar to targetChar
mChar.SpellMoveEffect( targetChar, mSpell );Prototype
void SpellStaticEffect( mSpell );
Purpose
Play the STATFX effect specified for the specified spell in SPELLS.DFN, on the character
Example of usage
// Get ID of spell being cast
var spellNum = mChar.spellCast;
// Get Spell object based on ID
var mSpell = Spells[spellNum];
// Play mSpell's MOVEFX from mChar to targetChar
targetChar.SpellStaticEffect( mSpell );Prototype
void SysMessage( [msgColor,] string message, ... );
Purpose
Sends a string as a system message. Accepts up to 10 additional arguments which can be injected into the string as needed. Text colour can also be provided as an optional parameter prior to the string itself
Example of usage
myChar.SysMessage( "Isn't the world great?" );
myChar.SysMessage( GetDictionaryEntry(388), myNPC.name ); // Hello sir! My name is %s and I will be working for you.
myChar.SysMessage( 0x42, "This message has a different color!" );Prototype
void TurnToward( trgObj );
void TurnToward( x, y );
Purpose
Turn Character towards trgObj/specified location
Example of usage
myNPC.TurnToward( myObject );
myNPC.TurnToward( myObject.x, myObject.y );Prototype
int UseResource( amount, itemID );
int UseResource( amount, itemID, colour );
int UseResource( amount, itemID, colour, moreVal );
Purpose
Removes amount of items with specified itemID, colour (optional) and MORE value (optional) from character's backpack, and returns amount deleted
Notes
If an item of the specified resource is found with .usesLeft property higher than 1, the appropriate amount of uses is extracted from said item before eventually deleting the resource item itself.
Example of usage
// Use resource of specific ID, with specific color (0)
myChar.UseResource( 5, 0x1bf2, 0 );
// Use resource of specific ID, and colour
myChar.UseResource( 5, 0x1bf2, 0x0482 );
// Use resource of specific ID, colour and MORE value
myChar.UseResource( 5, 0x1bf2, 0x0482, 1 );Prototype
void WalkTo( object, maxSteps );
void WalkTo( x, y, maxSteps );
Purpose
Makes the (NPC only) character walk to a specific object/location, halting if it takes too many steps.
Example of usage
myNPC.WalkTo( pUser, 10 );Prototype
void Wander( x1, y1, x2, y2 );
void Wander( x1, y1, radius );
Purpose
Specifies a wander area for an NPC, as either a box or a circle
Notes
NPCs will return to their wander area if they reset after combat, or if they wander too far off
Example of usage
// Specify a box set of coordinates as the NPC's wander area
myNPC.Wander( 5593, 1203, 5608, 1206 );
// Specify a circle with radius of 10 as the NPC's wander area
myNPC.Wander( 5600, 1204, 10 );Prototype
void WhisperMessage( message );
Purpose
Causes the Character to whisper a message that can be seen only by nearby players (within 1 tile)
Example of usage
myChar.WhisperMessage( "Shhhhh, we're hunting wabbits!" );Prototype
void YellMessage( message );
Purpose
Causes the Character to yell a message to all players within range (36 tiles)
Example of usage
myChar.YellMessage( "YARGH!" );Prototype
void BeginShutdown();
Purpose
Starts the UOX3 shutdown sequence
Example of usage
Console.BeginShutdown();Prototype
void ClearScreen();
Purpose
Clears the console screen
Example of usage
Console.ClearScreen();Prototype
void Error( errorMsg );
Purpose
Logs an error-message in default error log file, and prints it in the UOX3 console in bright red
Example of usage
Console.Error( "I found an error, and I'm logging it!" );Prototype
void Log( logMsg [, filename] );
Purpose
Logs a message either in default log file or in specified file
Notes
Note: Include \n at the end of the string to force a line break. Always do this unless you're printing multiple messages to the same line!
Example of usage
console.Log( "Logging a custom message to default logfile!" );
console.Log( "Logging a custom message to a specific logfile!", "myCustomLogFile.log" );
Prototype
void MoveTo( x, y );
Purpose
Moves console cursor position to specified x, y location.
Notes
If you want the same line, y == -1
Example of usage
Console.MoveTo( 100, 100 );Prototype
void Print( string );
Purpose
Prints a string to the UOX3 console
Notes
Note: Include \n at the end of the string to force a line break. Always do this unless you're printing multiple messages to the same line!
Example of usage
Console.Print( "Hello World!\n" );Prototype
void PrintDone();
void PrintDone( bool );
Purpose
Prints colored [done] message in console
Example of usage
Console.PrintDone();Prototype
void PrintFailed();
void PrintFailed( bool );
Purpose
Prints colored [failed] message in console
Example of usage
Console.PrintFailed();Prototype
void PrintPassed();
void PrintPassed( bool );
Purpose
Prints colored [skipped] message in console
Example of usage
Console.PrintPassed();Prototype
void PrintBasedOnVal( bool );
Purpose
Prints [done] or [failed] based on provided boolean (true/false)
Example of usage
Console.PrintBasedOnVal( true );Prototype
void PrintSectionBegin();
Purpose
Prints a section separator in the console
Example of usage
Console.PrintSectionBegin();Prototype
void PrintSpecial( textColour, string );
Purpose
Prints a special tag in console similar to [done] and [failed], but with custom text and colour
Notes
Available colours: 0 - Normal 1 - Blue 2 - Red 3 - Green 4 - Yellow 5 - Bright White
Example of usage
Console.PrintSpecial( 3, "Success" );Prototype
void Reload( reloadType );
Purpose
Reloads server data from console.
Notes
Available reload types:
Example of usage
Console.Reload( 4 ); //Reloads spellsPrototype
void TurnBlue();
Purpose
Activates blue text in console
Example of usage
Console.TurnBlue();Prototype
void TurnBrightWhite();
Purpose
Activates bright white text in console
Example of usage
Console.TurnBrightWhite();Prototype
void TurnGreen();();
Purpose
Activates green text in console
Example of usage
Console.TurnGreen();();Prototype
void TurnNormal();
Purpose
Activates normal text in console
Example of usage
Console.TurnNormal();Prototype
void TurnRed();
Purpose
Activates red text in console
Example of usage
Console.TurnRed();Prototype
void TurnYellow();
Purpose
Activates yellow text in console
Example of usage
Console.TurnYellow();Prototype
void Warning( warningMsg );
Purpose
Logs an warning-message in default warning log file, and prints it in the UOX3 console
Example of usage
Console.Warning( "Logging a warning message!" );Prototype
void Close();
Purpose
Closes a File that is currently open.
Notes
Closing an unopened file is undefined behaviour.
Example of usage
mFile.Close();Prototype
bool DeleteFile( fileName[, subFolderName[, useScriptDataDir]] );
Purpose
Deletes a specified file, either in root of shared folder, inside a subfolder, or in JS data folder
Notes
File and subfolder names cannot contain some characters such as forward or backwards slashes, double dots, etc.
Example of usage
// Define filename and subfolder where to find it
var fileName = "myFile.jsdata";
var folderName = "mySubFolder";
// Deletes UOX3/js/jsdata/mySubFolder/myFile.jsdata
DeleteFile( fileName, folderName, true );Prototype
bool EOF();
Purpose
A boolean value returning true if the file pointer is at the end of the file.
Example of usage
while( !mFileRead.EOF() ) { ... }Prototype
bool Free();
Purpose
Deallocates the memory associated with creating the file variable.
Notes
This must be called otherwise a slow memory leak will occur.
Example of usage
mFile.Free();Prototype
int Length();
Purpose
Returns the length of the file
Example of usage
var fileLength = mFile.Length();Prototype
UOXCFile Open( fileName, accessMethod[, subFolder, useScriptDataDir] );
Purpose
Opens a File for reading, writing (write file from scratch) or appending (add to file).
Notes
AccessMethod is a one byte string, which contains either "a" (append), "r" (read) or "w" (write). Subfolder is an optional parameter indicating which subfolder of UOX3/shared/ to open the file in, while useScriptDir is a boolean flag to indicate whether to open the file in the script-data folder (js/jsdata) instead.
Example of usage
// Create a new UOXCFile object
var mFile = new UOXCFile;
// Open a file called "test.dat" (in UOX3/shared/mySubFolder/) for appending
mFile.Open( "test.dat", "a", "mySubFolder" );Prototype
int Pos();
Purpose
Returns or sets the position we are at in the file
Notes
The current position that you are at in the file. This can be read and set, where setting it moves relative to the start of file (i.e. if you set it to 5, it would be 5 bytes from the start, not 5 bytes from it's current location). You cannot seek a location if you have opened the file for append.
Example of usage
var filePos = mFile.Pos();Prototype
string Read( int numBytes );
Purpose
Returns a string of length numBytes, reading numBytes from the opened file.
Notes
numBytes must be at least 1 and less than or equal to 512.
Example of usage
var mLine = mFile.Read( 80 );Prototype
string Read( string delimeter );
Purpose
Reads a string until it encounters a newline or the string specified by delimeter.
Notes
delimiter is at most a 2 character string (for C style character escapes, where \n is a newline, \' is a quote and so on). Will not read more than 512 bytes.
Example of usage
// Read a line of open file mFile until it hits the letter t, a newline, or 512 bytes in length.
var untilT = mFile.ReadUntil( "t" );Prototype
void AcceptRecruit( [trgChar] );
Purpose
Accepts specified character as a recruit in the guild
Purpose
If no character parameter is provided, UOX3 will attempt to accept into the guild... the character the Guild object was retrieved from? Not clear.
Example of usage
// Fetch reference to Guild object from character
var myGuild = myChar.guild;
// Accept a specified recruit pChar into the guild
myGuild.AcceptRecruit( pChar );Before any gump methods can be used, you need to instantiate a new Gump object:
var myGump = new Gump;Prototype
void AddBackground( topHeight, topLeft, bottomHeight, bottomRight, backImage )
Purpose
Adds a background (should come REALLY early in gump) of height (bottomHeight - topHeight) and width (bottomRight - topLeft) as image backImage (gump image like via AddGump).
Example of usage
myGump.AddBackground( 0, 0, 320, 340, 2600 );Prototype
void AddButton( topHeight, topLeft, buttonImage, (buttonPressedImage), unk1, unk2, unk3 )
Purpose
Adds a button to the gump.
Notes
Having an unk1 of 1 indicates the gump will close. unk2 should be the button's unique ID, and unk3 is the page the button will call. buttonPressedImage is optional, and without it a value of buttonImage + 1 is assumed.
When the button is pressed, onGumpPress event is called. If gump is closed without pressing a button, onGumpPress event's iButton parameter will be 0.
Example of usage
myGump.AddButton( 13, 290, 5050, 1, 1, 1 );Prototype
void AddButtonTileArt( topHeight, topLeft, buttonImage, buttonPressedImage, unk1, unk2, unk3, tileID, hue, tileX, tileY )
Purpose
Adds a button to the gump, with tileArt as part of the button
Notes
Having an unk1 of 1 indicates the gump will close. unk2 is the page it will call, while unk3 is the button's unique ID. tileID is tileArt added as part of the button, hue is the tileArt hue, and tileX and tileY is the tileArt's offset compared to the topHeight, topLeft coordinates
When the button is pressed, onGumpPress event is called, iButton is 0 if the gump has been closed without pressing a button: function onGumpPress( Sock, iButton ) { ... }
Example of usage
myGump.AddButtonTileArt( 13, 290, 5050, 5050, 1, 1, 1, 1193, 0, 10, 10 );Prototype
void AddCheckbox( topHeight, topLeft, checkImage, defaultStatus, unk2 )
Purpose
Adds a checkbox to the gump
Notes
DefaultStatus is true/false to determine the starting status of the checkbox, either checked or not. unk2 is the checkbox's ID. Uses same IDs as radiobuttons
Example of usage
myGump.AddCheckbox( 10, 10, 2706, 0, 1 );Prototype
void AddCroppedText( left, top, hue, width, height, actualText )
Purpose
Crops the text if it's too long to display properly. Adds scrollbar?
Example of usage
myGump.AddCheckbox( 10, 10, 2706, 0, 1 );Prototype
void AddCheckerTrans( left, top, width, height )
Purpose
Turns everything underneath the specified area transparent
Example of usage
myGump.AddCheckerTrans( 0, 0, 300, 220 );Prototype
void AddGroup( groupNum )
Purpose
For grouping sets of radio buttons
Example of usage
myGump.AddGroup( 1 );
// .. add radio button elements here, then end the group with EndGroup() methodPrototype
void AddGump( topHeight, topLeft, gumpImage, hue(optional) )
Purpose
Adds a gump on the current gump (ie any image in the gumps part of InsideUO). A fourth parameter - hue - is optional, and can be used to set the color of the gump.
Example of usage
myGump.AddGump( 5, 260, 1141 );
myGump.AddGump( 5, 260, 1141, 1154 );Prototype
void AddGumpColor( topHeight, topLeft, gumpImage, hue )
Purpose
Adds a gump on the current gump (ie any image in the gumps part of InsideUO). Same as AddGump, but with an additional parameter for hue/color.
Example of usage
myGump.AddGumpColor( 5, 260, 1141, 1154 );Prototype
void AddHTMLGump( topHeight, topLeft, width, height, background, scrollbar, HTMLText )
Purpose
Adds a gump element with HTML text support to the gump
Notes
background and scrollbar either false or true, for respectively off/on. HTMLText is the text in the gump, can use HTML here. Supported tags: <B></B> <BIG></BIG> <SMALL></SMALL> <EM></EM> <I></I> <U></U> <H1></H1> <H2></H2> <H3></H3> <H4></H4> <H5></H5> <H6></H6> <a href=\"\"></a> <div align=\"right\"><div align=\"left\"></DIV> <left></left> <P> <CENTER></CENTER> <BR></BR> <BASEFONT color=#ffffff size=1-7></BASEFONT>
Example of usage
myGump.AddHTMLGump( 15, 40, 110, 20, false, false, "This is a text with HTML" );Prototype
void AddItemProperty( myItem )
Purpose
Attaches an item property element to previous element in a gump, which will cause client to display the properties of that object as a regular tooltip on cursor when hovering over the gump element
Notes
Could be used to show item stats for items in a custom paperdoll
Example of usage
// Add item properties of myItem as a tooltip to the previous gump element
myGump.AddItemProperty( myItem );Prototype
void AddPage( pageNum )
Purpose
Adds a new page to the gump
Other Notes
Anything on page 0 is shown on ALL pages
Example of usage
myGump.AddPage( 1 );Prototype
void AddPageButton( topHeight, topLeft, buttonImage, (buttonPressedImage), pageNum )
Purpose
Adds a button to the gump allowing you to navigate pages without an onGumpPress event. buttonPressedImage is optional, and without it a value of buttonImage + 1 is assumed
Example of usage
myGump.AddPageButton( 13, 290, 5050, 1 );Prototype
void AddPicInPic( topLeft, topHeight, gumpImage, spriteX, spriteY, width, height )
Purpose
Adds a "picture in a picture" (picinpic) gump element to the gump, allowing one to display only a select area of a given piece of gump art
Notes
spriteX and spriteY are the starting point within the gump art, while width and height control how large area to display from that starting point. Only works in regular UO clients v7.0.80.0 or higher (not yet supported by ClassicUO)
Example of usage
// Display first sprite in a gump sprite sheet, starting from 0, 0 in the gump art
myGump.AddPicInPic( 10, 10, 0x9d3b, 0, 0, 30, 30 );
// Display only Lord British' head from a gump that displays the Lord British paperdoll art
myGump.AddPicInPic( 10, 10, 0x03de, 0, 0, 30, 30 );Prototype
void AddPicture( topHeight, topLeft, tilePic )
Purpose
Adds the image tilePic to the gump at topHeight/topLeft. tilePic is an ITEM ID
Example of usage
myGump.AddPicture( 5, 111, 0x0EED );Prototype
void AddPictureColor( topHeight, topLeft, tilePic, hue )
Purpose
Adds the image tilePic to the gump at topHeight/topLeft, with color hue. tilePic is an ITEM ID
Example of usage
myGump.AddPictureColor( 5, 111, 0x0EED, 1154 );Prototype
void AddRadio( topHeight, topLeft, radioImage, pressed, id )
Purpose
Adds a radio button to the gump
Notes
pressed (0/1) determines the default state of the radiobutton, id is the radiobutton's buttonID. Uses same IDs as CheckBoxes
Example of usage
myGump.AddRadio( 13, 40, 2151, 0, 2966 );Prototype
void AddText( topHeight, topLeft, textColour, text )
Purpose
Adds the text text to the gump represented by gumpHandle at topHeight/topLeft in textColour
Notes
Note that each AddText line automatically gets assigned a "TextID", starting with 0 and counting upwards for each new AddText line. When using both AddText and AddTextEntry in the same gump, be sure to put all the AddText lines FIRST, then the AddTextEntry lines - since they both use TextIDs and otherwise the automatic assignment will get messed up (or some such)..
Example of usage
myGump.AddText( 30, 30, 0, "Test text" );Prototype
void AddTextEntry( topHeight, topLeft, width, height, hue, unk4, textID, defaultText )
Purpose
It adds a text entry with default text to the gump
Notes
unk4 is..? seems to work when set to 1. textID uses an ID which is also automatically assigned to any AddText line, so be sure to place all AddTextEntry lines after any AddText lines, then assign these with the proper textIDs starting with the next free ID that hasn't been assigned as an ID for an AddText line..
Example of usage
myGump.AddTextEntry( 20, 62, 200, 20, 10, 1, 1, "Default text" );Prototype
void AddTextEntryLimited( topHeight, topLeft, width, height, hue, unk4, textID, defaultText, maxLength )
Purpose
It adds a text entry with default text to the gump
Notes
unk4 is..? seems to work when set to 1. textID uses an ID which is also automatically assigned to any AddText line, so be sure to place all AddTextEntry lines after any AddText lines, then assign these with the proper textIDs starting with the next free ID that hasn't been assigned as an ID for an AddText line.. maxLength specifies max amount of text that can be entered
Example of usage
myGump.AddTextEntryLimited( 20, 62, 200, 20, 10, 1, 1, "Default text", 20 );Prototype
void AddTiledGump( left, top, width, height, gumpID )
Purpose
Tiles specified gump within specified area
Example of usage
myGump.AddTiledGump( left, top, width, height, gumpID );Prototype
void AddToolTip( clilocNum )
Purpose
Adds a cliloc-based tooltip to the gump-element added prior to AddToolTip
Example of usage
myGump.AddPicture( 175, 50, 3644 );
myGump.AddToolTip( 1015094 ); //adds tooltip with cliloc 1015094 to the gump-picture added on the previous linePrototype
void AddXMFHTMLGump( left, top, width, height, number, hasBorder, hasScrollbar )
Purpose
The purpose of this is to load a HTML like gump using the cliloc "number". Its to do with Localisation settings etc.
Example of usage
myGump.AddXMFHTMLGump( 10, 10, 200, 300, 1, true, true );Prototype
void AddXMFHTMLGumpColor( left, top, width, height, number, hasBorder, hasScrollbar, rgbColour )
Purpose
The purpose of this is to load a HTML like gump using the cliloc "number". Its to do with Localisation settings etc.
Example of usage
myGump.AddXMFHTMLGumpColor( 10, 10, 200, 300, 1, true, true, ?? );Prototype
void AddXMFHTMLTok( left, top, width, height, hasBorder, hasScrollbar, rgbColour, clilocNum, clilocArg1, clilocArg2, clilocArg3 )
Purpose
The purpose of this is to load a HTML like gump using the cliloc "number". Its to do with Localisation settings etc. (Any of) the three cliloc-arguments are optional, but there must minimum be however many the cliloc requires.
Example of usage
myGump.AddXMFHTMLTok( 10, 10, 200, 300, true, true, 1, 1060656, 99 );
myGump.AddXMFHTMLTok( 10, 10, 200, 300, true, true, 1, 1060658, 99, "BottlesOfBeer" );
myGump.AddXMFHTMLTok( 10, 10, 200, 300, true, true, 1, 1041522, 99, "BottlesOfBeer", "onTheWall" );Prototype
void AddHTMLGump( topHeight, topLeft, width, height, background, scrollbar, HTMLText )
Purpose
background and scrollbar either false or true, for respectively off/on. HTMLText is the text in the gump, can use HTML here. Supported tags:
<B></B> <BIG></BIG> <SMALL></SMALL> <EM></EM> <I></I> <U></U>
<H1></H1> <H2></H2> <H3></H3> <H4></H4> <H5></H5> <H6></H6> <a href=""></a>
<div align="right"><div align="left"></DIV> <left></left> <P> <CENTER></CENTER> <BR></BR> <BASEFONT color=#ffffff size=1-7></BASEFONT>Example of usage
myGump.AddHTMLGump( 10, 10, 200, 300, true, true, "This is a test" );Prototype
void EndGroup()
Purpose
Ends a previously started group element
Example of usage
myGump.EndGroup();Prototype
void Free()
Purpose
Deletes all the memory allocated to the gump
Example of usage
myGump.Free();Prototype
void MasterGump( gumpID )
Purpose
Unknown, more information needed. Overrides GumpID sent with gump packet?
Notes
Introduced somewhere in UO client versions 4.0.4d to 5.0.5b
Example of usage
myGump.MasterGump( gumpID );Prototype
void NoClose()
Purpose
Adds noclose element to gump stream; specifies that gump cannot be closed by clicking the right mouse button
Example of usage
myGump.NoClose();Prototype
void NoClose()
Purpose
Adds nodispose element to gump stream; specifies that gump cannot be disposed of/closed using the Escape button
Notes
It's also possible it is used to prevent gumps from being closed using the "Close Dialogs" client macro. No response is sent to server upon closing the Gump in this manner.
Example of usage
myGump.NoDispose();Prototype
void NoMove()
Purpose
Adds nomove element to gump stream; specifies that gump cannot be moved
Example of usage
myGump.NoMove();Prototype
void NoResize()
Purpose
Adds noresize element to gump stream; specifies that gump cannot be resized
Example of usage
myGump.NoResize();Prototype
void Send( targSocket )
Purpose
Sends the gump to targSocket
Example of usage
myGump.send( mySock );Purpose
Displays a test gump with handling of button presses when item with script attached is double-clicked
Example
function onUseChecked( pUser, iUsed )
{
var myGump = new Gump; // create a new gump
myGump.AddBackground( 0, 0, 300, 300, 2600 ); // add an automic scaled background
myGump.AddCheckerTrans( 0, 0, 100, 100 ); // Let's make part of the gump transparent! Whee!
myGump.AddButton( 300, 5, 0xa50, 1, 0, 0); // Add a close-gump button
myGump.AddGump( 120, 40, 0x157E ); // add some gump art
myGump.AddPicture( 20, 40, 0x12D8 ); // add tile art
myGump.AddText( 100, 20, 5, "My first gump!" ); // add text, gets assigned TextID 0
myGump.AddText( 100, 95, 7, "Some more text!" ); // add text, gets assigned TextID 1
myGump.AddText( 20, 200, 7, "TextEntry 1[ ]" ); // add text, gets assigned TextID 2
myGump.AddText( 20, 220, 7, "TextEntry 2[ ]" ); // add text, gets assigned TextID 3
myGump.AddTextEntry( 100, 200, 120, 25, 10, 0, 4, "First Entry" ); //TextID 4
myGump.AddTextEntry( 100, 220, 120, 25, 10, 0, 5, "Second Entry" ); //TextID 5
myGump.AddRadio( 20, 130, 2152, 0, 0 ); //RadioButton with ID 0
myGump.AddRadio( 20, 150, 2152, 0, 1 ); //RadioButton with ID 1
myGump.AddCheckbox( 20, 175, 2706, 0, 2 ); //CheckBox with ID 2
myGump.AddButton( 160, 265, 0xF7, 1, 0, 1 ); // add the "okay" button
myGump.Send( pUser.socket ); // send this gump to client now
myGump.Free(); // clear this gump from uox-memory
return false;
}
function onGumpPress( pSock, pButton, gumpData )
{
var pUser = pSock.currentChar;
switch(pButton)
{
case 0:
// abort and do nothing
break;
case 1:
var Text1 = gumpData.getEdit(0);
pUser.SysMessage( "The first TextEntry was: "+Text1 );
var Text2 = gumpData.getEdit(1);
pUser.SysMessage( "The second TextEntry was: "+Text2 )
var OtherButton = gumpData.getButton(0);
switch( OtherButton )
{
case 0:
pUser.SysMessage( "You selected RadioButton number: "+OtherButton );
pUser.DoAction( 15 );
break;
case 1:
pUser.SysMessage( "You selected RadioButton number: "+OtherButton );
pUser.DoAction( 11 );
break;
case 2:
pUser.SysMessage( "The Checkbox with ID "+OtherButton+" was checked." );
pUser.DoAction( 18 );
break;
}
break;
}
}GumpData objects are retrieved via one of the function parameters in the onGumpPress() event
Prototype
void Free();
Purpose
Deletes JS Gump Data object and frees up associated memory
Example of usage
myItem.ApplyRank( 5, 10 );Prototype
int getButton( gumpDataIndex );
Purpose
Gets value of button at specified index in Gump Data
Example of usage
// Example from Admin Welcome gump in UOX3/js/server/misc/admin_welcome.js
for( var i = 0; i < numCheckedBoxes; i++ )
{
buttonID = tempGumpData.getButton(i);
if( buttonID >= 0 && buttonID <= 7 )
{
facetName = "felucca";
}
...
}Prototype
string getEdit( editIndex );
Purpose
Gets data input from TextEntr(y/ies) in JS Gump
Example of usage
// Example from onGumpPress() event in UOX3/js/server/house/housesign.js
var newName = gumpData.getEdit(0);
if( newName.length <= 60 ) // Estimated longest name that fits inside sign gump
{
iSign.name = newName;
pSocket.SysMessage( GetDictionaryEntry( 1943, pSocket.language ), newName ); // House name changed to %s.
}
else
pSocket.SysMessage( GetDictionaryEntry( 1944, pSocket.language )); // That name is too long.Prototype
int getID( gumpDataIndex );
Purpose
Gets nID at specified index in Gump Data
Example of usage
// To be addedPrototype
void ApplyRank( rank, maxRank );
Purpose
Modifies item properties based on item's rank (could be calculated based on player's crafting skill, but is always 10 if rank system not enabled. Higher values will increase base properties of item, lower will decrease base properties). maxRank is the maximum amount of ranks in the rank system (10 by default).
Example of usage
myItem.ApplyRank( 5, 10 );Prototype
void Carve( socket );
Purpose
Makes the character belonging to socket carve up a corpse
Example of usage
myCorpse.Carve( socket );Prototype
void Dupe( [socket] );
Purpose
Creates a duplicate of the item, and optionally places it in a character's backpack
Notes
If socket parameter is provided, item is placed in associated character's backpack. If no parameter is provided, item is duped, but it's up to the script to place it in the world.
Example of usage
// Dupe myItem and place is it the backpack of character associated with mySock
myItem.Dupe( mySock );
// Dupe myItem and place it somewhere in the world
var newItem = myItem.Dupe( mySock );
newItem.Teleport( 1000, 1000, 0 );Prototype
int GetMoreVar( moreVarName, moreVarPart );
void SetMoreVar( moreVarName, moreVarPart, value );
Purpose
Get/set the value (0x00 to 0xFF) for a specific part (1-4) of temp variables ("more", "morex", "morey", "morez") associated with an item
Example of usage
// Set all 4 parts of item's "morex" property in one go:
myItem.morex = 0x01223452; // The four values are 0x01 0x22 0x34 0x52
// Set each part of item's "morex" property individually
myItem.SetMoreVar( "morex", 1, 0x01 );
myItem.SetMoreVar( "morex", 2, 0x22 );
myItem.SetMoreVar( "morex", 3, 0x34 );
myItem.SetMoreVar( "morex", 4, 0x52 );
// Fetch the values stored in different parts of item's "morex" property
var moreXPart1 = myItem.GetMoreVar( "morex", 1 ); // value is 0x01
var moreXPart2 = myItem.GetMoreVar( "morex", 2 ); // value is 0x22
var moreXPart3 = myItem.GetMoreVar( "morex", 3 ); // value is 0x34
var moreXPart4 = myItem.GetMoreVar( "morex", 4 ); // value is 0x52
Prototype
void GetTileName();
Purpose
Fetches item name, and looks in tiledata for name if no name is specified for object (or name is "#")
Example of usage
var itemName = myItem.GetTileName();Prototype
void Glow( socket );
Purpose
Causes the object to begin glowing, by attaching an invisible light
Notes
Can only be applied to players, and only to player whose socket is also provided as an argument to the Glow() function.
Example of usage
myItem.Glow( pSock );Prototype
bool IsOnFoodList( foodListName );
Purpose
Returns true if item is on a specified food list from UOX3/dfndata/items/itemlists/foodlists.dfn
Example of usage
// Check if myItem is a vegetable
if( myItem.IsOnFoodList( "VEGETABLES" ))
{
pUser.TextMessage( "Yeah, my item is definitely a vegetable!" );
}Prototype
void LockDown();
Purpose
Locks item down (sets movable value to 3)
Example of usage
myItem.LockDown();Prototype
void OpenPlank()
Purpose
Opens the plank of a boat.
Example of usage
// Step 1, find plank by iterating through all objects in a boat - or perhaps the plank is the item being used in an onUseChecked event?
// ...
// Step 2, open plank once found
myPlank.OpenPlank();Prototype
void PlaceInPack( autoStackBool );
Purpose
Randomly sets the placement of an item inside the container it is in.
Notes
If autoStackBool is set to true, UOX3 will attempt to stack the item with existing similar items in its container before randomly placing it.
Example of usage
// Randomly place item in container
myItem.PlaceInPack();
// Attempt to autostack item with similar items
myItem.PlaceInPack( true );Prototype
void SetCont( object );
Purpose
Sets the container of the item to the specified object.
Example of usage
myItem.SetCont( mChar );Prototype
void UnGlow( socket );
Purpose
Causes the object to stop glowing, by removing the invisible light
Example of usage
myItem.UnGlow( pSock );Prototype
bool AddToBanList( pChar );
Purpose
Adds the character pChar to the multi's ban list. Returns true if the parameters are valid.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Oh no! I'm getting banned from this house!" );
iMulti.AddToBanList( pChar );Prototype
bool AddToFriendList( pChar );
Purpose
Adds the character pChar to the multi's friend list. Won't duplicate if already on the list.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Yay, I'm being added as a friend of this house!" );
iMulti.AddToFriendList( pChar );Prototype
bool AddToGuestList( pChar );
Purpose
Adds the character pChar to the multi's guest list. Won't duplicate if already on the list.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Yay, I'm being added as a guest of this house!" );
iMulti.AddToGuestList( pChar );Prototype
bool AddToOwnerList( pChar );
Purpose
Adds the character pChar to the multi's owner list. Doesn't remove existing owners at all. Won't duplicate if already on the list.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Yay, I'm being added as an owner of this house!" );
iMulti.AddToOwnerList( pChar );Prototype
bool AddTrashCont( trashContObj );
Purpose
Add trash container to multi's list of trash containers
Example of usage
var iMulti = FindMulti( trashContObj.x, trashContObj.y, trashContObj.z, trashContObj.worldnumber );
iMulti.AddTrashCont( trashContObj );Prototype
bool ClearBanList();
Purpose
Clears all players from multi's ban list
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
iMulti.ClearBanList();Prototype
bool ClearFriendList();
Purpose
Clears all players from multi's friend list
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
iMulti.ClearFriendList();Prototype
bool ClearGuestList();
Purpose
Clears all players from multi's guest list
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
iMulti.ClearGuestList();Prototype
bool ClearOwnerList();
Purpose
Clears all players from multi's co-owner list
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
iMulti.ClearOwnerList();Prototype
bool FinishedChar( [charType] );
Purpose
Returns true if there are no more items left to look through in the container (or multi)
Example of usage
See FirstChar() Method
Prototype
CHARACTER FirstChar( [charType] );
Purpose
Returns a handle to the first character in the multi.
Notes
If it's null, then there are no characters inside. An optional parameter is supported by both FirstChar(), NextChar() and FinishedChar() to specify the type of characters to look for... options are none (find all chars), "owner", "friend", "guest" or "banned".
Example of usage
// Example 1 - Iterate through all characters in Multi
function onUseChecked( pUser, iUsed )
{
var iMulti = pUser.multi;
var mChar;
for( mChar = iMulti.FirstChar(); !iMulti.FinishedChar(); mChar = iMulti.NextChar() )
{
if( mChar != null )
{
mChar.TextMessage( "I'm a character in this multi!" );
}
}
}
// Example 2 - Iterate through only characters on ownerlist of multi
function onUseChecked( pUser, iUsed )
{
var iMulti = pUser.multi;
var mChar;
for( mChar = iMulti.FirstChar( "owner" ); !iMulti.FinishedChar( "owner" ); mChar = iMulti.NextChar( "owner" ) )
{
if( mChar != null )
{
mChar.TextMessage( "I'm one of the owners of this multi!" );
}
}
}Prototype
string GetMultiCorner( cornerID );
Purpose
Gets coordinates for specified corner of multi ( 0 = NW corner, 1 = NE corner, 2 = SW corner, 3 = SE corner)
Example of usage
var multiCornerCoords = (iMulti.GetMultiCorner( 3 )).split( "," );
var cornerX = parseInt(multiCornerCoords[0]);
var cornerY = parseInt(multiCornerCoords[1]);Prototype
bool IsInMulti( ourObj );
Purpose
Returns true if the object is in the multi. See also: FindMulti() Function
Example of usage
// Grab a reference to any potential Multi at object's location
var iMulti = FindMulti( ourObj.x, ourObj.y, ourObj.z, ourObj.worldnumber );
// If a Multi was found, check if object is considered inside
if( ValidateObject( iMulti ))
{
if( iMulti.IsInMulti( ourObj ) )
{
ourObj.TextMessage( "I am in a multi!" );
}
{Prototype
bool IsMulti();
Purpose
Returns true if an Item is actually a Multi
Example of usage
if( iToCheck.IsMulti() )
{
pUser.TextMessage( "Yep, it's definitely a multi." );
}Prototype
bool IsMulti();
Purpose
Returns true if an Item is actually a Multi
Example of usage
if( iToCheck.IsMulti() )
{
pUser.TextMessage( "Yep, it's definitely a multi." );
}Prototype
bool IsOnBanList( pChar );
Purpose
Returns true if the character pChar is on the multi's ban list
Example of usage
var iMulti = FindMulti( ourObj.x, ourObj.y, ourObj.z, pChar.worldnumber );
if( iMulti.IsOnBanList( pChar ))
{
pChar.TextMessage( "Oops, I appear to be on the banlist of this house!" );
}Prototype
bool IsOnFriendList( pChar );
Purpose
Returns true if the character pChar is on the list of friends of the multi
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
if( iMulti.IsOnFriendList( pChar ))
{
pChar.TextMessage( "Ahh, I appear to be on the friend-list of this house!" );
}Prototype
bool IsOnGuestList( pChar );
Purpose
Returns true if the character pChar is on the list of guests of the multi
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
if( iMulti.IsOnGuestList( pChar ))
{
pChar.TextMessage( "Ahh, I appear to be on the guest-list of this house!" );
}Prototype
bool IsOnOwnerList( pChar );
Purpose
Returns true if the character pChar is on the list of owners of the multi
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
if( iMulti.IsOnOwnerList( pChar ))
{
pChar.TextMessage( "Ahh, I appear to be on the owner-list of this house!" );
}Prototype
bool IsOwner( pUser );
Purpose
Returns true if specified character is the (true) owner of the Multi
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
if( iMulti.IsOwner( pUser ) )
{
pUser.TextMessage( "Yep, I'm the owner of this multi!." );
}Prototype
bool IsSecureContainer( myTarget );
Purpose
Checks if specified item is a secure container in the multi
Example of usage
var iMulti = FindMulti( myTarget.x, myTarget.y, myTarget.z, myTarget.worldnumber );
var isSecure = iMulti.IsSecureContainer( myTarget );
if( iSecure )
{
pChar.TextMessage( "Container is secure!" );
}Prototype
bool KillKeys( [characterSerial] );
Purpose
Deletes ALL keys associated with a multi, or all keys owned by a specific character
Example of usage
var iMulti = FindMulti( pUser.x, pUser.y, pUser.z, pUser.worldnumber );
// Kill all keys that match house
iMulti.KillKeys();
// Kill all keys for this house owned by pUser
iMulti.KillKeys( pUser );Prototype
bool LockDownItem( myTarget );
Purpose
Locks down targeted item in multi
Example of usage
var iMulti = FindMulti( myTarget.x, myTarget.y, myTarget.z, myTarget.worldnumber );
iMulti.LockDownItem( myTarget );Prototype
CHARACTER NextChar( [charType] );
Purpose
Returns the next character found in the multi
Example of usage
See FirstChar() Method
Prototype
bool ReleaseItem( myTarget );
Purpose
Releases targeted item in multi from lockdown
Example of usage
var iMulti = FindMulti( myTarget.x, myTarget.y, myTarget.z, myTarget.worldnumber );
iMulti.ReleaseItem( myTarget );Prototype
bool RemoveFromBanList( pChar );
Purpose
Removes pChar from the multi's ban list. Returns true on correct parameters.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Yay! I've been removed from the ban-list of this house!" );
iMulti.RemoveFromBanList( pChar );Prototype
bool RemoveFromFriendList( pChar );
Purpose
Removes pChar from the multi's friend list. Returns true on correct parameters.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Zoinks! I am being removed as a friend of this house!" );
iMulti.RemoveFromFriendList( pChar );Prototype
bool RemoveFromGuestList( pChar );
Purpose
Removes pChar from the multi's guest list. Returns true on correct parameters.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Oops! I am being removed as a guest of this house!" );
iMulti.RemoveFromGuestList( pChar );Prototype
bool RemoveFromOwnerList( pChar );
Purpose
Removes pChar from the multi's owner list. Returns true on correct parameters.
Example of usage
var iMulti = FindMulti( pChar.x, pChar.y, pChar.z, pChar.worldnumber );
pChar.TextMessage( "Oops! I am being removed as owner of this house!" );
iMulti.RemoveFromOwnerList( pChar );Prototype
bool RemoveTrashCont( trashContObj );
Purpose
Remove trash container from multi's list of trash containers
Example of usage
var iMulti = FindMulti( trashContObj.x, trashContObj.y, trashContObj.z, trashContObj.worldnumber );
iMulti.RemoveTrashCont( trashContObj );Prototype
bool SecureContainer( myTarget );
Purpose
Turns specified container into a secure container in the Multi
Example of usage
var iMulti = FindMulti( myTarget.x, myTarget.y, myTarget.z, myTarget.worldnumber );
}
iMulti.SecureContainer( myTarget );Prototype
bool UnsecureContainer( myTarget );
Purpose
Turns specified secure container into a regular container in the Multi
Example of usage
var iMulti = FindMulti( myTarget.x, myTarget.y, myTarget.z, myTarget.worldnumber );
iMulti.UnsecureContainer( myTarget );Before any Packet methods can be used, you need to instantiate a new Packet object:
var myPacket = new Packet();Prototype
PacketStream Packet();
Purpose
Prepares a new packet stream
Example of usage
// Prepare a new packet stream
var myPacket = new Packet();Prototype
void ReserveSize( packetSize );
Purpose
Reserves a specific size for the packet stream
Example of usage
// Prepare a new packet stream
var myPacket = new Packet();
// Reserve a size of 7 bytes for myPacket
myPacket.ReserveSize( 7 );Prototype
void WriteByte( position, value );
Purpose
Writes a single byte at the specified position in the packet stream
Example of usage
// In byte-position 0 of a myPacket, write the value 0x73 as a Byte
myPacket.WriteByte( 0, 0x73 );Prototype
void WriteShort( position, value );
Purpose
Writes two bytes at the specified position in the packet stream
Example of usage
// In byte-position 1 of myPacket, write the value 0x02 as a Short
myPacket.WriteShort( 1, 0x02 );Prototype
void WriteLong( position, value );
Purpose
Writes four bytes at the specified position in the packet stream
Example of usage
// In byte-position 3 of myPacket, write the serial of mChar as a Long
myPacket.WriteLong( 3, mChar.serial );Prototype
void WriteString( position, string );
Purpose
Writes four bytes at the specified position in the packet stream
Example of usage
// In byte-position 7 of myPacket, write the specified text as a String, 4 bytes long
myPacket.WriteString( 7, "Text", 4 );Prototype
void Send( packet );
Purpose
Send the specified network-packet to a socket
Example of usage
// Send myPacket to pSock
pSock.Send( myPacket );Prototype
void Free();
Purpose
Free up the memory used for the packet?
Example of usage
myPacket.Free();Prototype
void Add( playerToAdd );
Purpose
Add a player to a party
Example of usage
// Create a new Party with leaderChar as party leader
var myParty = CreateParty( leaderChar );
// Add player playerToAdd to the newly created Party
myParty.Add( playerToAdd );Prototype
void Remove( playerToRemove );
Purpose
Removes player from party
Example of usage
myParty.Remove( playerToRemove );Prototype
void GetMember( indexPos );
Purpose
Gets party member at specified index in list of party members
Example of usage
// Fetch party member at party index slot 3
var partyMember3 = myParty.GetMember( 3 );Prototype
bool CanWearArmor( armorClass );
Purpose
Checks if members of race can equip items of specified armorClass
Example of usage
if( pUser.race.CanWearArmor( 1 ))
{
pUser.TextMessage( "Woho! My race can wear items of armor class 1!" );
}Prototype
bool IsValidBeardColor( colour );
Purpose
Returns true if the beard colour is valid for raceID.
Example of usage
if( !pTalking.race.IsValidBeardColour( 1 ))
{
pTalking.TextMessage( "awww, my beard can't be this colour?" );
}Prototype
bool IsValidHairColor( colour );
Purpose
Returns true if the hair colour is valid for raceID.
Example of usage
if( !pTalking.race.IsValidHairColour( 1 ))
{
pTalking.TextMessage( "awww, my hair can't be this colour?" );
}Prototype
bool IsValidSkinColor( colour );
Purpose
Returns true if the skin colour is valid for raceID.
Example of usage
if( !pTalking.race.IsValidSkinColour( 1 ))
{
pTalking.TextMessage( "awww, my skin can't be this colour?" );
}Prototype
void AddScriptTrigger( scriptID );
Purpose
Adds a scriptTrigger to a (town-)region's list of scriptTriggers.
Notes
See also: onEnterRegion()/onLeaveRegion() events.
Example of usage
// Fetch reference to region pUser is in
var myRegion = pUser.region;
// Adds hypothetical script with ID 16003 to region
myRegion.AddScriptTrigger( 16003 );Prototype
void RemoveScriptTrigger( scriptID );
Purpose
Removes a scriptTrigger from a (town-)region's list of scriptTriggers.
Notes
See also: onEnterRegion()/onLeaveRegion() events.
Example of usage
// Fetch reference to region pUser is in
var myRegion = pUser.region;
// Removes hypothetical script with ID 16003 to region
myRegion.RemoveScriptTrigger( 16003 );Prototype
void BuyFrom( targNPC );
Purpose
Brings up the shopkeeper gump or PV backpack for buying for vendor targNPC.
Example of usage
mySock.BuyFrom( myNPC );Prototype
void CloseGump( gumpID, buttonID );
Purpose
Closes specified gump based on its ID, and provides a button ID response
Example of usage
// Store a reference to this script's scriptID
var scriptID = 8000;
// Close gump opened via this script (by default, gumps are assigned a gumpID based on script ID + 0xffff)
mySocket.CloseGump( scriptID + 0xffff, 0 );Prototype
void CustomTarget( targetNum, toSay )
Purpose
Very similar to PopUpTarget. It's a callback situation instead. targetNum must be between 0 and 255. Character associated with Socket says toSay, and is shown a cursor. Re-enters the script associated with the socket's player (i.e. player who gets the cursor). Enters function name based on the value of tNum. if tNum is 0, then the function would be onCallback0. Prototype of callback is:
function onCallback0( pSock, myTarget )
Example of usage
// User double-clicks an item, which brings up a custom target cursor
function onUseChecked( pUser, iUsed )
{
pUser.socket.CustomTarget( 0, "Select your custom target:" );
}
// After player targets something, onCallback0 is called
function onCallback0( pSock, myTarget )
{
// ... do something with target here
}Prototype
void Disconnect();
Purpose
Disconnects specified client
Example of usage
mySock.Disconnect();Prototype
void DisplayDamage( pUser, damage );
Purpose
Displays specified damage value over character's head
Example of usage
socket.DisplayDamage( pUser, 15 );Prototype
bool FinishedTriggerWords();
Purpose
Returns true if finished all trigger words in the socket's list
Example of usage
See FirstTriggerWord() Method
Prototype
int FirstTriggerWord();
Purpose
Returns first trigger word in the socket's list
Example of usage
// Example from Banker NPC AI script in UOX3/js/npc/ai/banker.js
// ...
var trigWordHandled = false;
// Iterate through all trigger words currently active on socket
for( var trigWord = pSock.FirstTriggerWord(); !pSock.FinishedTriggerWords(); trigWord = pSock.NextTriggerWord() )
{
if( trigWordHandled )
break;
switch( trigWord )
{
case 0: // Withdraw
WithdrawFromBank( pSock, pTalking, pTalkingTo, bankBox, strSaid );
trigWordHandled = true;
break;
case 1: // Balance, Statement
CheckBalance( pSock, pTalking, pTalkingTo, bankBox );
trigWordHandled = true;
break;
case 2: // Bank
OpenBank( pSock, pTalking, pTalkingTo, bankBox );
trigWordHandled = true;
break;
case 3: // Check
CreateCheck( pSock, pTalking, pTalkingTo, bankBox, strSaid );
trigWordHandled = true;
break;
default:
break;
}
}Prototype
int GetByte( offset );
void SetByte( offset, value );
Purpose
Get/Set a byte from a socket at offset, positive value assumed
Example of usage
// Get value of byte 0
var byte0 = sock.GetByte( 0 );
// Set byte 1 to value 64
sock.SetByte( 1, 64 );Prototype
int GetSByte( offset );
Purpose
Return a byte from a socket at offset, negative value accepted
Example of usage
var byte0 = sock.GetSByte( 0 );Prototype
int GetWord( offset );
void SetWord( offset, value );
Purpose
Get/Set 2 bytes of data from socket at offset, positive value assumed
Example of usage
var word0 = sock.GetWord( 0 );
sock.SetWord( 1, 0x0164 );Prototype
int GetSWord( offset );
Purpose
Return 2 bytes of data from socket at offset, negative value assumed
Example of usage
var sWord0 = sock.GetSWord( 0 );Prototype
int GetDWord( offset );
void SetDWord( offset, value );
Purpose
Get/Set 4 bytes of data from socket at offset, positive value assumed
Example of usage
var dWord0 = sock.GetDWord( 0 );
sock.SetDWord( 1, 0x01640164 );Prototype
int GetSDWord( offset );
Purpose
Return 4 bytes of data from socket at offset, negative value assumed
Example of usage
var dWord0 = sock.GetSDWord( 0 );Prototype
string GetString( offset[, len] );
void SetString( offset, value );
Purpose
Return a string from a socket at offset with optional length len
Example of usage
var sName = sock.GetString( 0 );
sock.SetString( 0, "myText!" );Prototype
int GetTimer( timerID )
int SetTimer( timerID, numMilliSeconds )
Purpose
Get/Set the time in milliseconds until specified timer expires for a Socket object
Notes
Supported timerIDs for Sockets
Timer.SOCK_SKILLDELAY // Time until player can use another skill
Timer.SOCK_OBJDELAY // Time until player can use another item
Timer.SOCK_SPIRITSPEAK // Time until Spirit Speak effect wears off
Timer.SOCK_TRACKING // Time until next time player can track
Timer.SOCK_FISHING // Time until next time player can fish
Timer.SOCK_MUTETIME // Time until character is no longer muted
Timer.SOCK_TRACKINGDISPLAY // Time until next time tracking arrow updates
Timer.SOCK_TRAFFICWARDEN // Time until next time traffic warden resetsAlso see GetTimer()/SetTimer() Character Methods.
Example of usage
// Get remaining time in milliseconds until next time player can use an object
var objectDelay = mySock.GetTimer( Timer.SOCK_OBJDELAY );
// Set time from now in milliseconds until next time player can use another item
mySock.SetTimer( timer.SOCK_OBJDELAY, 3000 );Prototype
void Music( musicNum );
Purpose
Plays the specified music for socket
Example of usage
mySock.Music( 1 );Prototype
int NextTriggerWord();
Purpose
Returns next trigger word in the socket's list
Example of usage
See FirstTriggerWord() Method
Prototype
void OpenGump( gumpMenuID );
Purpose
Opens specified gumpmenu from dfndata\misc\gumps.dfn for socket
Example of usage
mySock.OpenGump( 1 );Prototype
void OpenURL( UrlString );
Purpose
Opens a specified URL in player's default browser
Example of usage
mySock.OpenURL( "https://www.uox3.org" );Prototype
void PopUpTarget( tNum, toSay )
Purpose
Provides a call to hard-coded targeting cursors.
Notes
tNum must be between 0 and 255 inclusive. Says toSay, and shows a cursor. Note that some of these might depend on factors in code to actually work, and might not have much effect when ran through a script - or could grant access to functionality that a player would normally not have access to.
Example of usage
// Can be used with a socket object
myChar.socket.PopUpTarget( 1, "Where do you wish to teleport to?" );1 - TELEPORT (teleports character to target location)
2 - DYE (will reset targeted item to default colour)
4 - REPAIRMETAL (Targeted metal item will be repaired. Checks Blacksmithing skill)
5 - DYEALL (used to give color to dyetubs)
6 - DVAT (Used for dying objects with the colour of the used dye tub)
9 - ITEMID (Select item to identify. Checks Item Identification skill)
10 - FISH (Select fishing location. Checks Fishing skill)
11 - INFO (Get info on targeted tile)
13 - SMITH (Blacksmithing skill usage via tools)
14 - MINE (Mining skill usage via tools)
15 - SMELTORE (Ore smelting targeting cursor)
16 - WSTATS (Show wander/movement details for targeted NPC)
17 - NPCRESURRECT (Used by NPC healers to resurrect dead players. In this context only works if target is identical to popuptarget user. Self-resurrection item?)
(To be continued)
Prototype
int ReadBytes( byteCount );
Purpose
Reads byteCount bytes from socket
Example of usage
sock.ReadBytes( 12 );Prototype
void SellTo( targNPC );
Purpose
Brings up the shopkeeper gump for selling to a vendor targNPC.
Example of usage
mySock.SellTo( myNPC );Prototype
void SendAddMenu( menuNum );
Purpose
Send the Add-menu to the character
Example of usage
socket.SendAddMenu( 1 );Prototype
void SoundEffect( soundID, bAllHear );
Purpose
Plays a sound originating from character associated with Socket
Notes
SoundID is the ID of the sound to play. If bAllHear is true, then everyone nearby hears it. If it's false, then only the Character associated with the Socket hears it.
Example of usage
// Play sound effect originating from character associated with the socket, which only that character can hear
socket.SoundEffect( 568, false );Prototype
void SysMessage( [msgColor,] string message, ... );
Purpose
Sends a string as a system message. Accepts up to 10 additional arguments which can be injected into the string as needed. Text colour can also be provided as an optional parameter prior to the string itself
Example of usage
socket.SysMessage( "Isn't the world great?" );
socket.SysMessage( GetDictionaryEntry(388), myNPC.name ); // Hello sir! My name is %s and I will be working for you.
socket.SysMessage( 0x42, "This message has a different color!" );Prototype
void WhoList( [bSendOnList] );
Purpose
Sends a list to client with all players currently online (if true parameter is provided) or offline (if no parameter or false is provided)
Example of usage
mySock.WhoList( true );Prototype
void GetSpawnRegion( spawnRegionNum )
Purpose
Returns SpawnRegion object for specified spawnRegionNum
Example of usage
// Return SpawnRegion object for spawn region #1 from spawns.dfn
var spawnRegion = GetSpawnRegion( i );
// Have character object pUser say the name of the spawnRegion
pUser.TextMessage( "The name of this SpawnRegion is: " + spawnRegion.name );Prototype
void GetSpawnRegionCount()
Purpose
Returns amount of SpawnRegions that exist
Example of usage
// Get total number of spawn regions
var spawnRegionCount = GetSpawnRegionCount();
pUser.TextMessage( "There are " + spawnRegionCount + " SpawnRegions on this server!" );
// Loop through all the spawn regions and print name of each one in UOX3 console
var spawnRegion;
for( var i = 0; i < spawnRegionCount; i++ )
{
spawnRegion = GetSpawnRegion( i );
Console.Print( "SpawnRegion Name: " + spawnRegion.name + "\n" );
}Prototype
void IterateOverSpawnRegions()
Purpose
Iterates over all SpawnRegions on the server.
Notes
For every object it comes across, the iterator will call onIterateSpawnRegions( SpawnRegionObject ) in the calling script.
Example of usage
// Iterate over all spawn regions and count how many times the iterate function returned true
var count = IterateOverSpawnRegions();
// This function runs once per spawn region
function onIterateSpawnRegions( toCheck )
{
Console.Print( "Spawn Region Number: " + toCheck.regionNum + "\n" );
Console.Print( "Spawn Region Name: " + toCheck.name + "\n" );
Console.Print( "Spawn Region World: " + toCheck.world + "\n" );
return true;
}References to Account objects can be gotten from a player Character's .account property (or a Socket .account property). Example
// Fetch reference to a player's Account object
var myAccount = myChar.account;
// Fetch username of Account
var myAccountName = myAccount.username;
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.isBanned (bool, true/false)
Get/Set whether Account is banned
.isCounselor (bool, true/false)
Get/Set whether Account is marked as a Counselor account
.isGM (bool, true/false)
Get/Set whether Account is marked as a GM account
.isOnline (bool, true/false)
Get whether someone is logged in to the Account
.isPublic (bool, true/false)
Get/Set whether Account info (contact/comment) can be considered public info
.isSeer (bool, true/false)
Get/Set whether Account is marked as a Seer account
.isSlot1Blocked (bool, true/false)
Get/Set whether slot 1 on Account is blocked
.isSlot2Blocked (bool, true/false)
Get/Set whether slot 2 on Account is blocked
.isSlot3Blocked (bool, true/false)
Get/Set whether slot 3 on Account is blocked
.isSlot4Blocked (bool, true/false)
Get/Set whether slot 4 on Account is blocked
.isSlot5Blocked (bool, true/false)
Get/Set whether slot 5 on Account is blocked
.isSlot6Blocked (bool, true/false)
Get/Set whether slot 6 on Account is blocked
.isSlot7Blocked (bool, true/false)
Get/Set whether slot 7 on Account is blocked
.isSuspended (bool, true/false)
Get/Set whether Account is suspended
.unused9 (bool, true/false)
Get/Set the unused9 flag. Currently unused
.unused10 (bool, true/false)
Get/Set the unused10 flag. Currently unused
.flags (hex, 0x0 - 0xffff)
Get flags set on Account (Read-Only)
.timeban (int, 0 - 999999)
Get/Set how long player is banned for, in minutes
.firstLogin (int, 0 - 999999)
Get a timestamp for when the account receives its first login, in minutes (since epoch)
.id (int)
Get ID for Account (Read-Only)
.lastIP (int)
Get last IP that was used to login with Account (Read-Only)
.character1 (object)
Get JS Object for character in slot 1 on Account (Read-Only)
.character2 (object)
Get JS Object for character in slot 2 on Account (Read-Only)
.character3 (object)
Get JS Object for character in slot 3 on Account (Read-Only)
.character4 (object)
Get JS Object for character in slot 4 on Account (Read-Only)
.character5 (object)
Get JS Object for character in slot 5 on Account (Read-Only)
.character6 (object)
Get JS Object for character in slot 6 on Account (Read-Only)
.character7 (object)
Get JS Object for character in slot 7 on Account (Read-Only)
.currentChar (object)
Get JS Object for character currently logged in on Account (Read-Only)
.comment (text, max 200 characters)
Get/Set Contact info/comment for Account
.username (text, max 200 characters)
Get username for Account (Read-Only)
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.allmove (bool, true/false)
Get/Set whether this character can move items set as immovable
.attackFirst (bool, true/false)
Get/Set whether character attacked first
.atWar (bool, true/false)
Get/Set whether character is in war mode
.canAttack (bool, true/false)
Get/Set whether character can attack other characters
.canBroadcast (bool, true/false)
Get/Set whether character can broadcast messages to other players by yelling
.canRun (bool, true/false)
Get/Set whether character (NPCs only) can run
.canSnoop (bool, true/false)
Get/Set whether character can snoop in backpacks of other characters
.createdOn (int, 0 - 999999)
Get a timestamp for when a player character was created, in minutes (since epoch)
.criminal (bool, true/false)
Get/Set whether the character is flagged as a criminal
.dead (bool, true/false)
Get whether character is dead (Read-Only)
.frozen (bool, true/false)
Get/Set whether character is frozen on the spot, unable to move
.hireling (bool, true/false)
Get/Set whether NPC can be hired as a hireling
.houseIcons (bool, true/false)
Get/Set whether player should see house icons instead of multis
.innocent (bool, true/false)
Get/Set whether character is flagged as innocent
.isAwake (bool, true/false)
Get/Set whether the character (NPC only) is marked as permanently awake or not. If true, NPC is always active regardless of the active status of the region it's in (which can be deactivated based on lack of player activity)
.isAnimal (bool, true/false)
Get whether character is flagged as an animal (Read-Only)
.isCasting (bool, true/false)
Get/Set whether character is casting a spell
.isChar (bool, true/false)
Get whether character is a character (always returns true for Characters) (Read-Only)
.isCounselor (bool, true/false)
Get/Set whether player has Counselor privileges
.isDispellable (bool, true/false)
Get/Set whether (NPC) character can be dispelled by the Dispel spell
.isflying (bool, true/false)
Get whether character is flying (Read-Only)
.isGM (bool, true/false)
Get/Set whether player has GM privileges
.isGMPageable (bool, true/false)
Get/Set whether player can see and respond to GM pages
.isGuarded (bool, true/false)
Get/Set whether character is guarded
.isHuman (bool, true/false)
Get whether character is considered a human (Read-Only)
.isIncognito (bool, true/false)
Get/Set whether character is incognito
.isItem (bool, true/false)
Get whether character is an item (always returns false for Characters) (Read-Only)
.isJailed (bool, true/false)
Get whether player is jailed (Read-Only)
.isMeditating (bool, true/false)
Get whether character is meditating (Read-Only)
.isonhorse (bool, true/false)
Get whether character is mounted (Read-Only)
.isPolymorphed (bool, true/false)
Get/Set whether player is polymorphed
.isRunning (bool, true/false)
Get whether character is running (Read-Only)
.isShop (bool, true/false)
Get/Set whether (NPC) character is a shopkeeper
.isSpawner (bool, true/false)
Get whether character is a spawner (always returns false for Characters) (Read-Only)
.isUsingPotion (bool, true/false)
Get/Set whether character is using a potion
.magicReflect (bool, true/false)
Get/Set whether magic reflection is active for the character
.mounted (bool, true/false)
Get/Set whether character is mounted
.murderer (bool, true/false)
Get/Set whether character is flagged as a murderer
.neutral (bool, true/false)
Get/Set whether character is flagged as neutral
.noNeedMana (bool, true/false)
Get/Set whether character needs mana to cast spells
.noNeedReags (bool, true/false)
Get/Set whether character needs magical reagents to cast spells
.noSkillTitles (bool, true/false)
Get/Set whether skill titles show for the character
.npc (bool, true/false)
Get whether character is an NPC (Read-Only)
.online (bool, true/false)
Get whether (player) character is online (Read-Only)
.partyLootable (bool, true/false)
Get/Set whether (player) character is lootable by party members upon death
.permanentMagicReflect (bool, true/false)
Get/Set whether permanent magic reflection is active for the character
.singClickSer (bool, true/false)
Get/Set whether single-clicking objects show their serial above the name
.squelch (bool, true/false)
Get/Set whether character is muted
.stabled (bool, true/false)
Get/Set whether (NPC) creature is stabled
.tamed (bool, true/false)
Get/Set whether (NPC) character is tame
.trainer (bool, true/false)
Get/set whether (NPC) character can train players in skills they know
.vulnerable (bool, true/false)
Get/Set whether character is vulnerable to damage/being attacked
.willhunger (bool, true/false)
Get/Set whether character will grow more hungry over time
.willthirst (bool, true/false)
Get/Set whether character will grow more thirsty over time
.shouldSave (bool, true/false)
Get/Set whether character should be saved in worldfiles. If false, character will not be saved and will be gone after the next server restart
.colour (hex, 0x0 - 0xffff)
Get/Set the color/hue of the character
.direction (hex, 0x0 - 0x7)
Get/Set the direction the character is facing
.emoteColour (hex, 0x0 - 0xffff)
Get/Set colour of the character's emote speech
.flag (hex, 0x1 - 0x8)
Get/Set NPC flag (0x1 = murderer, 0x2 = criminal, 0x4 = innocent, 0x8 = neutral)
.id (hex, 0x0 - 0xffff)
Get/Set the character's current body ID
.nextAct (hex, 0x0 - 0xff)
Get/Set the next spellcasting action character is going to do
.orgID (hex, 0x0 - 0xffff)
Get/Set the character's original body ID
.orgSkin (hex, 0x0 - 0xffff)
Get/Set the character's original skin (colour)
.priv (hex, 0x0 - 0xffff)
Get/Set the character's special privileges (if any) as a 16-bit bit-field. Combine values to set multiple privs. Supported privs:
.sayColour (hex, 0x0 - 0xffff)
Get/Set the colour/hue of the character's regular speech
.accountNum (int, 0 - 65535)
Get the account number the character belongs to
.actualDexterity (int, 0 - 32767)
Get the base dexterity stat for character, excluding any mods, bonuses etc. (Read-Only)
.actualIntelligence (int, 0 - 32767)
Get the base intelligence stat for character, excluding any mods, bonuses etc. (Read-Only)
.actualStrength (int, 0 - 32767)
Get the base strength stat for character, excluding any mods, bonuses etc. (Read-Only)
.aitype (int, 0 - 666)
Get/Set the AI Type for NPCs
See UOX3 Documentation section on NPC AI for details on available AIs and what they do.
.attack (int, 0 - 32767)
Get a randomized attack value for the character based on their skills, stats and equipment (Read-Only)
.attacker (object)
Get/Set the character currently attacking this character
.brkPeaceChance (int, 0 - 255)
Chance of character affected by peacemaking will break out of peace state
.cell (int, 0 - 127)
Get/Set the jail cell number of the character (if any)
.commandlevel (int)
Get/Set the command-level of the character. Default command-levels, as setup in dfndata/commands/commands.dfn: 0 = Player, 1 = Counselor, 2 = GM, 5 = Admin
.controlSlots (int, 0 - 65535)
Get/Set the total number of pet control slots available to the character
.controlSlotsUsed (int, 0 - 65535)
Get/Set the number of pet control slots currently in use by the character's pets
.deaths (int, 0 - 65535)
Get/Set the total number of deaths of a player character
.dexterity (int, 0 - 32767)
Get/Set the character's dexterity stat
.fame (int, 0 - 32767)
Get/Set the character's fame level
.fontType (int, 0 - 12)
Get/Set font type used by character's speech (0-9 ASCII, 0-12 Unicode)
.fx1 (int)
Get/Set FX1 coordinate of a character's wander area. See NPC Movement and Pathfinding in UOX3 Docs for details on how these are setup for different NPC wander types.
.fy1 (int)
Get/Set FY1 coordinate of a character's wander area. See NPC Movement and Pathfinding in UOX3 Docs for details on how these are setup for different NPC wander types.
.fx2 (int)
Get/Set FX2 coordinate of a character's wander area. See NPC Movement and Pathfinding in UOX3 Docs for details on how these are setup for different NPC wander types.
.fy2 (int)
Get/Set FY2 coordinate of a character's wander area. See NPC Movement and Pathfinding in UOX3 Docs for details on how these are setup for different NPC wander types.
.fz (int)
Get/Set FZ coordinate of a character's wander area. See NPC Movement and Pathfinding in UOX3 Docs for details on how these are setup for different NPC wander types.
.gender (int, 0 - 1)
Get/Set gender of character. 0 = male, 1 = female
.health (int, 0 - 32767)
Get/Set character's current health/hitpoints (cannot exceed value of maxhp property)
.hidamage (int, 0 - 32767)
Get/Set highest damage character can deal in combat with wrestling/unarmed attacks (randomized between lodamage and hidamage)
.housesCoOwned (int, 0 - 999)
Get number of houses co-owned by character (Read-Only)
.housesOwned (int, 0 - 999)
Get number of houses owned by character (Read-Only)
.hunger (int, 0 - 6)
Get/Set character's hunger status (0 - 6, where 0 is max hungry and 6 is max full. At 0, characters may start take hunger damage depending on server settings)
.hungerRate (int)
Get character's hunger rate, which determines how quickly (in seconds) they grow more hungry. This is either defined by the hunger DFN tag (hunger=hungerRate,hungerDamage) specified for the character's Race, or if that is not set (or set to 0), by the global hunger rate specified in uox.ini under the HUNGERRATE setting (Read-Only)
.hungerWildChance (int, 0 - 100)
Get/Set chance for an extremely hungry pet to go wild with every NPC AI loop
.instanceID (int, 0 - 65535)
Get/Set ID of instance of world that item exists in. Objects in different instances will not be able to interact with one another
.intelligence (int, 0 - 32767)
Get/Set intelligence attribute of character
.karma (int, -32768 - 32767)
Get/Set character's current karma level
.lightlevel (int, 0 - 255)
Get/Set character's fixed light level. Use value of 255 to disable fixed light level and start using global lightlevel again.
.lodamage (int, 0 - 32767)
Get/Set lowest damage character can deal in combat with wrestling/unarmed attacks (randomized between lodamage and hidamage)
.loyalty (int, 0 - 65535)
Get/Set the current loyalty of the NPC
.loyaltyRate (int, 0 - 65535)
Get the global royalty rate from UOX.INI. This is the amount of seconds between each time an NPC loses 1 loyalty (Read-Only)
.mana (int, 0 - 32767)
Get/Set character's current mana
.maxhp (int, 0 - 65535)
Get/Set character's maximum health
.maxLoyalty (int, 0 - 65535)
Get/Set the maximum loyalty of an NPC
.maxmana (int, 0 - 65535)
Get/Set character's maximum mana
.maxstamina (int, 0 - 65535)
Get/Set character's maximum stamina
.murdercount (int, 0 - 32767)
Get/Set number of players character has killed
.npcFlag (int, 0 - 2)
Get/Set (NPC) character's flag (0 = neutral (grey), 1 = innocent (blue), 2 = evil (red))
.oldWandertype (int, 0 - 7)
Get/Set character's old wandertype, usually set by code
.oldX (int, 0 - 7)
Get/Set the previous X coordinate of character (usually set by code when character moves)
.oldY (int, 0 - 7)
Get/Set the previous Y coordinate of character (usually set by code when character moves)
.oldZ (int, 0 - 7)
Get/Set the previous Z coordinate of character (usually set by code when character moves)
.orneriness (int, 0 - 65535)
Get/Set a pet's orneriness level - i.e. the difficulty of controlling the pet
.ownedItemsCount (int, 0 - 65535)
Get number of items player owns (Read-Only)
.ownerCount (int, 0 - 255)
Get the total number of owners a pet/follower has had (Read-Only)
.petCount (int, 0 - 65535)
Get/Set number of pets owned by character (Read-Only)
.poison (int, 0 - 5)
Get/Set character's current poisoned state
.poisonStrength (int, 0 - 5)
Get/Set the poison strength of the character, used to poison other characters in combat
.raceGate (int, 0 - 65535)
Get/Set ID of Race for which character has used a Race Gate, if any
.serial (int, 0 - 4294967295)
Get/Set unique serial for the character
.setPeace (int, 0 - 4294967295)
Set number of seconds that character will be forced into "peace" mode, unable to attack anyone in combat (Write-Only)
.scripttrigger (int)
(Legacy property for backwards compatibility) Get/Set a scriptID associated with the character. When using this to set a new scriptID, all other scriptIDs are cleared from the character. When getting the scriptID, the last scriptID in the character's list of scriptIDs are returned. To get/set multiple scriptIDs for a character, see .scriptTriggers property and/or AddScriptTrigger() Method.
.skillToPeace (int, 0 - 32767)
Get/Set peacemaking skill required to successfully pacify this NPC (1000 = 100.0 skillpoints)
.skillToProv (int, 0 - 32767)
Get/Set provocation skill required to successfully provoke this NPC (1000 = 100.0 skillpoints)
.skillToTame (int, 0 - 32767)
Get/Set animal taming skill required to successfully tame this NPC (1000 = 100.0 skillpoints)
.spattack (int, 1 - 8)
Get/Set maximum spell circle from which (NPC) character will cast spells in combat. See Spellcasting NPCs in UOX3 Documentation for more details
.spdelay (int, 0 - 127)
Get/Set the minimum delay in seconds between each time the (NPC) character will cast spells in combat. See Spellcasting NPCs in UOX3 Documentation for more details
.spellCast (int)
Get spell currently being cast by character (Read-Only)
.split (int, 0 - 127)
Get/Set the amount of NPCs a character will split into when hit in combat
.splitchance (int, 0 - 255)
Get/Set the chance of an NPC splitting into more characters when hit in combat
.stamina (int, 0 - 32737)
Get/Set the character's current stamina
.stealth (int, 0 - 127)
Get the number of steps character has taken in stealth (Read-Only)
.strength (int, 0 - 32737)
Get/Set the character's current strength
.tamedHungerRate (int, 0 - 32737)
Get/Set rate (in seconds) at which a tamed NPC pet grows hungry, as defined by the NPC DFN tag tamedhungerrate
.tamedThirstRate (int, 0 - 32737)
Get/Set rate (in seconds) at which a tamed NPC pet grows thirsty, as defined by the NPC DFN tag tamedthirstrate
.tempdex (int, 0 - 32737)
Get/Set a character's secondary dexterity stat, as set by stuff like bonuses from equipment, spells, via dexadd Item DFN tag, etc.
.tempint (int, 0 - 32737)
Get/Set a character's secondary intelligence stat, as set by stuff like bonuses from equipment, spells, via intadd Item DFN tag, etc
.tempstr (int, 0 - 32737)
Get/Set a character's secondary strength stat, as set by stuff like bonuses from equipment, spells, via stradd Item DFN tag, etc
.thirst (int, 0 - 6)
Get/Set character's thirst status (0 - 6, where 0 is max thirsty and 6 is max thirst quenched. At 0, characters may start take thirst stamina damage depending on server settings)
.thirstRate (int)
Get character's thirst rate, which determines how quickly (in seconds) they grow more thirsty. This is either defined by the thirst DFN tag (thirst=thirstRate,thirstDamage) specified for the character's Race, or if that is not set (or set to 0), by the global thirst rate specified in uox.ini under the THIRSTRATE setting (Read-Only)
.thirstWildChance (int, 0 - 100)
Get/Set chance for an extremely thirsty pet to go wild with every NPC AI loop
.townPriv (int, 0 - 2)
Get/Set the privilege a character has with their town (0 = Doesn't belong to a town, 1 = Resident, 2 = Mayor)
.visible (int, 0 - 3)
Get/Set visibility of character to other players (0 = Visible, 1 = Hidden, 2 = Magically Invisible, 3 = Visible to GMs only)
.wandertype (int, 0 - 3)
Get/Set wandertype for NPC (0 = None, [1 = Follow], 2 = Free, 3 = Box, 4 = Circle, 5 = Frozen, [6 = Flee, 7 = Pathfind]. Types 1, 6 and 7 are set primarily by code)
.weight (int, 0 - 2147483647)
Get/Set total weight of character (100 = 1.0 stone)
.worldnumber (int, 0 - 255)
Get/Set current world character is in
.x (int, 0 - 7144)
Get/Set X coordinate of character in the world
.y (int, 0 - 4095)
Get/Set Y coordinate of character in the world
.z (int, -128 - 127)
Get/Set Z coordinate of character in the world
.account (object)
Get JS Object reference to Account character belongs to (Read-Only)
.baseskills (object)
Get JS Object reference for baseskills (skill without modifiers) that can be used to get/set the value of individual skills using a syntax like .baseskills.alchemy = [0 - 1000] (1000 = 100.0 skillpoints) (Read-Only)
.guarding (object)
Get/Set the object (item/character) being guarded by this character
.guild (object)
Get/Set guild object that character belongs to
.multi (object)
Get/Set multi character is inside (Read-Only)
.owner (object)
Get/Set owner of character
.pack (object)
Get/Set character's root backpack object
.party (object)
Get/Set party character is a member of
.race (object)
Get/Set race (player) character belongs to. Currently simulates character going through a race gate - which only works for players!
.region (object)
Get/Set region character is in (Read-Only)
.scriptTriggers (object)
Get a list of scriptIDs associated with the character in the form of a JS object/comma-separated string, or set (add) a scriptID to the character's existing list of scriptIDs. If property sets a NULL value, all scriptIDs are cleared from character
.skillLock (object)
Get JS Object reference for skills that can be used to get/set the skill-lock value of individual skills using a syntax like .skillLock.alchemy = [0/1/2] (0 = increase, 1 = decrease, 2 = locked) (Read-Only)
.skills (object)
Get JS Object reference for skills that can be used to get/set the value of individual skills using a syntax like .skills.alchemy = [0 - 1000] (1000 = 100.0 skillpoints) (Read-Only)
.skillsused (object)
Get JS Object reference for skills that can be used to get/set whether individual skills are in use (???) (Read-Only)
.socket (object)
Get JS Object reference for socket associated with player character (Read-Only)
.target (object)
Get/Set character's current target
.town (object)
Get/Set town character is a citizen of
.foodList (text, max 127 characters)
Get/Set sectionID for list of food that creature will accept as food, from UOX3/dfndata/items/itemlists/foodlist.dfn
.guildTitle (text, max 127 characters)
Get/Set guild title of character that belongs to a guild
.name (text, max 127 characters)
Get/Set name of character
.title (text, max 60 characters)
Get/Set character's title, displayed in paperdoll
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.logEcho (int, 0 - 1)
Get/Set whether log calls get echo'd to screen
.mode (int, 0 - 127)
Get/Set current filter mode of the Console
References to Create entries can be gotten from the global CreateEntries object. Example:
// Fetch reference to Create entry 7 from Create DFNs
var createEntry = CreateEntries[7];
// Fetch name of Create entry
var createEntryName = createEntry.name;
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.colour (hex, 0x0 - 0xffff)
Get the colour associated with this Create entry (unused by code, but could be used by scripts) (Read-Only)
.sound (hex, 0x0 - 0xffff)
Get the sound effect to be played when item associated with Create entry is crafted (Read-Only)
.id (int)
Get the artwork ID used to display the item in crafting menus (Read-Only)
.minRank (int)
Get the minimum item rank that can be randomly applied to the crafted item based on the rank system, which can cause items to become weaker or stronger than average (Read-Only)
.maxRank (int)
Get the maximum item rank that can be randomly applied to the crafted item based on the rank system, which can cause items to become weaker or stronger than average. If rank system is off, the default rank value is 10 (max) (Read-Only)
.delay (int)
Get the delay in milliseconds before the crafting process completes and the item has been crafted (Read-Only)
.spell (int)
Get the spell ID of a spell required to be in the player's possession (in a spellbook) in order to craft the item. Primarily used by the Inscription skill (Read-Only)
.avgMinSkill (int)
Get the average minimum skill required to craft the item, based on all skills required to craft item (Read-Only)
.avgMaxSkill (int)
Get average skill required to craft the item with 100% success, based on all skills required to craft item (Read-Only)
.resources (object)
Get a JS object containing details for all the resources required to craft the item from this Create entry. Each resource reference comes with a few properties: amountNeeded, colour (Read-Only). Example:
// Fetch reference to Create entry 7 from Create DFNs
var createEntry = CreateEntries[7];
// Fetch list of resource requirements from Create entry
var resources = createEntry.resources;
// List out resource requirements
for( var i = 0; i < resources.length; i++ )
{
var resource = resources[i];
var amountNeeded = resource[0];
var resourceColour = resource[1];
var resourceIDs = resource[2];
var resourcesNeeded = "Amount: " + amountNeeded.toString() + ", Colour: " + resourceColour.toString() + ", resource IDs:";
for( var j = 0; j < resourceIDs.length; j++ )
{
resourcesNeeded += (" " + resourceIDs[j] );
}
pUser.TextMessage( resourcesNeeded );
}.skills (object)
Get a JS object containing details for the skills required to craft the item from this Create entry. Each skill reference comes with a few properties: skillNumber, minSkill and maxSkill (Read-Only). Example:
// Fetch reference to Create entry 7 from Create DFNs
var createEntry = CreateEntries[7];
// Fetch list of skill requirements from Create entry
var skills = createEntry.skills;
// List out the skill requirements
for( var i = 0; i < skills.length; i++ )
{
var skillReq = skills[i];
var skillNumber = skillReq[0];
var minSkill = skillReq[1];
var maxSkill = skillReq[2];
var skillRequirements = "SkillNumber: " + skillNumber.toString() + ", minSkill: " + minSkill.toString() + ", maxSkill: " + maxSkill.toString();
pUser.TextMessage( skillRequirements );
}.name (text)
Get the label applied to the item when shown in the crafting menu, which is not necessarily a reflection of the name of the actual item that will be crafted in the end (Read-Only)
.addItem (text)
Get the Item section ID of the item actually being crafted in the end, from Item DFNs (Read-Only)
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.numMembers (int)
Get last IP that was used to login with Account (Read-Only)
.numRecruits (int)
Get last IP that was used to login with Account (Read-Only)
.type (int)
Get/Set type of guild (0 - Standard, 1 - Order, 2 - Chaos, 3 - Unknown)
.master (object)
Get/Set Character JS Object for character that is considered Guild Master of the guild
.stone (object)
Get/Set Item JS Object for Guildstone
.abbreviation (text, max 3 characters)
Get/Set guild abbreviation
.charter (text, max ??? characters)
Get/Set guild charter
.name (text, max 127 characters)
Get/Set name of guild
.webPage (text, max ??? characters)
Get/Set guild webpage URL
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.canBeLockedDown (bool, true/false)
Get/Set whether item can be locked down. Doors, field-spells, signs or already locked down items cannot be locked down.
.corpse (bool, true/false)
Get/Set whether item is considered a corpse
.damageHeat (bool, true/false)
Get/Set whether item can deal Heat damage (currently does nothing, but can be used in scripts)
.damageCold (bool, true/false)
Get/Set whether item can deal Cold damage (currently does nothing, but can be used in scripts)
.damageLight (bool, true/false)
Get/Set whether item can deal Light damage (currently does nothing, but can be used in scripts)
.damageLightning (bool, true/false)
Get/Set whether item can deal Lightning damage (currently does nothing, but can be used in scripts)
.damagePoison (bool, true/false)
Get/Set whether item can deal Poison damage (currently does nothing, but can be used in scripts)
.damageRain (bool, true/false)
Get/Set whether item can deal Rain damage (currently does nothing, but can be used in scripts)
.damageSnow (bool, true/false)
Get/Set whether item can deal Snow damage (currently does nothing, but can be used in scripts)
.decayable (bool, true/false)
Get/Set whether item will decay
.divinelock (bool, true/false)
Get/Set whether item was locked by a GM (i.e. cannot be unlocked with lockpicking/magic unlock)
.isChar (bool, true/false)
Returns false for items (Read-Only)
.isContType (bool, true/false)
Gets whether item is a container; returns true if item is on layer 21 (backpack) or 29 (bankbox) on a Character, or if item has types 1, 8, 63, 64, 65 or 87 (Read-Only
.isDamageable (bool, true/false)
Get/Set whether item can be damaged by attacks from Characters
.isDispellable (bool, true/false)
Get/Set whether item is considered dispellable by the Dispel spell (mostly used by field-spell effects)
.isDyeable (bool, true/false)
Get/Set whether item can be dyed using normal dye tubs
.isDoorOpen (bool, true/false)
Get/Set whether an object of type 12/13 (door/locked door) is open
.isFieldSpell (bool, true/false)
Get/Set whether item is considered part of a field spell
.isGuarded (bool, true/false)
Get/Set whether item is guarded by someone
.isItem (bool, true/false)
Returns true for items (Read-Only)
.isItemHeld (bool, true/false)
Get/Set whether item is being "held" on a player's cursor
.isLeatherType (bool, true/false)
Returns true if item ID is between 0x13C6 and 0x13E2 (leather/studded leather armor), or between 0x144E and 0x1457 (bone armor) (Read-Only)
.isLockedDown (bool, true/false)
Get/Set whether item is locked down, i.e. has a movable value of 3 (Read-Only)
.isMetalType (bool, true/false)
Returns true if item is made of metal based on a comparison to various item ID ranges (Read-Only)
.isNewbie (bool, true/false)
Get/Set whether item is marked as newbie/blessed. If true, item won't drop from a character upon death
.isPileable (bool, true/false)
Get/Set whether item can be stacked with other items of same type. Note that not all items support being stacked in client
.isShieldType (bool, true/false)
Returns true if item is a shield, based on comparison to various item ID ranges (Read-Only)
.isSpawner (bool, true/false)
Returns true if item is a spawner (Read-Only)
.isWipeable/.wipable (bool, true/false)
Get/Set whether item is marked as wipeable, i.e. can be deleted using the 'wipe command
.shouldSave (bool, true/false)
Get/Set whether item should be saved in worldfiles. If false, item will not be saved and will be gone after the next server restart
.ammoID (hex, 0x0 - 0xffff)
Get/Set ID for ammo used by ranged weapon
.ammoHue (hex, 0x0 - 0xffff)
Get/Set hue of ammo used by ranged weapon
.ammoFX (hex, 0x0 - 0xffff)
Get/Set ID for ammo used by ranged weapon
.ammoFXHue (hex, 0x0 - 0xffff)
Get/Set ID of projectile FX shown when firing ranged weapon
.ammoFXRender (hex, 0x0 - 0xffff)
Get/Set hue of projectiles fired by ranged weapons
.colour (hex, 0x0 - 0xffff)
Get/Set colour of item
.dir (hex, 0x0 - 0xff)
Get/Set direction in which this item is facing. For lightsources, this determines the light radius instead.
.id (hex, 0x0 - 0xffff)
Get/Set the ID of item
.layer (hex, 0x0 - 0xff)
Get/Set the layer this item is on when equipped. See full list of item layers in UOX3 Docs!
.more (hex, 0x0 - 0xffffffff)
Get/Set temporary more value for this item. See list of DFN tags for items in UOX3 Docs for more details!
.morex (hex, 0x0 - 0xffffffff)
Get/Set temporary morex value for this item. See list of DFN tags for items in UOX3 Docs for more details!
.morey (hex, 0x0 - 0xffffffff)
Get/Set temporary morey value for this item. See list of DFN tags for items in UOX3 Docs for more details!
.morez (hex, 0x0 - 0xffffffff)
Get/Set temporary morez value for this item. See list of DFN tags for items in UOX3 Docs for more details!
.ac (int)
Get/Set armor class of item. If a weapon's armor class matches the armor class of the hit location during combat, it deals double damage - if ARMORCLASSDAMAGEBONUS is enabled in UOX.INI
.amount (int, 1 - 65535)
Get/Set amount of items in pile
.att (int)
Get a randomized damage value between lodamage and hidamage properties. If used to set a value, will set both lodamage and hidamage properties to the same value (Read-Only)
.baseRange (int)
Get/Set the base range of a throwing weapon, before being affected by a character's strength
.baseWeight (int)
Get/Set the base, unchanging weight of an item - primarily used for the weight of containers without consideration for any items inside
.buyvalue (int)
Get/Set the amount of money it costs to buy this item from a vendor
.carveSection (int)
Get/Set the carve-section of a corpse item from carve.dfn. Determines which items to spawn when the corpse is carved
.creator (int)
Get/Set serial of item's creator - primarily used in crafting/for maker's marks
.decaytime (int)
Get/Set the amount of time (in seconds) it takes the item to decay
.def (int)
Get/Set the item's defense value (Physical Resistance post-AoS, AR pre-AoS)
.dexterity (int)
Get/Set the amount of dexterity required to wield this item, if it can be equipped
.entryMadeFrom (int)
Get/Set entry ID from create DFNs from which the item was crafted
.health (int)
Get/Set the current amount of hitpoints of the item
.hidamage (int)
Get/Set the maximum amount of damage the item can deal, if it's a weapon
.instanceID (int, 0 - 65535)
Get/Set the instanceID of the world instance the object exists in. Default is 0 for all objects. Objects in different instances cannot see/interact with one another.
.intelligence (int)
Get/Set the amount of intelligence required to wield this item, if it can be equipped
.itemsinside (int)
Get the amount of items inside a container (excluding sub-containers?) (Read-Only)
.lodamage (int)
Get/Set the minimum amount of damage the item can deal, if it's a weapon
.madeWith (int)
Get/Set ID of primary skill used to craft item
.maxhp (int)
Get/Set the maximum amount of hitpoints an item can have
.maxItems (int)
Get/Set the maximum amount of items a container can contain (including sub-containers)
.maxRange (int)
Get/Set the max range of archery weapons, and the cap for how far baseRange can extend for throwing weapons based on modifiers like character strength
.maxUses (int)
Get/Set the max amount of remaining uses an item (like a tool) can have.
.movable (int)
Get/Set the movable state of an item (0 - default according to client tiledata, 1 = movable, 2 = immovable, 3 = locked down)
.oldX (int)
Get the old X coordinate for an item, which will differ from current X coordinate if the position of the item has changed
.oldY (int)
Get the old Y coordinate for an item, which will differ from current Y coordinate if the position of the item has changed
.oldZ (int)
Get the old Z coordinate for an item, which will differ from current Z coordinate if the position of the item has changed (Read-Only)
.poison (int)
Get/Set poison strength applied to item such as weapons and food (from 1 to 4, where 1 = Weak poison, 4 = Deadly poison)
.rank (int, 1-10)
Get/Set the quality-rank of this item (used in item-creation, for instance)
.resistCold (int, 0-1000)
Get/Set the item's Cold Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.resistHeat (int, 0-1000)
Get/Set the item's Heat Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.resistLight (int, 0-1000)
Get/Set the item's Light Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.resistLightning (int, 0-1000)
Get/Set the item's Lightning Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.resistPoison (int, 0-1000)
Get/Set the item's Poison Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.resistRain (int, 0-1000)
Get/Set the item's Rain Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.resistSnow (int, 0-1000)
Get/Set the item's Snow Resistance (0-1000, where 1000 = 100.0%) - no effect implemented yet
.restock (int)
Get/Set the amount of this item a vendor will restock in their shop, if they carry it
.scripttrigger (int)
(Legacy property for backwards compatibility) Get/Set a scriptID associated with the item. When using this to set a new scriptID, all other scriptIDs are cleared from the item. When getting the scriptID, the last scriptID in the item's list of scriptIDs are returned. To get/set multiple scriptIDs for an item, see .scriptTriggers property and/or AddScriptTrigger() Method.
.serial (int)
Get the unique serial assigned to this item (Read-Only)
.sellvalue (int)
Get/Set the amount of gold one can receive by selling this item to a vendor that carries it in their stock
.speed (int)
Get/Set the speed of the item, primarily used for weapons to determine how fast/how often the character wielding the weapon can attack in combat
.strength (int)
Get/Set the amount of strength required to wield this item, if it can be equipped
.tempTimer (int)
Get/Set timer value used by container-spawners to determine when to spawn an item next (if maximum items spawned from container hasn't been reached yet)
.totalItemCount (int)
Get the total amount of items contained within a container, including sub-containers (Read-Only)
.type (int)
Get/Set the item type of the item. See full list in UOX3 Docs!
.usesLeft (int)
Get/Set the current amount of remaining uses an item (like a tool) has. Cannot exceed value of .maxUses property
.visible (int)
Get/Set the visibility state of the item (0 = Visible, 1 = Temporarily hidden (visible to Owner), 2 = Invisible (Magic), 3 = Permanently hidden (GM hidden))
.weight (int)
Get/Set the total weight of an item. 1000 = 10.00 stones, 100 = 1.00 stones, 10 = 0.1 stones, 1 = 0.01 stones
.weightMax (int)
Get/Set the maximum weight in stones a container can hold. 1000 = 10.00 stones, 100 = 1.00 stones, 10 = 0.1 stones, 1 = 0.01 stones
.worldnumber (int)
Get/Set the world in which the item currently exists (0 = Felucca, 1 = Trammel, 2 = Ilshenar, 3 = Malas, 4 = Ter-mur)
.x (int)
Get/Set item's X coordinate in the world. Also used to set item's location within a container
.y (int)
Get/Set item's Y coordinate in the world. Also used to set item's location within a container
.z (int, -128 to 127)
Get/Set item's Z coordinate in the world
.container (object)
Get/Set object reference to the container the item is contained in. Can be an Item or a Character
.multi (object)
Get object reference to Multi an item is contained within (Read-Only)
.owner (object)
Get/Set the owner (Character) of item
.race (object)
Get object reference to Race associated with item. Race can be set by providing race ID of new race to set
.scriptTriggers (object)
Get a list of scriptIDs associated with the item in the form of a JS object/comma-separated string, or set (add) a scriptID to the item's existing list of scriptIDs. If property sets a NULL value, all scriptIDs are cleared from item
.desc (text, max 127 characters)
Get/Set description of item. Primarily used to describe items in player vendors
.event (text, max 127 characters)
Get/Set custom event name to associate item with. Primarily used by world templates to allow loading/unloading event-specific decorations
.name (text, max 127 characters)
Get/Set name of item
.name2 (text, max 127 characters)
Get/Set secondary name of item - used in relation to magical items whose names get revealed upon successful use of Item Identification
.title (text, max 59 characters)
Get/Set title of item. Currently not used for anything
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
Multis (items spawned as boats/houses) inherit all the properties of regular Items, but also have the following unique ones:
.isPublic (bool, true/false)
Get/Set the private/public state of a multi
.bans (int)
Get the number of banned players in a multi's ban list (Read-Only)
.banX (int, 0 - 32767)
Get/Set the ban location X offset for the multi
.banY (int, 0 - 32767)
Get/Set the ban location Y offset for the multi
.friends (int)
Get the number of friends in a multi's friend list (Read-Only)
.guests (int)
Get the number of guests in a multi's guest list (Read-Only)
.lockdowns (int)
Get the number of lockdowns in a multi (Read-Only)
.maxBans (int, 0 - 65535)
Get/Set the max number of banned players allowed in a multi's ban list
.maxFriends (int, 0 - 65535)
Get/Set the max number of friends allowed in a multi's friend list
.maxGuests (int, 0 - 65535)
Get/Set the max number of guests allowed in a multi's guest list
.maxLockdowns (int, 0 - 65535)
Get/Set the max number of lockdowns allowed in a multi
.maxOwners (int, 0 - 65535)
Get/Set the max number of owners allowed in a multi's owner list
.maxSecureContainers (int, 0 - 65535)
Get/Set the max number of secure containers allowed in a multi
.maxTrashContainers (int, 0 - 65535)
Get/Set the max number of trash containers allowed in a multi
.maxVendors (int, 0 - 65535)
Get/Set the max number of player vendors allowed in a multi
.owners (int)
Get the number of owners in a multi's owner list (Read-Only)
.secureContainers (int)
Get the number of secure containers in a multi (Read-Only)
.trashContainers (int)
Get the number of trash containers in a multi (Read-Only)
.vendors (int)
Get the number of player vendors in a multi (Read-Only)
.buildTimestamp (text)
Get/Set the timestamp for when the house was originally placed. When getting, timestamp is returned as a string. When setting... it doesn't matter what you set, because server will generate a timestamp on its own!
.deed (text)
Get/Set the item sectionID for deed used to place multi
.tradeTimestamp (text)
Get/Set the timestamp for when the house was last traded to another player. When getting, timestamp is returned as a string. When setting... it doesn't matter what you set, because server will generate a timestamp on its own!
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.magicResistance (int, 0.0-100.0)
Get/Set magic resistance bonus for members of this race, between 0.0 and 100.0 % (currently not used in code, but can be used in scripts)
.poisonResistance (int, 0.0-100.0)
Get/Set poison resistance bonus for members of this race, between 0.0 and 100.0 % (currently not used in code, but can be used in scripts)
.isPlayerRace (bool, true/false)
Get/Set whether race is marked as a player race, i.e. a race usable by players (via something like Race Gates)
.requiresBeard (bool, true/false)
Get/Set whether a beard is required for members of this race. If true, and a player without a beard steps through a Race Gate associated with this race, a random beard will be assigned to them
.requiresNoBeard (bool, true/false)
Get/Set whether no beard is required for members of this race. If true, and a player with a beard steps through a Race Gate associated with this race, their beard will be removed
.armourClass (int, 0-255)
Get/Set the armor class restriction of the race. Race will be unable to equip any armor with the specified AC
.id (int, 0-65535)
Get the unique ID of the race (Read-Only)
.genderRestrict (int, 1-2)
Get/Set whether race is restricted to characters with male (1) or female (2) genders
.languageSkillMin (int, 0-65535)
Get/Set minimum skillpoints in Spirit Speak skill required for non-members of this race to understand speech from members of the race
.nightVision (int, 0-255)
Get/Set light level at which night vision kicks in for members of the race. If world light level (or light level of weather system in a region, or dungeon light level) is brighter than this (i.e. lower value) nothing happens. If light level is darker (higher value) than this, the character's personal light level gets adjusted to raceLightLevel - worldLightLevel.
.visibleDistance (int, 0-127)
Get/Set default visibility range of race. Defaults to 18
.name (text, max 3 characters)
Get/Set name of race
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.canCastAggressive (bool, true/false)
Get/Set whether aggressive spells can be cast in this region
.canGate (bool, true/false)
Get/Set whether Gate spell can be used in this region
.canMark (bool, true/false)
Get/Set whether Mark spell can be used in this region
.canPlaceHouse (bool, true/false)
Get/Set whether players can place houses within this region
.canRecall (bool, true/false)
Get/Set whether Recall spell can be used in this region
.canTeleport (bool, true/false)
Get/Set whether Teleport spell can be used in this region
.isDungeon (bool, true/false)
Get/Set whether region is considered a dungeon. Primarily used for light level stuff, and to determine if houses can be placed in a region (houses cannot be placed in dungeons)
.isGuarded (bool, true/false)
Get/Set whether region is under protection of NPC guards
.isSafeZone (bool, true/false)
Get/Set whether region is considered a safe zone. If true, no hostile actions can be taken towards other players in this region
.taxResource (hex, 0x0 - 0xffff)
Get/Set item ID of resource being taxed in this region. Used by Townstone system.
.appearance (int, 0-4)
Get/set appearance of region (0 = Spring, 1 = Summer, 2 = Autumn, 3 = Winter, 4 = Desolation)
.chanceBigOre (int, 0-100)
Get/Set chance to find big ore in the region
.health (int, 0-32767)
Get/Set the health of townstone in this region. Used by Townstone system
.id (int)
Get region number (from region DFNs) for the region (Read-Only)
.instanceID (int, 0-65535)
Get/Set the instanceID the region exists in
.mayor (int, 0-4294967295)
Get/Set serial of character who is considered town mayor of the region. Used by Townstone system
.music (int, 0-65535)
Get/set default music to play in this region, based on sections of music lists (MUSICLIST #) setup in regions.dfn based on entries from config.txt in UO client's music folder
.numGuards (int, 0-65535)
Get the number of guards supported by the region. Used by Townstone system
.numOrePrefs (int)
Get the number of ore preferences present for the region (Read-Only)
.population (int)
Get population of the region. Used by Townstone system (Read-Only)
.race (int, 0-65535)
Get/Set ID of the race this region belongs to
.reserves (int, 0-4294967295)
Get/set collected resource reserves for region. Used by Townstone system
.scripttrigger (int)
(Legacy property for backwards compatibility) Get/Set a scriptID associated with the region. When using this to set a new scriptID, all other scriptIDs are cleared from the region. When getting the scriptID, the last scriptID in the region's list of scriptIDs are returned. To get/set multiple scriptIDs for a region, see .scriptTriggers property and/or AddScriptTrigger() Method.
.tax (int, 0-65535)
Get/Set the amount of gold taxed from region members. Used by Townstone system
.taxes (int, 0-4294967295)
Get/Set collected gold reserves for region. Used by Townstone system
.weather (int, 0-65535)
Get/Set ID of weather system from UOX3/dfndata/weather/weather.dfn applied to this region
.worldNumber (int, 0-255)
Get/Set the worldnumber of the region
.scriptTriggers (object)
Get a list of scriptIDs associated with the region in the form of a JS object/comma-separated string, or set (add) a scriptID to the region's existing list of scriptIDs. If property sets a NULL value, all scriptIDs are cleared from region
.members (text)
Get list of serials belonging to members of the region, in the form of a comma-separated string. Used by Townstone system
.name (text, max 127 characters)
Get/Set name of region
.owner (text, max 127 characters)
Get/Set name of owner of the guards in the region
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.logAmount (int, 0-32767)
Get/Set amount of log resources available in given resource object
.logTime (int, 0-4294967295)
Get/Set the respawn timer of log resources in given resource object
.oreAmount (int, 0-32767)
Get/Set amount of ore resources available in given resource object
.oreTime (int, 0-4294967295)
Get/Set the respawn timer of ore resources in given resource object
.fishAmount (int, 0-32767)
Get/Set amount of fish resources available in given resource object
.fishTime (int, 0-4294967295)
Get/Set the respawn timer of fish resources in given resource object
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.cryptClient (bool, true/false)
Get/Set whether socket is set to crypt mode
.firstPacket (bool, true/false)
Get/Set whether socket has received its first packet yet
.logging (bool, true/false)
Get/Set whether packet logging is enabled for socket
.newClient (bool, true/false)
Get/Set property used to determine if connection is new or old
.wasIdleWarned (bool, true/false)
Get/Set whether socket has been warned of idling. If true, will eventually lead to client being disconnected if player keeps idling
.targetOK (bool, true/false)
Get/Set whether socket is ready/waiting to receive a target selection from client
.flags (hex, 0x0 - 0xffff)
Get flags set on Account (Read-Only)
.bytesSent (int, 0-4294967295)
Get amount of bytes sent to socket from server (resets every 10 seconds) (Read-Only)
.bytesReceived (int, 0-4294967295)
Get amount of bytes received from socket (resets every 10 seconds) (Read-Only)
.clickX (int, -32768 to 32767)
Get/Set temporary integer value on socket
.clickY (int, -32768 to 32767)
Get/Set temporary integer value on socket
.clickZ (int, -128 to 127)
Get/Set temporary integer value on socket
.clientMajorVer (int, 0-255)
Get/Set major client version value on socket. Normally sent by client and set by server during login
.clientMinorVer (int, 0-255)
Get/Set minor client version value on socket. Normally sent by client and set by server during login
.clientSubVer (int, 0-255)
Get/Set client sub version value on socket. Normally sent by client and set by server during login
.clientLetterVer (int, 0-255)
Get/Set client letter version value on socket. Normally sent by client and set by server during login
.clientType (int, 0-255)
Get/Set client type on socket. Normally sent by client and set by server during login. Supported values:
.currentSpellType (int, 0-255)
Get/Set the current spell type of the socket (0 = Normal spellcast, 1 = Scroll, 2 = Wand)
.language (int, 0-133)
Get/Set ID representing the language code set in the client. Languages values supported by UOX3's Dictionary system (Czech, English, French, German, Italian, Portuguese, Spanish)
.pickupSpot (int, 0-5)
Get/Set the spot where an item held on socket/cursor was picked up from (0 = Nowhere, 1 = Ground, 2 = Own pack, 3 = Other pack, 4 = Paperdoll, 5 = Bank)
.pickupX (int, 0-32767)
Get/Set the X world coordinate an item held on socket/cursor was picked up from
.pickupY (int, 0-32767)
Get/Set the Y world coordinate an item held on socket/cursor was picked up from
.pickupZ (int, -128 to 127)
Get/Set the Z world coordinate an item held on socket/cursor was picked up from
.tempInt (int, -2147483648 to 2147483647)
Get/Set temporary integer value on socket. Primarily used by code
.tempInt2 (int, -2147483648 to 2147483647)
Get/Set temporary integer value on socket. Primarily used by JS scripts
.walkSequence (int, 0-32767)
Get/Set walk sequence value of the socket. Set by server when client sends a movement request
.account (object)
Get JS object reference to account associated with socket (Read-Only)
.currentChar (object)
Get/Set JS object reference to character currently associated with socket (character player is logged in with)
.target (object)
Get JS object reference to last Item/Character targeted by client (Read-Only)
.tempObj (object)
Get/Set temporary JS object (Character/Item) reference on socket. Primarily used by code
.tempObj2 (object)
Get/Set temporary JS object (Character/Item) reference on socket. Primarily used by JS scripts
.xText (text)
Get/Set temporary text value on socket
A Character's Skill Properties can be gotten/set via object references to either "baseskills" (base skill before modifiers) or "skills" (skill after modifiers) JS objects. Examples:
// Get myChar's base Alchemy skill
var alchemy = myChar.baseskills.alchemy;
// Get myChar's Alchemy skill (after modifiers)
var alchemy = myChar.skills.alchemy;
// Set myChar's base Tinkering skill to 100.0
myChar.baseskills.tinkering = 1000; // 100.0 skillpoints
// Set myChar's Tinkering skill (after modifiers) to 73.5
myChar.skills.tinkering = 735; // 73.5 skillpointsObject properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
alchemy (int)
Get/Set a character's skill points in alchemy
anatomy (int)
Get/Set a Character's skillpoints in the Anatomy skill (1000 = 100.0, 10 = 1.0)
animallore (int)
Get/Set a Character's skillpoints in the Animal Lore skill (1000 = 100.0, 10 = 1.0)
itemid (int)
Get/Set a Character's skillpoints in the Item Identification skill (1000 = 100.0, 10 = 1.0)
armslore (int)
Get/Set a Character's skillpoints in the Arms Lore skill (1000 = 100.0, 10 = 1.0)
parrying (int)
Get/Set a Character's skillpoints in the Parrying skill (1000 = 100.0, 10 = 1.0)
begging (int)
Get/Set a Character's skillpoints in the Begging skill (1000 = 100.0, 10 = 1.0)
blacksmithing (int)
Get/Set a Character's skillpoints in the Blacksmithing skill (1000 = 100.0, 10 = 1.0)
bowcraft (int)
Get/Set a Character's skillpoints in the Bowcraft/Fletching skill (1000 = 100.0, 10 = 1.0)
peacemaking (int)
Get/Set a Character's skillpoints in the Peacemaking skill (1000 = 100.0, 10 = 1.0)
camping (int)
Get/Set a Character's skillpoints in the Camping skill (1000 = 100.0, 10 = 1.0)
carpentry (int)
Get/Set a Character's skillpoints in the Carpentry skill (1000 = 100.0, 10 = 1.0)
cartography (int)
Get/Set a Character's skillpoints in the Cartography skill (1000 = 100.0, 10 = 1.0)
cooking (int)
Get/Set a Character's skillpoints in the Cooking skill (1000 = 100.0, 10 = 1.0)
detectinghidden (int)
Get/Set a Character's skillpoints in the Detecting Hidden skill (1000 = 100.0, 10 = 1.0)
enticement (int)
Get/Set a Character's skillpoints in the Enticement skill (1000 = 100.0, 10 = 1.0)
evaluatingintel (int)
Get/Set a Character's skillpoints in the Evaluating Intelligence skill (1000 = 100.0, 10 = 1.0)
healing (int)
Get/Set a Character's skillpoints in the Healing skill (1000 = 100.0, 10 = 1.0)
fishing (int)
Get/Set a Character's skillpoints in the Fishing skill (1000 = 100.0, 10 = 1.0)
forensics (int)
Get/Set a Character's skillpoints in the Forensics skill (1000 = 100.0, 10 = 1.0)
herding (int)
Get/Set a Character's skillpoints in the Herding skill (1000 = 100.0, 10 = 1.0)
hiding (int)
Get/Set a Character's skillpoints in the Hiding skill (1000 = 100.0, 10 = 1.0)
provocation (int)
Get/Set a Character's skillpoints in the Provocation skill (1000 = 100.0, 10 = 1.0)
inscription (int)
Get/Set a Character's skillpoints in the Inscription skill (1000 = 100.0, 10 = 1.0)
lockpicking (int)
Get/Set a Character's skillpoints in the Lockpicking skill (1000 = 100.0, 10 = 1.0)
magery (int)
Get/Set a Character's skillpoints in the Magery skill (1000 = 100.0, 10 = 1.0)
magicresistance (int)
Get/Set a Character's skillpoints in the Resisting Spells skill (1000 = 100.0, 10 = 1.0)
tactics (int)
Get/Set a Character's skillpoints in the Tactics skill (1000 = 100.0, 10 = 1.0)
snooping (int)
Get/Set a Character's skillpoints in the Snooping skill (1000 = 100.0, 10 = 1.0)
musicianship (int)
Get/Set a Character's skillpoints in the Musicianship skill (1000 = 100.0, 10 = 1.0)
poisoning (int)
Get/Set a Character's skillpoints in the Poisoning skill (1000 = 100.0, 10 = 1.0)
archery (int)
Get/Set a Character's skillpoints in the Archery skill (1000 = 100.0, 10 = 1.0)
spiritspeak (int)
Get/Set a Character's skillpoints in the Spirit Speak skill (1000 = 100.0, 10 = 1.0)
stealing (int)
Get/Set a Character's skillpoints in the Stealing skill (1000 = 100.0, 10 = 1.0)
tailoring (int)
Get/Set a Character's skillpoints in the Tailoring skill (1000 = 100.0, 10 = 1.0)
taming (int)
Get/Set a Character's skillpoints in the Animal Taming skill (1000 = 100.0, 10 = 1.0)
tasteid (int)
Get/Set a Character's skillpoints in the Taste Identification skill (1000 = 100.0, 10 = 1.0)
tinkering (int)
Get/Set a Character's skillpoints in the Tinkering skill (1000 = 100.0, 10 = 1.0)
tracking (int)
Get/Set a Character's skillpoints in the Tracking skill (1000 = 100.0, 10 = 1.0)
veterinary (int)
Get/Set a Character's skillpoints in the Veterinary skill (1000 = 100.0, 10 = 1.0)
swordsmanship (int)
Get/Set a Character's skillpoints in the Swordsmanship skill (1000 = 100.0, 10 = 1.0)
macefighting (int)
Get/Set a Character's skillpoints in the Mace Fighting skill (1000 = 100.0, 10 = 1.0)
fencing (int)
Get/Set a Character's skillpoints in the Fencing skill (1000 = 100.0, 10 = 1.0)
wrestling (int)
Get/Set a Character's skillpoints in the Wrestling skill (1000 = 100.0, 10 = 1.0)
lumberjacking (int)
Get/Set a Character's skillpoints in the Lumberjacking skill (1000 = 100.0, 10 = 1.0)
mining (int)
Get/Set a Character's skillpoints in the Mining skill (1000 = 100.0, 10 = 1.0)
meditation (int)
Get/Set a Character's skillpoints in the Meditation skill (1000 = 100.0, 10 = 1.0)
stealth (int)
Get/Set a Character's skillpoints in the Stealth skill (1000 = 100.0, 10 = 1.0)
removetrap (int)
Get/Set a Character's skillpoints in the Remove Trap skill (1000 = 100.0, 10 = 1.0)
necromancy (int)
Get/Set a Character's skillpoints in the Necromancy skill (1000 = 100.0, 10 = 1.0)
focus (int)
Get/Set a Character's skillpoints in the Focus skill (1000 = 100.0, 10 = 1.0)
chivalry (int)
Get/Set a Character's skillpoints in the Chivalry skill (1000 = 100.0, 10 = 1.0)
bushido (int)
Get/Set a Character's skillpoints in the Bushido skill (1000 = 100.0, 10 = 1.0)
ninjitsu (int)
Get/Set a Character's skillpoints in the Ninjitsu skill (1000 = 100.0, 10 = 1.0)
spellweaving (int)
Get/Set a Character's skillpoints in the Spellweaving skill (1000 = 100.0, 10 = 1.0)
imbuing (int)
Get/Set a Character's skillpoints in the Imbuing skill (1000 = 100.0, 10 = 1.0)
mysticism (int)
Get/Set a Character's skillpoints in the Mysticism skill (1000 = 100.0, 10 = 1.0)
throwing (int)
Get/Set a Character's skillpoints in the Throwing skill (1000 = 100.0, 10 = 1.0)
allskills (int)
Get/Set a Character's skillpoints in ALL skills (1000 = 100.0, 10 = 1.0)
Skills also have some inherit properties unrelated to Characters. These can be accessed by getting a reference to the skill in question via the global Skills reference. Examples:
// Fetch reference to Alchemy skill
var alchemySkill = Skills[0]; // 0 = ID of Alchemy skill in skills.dfn
var alchemySkillDelay = alchemySkill.skillDelay; // Get the skill-delay defined for Alchemy skill in skills.dfnstrength (int)
Get the weighting value that determines how likely the Strength stat is to increase from using the skill in question
dexterity (int)
Get the weighting value that determines how likely the Dexterity stat is to increase from using the skill in question
intelligence (int)
Get the weighting value that determines how likely the Intelligence stat is to increase from using the skill in question
skillDelay (int)
Get the amount of time in seconds from the skill in question is used, until it can be used again
scriptID (int)
Get the scriptID associated with the skill, as registered by skill-scripts in jse_fileassociations.scp
.name (text)
Get name of skill (Read-Only)
.madeWord (text)
Get skill's "made word" - i.e. verb used to describe how an item was crafted. Ex: "forged" for Blacksmithing, "mixed" for Alchemy (Read-Only)
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
Spawners (items spawned as Spawner objects with item type 61-65 or 69) inherit all the properties of regular Items, but also have a few unique ones:
.sectionalist (bool, true/false)
Get/Set whether spawner should be trying to spawn objects from a list of objects
.mininterval (int)
Get/Set the minimum amount of time for this spawner to spawn another object
.maxinterval (int)
Get/Set the maximum amount of time for this spawner to spawn another object
.spawnsection (text)
Get/Set the Item or NPC script section (or ITEMLIST/NPCLIST) to spawn from
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
.onlyOutside (bool, true/false)
Get/Set whether NPCs should only spawn outside buildings
.isSpawner (bool, true/false)
Get/Set whether items spawned from Spawn Region is of object type Spawner
.call (int)
Get/Set number of objects that should be spawned in each respawn call for Spawn Region
.instanceID (int)
Get/Set the instanceID of the instance in which the Spawn Region exists
.itemCount (int)
Get the current amount of items spawned in Spawn Region (Read-Only)
.maxItems (int)
Get/Set the maximum amount of items to spawn in Spawn Region
.maxTime (int)
Get/Set maximum amount of time to pass before Spawn Region spawns a new object
.maxNpcs (int)
Get/Set the maximum amount of NPCs to spawn in Spawn Region
.minTime (int)
Get/Set minimum amount of time to pass before Spawn Region spawns a new object
.npcCount (int)
Get the current amount of NPCs spawned in Spawn Region (Read-Only)
.prefZ (int)
Get/Set the maximum Z value a dynamic or static item can have on spawning. If dynamic/static item at a given location is higher up than this, a lower spawn point will be selected
.regionNum (int)
Get/Set unique Spawn Region ID/number
.x1 (int)
Get/Set left/western boundary of Spawn Region. Along with .y1 this makes up the top-left/northwest corner of the Spawn Region
.x2 (int)
Get/Set right/eastern boundary of Spawn Region. Along with .y2 this makes up the lower-right/southeast corner of the Spawn Region
.y1 (int)
Get/Set top/northern boundary of Spawn Region
.y2 (int)
Get/Set bottom/southern boundary of Spawn Region
.world (int)
Get/Set world number that spawn region should be spawning objects in
.item (text)
Get/Set Item section ID of item to spawn in Spawn Region
.itemList (text)
Get comma-separated list of Items to spawn in Spawn Region, or set ITEMLIST to spawn items from
.name (text)
Get/Set name of Spawn Region, for internal tracking
.npc (text)
Get comma-separated list of NPCS to spawn in Spawn Region, or set NPCLIST to spawn NPCs from
.npcList (text)
Get/Set guild abbreviation
Object properties are accessed like this:
// Read an object property and store it in a variable
var myVar = myObject.propertyName;
// Modify a (modifiable) object property. Note that some properties are read-only
myObject.propertyName = newValue;
Spells have properties that can be accessed via references to the spells in question via the global Spells object. Examples:
// Fetch reference to Create Food spell
var createFoodSpell = Spells[1]; // 1 = ID of Create Food spell in spells.dfn
var createFoodSpellSFX = createFoodSpell.soundEffect; // Get the sound effect defined for Create Food spell in spells.dfn.aggressiveSpell (bool, true/false)
Get whether the spell is flagged as an aggressive/hostile spell (Read-Only)
.enabled (bool, true/false)
Get whether the spell is enabled (Read-Only)
.fieldSpell (bool, true/false)
Get whether the spell is considered a field spell (Read-Only)
.reflectable (bool, true/false)
Get whether the spell can be reflected by the Magic Reflection spell (Read-Only)
.requireChar (bool, true/false)
Get whether the requires a Character target (Ex: Energy Bolt, Flamestrike) (Read-Only)
.requireItem (bool, true/false)
Get whether the spell requires an Item target (Ex: Magic Lock/Unlock) (Read-Only)
.requireLocation (bool, true/false)
Get whether the spell requires a location target (Read-Only)
.requireTarget (bool, true/false)
Get whether the spell requires a target (Read-Only)
.resistable (bool, true/false)
Get whether the spell can be resisted (Read-Only)
.travelSpell (bool, true/false)
Get whether the spell is considered a travel spell (Read-Only)
.action (hex, 0x0 - 0xff)
Get which Character action/animation should be played when casting the spell (Read-Only)
.soundEffect (hex, 0x0 - 0xffff)
Get which sound FX should be played when casting the spell (Read-Only)
.ash (int)
Get amount of Sulphurous Ash required to cast the spell (Read-Only)
.baseDmg (int)
Get amount of Sulphurous Ash required to cast the spell (Read-Only)
.circle (int)
Get the spell circle that spell belongs to (Read-Only)
.damageDelay (int)
Get the delay (in seconds, using decimals) between targeting someone with the spell and the spell's damage being applied to the target (Read-Only)
.delay (int)
Get the duration (in seconds, using decimals) it takes to finish casting the spell (Read-Only)
.drake (int)
Get amount of Mandrake Root required to cast the spell (Read-Only)
.garlic (int)
Get amount of Garlic required to cast the spell (Read-Only)
.ginseng (int)
Get amount of Ginseng required to cast the spell (Read-Only)
.health (int)
Get amount of hitpoints required to cast the spell (Read-Only)
.highSkill (int)
Get the amount of Magery skill points required to always cast this spell with 100% success (Read-Only)
.id (int)
Get the unique ID of this spell (from spells.dfn) (Read-Only)
.lowSkill (int)
Get the minimum amount of Magery skill points required to have a chance of successfully casting this spell (Read-Only)
.mana (int)
Get the amount of mana required to cast this spell (Read-Only)
.moss (int)
Get amount of Bloodmoss required to cast the spell (Read-Only)
.pearl (int)
Get amount of Black Pearl required to cast the spell (Read-Only)
.recoveryDelay (int)
Get amount of time (in seconds, using decimals) it takes to recover from casting this spell before Character can cast another spell (Read-Only)
.scrollHigh (int)
Get the amount of Magery skill points required to always cast this spell with 100% success when cast from a magic scroll (Read-Only)
.scrollLow (int)
Get the minimum amount of Magery skill points required to have a chance of successfully casting this spell when cast from a magic scroll (Read-Only)
.shade (int)
Get amount of Nightshade required to cast the spell (Read-Only)
.silk (int)
Get amount of Silk required to cast the spell (Read-Only)
.stamina (int)
Get the amount of stamina required to cast this spell (Read-Only)
.mantra (text)
Get the spell mantra/words of power spoken by the Character when casting this spell (Read-Only)
.name (text)
Get the name of the spell, as defined in spells.dfn (Read-Only)
.strToSay (text)
Get the text string accompanying the target cursor (if any) as the spell finishes casting (Read-Only)
Pick up the fundamentals of scripting with UOX3's JS Engine here!
Scripting with UOX3's JS Engine is quite straight-forward, and easy to pick up even for non-programmers. Here's a very basic example of what a fully functional script in UOX3 looks like:
// Script event that triggers when an item is double-clicked
function onUseChecked( pUser, iUsed )
{
// Send an overhead text message to the player who double-clicked the item
pUser.TextMessage( "I double-clicked on an item called " + iUsed.name );
}In the above example, "pUser" represents the player, and "iUsed" represents the item that the player double-clicked. The names of these representations are not important, just that their use is consistent within a script or function. They could have been called "myChar" and "myItem" instead, and it would still have worked!
Such scripts are usually (but not always) attached to objects in the game, and are triggered by UOX3 when special pre-defined events in code run.
The basic building blocks of a script in UOX3 consist of one or more of the following:
JS Events are script functions that are triggered by pre-defined events in UOX3's source code. For example, the onEquipAttempt JS event will be triggered for any character that has a script attached with that JS event present, if they attempt to equip an item on their paperdoll. Similarly, the onResurrect JS event would trigger for characters getting resurrected - if they have a script attached with that JS Event present.
Note that other than being special in the way that UOX3 will trigger them directly when special events take place, JS events can also be triggered manually by calling them from other functions in the same script, or from events/functions in other scripts using the TriggerEvent() function.
For full lists of JS Events, check the JS Events section.
JS Functions are uniquely named script functions that can be called upon to make UOX3 run hard-coded pieces of code and potentially return some data to the script. This could be calculating the height of the map at a given set of coordinates, playing some visual effects at an object's location, broadcasting a message to all connected players, etc.
Here's an example of a function that simulates the rolling of a dice, and stores the result of that die roll in a variable named mDie for use later in the script:
// Roll a DnD style dice of type 2d3+1 (2 dice with 3 faces, add 1 to result)
var mDie = RollDice( 2, 3, 1 );It's also possible to make custom JS functions and call upon those from other functions or scripts. This can be helpful for instance to avoid having to repeat some specific code in a script over and over in multiple locations; just call the custom function which contains the shared code to run!
For full lists of JS Functions, check the JS Functions section.
JS Object Methods are similar to JS Functions in that they can run hard-coded pieces of code and even return data to the calling script, but unlike JS Functions they are associated directly with specific types of objects, and don't exist (or work differently) for other types of objects.
For instance, Character objects have a method that can be used to make NPCs follow a specific target:
myNPC.Follow( myTarget );When this runs, myNPC will attempt to follow myTarget. However, if you tried using that method with an Item object, you'd see an error instead, since the method doesn't exist for the Item object type!
For full lists of JS Object Methods per object type, check the JS Object Methods section.
Any pre-defined JS Objects in UOX3 (like Characters, Items, Multis, Regions, etc) have pre-defined sets of object properties that can be accessed from a script. Some of those properties are read-only, but most can also be modified (permanently or temporarily).
A couple of examples of how to access/modify object properties:
// Store the name of myObject in a variable called objectName
var objectName = myObject.name;
// Modify the name of myObject to become "new object name"
myObject.name = "new object name";
// Check if myObject is a GM, and have them say something if that's true
if( myObject.isGM )
{
myObject.TextMessage( "I'm a GM! Endless power! Muhahaha!" );
}For full lists of pre-defined object properties per object type, check the JS Object Properties section.
Before a script can be triggered by UOX3, it generally needs to be attached to an object in the game - like a character or an item - via a unique scriptID assigned to each and every script in UOX3 via UOX3/js/jse_fileassociations.scp.
Several methods exist to attach scripts to objects:
Example of a script attached to objects via DFN files:
Example of a script attached to objects via object ID:
Example of a script attached to objects via object type:
If you've read the above Introduction, info about script building blocks and how to attach scripts to objects, you should be all set to start creating your own JS script for UOX3! Tools you'll need:
Let's start off by creating a simple script that will roll two dice when an item is double-clicked, and announce the results to all nearby players! So start your text editor of choice, and enter the following lines of text at the top of a fresh new document:
function onUseChecked( pUser, iUsed )
{
pUser.TextMessage( "Hello, world!" );
}This is the declaration of a JS event called onUseChecked(), which can trigger for items when double-clicked by players. pUser will contain a reference to the character that double-clicked the item, while iUsed will refer to the item that was double-clicked. Inside the curly brackets we put a line that causes pUser to say some text ("Hello, world!") with the help of a JS Object Method for Characters called TextMessage().
Before we do anything else with our script, let's save it so UOX3 can read it, and assign it a unique scriptID - so we can assign the script to an object in-game! First, save the document in the UOX3/js/custom/ folder with a name of your choosing, but with a .js file extension (suggestion: myFirstScript.js).
Next, open UOX3/js/jse_fileassociations.scp in your text-editor, and add a new line somewhere inside the curly brackets under the [SCRIPT_LIST] section, saying: 20000=custom/myFirstScript.js (or whatever you named your script). Save the file!
Now, to get UOX3 to load your newly added script, go to the UOX3 console and hit the '*' key to unlock the console, followed by '8' - which will reload all JS scripts (including your new script). This will take a few moments.
To test out the script as it stands so far, login with your admin/GM character and use the command 'addscptrig 20000, before targeting an item in your inventory (or on your character's paperdoll). Now double-click said item and observe some text appearing over the head of your character!
Once this is confirmed to be working, let's extend our script and change it up a little:
function onUseChecked( pUser, iUsed )
{
var diceResult1 = RandomNumber( 1, 6 );
var diceResult2 = RandomNumber( 1, 6 );
return false;
}Above, we removed the dummy TextMessage line, and replaced it with some new lines that generate two random numbers between 1 yo 6, simulating the throw of two regular six-sided dices, and store the results in a couple of variables we call diceResult1 and diceResult2, which we will make use of soon!
At the bottom of the function, we threw in a line saying "return false;", which for the onUseChecked() event tells UOX3 to disregard any hard-coded functionality for double-clicking the item; we're handling it in our script. Next up, let's fetch the name of the character that's doing the virtual dice-rolling:
function onUseChecked( pUser, iUsed )
{
var diceResult1 = RandomNumber( 1, 6 );
var diceResult2 = RandomNumber( 1, 6 );
var pName = pUser.name;
return false;
}Here, we've stored the .name property of pUser - the character who double-clicked on the item iUsed - in a variable we call pName. The name of this variable (and of diceResult1 and diceResult2) are up to us, but it helps to name them something that can help us identify what they're used for, if we come back to the script later!
Now we have the name of the high-roller, and the result of the two dice-rolls, so let's make the script announce the results:
function onUseChecked( pUser, iUsed )
{
var diceResult1 = RandomNumber( 1, 6 );
var diceResult2 = RandomNumber( 1, 6 );
var pName = pUser.name;
pUser.EmoteMessage( diceResult1 );
pUser.EmoteMessage( diceResult2 );
return false;
}With the above additions, the character pUser will emote the results of the two dice rolls in-game! However, all you see is a couple of numbers appearing above the character's head, as two separate messages. Let's improve the message displayed:
function onUseChecked( pUser, iUsed )
{
var diceResult1 = RandomNumber( 1, 6 );
var diceResult2 = RandomNumber( 1, 6 );
var pName = pUser.name;
pUser.EmoteMessage( pName + " rolls the dice and gets a " + diceResult1 + " and " + diceResult2 + "." );
return false;
}Much better! Now both the player doing the clicking and others nearby get some context to the numbers they're seeing. We did this by combining the name, the dice results and some other text into one string of text with the help of some simple addition and some quotes around the extra pieces of text!
And that's it! Your first script is complete!
This section acts as a quick-reference guide for doing specific things with JavaScript in UOX3.
JavaScript Reference - match [mozilla.org]
Search a string for a match against a regular expression. Returns null if no match is found, otherwise returns an array with details about where the match was found. If the regular expression includes /g modifier, match will return an array with all matches found throughout the string, but without additional details. If an /i modifier is included, the search is case insensitive:
Example 1:
if( mySpeech.match( /hello/i ) )Example 2:
var matchResultArray = mySpeech.match( /follow/i/g );
Console.Print( "Matches found: " + matchResultArray.length + "\n" );JavaScript Reference - typeof [mozilla.org]
Using typeof, you can check the type of a variable based on the string returned. It can return types like "boolean", "number", "string" or "undefined" (a variable with no value).
Example 1:
pSock.SysMessage( "The variable myVar is a " + typeof( myVar ) + " variable." );Using the JS Character Method SetTimer, you can pause an NPC in their tracks for a specific amount of seconds. After this they will return to their previous wandering.
myNPC.SetTimer( Timer.MOVETIME, 10000 ); // 10000 = 10 secondsBy manually setting the decay time of an item to 0, you can actually reset the decay time for said item to the default value (as defined in UOX.INI):
myItem.decaytime = 0;To remove an item from the container it's inside, you can set the container property of the item to null, and then move the item to the desired new location (or new container, in which case the step to set it to null can be skipped):
myItem.container = null;
// Next, teleport myItem to new locationTo move an item from the ground into a container, or from one container to another, you can set the .container property of the item to match the new container:
myItem.container = containerItem;To move an item directly into a character's backpack, you can set the .container property of the item to equal the .pack property of the character:
myItem.container = myChar.pack;To equip an item on a character (after first checking for conflicting items on the layer in question), you set the character as the new container for the item, then set the layer to match the layer the item should be equipped on:
myItem.container = myChar;
myItem.layer = [layerID];)If you need to bring an object reference from one function to another, and it's not possible to include the object in the function call, you can temporarily store the object reference in a player's socket's .tempObj (primarily used by code) or .tempObj2 (primarily used by scripts) property:
mySocket.tempObj = myObject;
// or
myChar.socket.tempObj = myObject;Other temporary storage variables available on sockets:
mySocket.tempInt // Temporary variable to store larger numbers (supports negatives).
mySocket.tempInt2 // Temporary variable to store larger numbers (supports negatives).
mySocket.xText // Temporary variable to store strings of text.
mySocket.clickX // Temporary variable to store small numbers (supports negatives).
mySocket.clickY // Temporary variable to store small numbers (supports negatives).
mySocket.clickZ // Temporary variables to store very small numbers (-128 to 128).To find characters or items near another object, you can make use of the AreaCharacterFunction() - for finding characters, AreaItemFunction() - for finding items, or AreaObjFunc() - for finding both characters and items.
function onUseChecked( pUser, iUsed )
{
// Finding items within a radius of 10 tiles from pUser
// Replace with AreaCharacterFunction to find characters.
// Socket can be a player socket or NULL (if script runs for item/npc)
// var numberOfCharsFound = AreaCharacterFunction( "findNearbyChars", pUser, 10, pUser.socket );
var numberOfItemsFound = AreaItemFunction( "findNearbyItems", pUser, 10, pUser.socket );
pUser.TextMessage( "I found "+numberOfItemsFound+" items nearby!" );
return false;
}
// function findNearbyChars( pUser, trgChar, pSock )
function findNearbyItems( pUser, trgItem, pSock )
{
if( trgItem && trgItem.isItem )
return true;
else
return false;
}UOX3 JSE Docs by Geir Ove Alnes @ Copyright 2022
Built upon FAQ Template framwork provided by CodyHouse.