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:

• Command scripts - CommandRegistration()
• Console scripts - ConsoleRegistration()
• Packet scripts - PacketRegistration()
• Skill scripts - SkillRegistration()
• Spell scripts - SpellRegistration()

Scripts from each type need to be assigned scriptIDs in specific sections of jse_fileassociations.scp:

• Command scripts - [COMMAND_SCRIPTS]
• Console scripts - [CONSOLE_SCRIPTS]
• Packet scripts - [PACKET_SCRIPTS]
• Skill scripts - [SKILLUSE_SCRIPTS]
• Spell scripts - [MAGIC_SCRIPTS]
• All other scripts - [SCRIPT_LIST]

Access levels (or command levels) are specified in dfndata/command/commands.dfn, and the default setup goes like this:

• Admin - 5
• GM - 2
• CNS - 1
• Player - 0

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

• return false or nothing to allow hard-coded AI to execute
• return true to prevent hard-coded AI from executing, though does not prevent other scripts with event from running

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

• return false to block vendor trade gump
• return true to allow it

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, iAmount )

Purpose

To allow restricting the purchase of specific items

When Triggered

Runs on item and/or NPC vendor after player verifies purchase, but before purchase has gone through

Return Values

• return false will block the sale from going through, without closing the menu.
• return true will make the purchase go through as normal.

Example of usage

function onBuyFromVendor( pSock, npcVendor, iBought, iAmount )
{
	var pUser = pSock.currentChar;
	pUser.TextMessage( "I am buying " + iAmount + " item(s) ("+iBought.name+") from a vendor!" );
	npcVendor.TextMessage( "I am selling an item!" );
	return true;
}

Prototype

function onBoughtFromVendor( pSock, npcVendor, iBought, iAmount )

Purpose

To allow manipulating the item that has been bought, immediately after it reaches the player's backpack.

When Triggered

Runs on item and/or NPC vendor after purchase has gone through and item has reached player's backpack.

Return Values

• return false or nothing to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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, iAmount )
{
	var pUser = pSock.currentChar;
	pUser.TextMessage( "I bought " + iAmount + " item(s) ("+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 onCarveCorpse( pChar, iCorpse )

Purpose

To allow custom behaviour when players carves corpses

When Triggered

Triggered for corpse object when player tries to carve it

Return Values

• return false or nothing to prevent hardcoded carving of corpse, and prevent other scripts with same event from running
• return true to proceed with hardcoded carving of corpse and/or allow other scripts with same event to run

Example of usage

function onCarveCorpse( pChar, iCorpse )
{
	pChar.TextMessage( "I'll just carve this corpse..." );
	iCorpse.TextMessage( "But I'm not dead yet!" );
	return false;
}

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

• return false or nothing to prevent opening of paperdoll, and prevent other scripts with same event from running
• return true to allow opening of paperdoll. Other scripts with same event can also run

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

• return false or nothing to allow default hard-coded behaviour for clicking on objects
• return true to override default hard-coded behaviour for clicking on an object (such as showing name of object clicked)

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

• return false or nothing to continue checking any additional scripts with same event, while preventing hard-coded collision handling from running
• return true to allow default hard-coded handling of collision (prevents other scripts with event from running)

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

• return false to deem the current target invalid for selection and look for another
• return true to deem the current target valid for selection, and stop looking for other targets

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 example

Prototype

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

• return false to override existing hard-coded combat completely and/or disallow combat from being started
• return true to let hard-coded combat run its course

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

• return false to override what happens after combat ends. Usually this is handled by hard code, which takes care of setting targets and attacker properties to null, invalidates first attacker status, toggles combat mode, etc.
• return true to allow hard-coded implementation to run

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

• return a negative value to use hard-coded combat damage calculations
• return a positive value to override hard-coded combat damage calculations and to use this value as the damage value

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

• return false to provide default system message about unrecognized command - unless command is handled in another script with same event
• return true to indicate that the command has been handled by script, and prevent UOX3 from displaying system message about unrecognized command

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

Prototype

function onCreateDFN( objMade, objType )

Purpose

Used for tinkering with newly created items/NPCs

When Triggered

• When an non-player character object is created, event will trigger in script for the created object

Usable in Global script (scriptID 0)? For NPCs/Items, No.

Notes

• objType == 0 indicates an item
• objType == 1 indicates a character

Example of usage

// When this script is setup as "global id" (0) in JSE_FILEASSOCIATIONS.SCP,
// it will send a textmessage for all new NPC characters that enters the world.
function onCreateDFN( objMade, objType )
{
	if( objType == 1 )
	{
		objMade.TextMessage( "I have SPAWNED! Tremble before me, world!" );
	}
}

Prototype

function onCreatePlayer( pChar )

Purpose

Used for customization of players at creation

When Triggered

• For player characters, this is triggered in global script when they first enter the world

Usable in Global script (scriptID 0)? For Players, Yes

Example of usage

// When this script is setup as "global id" (0) in JSE_FILEASSOCIATIONS.SCP,
// it will send the sysmessage to all new PLAYER characters that enters the world.
function onCreatePlayer( pChar )
{
	pChar.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

• objType == 0 indicates an item
• objType == 1 indicates a character (unused for onCreateTile)

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

• return false to override and prevent damage from taking place
• return true to allow damage to go through and continue with hard-coded application of damage

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 onDamageDeal( attacker, damaged, damageValue, damageType )

Purpose

Custom reactions to damage, or to prevent damage from taking place

When Triggered

When the char "attacker" deals damage

Usable in Global script? No

Return Values

• return false to override and prevent damage from taking place
• return true to allow damage to go through and continue with hard-coded application of damage

Notes

Unlike the onDamage event, neither attacker nor damaged can be NULL in this one. 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 onDamageDeal( attacker, damaged, 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;
		}
		attacker.TextMessage( "Look at me, I'm dealing " + damageValue + " points of " + dmgTypeString + " damage to a target! *manic laughter*" );
		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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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

• return false to prevent deathblow from killing character
• return true to allow deathblow to kill character

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

• return false to prevent code from decaying/deleting item
• return true to allow default hard-coded decay process

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

• objType == 0 indicates an item
• objType == 1 indicates a character

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

• return false to allow default hard-coded dispel process
• return true to prevent object from being dispelled by code. Also prevents other scripts with same event from running.

Notes

• objType == 0 indicates a character
• objType == 1 indicates an item

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

• return false/0 (or nothing) to reject drop and bounce item back to where it came from
• return true/1 to allow drop and proceed with default hard code behaviour
• return 2 to handle drop entirely in script; don't bounce, don't run hard code

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

• return false/0 (or nothing) to reject drop and bounce item back to where it came from
• return true/1 to allow drop and proceed with default hard code behaviour
• return 2 to handle drop entirely in script; don't bounce, don't run hard code

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

• return false/0 (or nothing) to reject drop and bounce item back to where it came from
• return true/1 to allow drop and proceed with default hard code behaviour
• return 2 to handle drop entirely in script; don't bounce, don't run hard code

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 onDyeTarget( pUser, dyeTub, targItem )

Purpose

Allowing custom behaviour when targeting items to dye with a dye tub

When Triggered

When pUser attempts to use dyeTub to dye targItem, the event is triggered from dyeTub's script

Return Values

• return false/0 (or nothing) to override hard coded dye behaviour
• return true/1 to allow hard coded dye behaviour to proceed as normal

Example of usage

function onDyeTarget( pUser, dyeTub, targItem )
{
	if( targItem.type == 11 )
	{
		pUser.TextMessage( "I can't dye doors!" );
		return false;
	}
	return true;
}

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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

Notes

• objType == 0 indicates objEntering is a character
• objType == 1 indicates objEntering is an item

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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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

• return false/0 (or nothing) to reject attempt to equip iEquipped
• return true to allow equip code to continue running like normal (with additional equip checks done there).

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 onFacetChange( mChar, oldFacet, newFacet )

Purpose

Allows custom behaviour to be added for characters that moves from one facet to another, or to deny this change altogether

When Triggered

When character with event attached in a script moves from one facet to another

Return Values

• return false/0 (or nothing) to disallow facet change
• return true to allow facet change

Notes

This event only runs for characters, and using the event in the global script is not supported.

Example of usage

function onFacetChange( mChar, oldFacet, newFacet )
{
	// Add a specific script to all characters that switch to the Trammel facet,
	// but remove said script if character moves to any other facet
	switch( newFacet )
	{
		case 1: // Trammel
			mChar.AddScriptTrigger( X ); // X is a scriptID
			break;
		default:
			mChar.RemoveScriptTrigger( X ); // X is a scriptID
			break;

	}

	// Return true allows the facet change to happen like normal
	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

• return false/0 (or nothing) to allow other scripts with event to run
• return true to prevent other scripts with event from running

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

• return false/0 (or nothing) to prevent hard-coded response and/or other scripts with event from running
• return true to allow hard-coded button response to run like normale

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

• return false/0 (or nothing) to allow hard-coded response and/or other scripts with event from running
• return true to prevent hard-coded response and/or other scripts with event from running

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

• return false to override hard-code and handle hunger in script
• return true to proceed with hard-code, and/or let other scripts with event handle hunger change

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

• return false to continue iterating over objects without including the current object in the count of objects iterated over
• return true to continue iterating over objects while including the current object in the count of objects iterated over

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

• return false or nothing to allow other scripts with event to also run
• return true to prevent other scripts with event from running

Notes

• objType == 0 indicates objLeaving is a character
• objType == 1 indicates objLeaving is an item

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

• return false or nothing to allow other scripts with event to also run
• return true to prevent other scripts with same event from running

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

Prototype

function onMultiLogout( iMulti, cPlayer )

Purpose

To validate/allow custom behaviour for players attempting to safely log out while inside a multi

When Triggered

When cPlayer logs out while inside iMulti, event triggers in iMulti's script

Return Values

• return false or nothing to disallow player's attempt to safely log out from inside multi
• return true to allow player's attempt to safely log out from inside multi. Prevents same event from running in other scripts

Notes

When a safe logout attempt (by just logging out normally while inside multi) is allowed, script informs code that a safe/instant logout can be attempted. Code then performs other hard-coded checks before allowing this (checking for criminal status, aggressor status, etc). When safe logout attempt is disallowed, server rejects the instant log out, and character remains behind in the world for the normal logout timer, and additionally gets booted out of the multi they're in.

Example of usage

function onMultiLogout( iMulti, cPlayer )
{
	if( ValidateObject( iMulti.owner ) && iMulti.owner == cPlayer )
	{
		// Owner of house! Allow safe logout
		return true;
	}
	return false;
}

Prototype

function onNameRequest( myObj, requestedBy, requestSource )

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

• return empty string/false/true to use default name of object
• return [string] to use custom name for object

Notes

• requestedBy is a reference to the character (if any) that requested the name, for instance via dragging myObj's health-bar, using all-names macro, opening of paperdoll or just from general client requests for info about myObj
• If an attempt to retrieve myObj's name is done from within the onNameRequest event, it will return the real name of the object (to avoid infinite loop situations)
• requestSource is a value that indicates where the name request originated, to allow scripts to tailor the response accordingly

  0 - Speech/System Messages
  1 - Guild Menus
  2 - Stat Window (self)
  3 - Stat Window (other)
  4 - Tooltip
  5 - Paperdoll Journal
  6 - Paperdoll
  7 - Single Click / All-Names
  8 - System
  9 - Secure Trade Window

Example of usage

function onNameRequest( myObj, requestedBy, requestSource )
{
	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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with same event from running

Notes

pathfindResult parameter contains...

• -1 if pathfinding failed
• 0 if pathfinding partially succeeded but final location was blocked by a character
• 1 if pathfinding succeeded and NPC reached target location

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, containerObj )

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, then in pGrabber's script - then finally in containerObj's script (if not null)

Return Values

• return false to prevent the pickup from happening, and bounce item back
• return true to allow the pickup

Example of usage

function onPickup( iPickedUp, pGrabber, containerObj )
{
	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
			var contName = ValidateObject( containerObj ) ? containerObj.name : "unknown";
			pGrabber.TextMessage( "I picked up this item from a container (" + contName + ")." );
			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

• return false to allow other scripts with same event to run
• return true to prevent other scripts with same event from running

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

• return false to prevent resurrection
• return true to allow resurrection

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

• return -2 to use normal spellcasting
• return -1 to cancel normal spellcasting, and handle everything in script
• return a value between 0 to 32767 to use normal spellcasting, but with a delay matching the value provided in ms

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

• return false to prevent hard code from executing and trade gump from opening
• return true to let trade gump open like normal, via hard code

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, iAmount )

Purpose

To allow greater control over the selling of specific items to vendors

When Triggered

Event triggers for iSold's (and/or Vendor's) script after player verifies sale, but before sale has actually gone through

Return Values

• return false will prevent sale from going through, without closing the menu
• return true will make the sale go through as normal

Example of usage

function onSellToVendor( pSock, Vendor, iSold, iAmount )
{
	var pUser = pSock.currentChar;
	pUser.TextMessage( "I am selling " + iAmount + " item(s) (" + iSold.name + ") to a vendor!" );
	Vendor.TextMessage( "I am buying an item!" );
	return true;
}

Prototype

function onSoldToVendor( pSock, Vendor, iSold, iAmount )

Purpose

To allow greater control over what happens after specific items have been sold to NPCs

When Triggered

Event triggers for iSold's (and/or Vendor's) script after the item has already been sold and has reached the NPC vendor's "bought items"-backpack

Return Values

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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, iAmount )
{
	var pUser = pSock.currentChar;
	pUser.TextMessage( "I sold " + iAmount + " item(s) (" + 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

• objType == 0 indicates objUsing is a character
• objType == 1 indicates objUsing is an item

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

• return false to allow hard-coded skillcheck to run
• return true to prevent hard-coded skillcheck and other scripts with event from running. Skillcheck is then optionally handled in script

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

• return false to prevent skill gain from taking place, and prevent event in other scripts from executing
• return true to allow skill gain from taking place, and allow events in other scripts and/or hard code to execute

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

• return false to prevent skill loss from taking place, and prevent event in other scripts from executing
• return true to allow skill loss from taking place, and allow events in other scripts and/or hard code to execute

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

• return false to prevent default skill gump from opening
• return true to proceed with opening default skill gump

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 pSnooping snoops into pSnooped's pack

Return Values

• return false (or nothing) to allow same event in other scripts to trigger (if snooping succeeded), or to let hard code handle result of failed snooping (if snooping failed)
• return true to prevent same event in other scripts from triggering (if snooping succeeded), or to prevent hard code from handling result (if snooping failed)

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, iCont, pSnooping )

Purpose

To allow for custom behaviour when players attempt to snoop into other characters' iCont

When Triggered

When pSnooping attempts to snoop into pSnooped's iCont container

Return Values

• return false (or nothing) to prevent hard-code and other snooping-related events from running
• return true to allow hard-code and other snooping-events to run

Example of usage

function onSnoopAttempt( pSnooped, iCont, 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

• return -1 No such function or bad call (usually by code)
• return 0 Let other NPCs and PCs see strSaid (default)
• return 1 Let other PCs see strSaid (but not NPCs)
• return 2 Let no one else see strSaid

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

• return false (or nothing) to allow other scripts with event to run
• return true to prevent other scripts with event from running

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):

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

• return -2 to use normal spellcasting
• return -1 to cancel normal spellcasting, and handle everything in script
• return a value between 0 to 32767 to use normal spellcasting, but with a delay matching the value provided in ms

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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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, 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. Check target type using myTarget.isChar or .isItem

Return Values

• return false/0 (or nothing) to allow other scripts with event to also run.
• return true/1 to prevent other scripts with event from running
• return 2 to reject spell being cast on target

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, 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 onSpellTargetSelect( pCaster, myTarget, spellID )

Purpose

To allow custom behaviour when caster with event attached targets an object with spells

When Triggered

When targeting something/someone with a spell, event triggers in caster's script

Notes

myTarget can be both items and characters. Check target type using myTarget.isChar or .isItem

Return Values

• return false/0 (or nothing) to allow other scripts with event to also run.
• return true/1 to prevent other scripts with event from running
• return 2 to reject spell being cast on target

Example of usage

// Script attached to an NPC that's immune to magic, where event returns 2 to reject spell being cast
function onSpellTargetSelect( pCaster, myTarget, 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

• return false (or nothing) to prevent stat gain from taking place, and prevent event in other scripts and/or hard code from executing
• return true allow stat gain to take place, and allow events in other scripts and/or hard code to execute

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

• return false (or nothing) to prevent stat loss from taking place, and prevent event in other scripts and/or hard code from executing
• return true allow stat loss to take place, and allow events in other scripts and/or hard code to execute

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

• return false/0 (or nothing) to allow code to run like normal
• return true/1 to prevent hard code from running, as well as the onStolenFrom event (theft failed?)
• return 2 to prevent hard code from executing, but allow onStolenFrom event to run like normal (theft succeeded, but handled in script?)

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

• return false (or nothing) to allow other scripts with event and/or hard code to run like normal
• return true to prevent other scripts with event and/or hard code from running

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

• return false (or nothing) to prevent swing and subsequent combat (damage, etc) code from happening
• return true to allow swing and let subsequent combat events and/or hard code execute

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

• return false (or nothing) to prevent hard code from running and speech from being displayed
• return true to allow hard code to run and display speech

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 onThirstChange( pChanging, newStatus )

Purpose

To allow customization of behaviour when a character's thirst level changes. Could be used for changing AI of monsters, display custom messages to player, etc.

When Triggered

When a player's thirst level changes, event triggers in pChanging's script

Return Values

• return false to override hard-code and handle thirst in script
• return true to proceed with hard-code, and/or let other scripts with event handle thirst change

Notes

If overridden, the normal thirst messages are not displayed.

Example of usage

function onThirstChange( pChanging, newStatus )
{
	pChanging.TextMessage( "ooooo, I feel more thirsty" );
	if( newStatus == 0 )
	{
		TextMessage( pChanging, "I'm melting, I'm melting!" );
	}
	return true;
}

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, pSocket )

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, pSocket )
{
	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

• return false (or nothing) to allow other scripts with event to also run
• return true to prevent other scripts with event from running

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

• return false (or nothing) to reject the attempt to unequip the item
• return true to allow unequip code to run like normal (with additional checks being done there)

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

• return false (or nothing) to allow other scripts with event to run
• return true to prevent other scripts with event from running

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

• return false (or nothing) to prevent hard code and/or other scripts with event from running
• return true to allow hard code and/or other scripts with event to run

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

• return false (or nothing) to prevent hard code and/or other scripts with event from running
• return true to allow hard code and/or other scripts with event to run

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

• return false (or nothing) to allow other scripts with same event to run
• return true to prevent other scripts with same event from running

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

• return false (or nothing) to prevent the toggling of war mode
• return true to allow the toggling of war mode to continue

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 );
}