# UOX3 Script Engine

### API and Event handling

inRange
Prototype |
    function inRange( pCharacter, objInRange, objType )
When triggered | objInRange comes into visible range of pCharacter. pCharacter's script is activated
Notes | objType == 0 indicates objInRange is a character objType == 1 indicates objInRange is an item
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.
Example of Usage |
    function inRange( pCharacter, objInRange, objType )
    {
    	if( objType == 1 )	// An item came into range
    	{
    		pCharacter.DoStaticEffect( 0x376A, 9, 0, );	// Make some sparkles!
    		if( objInRange.id == 0x1416 )	// Ooh, it's a purty piece of armour
    		{
    			pCharacter.EmoteMessage( "*ooooooooooooo*" );
    		}
    	}
    }

onAISliver
Prototype |
    function onAISliver( npcChar )
When triggered | Every AI loop, during their AI slice
Notes |
Purpose | Great customization of AI on a per NPC basis.
Example of Usage |
    function onAISliver( tChar )
    {

    tChar.DoAction( 111 );
    }
    //The NPC tChar performs action 111 (dance-animation in 3D UO clients)
    //on every NPC ai check, essentially looping the animation =)

onAttack
Prototype |
    function onAttack( pAttacker, pDefender )
When triggered | When pAttacker attacks pDefender (in each "round" of combat)
Notes | pAttacker's script is activated, and pDefender's onDefense event is fired!
Purpose | Flesh out the attacking code.
Example of Usage |
    function onAttack( pAttacker, pDefender )
    {
    	pAttacker.TextMessage( "Who lives in that castle?" );
    	pDefender.TextMessage( "Help! Help! I'm being repressed!" );
    }

onBuy
Prototype |
    function onBuy( pSock, Vendor )
When triggered | Runs on NPC vendor before tradegump opens
Notes | Can be used to completely block access to a vendor based on criterias of one's choosing.
Purpose | To allow more control over who can access NPC vendors.
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;
    	}
    	else
    		return true;
    }

onBuyFromVendor
Prototype |
    function onBuyFromVendor( pSock, Vendor, iBought )
When triggered | Runs on item after player verifies purchase, but before purchase has gone through
Notes | Return false will block the sale from going through, without closing the menu. Return true will make the purchase go through as normal.
Purpose | To allow restricting the purchase of specific items
Example of Usage |
    function onBuyFromVendor( pSock, Vendor, iBought )
    {
    	var pUser = pSock.currentChar;
    	pUser.TextMessage( "I am buying an item ("+iBought.name+") from a vendor!" );
    	Vendor.TextMessage( "I am selling an item!" );
    	return true;
    }

onBoughtFromVendor
Prototype |
    function onBoughtFromVendor( pSock, Vendor, iBought )
When triggered | Runs on item after purchase has gone through and item has reached player's backpack.
Notes | Used, amongst other things, for automatically turning pet-statues bought from animal-trainers into actual pets
Purpose | To allow manipulating the item that has been bought, immediately after it reaches the player's backpack.
Example of Usage |
    function onBoughtFromVendor( pSock, Vendor, iBought )
    {
    	var pUser = pSock.currentChar;
    	pUser.TextMessage( "I bought an item ("+iBought.name+") from a vendor!" );
    	Vendor.TextMessage( "I just sold an item to some random dude!" );
    	return true;
    }

onCallback
Prototype |
    function onCallback#( socket, target )
When triggered | Triggered for player who selects a target initiated from a CustomTarget method
Notes | # behind onCallback function-name is linked to the # used in the CustomTarget method that initiated the targeting cursor.
Purpose | To handle callbacks from targeting cursors
Example of Usage |
    function CommandRegistration()
    {
    	RegisterCommand( "disconnect", 2, true );
    }
    function command_DISCONNECT( socket, cmdString )
    {
    	var targMsg = GetDictionaryEntry( 196, socket.Language );
    	socket.CustomTarget( 0, targMsg );
    }
    function onCallback0( socket, ourObj )
    {
    	if( !socket.GetWord( 1 ) && ourObj.isChar && ourObj.online )
    	{
    		var targSock = ourObj.socket;
    		if( targSock && targSock != socket )
    		{
    			socket.SysMessage( GetDictionaryEntry( 1029, socket.Language ) );
    			targSock.SysMessage( GetDictionaryEntry( 1030, targSock.Language ) );
    			targSock.Disconnect();
    		}
    	}
    }

onCharDoubleClick
Prototype |
    function onCharDoubleClick( pUser, targChar )
When triggered | When pUser double-clicks targChar. Replaces any code behaviour that may exist
Notes | targChar's script is activated
Purpose | To allow greater customization of doubleclicking on characters.
Example of Usage |
    function onCharDoubleClick( pUser, targChar )
    {
    	targChar.TextMessage( "If you think you'll be allowed to see my paperdoll, think again!" );
    	return false;
    }

onClick
Prototype |
    function onClick( pUser, iUsed )
When triggered | When pUser single-clicks iUsed. Replaces any code behaviour that may exist
Notes | iUsed's script is activated
Purpose | To allow greater customization on clicking on items.
Example of Usage |
    function onClick( pUser, iUsed )
    {
    	pUser.SysMessage("You have clicked on: "+iUsed.name );
    }

onCollide
Prototype |
    function onCollide( targSock, pColliding, objCollidedWith )
When triggered | When pColliding collides with objCollidedWith (stepped on basically)
Notes | objCollidedWith is only an item currently. targSock is -1 if pColliding is an NPC
Purpose | Replace of collision based triggers, increase teleporter abilities
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!*" );
    	//srcChar.DoStaticEffect( 0x376A, 9, 0, 0 );
    }

onCombatStart
Prototype |
    function onCombatStart( pAttacker, pDefender )
When triggered | When pAttacker attacks someone, pAttacker's script is triggered.
Notes | Return false to override existing hardcoded combat completely, return true to let hardcoded combat run it's course
Purpose | To allow overriding combat functionality
Example of Usage |
    function onCombatStart( pAttacker, pDefender )
    {
    	pAttacker.TextMessage( "I'm attacking!" );
    	pDefender.TextMessage( "I'm being attacked!" );
    	return true;
    }

onCombatEnd
Prototype |
    function onCombatEnd( currChar, targChar )
When triggered | When either currChar or targChar dies or goes out of range, the script is fired
Notes | return false to override what happens after combat ends, return true to allow hardcoded implementation to run
Purpose | Allow to override what happens when combat between two characters ends
Example of Usage |
    function onCombatEnd( pDefender, pAttacker )
    {
    	if( currChar.health != 0 )
    		currChar.TextMessage( "Whee! I survived combat!" );
    	if( targChar.health != 0 )
    		targChar.TextMessage( "Yay! I survived combat!" );
    	return true;
    }

onCombatDamageCalc
Prototype |
    function onCombatDamageCalc( attacker, defender, getFightSkill )
When triggered | Everytime combat damage calculation occurs this event is fired
Notes | Return a damage value to override the combat calculation of the engine, or a negative value to use the engine
Purpose | Allow to override the combat damage calculation
Example of Usage |
    function onCombatDamageCalc( pAttacker, pDefender, fightSkill )
    {
    	var baseDamage = pAttacker.attack;
    	var hitLoc = CalculateHitLoc();

    	if( baseDamage == -1 )  // No damage if weapon breaks
    		return 0;

    	var damage = ApplyDamageBonuses( 1, pAttacker, pDefender, fightSkill, hitLoc, baseDamage );

    	if( damage < 1 )
    		return 0;

    	damage = ApplyDefenseModifiers( 1, pAttacker, pDefender, fightSkill, hitLoc, damage, true);

    	if( damage <= 0 )
    		damage = RandomNumber( 0, 4 );

    	if( !pDefender.npc )
    		damage /= 2;

    	return damage;
    }

onCreateDFN
Prototype |
    function onCreateDFN( objMade, objType )
When triggered | When an item or char is created. Note that for PCs, this is triggered when they first enter the world.
Notes | objType == 0 indicates an item objType == 1 indicates a character
Purpose | Used for customization of players at creation, or tinkering items/chars when they're made.
Example of Usage |
    function onCreate( objMade, objType )
    {
    	if( objType == 1 )
    		objMade.SysMessage( "Welcome to Our Unique World(TM)!" );
    }
    // 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.

onCreateTile
Prototype |
    function onCreateTile( objMade, objType )
When triggered | When a non-DFN based item is created.
Notes | objType == 0 indicates an item objType == 1 indicates a character
Purpose | Used for customization of non-DFN based items at creation.
Example of Usage |
    function onCreate( objMade, objType )
    {
    	objMade.name = "A renamed item";
    }
    // Only scripts using script-id 0 or ones assigned through harditems.dfn will work with this event.

onDamage
Prototype |
    function onDamage( damaged, attacker, damageValue );
When triggered | When the char "damaged" gets damaged
Notes | The attacker can be a char or NULL
Purpose | Custom reactions to damage.
Example of Usage |
    function onDamage( damaged, attacker, damageValue )
    {
    	damaged.TextMessage( "Ouch, those "+damageValue+" points of damage hurt." );
    }

onDeath
Prototype |
    function onDeath( pDead );
When triggered | When the player or NPC pDead dies
Notes |
Purpose | Custom death sequence. Can do things like an explosion anim and what not here, for impact's sake.
Example of Usage |
    function onDeath( pDead )
    {
    	pDead.Teleport( 1000, 1000, 0 );
    }

onDeathBlow
Prototype |
    function onDeathBlow( pKilled, pKiller );
When triggered | When a killing blow has been made
Notes
Purpose | Custom reactions after a killing blow has been made
Example of Usage |
    function onDeathBlow( pDead, pKiller )
    {
    	pDead.health = pDead.health + 10;
    	pDead.TextMessage( "But I'm not dead!" );
    	return true;
    }

onDecay
Prototype |
    function onDecay( iDecaying )
When triggered | When iDecaying decays
Notes | CURRENTLY BROKEN!!!
Purpose |
Example of Usage |
    function onDecay( iDecaying )
    {
    	iDecaying.StaticEffect( 0x376A, 9, 6 );
    }

onDefense
Prototype |
    function onDefense( pAttacker, pDefender )
When triggered | When pAttacker attacks pDefender (in each "round" of combat)
Notes | pDefender's script fires, pAttacker's onAttack event is also fired
Purpose | Flesh out the attacking code.
Example of Usage |
    function onDefense( pAttacker, pDefender )
    {
    	pAttacker.TextMessage( "Who lives in that castle?" );
    	pDefender.TextMessage( "Help! Help! I'm being repressed!" );
    }

onDelete
Prototype |
    function onDelete( objDestroyed, objType )
When triggered | When an item or character is deleted
Notes | objType == 0 indicates an item objType == 1 indicates a character
Purpose |
Example of Usage |
    function onDelete( objDestroyed, objType )
    {
    	if( objType == 0 )
    		ConsoleMessage( objDestroyed.name+" has been deleted from the world." );
    }

onDispel
Prototype |
    function onDispel( objDispelled, objType )
When triggered | When objDispelled is dispelled. objDispelled's script is activated.
Notes | objType == 0 indicates a character objType == 1 indicates an item
Purpose |
Example of Usage |
    function onDispel( objDispelled, objType )
    {
    	ConsoleMessage( objDispelled.name+" has been dispelled." );
    }

onDrop
Prototype |
    function onDrop( iDropped, pDropper )
When triggered | When pDropper drops iDropped.
Notes | iDropped's script is activated.
Purpose | Allowing control over dropping items from cursor
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;
    	}
    	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;
    	}
    }

onDropItemOnItem
Prototype |
    function onDropItemOnItem( iDropped, cDropper, iDroppedOn )
When triggered | When iDropped is dropped by cDropper on iDroppedOn
Notes | First iDropped's script is activated, and if it doesn't bounce, then same script is activated for iDroppedOn Return Value Table: 0 == bounce 1 == don't bounce, use code 2 == don't bounce, don't use code
Purpose |
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 );
    		}
    	}
    	else
    	{
    		cDropper.TextMessage( "Generic error message!" );
    		return 0;
    	}
    }

onDropItemOnNpc
Prototype |
    function onDropItemOnNpc( pDropper, pDroppedOn, iDropped )
When triggered | When iDropped is dropped on pDroppedOn
Notes | First iDropped's script is activated, and if it doesn't bounce, then same script is activated for pDroppedOn Return Value Table: 0 == bounce 1 == don't bounce, use code 2 == don't bounce, don't use code
Purpose |
Example of Usage |
    function onDropItemOnNpc( pDropper, pDroppedOn, iDropped )
    {
    	pDropper.TextMessage("Here, I offer you my this object as a gift of friendship.");
    	pDroppedOn.TextMessage("Fudge off!");
    	iDropped.colour =13;
    	return 0;
    }

onEnterRegion
Prototype |
    function onEnterRegion( pEntering, regionEntered )
When triggered | When pEntering enters regionEntered
Notes | Region-scripts can be attached to regions through regions.dfn, using the script=# tag
Purpose | To allow custom reactions when players enter regions
Example of Usage |
    function onEnterRegion( pEntering, regionEntered )
    {
    	if( pEntering.raceID != 11 )
    	{
    		//sound the alarm! non-undead intruder to region
    		//spawn undead guards
    	}
    }

onEntrance
Prototype |
    function onEntrance( iEntered, objEntering, objType )
When triggered | When objEntering enters the multi object iEntered
Notes | objType == 0 indicates objEntering is a character objType == 1 indicates objEntering is an item iEntered's script is activated
Purpose |
Example of Usage |
    function onEntrance( iEntered, objEntering, objType )
    {
    	if( objType == 0 )
    		objEntering.SysMessage("You have entered "+iEntered.name);
    }

onEquip
Prototype |
    function onEquip( pEquipper, iEquipped )
When triggered | When pEquipper equips iEquipped
Notes | iEquipped's script is activated
Purpose |
Example of Usage |
    function onEquip( pEquipper, iEquipped )
    {
    	pEquipper.StaticEffect( 0x376A, 9, 6 );
    }

onFall
Prototype |
    function onFall( pFall, fallDistance )
When triggered | When pFall falls fallDistance
Notes | pFall can be either an npc or pc, will only trigger if fallDistance is over 20, so it does not trigger whenever a character walks down steps/off small ledges/down hills, etc.
Purpose |
Example of Usage |
    function onFall( pFall, fallDistance )
    {
    	if( fallDistance > 20 )
    		pFall.SysMessage("Yikes! That was a long fall!");
    }

onFlagChange
Prototype |
    function onFlagChange( pChanging, newStatus, oldStatus );
When triggered | When a player's status changes. IE innocent -> criminal, criminal->murderer, and so on.
Notes | May not fire instantly when the action is made. However, won't be long after change occurs will it be visible.
Purpose |
Example of Usage |

onGumpInput
Prototype |
When triggered |
Notes |
Purpose |
Example of Usage |

onGumpPress
Prototype |
    function onGumpPress( pSock, pButton, gumpData )
When triggered | When a player presses a button in a Gump.
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).
Purpose |
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;
    	}
    }

onHungerChange
Prototype |
    function onHungerChange( pChanging, newStatus );
When triggered | When a player's hunger level changes goes down.
Notes | If overridden, the normal hunger messages are not displayed.
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.
Example of Usage |
    function onHungerChange( pChanging, newStatus )

    {

    	TextMessage( pChanging, "ooooo, I feel more hungry" );

    	if( newStatus == 0 )

    	{

    		TextMessage( pChanging, "I'm melting, I'm melting!" );

    	}

    }

onIterate
Prototype |
    function onIterate( object )
When triggered | On every object our iterator comes across.
Notes | if return value from script is true, it continues on running the loop if return value is false, then the loop is halted
Purpose | To allow JS to loop through all world objects.
Example of Usage |
    function doStuff( socket, pUser )
    {
    	socket.SysMessage( "Killing all NPCs" );
    	var numKilled = IterateOver( "CHARACTER" );
    	socket.SysMessage( "Killed " + NumToString( numKilled ) + " NPCs " );
    }

    function onIterate( charCheck )
    {
    	if( !charCheck )
    		return false;
    	if( charCheck.npc )
    		charCheck.Kill();
    	return true;
    }

onLeaveRegion
Prototype |
    function onLeaveRegion( pLeaver, regionLeft )
When triggered | When pLeaver leaves regionLeft
Notes | Region-scripts can be attached to regions through the script=# tag in regions.dfn
Purpose | To allow reactions when characters leave regions
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!
    }

onLeaving
Prototype |
    function onLeaving( iLeft, objLeaving, objType )
When triggered | when objLeaving leaves the multi object iLeft
Notes | objType == 0 indicates objLeaving is a character objType == 1 indicates objLeaving is an item iLeft's script is activated
Purpose |
Example of Usage |
    function onLeaving( iLeft, objLeaving, objType )
    {
    	if( objType == 0 )
    		objLeaving.SysMessage("You have left "+iLeft.name);
    }

onLightChange
Prototype |
    function onLightChange( object, lightlevel )
When triggered | Triggers for object (char or item) when lightlevel changes
Notes |
Purpose |
Example of Usage |
    function onLightChange( object, lightlevel )
    {
    	(pseudo-code)
    	if( object && object is item )
    	{
    		if( object.id equals unlit lamppost )
    		{
    			if( lightlevel > 10 ) //high light levels = dark, low light levels = bright
    			{
    				object.id = lit lamppost
    			}
    		}
    		else if( object.id equals lit lamppost )
    		{
    			if( lightlevel < 10 )
    			{
    				object.id = unlit lamppost
    			}
    		}
    	}
    }

onLogin
Prototype |
    function onLogin( sockPlayer, pChar )
When triggered | When pChar is logged in to the world
Notes | sockPlayer is never -1
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 in. Diabloesque hall logins).
Example of Usage |
    function onLogin( sockPlayer, pChar )

    {

    	pChar.Teleport( 1000, 1000, 0, 0 );

    }

onLogout
Prototype |
    function onLogout( sockPlayer, pChar )
When triggered | When pChar is logging out of the world
Notes | sockPlayer is never -1
Purpose | To allow customization of what happens when a player logs out. Could pop up custom gumps, or do certain things to the character.
Example of Usage |
    function onLogin( sockPlayer, pChar )

    {

    	sockPlayer.SysMessage ( "Farewell! Come back soon." );

    }

onPacketReceive
Prototype |
    function onPacketReceive( socket, packetNum )
When triggered | When receiving a network packet
Notes | OVERLOADPACKETS needs to be enabled in UOX.INI and each specific packet must be registered in jse_fileassociations.scp
Purpose | Similar as "packet-hooks" in other emulators - allows overriding network packet-handling without modifying the server source-code
Example of Usage |
    function onPacketReceive( socket, packetNum )
    {
    	//???
    }

onPickup
Prototype |
    function onPickup( iPickedUp, pGrabber )
When triggered | When pGrabber picks up iPickedUp
Notes | iPickedUp's script is activated.
Purpose |
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;
    }

onResurrect
Prototype |
    function onRessurect( pAlive );
When triggered | When a player pAlive is being resurrected
Notes | Only applies to PCs
Purpose | Control over what happens when a person comes to life once more
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!" );
    		return false;
    	}
    }

onScrollCast
Prototype |
    function onScrollCast( pUser, spellID )
When triggered | When a spell is cast using a magic scroll
Notes | Return value table: -2: use NORMAL non-JS casting -1: CANCEL normal spellcasting 0->inf: Spell delay in ms
Purpose | To allow overriding spellcasting from magic scrolls
Example of Usage |
    function onScrollCast( pUser, spellID )
    {
    	if( spellID == 18 )
    	{
    		pUser.TextMessage( "I'm casting a fireball from a fireball-scroll!" );
    		return -1;
    	}
    }

onSell
Prototype |
    function onSell( pSock, Vendor )
When triggered | Runs on vendor before tradegump opens.
Notes |
Purpose | To allow greater control over who can sell stuff to specific vendors.
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;
    }

onSellToVendor
Prototype |
    function onSellToVendor( pSock, Vendor, iSold )
When triggered | Runs on item after player verifies sale, but before sale actually goes through.
Notes | Return false will block the sale from going through, without closing the menu. Return true will make the sale go through as normal.
Purpose | To allow greater control over the selling of specific items to vendors
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;
    }

onSoldToVendor
Prototype |
    function onSoldToVendor( pSock, Vendor, iSold )
When triggered | Runs on item after it has already been sold to the NPC vendor and has reached the NPC vendor's "bought"-backpack
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!
Purpose | To allow greater control over what happens after specific items have been sold to NPCs.
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;
    }

onSkill
Prototype |
    function onSkill( objUsing, skillUsed, objType )
When triggered | when objUsing uses skill skillUsed. objUsing's script is activated.
Notes | objType == 0 indicates objUsing is a character objType == 1 indicates objUsing is an item
Purpose | Complements the use of current skill code. Fires before any existing usage code kicks in.
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.:
    	}
    }

onSkillChange
Prototype |
    function onSkillChange( pPlayer, skill )
When triggered | This is fired if onSkillLoss isn't defined for skill loss, or onSkillGain isn't defined for skill gain.
Notes |
Purpose | Allows you to take action when your skill level changes
Example of Usage |
    function onSkillChange( pPlayer, skill )
    {
    	pPlayer.TextMessage( pPlayer, "Oh dear, my skill's changed" );
    }

onSkillCheck
Prototype |
    function onSkillCheck( pUser, skillID, lowSkill, highSkill )
When triggered |
Notes |
Purpose |
Example of Usage |

onSkillGain
Prototype |
    function onSkillGain( pPlayer, skill )
When triggered | when pPlayer gains in skill skill
Notes |
Purpose | For taking actions when you gain skill.
Example of Usage |
    function onSkillGain( pPlayer, skill )
    {
    	pPlayer.TextMessage("Wheee! I've gained some skill!");
    }

onSkillLoss
Prototype |
    function onSkillLoss( pPlayer, skill )
When triggered | When pPlayer loses in skill skill
Notes |
Purpose | For doing something when you lose skill
Example of Usage |
    function onSkillLoss( pPlayer, skill )
    {
    	pPlayer.TextMessage( "Oh no, I've lost skill!" );
    }

onSkillGump
Prototype |
    function onSkillGump( pUser )
When triggered | When pUser tries opening the skill-gump
Notes |
Purpose | For overriding the client's request to open the default skillgump
Example of Usage |
    function onSkillGump( pUser )
    {
    	pUser.SysMessage( "Overriding default skillgump, opening custom one instead..." );
    	// Insert custom skillgump here!
    }

onSpellGain
Prototype |
    function onSpellGain( spellBook, spellNum )
When triggered | Triggered for spellbooks when spells are added to them
Notes |
Purpose | To allow overriding what happens when spells are added to spellbooks?
Example of Usage |

onSpellLoss
Prototype |
    function onSpellLoss( spellBook, spellNum )
When triggered | Triggered for spellbooks when spells are removed from them
Notes |
Purpose | To allow overriding what happens when spells are removed from spellbooks?
Example of Usage |

onSnooped
Prototype |
    function onSnooped( pSnooped, pSnooping, bSuccess );
When triggered | When pSnooped snoops into pSnooping's pack.
Notes | If overridden, internal behaviour not executed. IE no calling for guards, no messages sent to snooper or snooped. bSuccess is true if successfully snooped, or false if not
Purpose | To allow for behavioural change on snooping behaviour.
Example of Usage |
    function onSnooped( pSnooped, pSnooping, bSuccess )
    {
    	pSnooped.TextMessage( "Oi! You! Stop snooping!" );
    }

onSpeech
Prototype |
    function onSpeech( strSaid, pTalking, pTalkingTo )
When triggered | When pTalking says strSaid to pTalkingTo. pTalkingTo's script is activated
Notes |
Purpose | Greatly improve the speech handling capabilities
Example of Usage |
    function onSpeech( strSaid, pTalking, pTalkingTo )
    {
    	pTalkingTo.TextMessage( strSaid );
    }
    // This is a simple mimic NPC.  Everything that someone says to it is quoted back verbatim

onSpeechInput
Prototype |
    function onSpeechInput(pUser, pItem, pSpeech, pSpeechID)
When triggered | When the SpeechInput method is executed
Notes |
Purpose | To allow action after speech-input has been requested.
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;
    	}
    }

onSpellCast
Prototype |
    function onSpellCast( pUser, spellID )
When triggered | When any spell is cast
Notes | Return value table: -2: use NORMAL non-JS casting -1: CANCEL normal spellcasting 0->inf: Spell delay in ms
Purpose | To allow overriding spellcasting on a spell-per-spell basis
Example of Usage |
    function onSpellCast( pUser, spellID )
    {
    	if( spellID == 18 )
    	{
    		pUser.CustomTarget( 0, "What do you want to target with your fireball?" );
    	        return -1;
    	}
    }

onSpellTarget
Prototype |
    function onSpellTarget( myTarget, pUser, spellID )
When triggered | When targeting something/someone with a spell
Notes | myTarget can be both items and characters
Purpose |
Example of Usage |
    function onSpellTarget( myTarget, pUser, spellID )
    {
    	if( spellID == 18 )
    	{
    		myTarget.TextMessage( "AAAAAAaaaaaaa! I've been hit by a fireball!" );
    	}
    }

onSpellSuccess
Prototype |
    function onSpellSuccess( pUser, spellID )
When triggered | When successfully castin a spell
Notes |
Purpose |
Example of Usage |
    function onSpellSuccess( pUser, spellID )
    {
    	if( spellID == 18 )
    	{
    		pUser.TextMessage( "Yes! I managed to cast a fireball!" );
    	}
    }

onStatChange
Prototype |
    function onStatChange( pPlayer, stat )
When triggered | If onStatLoss isn't defined, and stat went down, or if onStatGained isn't defined and stat went up
Notes |
Purpose |
Example of Usage |
    function onStatChange( pPlayer, stat )
    {
    	pPlayer.TextMessage("Whee my stats changed!");
    }

onStatGained
Prototype |
    function onStatGained( pPlayer, stat )
When triggered | When pPlayer gains in stat stat
Notes |
Purpose | For taking action when a person gains in a stat
Example of Usage |
    function onStatGained( pPlayer, stat )
    {
    	pPlayer.TextMessage("Whee I gained some stat!");
    }

onStatLoss
Prototype |
    function onStatLoss( pPlayer, stat )
When triggered | When pPlayer loses in stat stat
Notes |
Purpose | For taking action when a person loses in a stat
Example of Usage |
    function onStatLoss( pPlayer, stat )
    {
    	pPlayer.TextMessage("Awww I lost some stats.");
    }

onSteal
Prototype |
    function onSteal( thief, objStolen )
When triggered | When objStolen is stolen, objStolen's script is activated
Notes | Works, but gives a console error: ERROR: Chars[-1] referenced is invalid. Crash averted!
Purpose | Specialization of stealing.
Example of Usage |
    function onSteal( thief, objStolen )
    {
    	thief.SysMessage( "You attempt to steal the "+objStolen.name );
    	ConsoleMessage( objStolen.name+" has been attempted stolen!" );

    }

onStolenFrom
Prototype |
    function onStolenFrom( pThief, pVictim, iStolen );
When triggered | When the player pThief steals the item iStolen from the character pVictim
Notes |
Purpose | To allow for response when items are stolen from a player.
Example of Usage |
    function onStolenFrom( pThief, pVictim, iStolen )

    {

    	TextMessage( pVictim, "Hey you, get your hands off my banana!" );

    	Attack( pVictim, pThief );

    	YellMessage( pVictim, "GUARDS!!!!!!!" );

    }

onSwing
Prototype |
    function onSwing( iSwung, pSwinging, pSwingAt )
When triggered | When pSwinging swings iSwung at pSwingAt.
Notes | iSwung's script is activated
Purpose |
Example of Usage |
    function onSwing( iSwung, pSwinging, pSwingAt )
    {
    	pSwinging.TextMessage("Have at thee, knave!");
    }

onSystemSlice
Prototype |
When triggered |
Notes |
Purpose |
Example of Usage |

onTalk
Prototype |
    function onTalk( pTalking, strSaid )
When triggered | When pTalking says strSaid. pTalking's script is activated
Notes |
Purpose | Greatly improve the speech handling capabilities
Example of Usage |
    function onTalk( myChar, mySpeech )
    {
    	if( mySpeech == "'dig")
    		myChar.DoAction(11);
    	else
    		return true;
    }
    // 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.

onTempChange
Prototype |
    function onTempChange( object, temperature )
When triggered | Triggers for object (char/item) when temperature changes
Notes |
Purpose | To allow reactions for characters/items when temperature changes
Example of Usage |

onTimer
Prototype |
    function onTimer( tChar, timerID )
When triggered | When tempeffect 40 (StartTimer) duration has elapsed for timer timerID
Notes |
Purpose | To be used for custom timer information for characters.
Example of Usage |
    function onTimer( tChar, timerID )

    {

    	if( timerID == 0 )

    	{

    		DoStaticEffect( pCharacter, 0x376A, 9, 0, 0 );	// Make some sparkles!

    	}

    }

onTransfer
Prototype |
    function onTransfer( iTransferred, pSrc, pTrg )
When triggered | When pSrc transfers iTransferred to pTrg
Notes | iTransferred's script is activated CURRENTLY BROKEN!!!
Purpose |
Example of Usage |
    function onTransfer( iTransferred, pSrc, pTrg )
    {
    	pSrc.TextMessage("Whee I'm transferring this item to you, "+pTrg.name+"!");
    	pTrg.TextMessage("Thank you, "+pSrc.name+"!");
    }

onUnequip
Prototype |
    function onUnequip( pEquipper, iUnequipped )
When triggered | When pEquipper unequips iUnequipped
Notes | iUnequipped's script is activated
Purpose |
Example of Usage |
    function onUnequip( pUnequipper, iUnequipped )
    {
    	pUnequipper.StaticEffect( 0x376A, 9, 6 );
    }

onUnknownTrigger
Prototype |
When triggered |
Notes |
Purpose |
Example of Usage |

onUseBandageMacro
Prototype |
    function onUseBandageMacro( pSock, targChar, iUsed )
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.
Purpose | To allow greater control of bandage self macro
Example of Usage |
    function onUseBandageMacro( pSock, targChar, bandageItem )
    {
    	targChar.TextMessage( "#0" );
    	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 )
    {
    	pUser.TextMessage( "#1" );
    	if( pUser && iUsed && iUsed.isItem )
    	{
    		pUser.TextMessage( "#2" );

    		var socket = pUser.socket;
    		if( socket )
    		{
    			pUser.TextMessage( "#3" );

    			if( pUser.skillsused.healing || pUser.skillsused.veterinary )
    			{
    				pUser.TextMessage( "#4" );
    				socket.SysMessage( "You are too busy to do that." );
    			}
    			else if( socket.GetTimer( 0 ) <= GetCurrentClock() )
    			{
    				pUser.TextMessage( "#5" );
    				socket.tempObj = iUsed;
    				socket.SetTimer( 0, 5000 );
    				onCallback1( socket, targChar );
    			}
    			else
    			{
    				pUser.TextMessage( "#6" );
    				socket.SysMessage( GetDictionaryEntry( 473, socket.Language ) );
    			}
    		}
    	}
    	return true;
    }

onUseChecked
Prototype |
    function onUseChecked( pUser, iUsed )
When triggered | When pUser uses iUsed.
Notes | if return value from script is true, it continues on executing with hard coded implementation if return value is false, then no hard code is executed
Purpose | To allow greater customization on using items.
Example of Usage |
    function onUseChecked( pUser, iUsed )
    {
    	var trgSock = pUser.socket;
    	if(pUser.InRange( iUsed, 8 ))
    		pUser.OpenBank(trgSock);
    	return false;
    }

onUseUnChecked
Prototype |
    function onUseUnChecked( pUser, iUsed )
When triggered | When pUser uses iUsed.
Notes | Unlike the onUseChecked event this one runs without any hardcoded checks.
Purpose | To allow greater customization on using items.
Example of Usage |
    function onUseUnChecked( pUser, iUsed )
    {
    	var trgSock = pUser.socket;
    	if(pUser.InRange( iUsed, 8 ))
    		pUser.OpenBank(trgSock);
    	return false;
    }

onVirtueGumpPress
Prototype |
    function onVirtueGumpPress( mChar, tChar, buttonID )
When triggered | When Virtue gumps are pressed?
Notes |
Purpose |
Example of Usage |

onWeatherChange
Prototype |
    function onWeatherChange( object, weatherType )
When triggered | Triggers for object (char/item) when weather changes
Notes |
Purpose | To allow reactions for characters/items when weather changes
Example of Usage |

OutOfRange
Prototype |
    function OutOfRange( pChar, objVanish, objType )
When triggered | When objVanish goes out of range of pChar
Notes | objType == 0 indicates objVanish is a character objType == 1 indicates objVanish is an item
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.
Example of Usage |

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