UOX3 Script Engine

API and Event handling

onCreate
Prototype
function onCreate( objMade, objType )
When triggeredWhen an item or char is created. Note that for PCs, this is triggered when they first enter the world.
NotesobjType == 0 indicates an item
objType == 1 indicates a character
PurposeUsed 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.

 

onDelete
Prototype
function onDelete( objDestroyed, objType )
When triggeredWhen an item or character is deleted
NotesobjType == 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." );
}

 

onSpeech
Prototype
function onSpeech( strSaid, pTalking, pTalkingTo )
When triggeredWhen pTalking says strSaid to pTalkingTo. pTalkingTo's script is activated
Notes
PurposeGreatly 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

 

onTalk
Prototype
function onTalk( pTalking, strSaid )
When triggeredWhen pTalking says strSaid. pTalking's script is activated
Notes
PurposeGreatly 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.

 

inRange
Prototype
function inRange( pCharacter, objInRange, objType )
When triggeredobjInRange comes into visible range of pCharacter. pCharacter's script is activated
NotesobjType == 0 indicates objInRange is a character
objType == 1 indicates objInRange is an item
CURRENTLY BROKEN!!!
PurposeUseful 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
	{
		DoStaticEffect( pCharacter, 0x376A, 9, 0, 0 );	// Make some sparkles!
		var iID;
		iID = GetID( objInRange, objType );	// What's the ID of the item?
		if( iID == 0x1416 )			// Ooh, it's a purty piece of armour
		{
			EmoteMessage( pCharacter, "*ooooooooooooo*" );
		}
	}	
}

 

onCollide
Prototype
function onCollide( targSock, pColliding, objCollidedWith )
When triggeredWhen pColliding collides with objCollidedWith (stepped on basically)
NotesobjCollidedWith is only an item currently. targSock is -1 if pColliding is an NPC
PurposeReplace 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 );
}

 

onSteal
Prototype
function onSteal( thief, objStolen )
When triggeredWhen objStolen is stolen, objStolen's script is activated
NotesWorks, but gives a console error: ERROR: Chars[-1] referenced is invalid. Crash averted!
PurposeSpecialization 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!" );
	
}

 

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

 

onSkill
Prototype
function onSkill( objUsing, skillUsed, objType )
When triggeredwhen objUsing uses skill skillUsed. objUsing's script is activated.
NotesobjType == 0 indicates objUsing is a character
objType == 1 indicates objUsing is an item
PurposeComplements 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.:
	}
}

 

onAttack
Prototype
function onAttack( pAttacker, pDefender )
When triggeredWhen pAttacker attacks pDefender
NotespAttacker's script is activated, and pDefender's onDefense event is fired
CURRENTLY BROKEN!!!
PurposeFlesh out the attacking code.
Example of Usage

 

onDefense
Prototype
function onDefense( pAttacker, pDefender )
When triggeredWhen pAttacker attacks pDefender
NotespDefender's script fires, pAttacker's onAttack event is also fired
CURRENTLY BROKEN!!!
PurposeFlesh out the attacking code.
Example of Usage

 

onSkillGain
Prototype
function onSkillGain( pPlayer, skill )
When triggeredwhen pPlayer gains in skill skill
Notes 
PurposeFor 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 triggeredWhen pPlayer loses in skill skill
Notes 
PurposeFor doing something when you lose skill
Example of Usage
function onSkillLoss( pPlayer, skill )
{
	pPlayer.TextMessage( "Oh no, I've lost skill!" );
}

 

onSkillChange
Prototype
function onSkillChange( pPlayer, skill )
When triggeredThis is fired if onSkillLoss isn't defined for skill loss, or onSkillGain isn't defined for skill gain.
Notes 
PurposeAllows 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" );
}

 

onStatGain
Prototype
function onStatGain( pPlayer, stat )
When triggeredWhen pPlayer gains in stat stat
Notes
PurposeFor taking action when a person gains in a stat
Example of Usage
function onStatGain( pPlayer, stat )
{
	pPlayer.TextMessage("Whee I gained some stat!");
}

 

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

 

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

 

onDrop
Prototype
function onDrop( iDropped, pDropper )
When triggeredWhen pDropper drops iDropped.
NotesiDropped's script is activated.
CURRENTLY BROKEN!!!
Purpose
Example of Usage

 

onDropItemOnNPC
Prototype
function onDropItemOnNPC( pDropper, pDroppedOn, iDropped )
When triggeredWhen pDropper drops iDropped on pDroppedOn
NotesiDropped's script is activated.
Purpose
Example of Usage

 

onPickup
Prototype
function onPickup( iPickedUp, pGrabber )
When triggeredWhen pGrabber picks up iPickedUp
NotesiPickedUp's script is activated.
CURRENTLY BROKEN!!!
Purpose
Example of Usage

 

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

 

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

 

onTransfer
Prototype
function onTransfer( iTransferred, pSrc, pTrg )
When triggeredWhen pSrc transfers iTransferred to pTrg
NotesiTransferred'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+"!");
}

 

onLeaving
Prototype
function onLeaving( iLeft, objLeaving, objType )
When triggeredwhen objLeaving leaves the multi object iLeft
NotesobjType == 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);
}

 

onEntrance
Prototype
function onEntrance( iEntered, objEntering, objType )
When triggeredWhen objEntering enters the multi object iEntered
NotesobjType == 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 triggeredWhen pEquipper equips iEquipped
NotesiEquipped's script is activated
Purpose
Example of Usage
function onEquip( pEquipper, iEquipped )
{
	pEquipper.StaticEffect( 0x376A, 9, 6 );
}

 

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

 

onUse
Prototype
function onUse( pUser, iUsed )
When triggeredWhen pUser uses iUsed. Replaces any code behaviour that may exist
NotesiUsed's script is activated
PurposeTo allow greater customization on using items.
Example of Usage
function onUse( pUser, iUsed )
{
var trgSock = pUser.socket;
if(pUser.InRange( iUsed, 8 ));
	pUser.OpenBank(trgSock);
}

 

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

 

OutOfRange
Prototype
function OutOfRange( pChar, objVanish, objType )
When triggeredWhen objVanish goes out of range of pChar
NotesobjType == 0 indicates objVanish is a character
objType == 1 indicates objVanish is an item
PurposeTo 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

 

onLogin
Prototype
function onLogin( sockPlayer, pChar )
When triggeredWhen pChar is logged in to the world
NotessockPlayer is never -1
PurposeTo 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 triggeredWhen pChar is logging out of the world
NotessockPlayer is never -1
PurposeTo 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." );
}

 

onFall
Prototype
function onFall( pFall, fallDistance )
When triggeredWhen pFall falls fallDistance
NotespFall can be either an npc or pc
CURRENTLY BROKEN!!!
Purpose
Example of Usage
function onFall( pFall, fallDistance )
{
	if( fallDistance > 10 )
		pFall.SysMessage("Ouch!");
}

 

onSell
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onBuy
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onAISliver
Prototype
function onAISliver( npcChar )
When triggeredEvery AI loop, during their AI slice
Notes
PurposeGreat 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 =)

 

onSystemSlice
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onUnknownTrigger
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onLightChange
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onXYZEvent
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onPortal
Prototype
When triggered
Notes
Purpose
Example of Usage

 

onTimer
Prototype
function onTimer( tChar, timerID )
When triggeredWhen tempeffect 40 (StartTimer) duration has elapsed for timer timerID
Notes
PurposeTo 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!
}
}

 

onDeath
Prototype
function onDeath( pDead );
When triggeredWhen the player or NPC pDead dies
NotesCURRENTLY BROKEN!!!
PurposeCustom 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 );
}

 

onResurrect
Prototype
function onRessurect( pAlive );
When triggeredWhen a player pAlive is resurrected.
NotesOnly applies to PCs
CURRENTLY BROKEN!!!
PurposeControl over what happens when a person comes alive once more
Example of Usage
function onResurrect( pAlive )
{
	pAlive.Teleport( 1000, 1000, 0 );
}

 

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

 

onHungerChange
Prototype
function onHungerChange( pChanging, newStatus );
When triggeredWhen a player's hunger level changes goes down.
NotesIf overridden, the normal hunger messages are not displayed.
PurposeTo 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!" );
}
}

 

onSnooped
Prototype
function onSnooped( pSnooped, pSnooping, bSuccess );
When triggeredWhen pSnooped snoops into pSnooping's pack.
NotesIf 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
PurposeTo allow for behavioural change on snooping behaviour.
Example of Usage
function onSnooped( pSnooped, pSnooping, bSuccess )

{
TextMessage( pSnooped, "Oi! You! Stop snooping!" );
}

 

onStolenFrom
Prototype
function onStolenFrom( pThief, pVictim, iStolen );
When triggeredWhen the player pThief steals the item iStolen from the character pVictim
Notes
PurposeTo 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!!!!!!!" );
}
©Copyright 2000-2001 WWW.UOX3.NET (Daniel Stratton/Matthew Randall)