# UOX3 Script Engine

### Functions, Methods, Properties and Event handling

### Character Related Methods

TextMessage
Prototype |
    void TextMessage( message );
    void TextMessage( message, allHear, txtHue );
Purpose | Causes the Char to say a message. The extended version of TextMessage has two optional arguments: allHear (broadcast true/false) txtHue (color of the text sent to the client).
Example of Usage |
    myChar.TextMessage( "Hello world!" );
    myChar.TextMessage( "Public, ice-colored message sent to everyone as if I said it.", true, 0x0480 );
    myChar.TextMessage( "Private, ice-colored message just for me!", false, 0x0480 );

YellMessage
Prototype |
    void YellMessage( message );
Purpose | Causes the Char to yell a message to all players within range
Example of Usage |
    myChar.YellMessage( "YARGH!" );

WhisperMessage
Prototype |
    void WhisperMessage( message );
Purpose | Causes the Char to whisper a message that can be seen only by nearby players
Example of Usage |
    myChar.WhisperMessage( "Shhhhh, we're hunting wabbits!" );

EmoteMessage
Prototype |
    void EmoteMessage( message );
Purpose | Causes the Char to emote message. You have to put the start and end * manually in!
Example of Usage |
    myChar.EmoteMessage( "*looks around*" );

Delete
Prototype |
    void Delete();
Purpose | Causes the Char to be deleted.
Example of Usage |
    myChar.Delete();

DoAction
Prototype |
    void DoAction( trgAction );
Purpose | Makes Char do action trgAction. NOTE: Anyone got a list of the possible actions?
Example of Usage |
    myChar.DoAction( 0x0B );

SoundEffect
Prototype |
    void SoundEffect( soundID, bAllHear );
Purpose | Plays a sound from Character. SoundID is the full ID of the sound to play. If bAllHear is TRUE, then everyone nearby hears it. If it's false, then only the Character hears it.
Example of Usage |
    myChar.SoundEffect( 568, TRUE );

SellTo
Prototype |
    void SellTo( targNPC );
Purpose | Brings up the shopkeeper gump for selling to a vendor targNPC.
Example of Usage |
    myChar.SellTo( myNPC );

BuyFrom
Prototype |
    void BuyFrom( targNPC );
Purpose | Brings up the shopkeeper gump or PV backpack for buying for vendor targNPC.
Example of Usage |
    myChar.BuyFrom( myNPC );

HasSpell
Prototype |
    bool HasSpell( spellNum );
Purpose | Scans through player's contents to see if they have spellNum in the first spellbook encountered
Example of Usage |
    if(myPlayer.HasSpell( 0 )==1);

RemoveSpell
Prototype |
    void RemoveSpell( spellNum );
Purpose | Removes spellNum from player's spellbook
Example of Usage |
    myChar.RemoveSpell( 0 );

OpenBank
Prototype |
    void OpenBank( trgSock );
Purpose | Open's Char's bank, sending it to trgSock
Example of Usage |
    myPlayer.OpenBank(trgSock);

DirectionTo
Prototype |
    unsigned char DirectionTo( trgObj );
    unsigned char DirectionTo( x, y );
Purpose | Returns the direction from character to trgObj/location
Example of Usage |
    var dir = myChar.DirectionTo( trgChar );
    var dir = myChar.DirectionTo( trgChar.x, trgChar.y );

TurnToward
Prototype |
    void TurnToward( trgObj );
    void TurnToward( x, y );
Purpose | Char turns to trgObj.
Example of Usage |
    myNPC.TurnToward( myObject );
    myNPC.TurnToward( myObject.x, myObject.y );

ResourceCount
Prototype |
    int ResourceCount( realitemid, colour );
Purpose | Returns the amount of items with specified ID realitemid and colour from character's backpack
Example of Usage |
    if(myChar.ResourceCount( 0x1BF2, 0 ));

UseResource
Prototype |
    int UseResource( amount, realitemid );
    void UseResource( amount, realitemid, colour );
Purpose | Removes amount of items with specified ID realitemid from character's backpack, and returns amount deleted
Example of Usage |
    myChar.UseResource( 5, 0x1BF2, 0 );

CustomTarget
Prototype |
    void CustomTarget( tNum, toSay );
Purpose | Very similar to PopUpTarget. It's a callback situation instead. tNum must be between 0 and 255. Says toSay, and shows a cursor. Reenters the script associated with the socket's player (ie player who gets the cursor). Enters function name based on the value of tNum. if tNum is 0, then the function would be onCallback0. Prototype of callback is:
    function onCallback0( tSock, targSerial )
Example of Usage |
    myChar.CustomTarget( 0, "Select your custom target:" );

PopUpTarget
Prototype |
    void PopUpTarget( tNum, toSay );
Purpose | Provides a call to an inbuilt popup target. tNum must be between 0 and 255 inclusive. Says toSay, and shows a cursor. Note that this allows access potentially to GM functions.
Example of Usage |
    myChar.PopUpTarget( 2, "Where do you wish to teleport to?" );

InRange
Prototype |
    bool InRange( trgObj, distance );
Purpose | Returns true if the distance to trgObj is less than distance
Example of Usage |
    if( myChar.InRange( trgObj, 18 ))
    	{
    		myChar.TextMessage( "I'm within range!" );
    	}

FindItemLayer
Prototype |
    *Item FindItemLayer( layer );
Purpose | A return value of -1 indicates there was no item at that particular layer. A common list of layers follow 0x01 - Single-Hand item/weapon 0x02 - Two-Hand item/weapon (including Shield) 0x03 - Foot Covering/Armor 0x04 - Leg Covering (including Pants, Shorts, Bone/Chain/Ring legs) 0x05 - Chest Clothing/Female Chest Armor 0x06 - Head Covering/Armor 0x07 - Hand Covering/Armor 0x08 - Ring 0x09 - N/A (not used) 0x0A - Neck Covering/Armor 0x0B - Hair 0x0C - Waist (Half-Apron) 0x0D - Torso (inner)(Chest Armor) 0x0E - Bracelet 0x0F - N/A (no info) 0x10 - Facial Hair 0x11 - Torso (Middle)(Surcoat, Tunic, Full Apron, Sash) 0x12 - Earrings 0x13 - Arm Covering/Armor 0x14 - Back (Cloak) 0x15 - BackPack 0x16 - Torso (outer)(Robe) 0x17 - Legs (outer)(Skirt/Kilt) 0x18 - Legs (inner)(Leg Armor) 0x19 - Mount (Horse, Ostard, etc.) 0x1A - NPC Buy Restock Container 0x1B - NPC Buy No Restock Container 0x1C - NPC Sell Container 0x1D - Bank Box
Example of Usage |
    lefthand=myChar.FindItemLayer(1);

StartTimer
Prototype |
    void StartTimer( numMiliSec, timerID, callback );
Purpose | Starts a timer that will elapse after numHundredthsOfSec seconds pass, for a character tChar. timerID must be between 0 and 100. Resulting onTimer event will be triggered. Which script it triggers in depends on the (optional, defaults to false) third parameter, which can be true (calls back to existing script), false (calls back into object's script) or an int (scriptID to call back to). This optional parameter defaults to false if not specified.
Example of Usage |
    myChar.StartTimer( 600, 0, true ); //Timer calls back to object's script
    myChar.StartTimer( 1200, 0, false ); //Timer calls back to existing script
    myChar.StartTimer( 1200, 0, 2012 ); //Timer calls back to script with ID 2012

CheckSkill
Prototype |
    bool CheckSkill( skillnum, minskill, maxskill );
Purpose | Returns true if the skill skillnum is between min and may skill.
Example of Usage |
    if( myChar.CheckSkill( 1, 200, 1000))

SpeechInput
Prototype |
    void SpeechInput( speechID );
Purpose | Calls up the onSpeechInput event with the text the user types.
Example of Usage |
    myChar.SpeechInput( 1 );

CastSpell
Prototype |
    void CastSpell( spellNum );
Purpose | Causes character to cast spellNum. Character can be an NPC or PC. spellNum can be any valid spellNum (0=>63).
Example of Usage |
    myChar.CastSpell( 32 );

SysMessage
Prototype |
    void SysMessage( string message );
Purpose | Sends a string as a sysmessage.
Example of Usage |
    myChar.SysMessage( "Isn't the world great?" );

MagicEffect
Prototype |
    void MagicEffect( spellID );
Purpose | Applies spell effects of specified spell to character.
Example of Usage |
    myChar.MagicEffect( 43 );

GetSerial
Prototype |
    int GetSerial( part );
Purpose | Gets a part (1-4) of a character's serial
Example of Usage |
    iSerial = myChar.GetSerial( 1 );

MakeMenu
Prototype |
    void MakeMenu( mnu );
Purpose | Opens up make menu mnu and sends it to sock
Example of Usage |
    myChar.MakeMenu( 1 );

Wander
Prototype |
    void Wander( x1, y1, x2, y2 );
    void Wander( x1, y1, radius );
Purpose | Forces the npc to wander in the coordinates specified, 2 coords and a radius is a circle, 4 coords is a box.
Example of Usage |
    myNPC.Wander( 5593, 1203, 5608, 1206 );

Follow
Prototype |
    void Follow( newmaster );
Purpose | Forces the char to follow the new master.
Example of Usage |
    myNPC.Follow( myChar );

Dismount
Prototype |
    void Dismount();
Purpose | Dismounts a char.
Example of Usage |
    myChar.Dismount();

SetPoisoned
Prototype |
    void SetPoisoned( poisonLevel, Length )
Purpose | Applies a specified level of poison to a character for a specified amount of time (in milliseconds).
Example of Usage |
    myChar.SetPoisoned( 2, 10000 );
    //Gives myChar a 2nd level poison for 10 seconds.

ExplodeItem
Prototype |
    void ExplodeItem( myItem );
Purpose | Deletes specified item by exploding it, dealing 5-10 dmg to nearby characters.
Example of Usage |
    myChar.ExplodeItem( myItem );

SetInvisible
Prototype |
    void SetInvisible( visibility, timeLength )
Purpose | Sets character to the specified visibility level for the specified amount of time (in milliseconds). NOTE: Timer seems to be broken, as character stays hidden forever.
Example of Usage |
    myChar.SetInvisible( 1, 1000 );

AddSpell
Prototype |
    void AddSpell( spellNum )
Purpose | Adds specified spell to the first spellbook in character's pack
Example of Usage |
    myChar.AddSpell( 3 ); //adds Feeblemind spell to myChar's spellbook (if he has one)

SpellFail
Prototype |
    void SpellFail()
Purpose | Does the actions associated in code with spell failure. Use after character fails to cast a spell, will play fail-effect, sound and give player default fail-message
Example of Usage |
    myChar.SpellFail();

ExecuteCommand
Prototype |
    void ExecuteCommand( cmdString );
Purpose | Executes the command cmdString(should include any params).
Example of Usage |
    myChar.ExecuteCommand( "add 0x04a9" );

WalkTo
Prototype |
    void WalkTo( object, maxsteps );
    void WalkTo( x, y, maxsteps );
Purpose | Makes the character walk to a specific location, halting if it takes too many steps.
Example of Usage |
    myNPC.WalkTo( pUser, 10 );

RunTo
Prototype |
    void RunTo( object, maxsteps );
    void RunTo( x, y, maxsteps );
Purpose | Makes the character run to a specific location, halting if it takes too many steps.
Example of Usage |
    myNPC.RunTo( pUser, 10 );

OpenLayer
Prototype |
    void OpenLayer( socket, layerToOpen )
Purpose | Opens the specified layer of the character to the specified socket.
Example of Usage |
    myChar.OpenLayer( pSock, 0x15 );

BoltEffect
Prototype |
    void BoltEffect()
Purpose | Plays the lightning bolt effect on specified character to all nearby players.
Example of Usage |
    myChar.BoltEffect();

Gate
Prototype |
    void Gate( item )
    void Gate( x, y, z, world )
Purpose | Opens a gate to the location marked on an item, or to a specific set of coordinates
Example of Usage |
    myChar.Gate( targItem );

Recall
Prototype |
    void Recall( item )
Purpose | Recalls the character gate to the location marked on an item.
Example of Usage |
    myChar.Recall( targItem );

Mark
Prototype |
    void Mark( item )
Purpose | Marks an item with the characters current location to be used later for recall or gate.
Example of Usage |
    myChar.Mark( targItem );

SetSkillByName
Prototype |
    bool SetSkillByName( "skillName", value )
Purpose | Sets the skill specified by name to the value specified (name must be the same as in skills.dfn, "ALLSKILLS" is also applicable.
Example of Usage |
    myChar.SetSkillByName( "alchemy", 1000 );

Kill
Prototype |
    void Kill()
Purpose | Kills the character.
Example of Usage |
    myChar.Kill();

Resurrect
Prototype |
    void Resurrect()
Purpose | Resurrects the deceased character.
Example of Usage |
    myChar.Resurrect();

Jail
Prototype |
    void Jail()
    void Jail( numSecsToJail )
Purpose | Jails character for n seconds (if specified).
Example of Usage |
    myChar.Jail( 1000 );

Release
Prototype |
    void Release()
Purpose | Releases the character from jail.
Example of Usage |
    myChar.Release();

SpawnNPC
Prototype |
    CChar SpawnNPC( "section", x, y, z, worldnumber )
Purpose | Spawns a character from a DFN entry (section)
Parameters | section - The entry string in npc-DFNs to spawn from. x, y and z - The target location to spawn at worldNumber - The world that it will spawn in (0 == britannia, 2 == ilshenar)
Example of Usage |
    function onUseChecked( pUser, iUsed )
    {
    	var nSpawned = SpawnNPC( "brownhorse", pUser.x, pUser.y, pUser.z, pUser.worldnumber );
    	if( nSpawned != null )
    		pUser.SysMessage( "Wheee - a brown horse just spawned at my location!" );
    }

Defense
Prototype |
    int Defense( hitLoc, damageType, doArmorDamage )
Purpose | Returns the defense value against damageType of the armor item at the location hitLoc and does armor damage if needed
Parameters | hitLoc = the hit location (0 the whole char, 1 the body, 2 the arms, 3 the head, 4 the legs, 5 the neck and 6 the rest), the damageType and if the armor gets damaged.
Example of Usage |
    Get the defense value of the head armor against Physical damage and damage the armor:
    value = mChar.Defense( 3, 1, true);

Resist
Prototype |
    int Resist( resistanceType );
    void Resist( resistanceType, amount );
Purpose | Used to get/set the resistance type and amount of the object
Parameters | Current resistanceTypes are: 1 - Armor 2 - Light 3 - Water 4 - Cold 5 - Heat 6 - Energy 7 - Poison
Example of Usage |
    pUser.Resist( 1, 20 );
    //or...
    var coldResist = pUser.Resist( 4 );

SpellMoveEffect
Prototype |
    void SpellMoveEffect( targetChar, mSpell )
Purpose | Plays the MOVEFX effect of the specified spell in SPELLS.DFN, going from the character to the target
Parameters |
Example of Usage |
    var spellNum	= mChar.spellCast;
    var mSpell	= Spells[spellNum];
    mChar.SpellMoveEffect( targetChar, mSpell );

SpellStaticEffect
Prototype |
    void SpellStaticEffect( mSpell )
Purpose | Play the STATFX effect specified for the specified spell in SPELLS.DFN, on the specificed character
Parameters |
Example of Usage |
    var spellNum	= mChar.spellCast;
    var mSpell	= Spells[spellNum];
    targetChar.SpellStaticEffect( mSpell );

BreakConcentration
Prototype |
    void BreakConcentration()
    void BreakConcentration( socket )
Purpose | Break a caster's concentration
Parameters |
Example of Usage |
    myNPC.BreakConcentration(); //for NPCs, who have no sockets
    myPlayer.BreakConcentration( mSocket ); //for players, who DO have sockets

FindItemType
Prototype |
    Item FindItemType( itemType )
Purpose | Look for items of a certain type in character's pack
Parameters |
Example of Usage |
    var spellBook = myPlayer.FindItemType( 9 ); //does the player have a spellbook?

InitWanderArea
Prototype |
    void InitWanderArea()
Purpose | Initialize a WanderArea (10x10 box, or 10 radius circle) for the specified NPC. Will only work if they already have a wandermode set to box or circle.
Parameters |
Example of Usage |
    myNPC.InitWanderArea();

ReactOnDamage
Prototype |
    void ReactOnDamage( damageType );
    void ReactOnDamage( damageType, attacker );
Purpose | Make a character react on damage
Parameters |
Example of Usage |
    myChar.ReactOnDamage( 2 );
    myChar.ReactOnDamage( 2, attackerChar );

Damage
Prototype |
    void Damage( amount );
    void Damage( amount, attacker );
    void Damage( amount, attacker, doRepSys );
Purpose | Cause damage to a character
Parameters | doRepSys true/false = flag as criminal?
Example of Usage |
    myChar.Damage( 15 );
    myChar.Damage( 15, attackerChar );
    myChar.Damage( 15, attackerChar, true );

Heal
Prototype |
    void Heal( amount );
    void Heal( amount, attacker );
    void Heal( amount, attacker, doRepSys );
Purpose | Heal a character
Parameters |
Example of Usage |
    myChar.Heal( 15 );
    myChar.Heal( 15, healerChar );

Original: ©Copyright 2000-2001 WWW.UOX3.NET (Daniel Stratton/Matthew Randall) ||| Rewrite: ©Copyright 2002 WWW.UOXDEV.DE (Florian "Rukus" Frick) ||| Re-Rewrite and further updates: @Copyright 2003-2012 WWW.UOX3.ORG Xuri