POL Script Types

This is a list of all the different script types used in the POL system. Some only pertain to specific objects, and/or specifc events, as described.



Last Modified: 6/23/2006

AIScript
program AIscript()
Return values
return value ignored
Scheduler Type
Normal
Default Priority
1
When Is It Called?
When an NPC is created (either new or from world save on startup)
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/ai
To Define
In the NPC's npcdesc.cfg entry, the 'Script' property defines the location of the AI script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/ai. Also, setting npc.script allows you to change the script.
Explanation
This script acts as an NPC's control script, allowing it to move, fight, and react to events. This script should not exit until the NPC dies, or the NPC will become 'braindead'. Normally there exists a loop where events are processed and other actions are performed.
This is the only script type where NPC.EM functions are allowed.
Examples
//Not a completely usable AI script, for example, doesn't close the distance to an opponent
// or react to other sysevents.
use uo;
use npc;
use os;
include "include/sysEvent";
var me;
program my_example_aicript()
    var me := Self();
    var event;
    EnableEvents(SYSEVENT_SPEECH,5);
    EnableEvents(SYSEVENT_ENGAGED);
    while(me)
        event := wait_for_event(15);
        if(event)
            case(event.type)
                SYSEVENT_SPEECH: Say( event.source.name + " said: " + event.text );
                SYSEVENT_ENGAGED: SetOpponent( event.source );
            endcase
        endif
        Wander();
    endwhile
endprogram
Related Objects
NPC
Related Config Files
npcdesc.cfg



AttackHitScript
program attackhitscript(attacker, defender, weapon, armor, basedamage, rawdamage )
Parameters:
NameType
attackerCharacter Ref of player attacking with weapon
defenderCharacter Ref
weaponWeapon Ref
armorArmor Ref, or 0 if no armor was hit.
basedamageInteger damage amount due to random weapon damage, strength, and tactics.
rawdamageInteger damage amount due basedamage, minus amount absorbed by armor.
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a weapon with a hit script defined successfully hits an opponent. (note not called automatically if Attack syshook is called)
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/items
To Define
In the NPC's npcdesc.cfg entry, the 'AttackHitScript' property defines the location of the NPC's intrinsic weapon hit script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/items.
Explanation
This script acts the same as a HitScript, but it is for an NPC's "intrinsic weapon" which is a fake weapon for NPCs that attack with bare fists. See HitScript and npcdesc.cfg.
Examples
Related Objects
Weapon
NPC
Related Config Files
npcdesc.cfg
Related Script Types
HitScript



AuxServiceScript
program auxservice(connection)
Parameters:
NameType
connectionAux Connection Object
Return values
return value ignored, exiting aux service script closes connection.
Scheduler Type
Normal
Default Priority
1
When Is It Called?
When a network connection is created on the defined port in auxsvc.cfg.
Where Does It Live?
The 'program' in a .src file, in a package.
To Define
Define the 'Script' property in auxsvc.cfg.
Explanation
This script allows a scripter to communicate with an external TCP/IP application, using the normal POL packed string format for communcation.
wait_for_event allows packet reads, with ev.type == "recv" and ev.value the unpacked data.
connection.transmit(unpacked object) is the interface for sending data to the external application.
If you save the service script PID to a global variable, other scripts may communicate with the external application via your service script.
Examples
//auxsvc.cfg:
AuxService
{
    Port 5009
    Script aux1
}
//aux1.src:
use uo;
use os;
program auxtest( connection )
	var ev;
	print( "aux service is running" );
	while (connection)
		ev := wait_for_event( 5 );
		if (ev)
			print(ev.value);
		endif
	endwhile
	print( "aux connection closed" );
endprogram
Related Objects
AuxConnection
Related Config Files
auxsvc.cfg



CanDeleteScript
program candelete( character, deleteby )
Parameters:
NameType
characterCharacter Ref
deletebyInteger
Return values
If 1, character is allowed to be removed from account, else it is not removed.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
Before character deletion.
Where Does It Live?
The 'program' in a .src file, in /scripts/misc
To Define
This script is called for all Players.
Explanation
This script allows control over what character may be removed by returning 1 or 0. This script is run critical, so try not to do too many calculations in it.
Examples
UO.EM constants used with the 'deleteby' parameter:    
const DELETE_BY_PLAYER := 0; // Delete-Request by Player
const DELETE_BY_SCRIPT := 1; // Delete-Request by account.DeleteCharacter( index )
Related Objects
Character
Account
Related Script Types
OnDeleteScript



CanInsertScript
program caninsertscript(character, container, movetype, inserttype, adding_item, existing_stack, amount_to_add)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
containerContainer Ref
movetypeinteger
inserttypeinteger
adding_itemItem Ref
existing_stackItem Ref
amt_to_addinteger
Return values
If 1, item is allowed to be inserted into the container, else it is not inserted.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
While the item is being moved into (or created in) a container, by user dragging, script function, or the core.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'CanInsertScript' property defines the location of the can insert script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script allows control over what items may be inserted into a container by returning 1 or 0. This script is called fairly often, and is run critical, so try not to do too many calculations in it.
IMPORTANT: the first parameter (character) MAY be passed as an uninitialized object if the item was not moved by character (i.e. by a script function or the core), so please check it before you use it.
inserttype will be INSERT_ADD_ITEM if a new item is being inserted into the container (existing_stack and amt_to_add are uninit), or INSERT_INCREASE_STACK if an existing item's amount is merely being increased (note 'adding_item' can be uninit if one of the CreateItem functions is merely adding to an existing stack, as opposed to a client action)
These are the times when canInsert scripts are called: Client drag/drop, vendor buy: when moving items to the player's backpack, vendor sell: when putting gold in the player's backpack, secure trade, when cancelling or confirming a trade, MoveItemToContainer, CreateItemInContainer, CreateItemInInventory, CreateItemInBackpack.
You should not destroy the adding_item in the CanInsert script.
Examples
use uo;
const MAX_WEIGHT := 400;
program my_example_caninsertscript(character, container, movetype, inserttype, 
                                   adding_item, existing_stack, amount_to_add)
    if(character != error)
      if(inserttype == INSERT_ADD_ITEM)
        if(character.weight + adding_item.weight > MAX_WEIGHT)
            return 0;
        else
            return 1;
        endif
      else
        if(adding_item)
          if(character.weight + adding_item.weight > MAX_WEIGHT)
            return 0;
          else
            return 1;
          endif
        else //need to go by the amount to add
          var weight_per_item := CDbl(existing_stack.weight) / CDbl(existing_stack.amount);         
          if(character.weight + (weight_per_item * amount_to_add) > MAX_WEIGHT)
            return 0;
          else
            return 1;
          endif
        endif
      endif          
    else
        return 1;
    endif
endprogram
UO.EM constants used with the 'movetype' parameter:    
const MOVETYPE_PLAYER     := 0; // physically moved (dragged) by a player
const MOVETYPE_COREMOVE   := 1; // moved by the core (eg, MoveItemToContainer().)
Insert scripts only:
const MOVETYPE_CORECREATE := 2; // created by core (eg, CreateItemInBackpack().)
UO.em constants used with the 'inserttype' parameter:
const INSERT_ADD_ITEM        := 1;
const INSERT_INCREASE_STACK  := 2;
Related Objects
Character
Container
Item
Related Config Files
itemdesc.cfg
Related Script Types
OnInsertScript
CanRemoveScript
OnRemoveScript



CanRemoveScript
program canremovescript(character, container, item, movetype)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
containerContainer Ref
itemItem Ref
movetypeInteger
Return values
If 1, item is allowed to be removed from the container, else it is not removed.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
While the item is being moved out of a container, by user dragging, script function, or the core.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'CanRemoveScript' property defines the location of the can remove script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script allows control over what items may be removed from a container by returning 1 or 0. This script is called fairly often, and is run critical, so try not to do too many calculations in it.
IMPORTANT: the first parameter (character) MAY be passed as an uninitialized object if the item was not moved by character (i.e. by a script function or the core), so please check it before you use it.
You should not destroy the item in the CanRemove script.
Examples
use uo;
program my_example_canremovescript(character, container, item)
    var cursed := GetObjPropert(item,"cursed");
    if(cursed == 1)
        return 0;
    else
        return 1;
endprogram
UO.EM constants used with the 'movetype' parameter:    
const MOVETYPE_PLAYER     := 0; // physically moved (dragged) by a player
const MOVETYPE_COREMOVE   := 1; // moved by the core (eg, MoveItemToLocation().)
Related Objects
Character
Container
Item
Related Config Files
itemdesc.cfg
Related Script Types
OnInsertScript
CanInsertScript
OnRemoveScript



ConsoleScript
program consolescript(cmd)
Parameters:
NameType
cmdcommand string, i.e. 'B'
Return values
return value ignored
Scheduler Type
Normal
Default Priority
1
When Is It Called?
When a character is entered into the POL Console, i.e. 'B'.
Where Does It Live?
The 'program' in a .src file, only in /scripts/console
To Define
Map a command character to a console script in /config/console.cfg
Explanation
This script allows an administrator to activate POL scripts without needing to log into the game. The scripts could be used to shut down theserver after a time, or print a online character list, etc.
Examples
There are four special command script names:
[lock]              lock the console
[unlock]            unlock the console
[lock/unlock]       toggle the lock status of the console
[threadstatus]      will display thread status and checkpoints
// Print number of toplevel items in the world.
use uo;
program consolescript( cmd )
    print( "System Message: Current # of Toplevel Items - " + polcore().itemcount );
endprogram
Related Config Files
console.cfg



ControlScript
program controlscript(item)
Parameters:
NameType
itemItem Ref
Return values
Return value ignored
Scheduler Type
Normal
Default Priority
1
When Is It Called?
Immediately after the item is created (includes boot-up).
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'ControlScript' property defines the location of the control script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script is called when the item is created and stays attached to the item. Usually control scripts do not exit until the item is destroyed (note, you must handle this yourself). They generally use a loop to process events or do some housecleaning after some sleeping, or wait_for_event.
Examples
use uo;
use os;
program my_example_controlscript(item)
    RegisterForSpeechEvents(item, 5);
    var who;
    while(item) //exit loop if item is destroyed
        ev := wait_for_event(120);
        if(ev)
            who := ev.source;
            PrintTextAbove(item, who.name + " said: " + ev.text);
        endif
    endwhile
endprogram
Related Objects
Item
Related Config Files
itemdesc.cfg
Related Script Types
AIScript



CreateScript
program createscript(item)
Parameters:
NameType
itemItem Ref
Return values
If 0, item is destroyed, else item is added to the world.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
While the item is being created (via uo.em create item functions, or by the core).
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'CreateScript' property defines the location of the create script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script is called when the item is created. Return 1 to allow the item to be created, 0 to destroy the item.
Examples
use uo;
program my_example_createscript(item)
    if(item.x >= 500 && item.x <= 600)
        print("Item created in illegal location");
        return 0;
    endif
    return 1;
endprogram
Related Objects
Item
Related Config Files
itemdesc.cfg
Related Script Types
DestroyScript



DestroyScript
program destroyscript(item)
Parameters:
NameType
itemItem Ref
Return values
If 1, item is allowed to be destroyed, else it is not destroyed.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
While the item is being destroyed (UO.EM::DestroyItem() or core decay).
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'DestroyScript' property defines the location of the create script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script is called while the item is being destroyed. Return 1 to allow the item to be destroy, 0 to not allow destruction.
Examples
use uo;
program my_example_destroyscript(item)
    var gm_flag := GetObjProperty(item,"GM_FLAG");
    if(gm_flag != error)
        return 0;
    else
        return 1;
    endif
endprogram
Related Objects
Item
Related Config Files
itemdesc.cfg



EnterScript
program enterscript(mobile, region_name)
Parameters:
NameType
mobileCharacter Ref
region_nameString
Return values
Return value ignored
Scheduler Type
Run To Completion
Default Priority
Critical
When Is It Called?
When a player enters the region.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts
To Define
In the regions's region.cfg or justice.cfg entry, the 'EnterScript' property defines the location of the script.
Explanation
This script is called when the player enters the region.
Examples
use uo;
program EnterRegionZone(mobile, region_name)
    ApplyRawDamage(mobile, 10000);
    SendSysMessage(mobile, "You just died because you entered an area that makes you dead!");
    return 1;
endprogram
Related Config Files
regions.cfg
justice.cfg
Related Script Types
LeaveScript



EquipScript
program equipscript(character, item, startup)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
itemItem Ref
startupInteger 0/1 if item is being equipped due to server start
Return values
1 if the item should be equipped, 0 to disallow equipping.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When the item is being equipped on character, either by client dragging or script function, after the equiptest.ecl check is passed.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'EquipScript' property defines the location of the equip script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control. Also, setting item.equipscript allows you to change the script.
Explanation
This script allows side effects to be triggered as a result of the item being equipped on a character.
Also can be used to disallow equipping, by the return value.
Doesn't make sense for items that cannot be equipped, like walls or doors and such.
Examples
use uo;
const FOR_CLASS := "warrior";
program my_example_equipscript(character, item, startup)
    var class := GetObjProperty(character, "class");
    if(class != FOR_CLASS)
        if(!startup)
            SendSysmessage(character,"Your class may not equip that item.");
        endif
        return 0;
    else
        return 1;
endprogram
Related Objects
Character
Item
Related Config Files
itemdesc.cfg
Related Script Types
UnEquipScript
equiptest.ecl
unequiptest.ecl



ExportedVitalsFunction
exported function vitalsfunc(character)
Parameters:
NameType
characterCharacter Ref
Return values
Integer return used by core, see below
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
Both exported functions on character create and when a script calls RecalcVitals()
Where Does It Live?
As exported functions in a .src, as defined in vitals.cfg.
To Define
Define vitals functions in vitals.cfg.
Explanation
There exists 2 exported functions for vitals calculation: RegenRateFunction and MaximumFunction.
Each vital defined should have both of these functions. RegenRateFunction should return the regeneration rate for that vital for that character (see vitals.cfg for format)
MaximumFunction should return the maximum vital value for the character in hundreths of a point
Examples
//In a .src file, like regen.src:
//vitals.cfg defines MaximumFunction regen:GetLifeMaximumValueExported , etc.
//Life vital funcs:
use uo;
exported function GetLifeMaximumValueExported(mob) 
	return (GetAttribute(mob, ATTRIBUTEID_STRENGTH) * 100);
endfunction
Related Objects
Character
Related Config Files
vitals.cfg



HitScript
program hitscript(attacker, defender, weapon, armor, basedamage, rawdamage )
Parameters:
NameType
attackerCharacter Ref of player attacking with weapon
defenderCharacter Ref
weaponWeapon Ref
armorArmor Ref, or 0 if no armor was hit.
basedamageInteger damage amount due to random weapon damage, strength, and tactics.
rawdamageInteger damage amount due basedamage, minus amount absorbed by armor.
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a weapon with a hit script defined successfully hits an opponent. (note not called automatically if Attack syshook is called)
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/items
To Define
In the weapon's itemdesc.cfg entry, the 'HitScript' property defines the location of the hit script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control. Also, setting weapon.hitscript allows you to change the script.
Explanation
This script allows the scripter to control damage dealt to a defender, equipment, and to trigger extra effects like poisoned weapons.
Only one core-called hitscript may be defined per weapon.
Examples
use uo;
use util;
program my_example_hitscript(attacker, defender, weapon, armor, basedamage, rawdamage)
    ApplyDamage(defender,rawdamage);
    if(RandomInt(20) == 2)
        armor.hp := armor.hp - 1;
    endif
endprogram
Related Objects
Character
Item
Weapon
Related Config Files
itemdesc.cfg
Related Script Types
OnHitScript



LeaveScript
program leavescript(mobile, region_name)
Parameters:
NameType
mobileCharacter Ref
region_nameString
Return values
Return value ignored
Scheduler Type
Run To Completion
Default Priority
Critical
When Is It Called?
When a player leaves the region.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts
To Define
In the regions's region.cfg or justice.cfg entry, the 'LeaveScript' property defines the location of the script.
Explanation
This script is called when the player leaves the region.
Examples
see EnterScript
Related Config Files
regions.cfg
justice.cfg
Related Script Types
EnterScript



MethodScript
exported function methodname(params,...)
Parameters:
NameType
itemItem Ref
Return values
core ignores return value, except for Install() see below
Scheduler Type
Install() Run To Completion, methods normal
Default Priority
Install() critical, methods 1
When Is It Called?
When a script calls the method for the item, i.e. item.methodname()
Where Does It Live?
In a .src file, and MUST BE in a package.
To Define
In the item's itemdesc.cfg entry, the 'MethodScript' property defines the location of the create script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package.
Explanation
Method Scripts allow new object methods to be defined, and can override built-in methods. For example, you may define a method door.wackymethod() or override door.open().
To enable the exported functions in the script, the 'program' in the file must return 1. This is the 'Install()' program that enables the exported methods.
The exported functions may take any number of parameters
To instead call the built-in methods for an object, preceed the name with an underscore '_'. So if you override door.close(), use door._close() to instead call the built-in version.
Examples
// This simple example shows how to override the door.open() method
pkg/.../door/itemdesc.cfg:
Door 0x0675
{
    xmod -1
    ymod +1
    script door
    doortype metal
    MethodScript cdoor.ecl  //note .ecl extension
}

pkg/.../door/cdoor.src:
exported function open( door )
    print( "cdoor::open(" + door.serial + ")" );
    return door._open();
endfunction

program install()
    print( "installing cdoor" );
    return 1;
endprogram
// This example shows how to define your own methods
//pkg/.../mypkg/itemdesc.cfg:
Item 0xE000
{
    //normal itemdesc.cfg entries, graphic, etc.
    Name widget
    MethodScript widget_methods.ecl
}

// pkg/.../mypkg/widget_methods.src:
program install()
    print("installing widget");
    return 1;
endprogram

exported function discombobulate(flag1, message) //pass by reference here is ok too!
    if(flag1 > 3)
        print(message);
        return 1;
    endif
    return 0;
endfunction

// So now, in another script, if 'widget' is a reference to 
// item 0xE000, call like this:
widget.discombobulate(4,"Meaningless message");
Related Objects
Item
Related Config Files
itemdesc.cfg



OnDeleteScript
program ondelete(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When a player character is deleted.
Where Does It Live?
The 'program' in ondelete.src file, in /scripts/misc or any package
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows the scripter to run code when a character is deleted.
Examples
use uo;
program ondelete( character )
	Broadcast(character.name + " was deleted.");
endprogram
Related Objects
Character
Related Script Types
oncreate.ecl



OnInsertScript
program oninsertscript(character, container, movetype, inserttype, adding_item, existing_stack, amount_to_add)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
containerContainer Ref
movetypeInteger
inserttypeInteger
adding_itemItem Ref
existing_stackItem Ref
amount_to_addInteger
Return values
return value ignored
Scheduler Type
Run-To-Completion
Default Priority
critical
When Is It Called?
After the item is moved into (or created in) a container, by user dragging, script function, or the core.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'OnInsertScript' property defines the location of the on-insert script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script allows side effects to be triggered as a result of the item insertion.
IMPORTANT: the first parameter (character) MAY be passed as an uninitialized object if the item was not moved by character (i.e. by a script function or the core), so please check it before you use it.
inserttype will be INSERT_ADD_ITEM if a new item is being inserted into the container (existing_stack and amt_to_add are uninit), or INSERT_INCREASE_STACK if an existing item's amount is merely being increased (and adding_item is uninit).
These are the times when onInsert scripts are called: Client drag/drop, vendor buy: when moving items to the player's backpack, vendor sell: when putting gold in the player's backpack, secure trade, when cancelling or confirming a trade, MoveItemToContainer, CreateItemInContainer, CreateItemInInventory, CreateItemInBackpack.
Examples
use uo;
program my_example_oninsertscript(character, container, movetype, inserttype, adding_item, 
                                  existing_stack, amount_to_add)
    if(inserttype == INSERT_INCREASE_STACK )
      SendSysmessage(character,"You insert " + amount_to_add + " more " 
                   + existing_stack.desc + " into the container.");
    else
      SendSysmessage(character,"You insert a " + adding_item.desc + " into the container.");
    endif
    PlaySoundEffectPrivate(character, SFX_INSERT, character);
endprogram
UO.EM constants used with the 'movetype' parameter:    
const MOVETYPE_PLAYER     := 0; // physically moved (dragged) by a player
const MOVETYPE_COREMOVE   := 1; // moved by the core (eg, MoveItemToContainer().)
Insert scripts only:
const MOVETYPE_CORECREATE := 2; // created by core (eg, CreateItemInBackpack().)
UO.em constants used with the 'inserttype' parameter:
const INSERT_ADD_ITEM        := 1;
const INSERT_INCREASE_STACK  := 2;
Related Objects
Character
Container
Item
Related Config Files
itemdesc.cfg
Related Script Types
CanInsertScript
CanRemoveScript
OnRemoveScript



OnRemoveScript
program onremovescript(character, container, item, item_amount, movetype)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
containerContainer Ref
itemItem Ref
item_amountInteger
movetypeInteger
Return values
return value ignored
Scheduler Type
Run-To-Completion
Default Priority
critical
When Is It Called?
After the item is out of a container, by user dragging, script function, or the core.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'OnRemoveScript' property defines the location of the on-remove script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control.
Explanation
This script allows side effects to be triggered as a result of the item removal.
IMPORTANT: the first parameter (character) MAY be passed as an uninitialized object if the item was not moved by character (i.e. by a script function or the core), so please check it before you use it.
Examples
use uo;
program my_example_onremovescript(character, container, item, item_amount)
    SendSysmessage(character,"You removed " + item_amount + " " 
                   + item.desc + " from the container.");
    PlaySoundEffectPrivate(character, SFX_REMOVE, character);
endprogram
UO.EM constants used with the 'movetype' parameter:    
const MOVETYPE_PLAYER     := 0; // physically moved (dragged) by a player
const MOVETYPE_COREMOVE   := 1; // moved by the core (eg, MoveItemToLocation().)
Related Objects
Character
Container
Item
Related Config Files
itemdesc.cfg
Related Script Types
CanInsertScript
OnInsertScript
CanRemoveScript



SkillScript
program skillscript(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a uses a "direct" skill like Hiding, Cartography, etc. (a blue 'crystal' appears next to the skill name on the default skill scroll gump) Also called with the client macros UseSkill, LastSkill, etc.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/skills
To Define
Define a "Script" property in the skills.cfg entry for the appropriate skill number.
Explanation
This script type handles the directly-usable skills in UO. It is not used for skills used via an item (like blacksmithy).
The script is 'attached' to the character, and he/she cannot use another skill or use an item until this skill script exits or calls Detach().
The skills.cfg entry defines the time delay for starting subsequent skill scripts
Examples
//example hide skill script   
use uo;
program hideskill( character )
	if(character.cmdlevel > 0)
	    character.hidden := 1;
	else
	    //obviously some skill checks go here, etc.
	endif
endprogram
Related Objects
Character
Related Config Files
skills.cfg



SpellScript
program spellscript(character, spell_id)
Parameters:
NameType
characterCaster Character ref
spell_idInteger
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a player casts a spell from the normal UO spellbook.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/spells
To Define
Define a "Script" property in the spells.cfg entry for the appropriate spell number.
Explanation
This script type handles the 'cast spell #' action in UO, via a spellbook or client macro. spell_id is taken from 'SPELLID' entry in '::spells.cfg'.
Examples
//example Lightning spell (#30), too simple to use directly!
use uo;
program lightning( character, spell_id )
	var tgt := Target(character, TGTOPT_HARMFUL);
	if(tgt)
	    if(tgt.isa(POLCLASS_MOBILE))
	        PlayLightningBoltEffect(tgt);
	        //some damage
	    endif
	endif
endprogram
Related Objects
Character
Related Config Files
spells.cfg



SyshookScript
exported function syshookname(params vary, see below)
Return values
return value usage varies, see below
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
At various times, depending on the syshook, see below.
Where Does It Live?
As exported functions in a .src, as defined in syshook.cfg or uopacket.cfg.
To Define
Define a system hook script in a syshook.cfg or a packet hook script in a uopacket.cfg.
Explanation
The valid system hook names are: CheckSkill, OpenSpellbook, GetBookPage, CombatAdvancement, ParryAdvancement, Attack, Pushthrough, SpeechMul. You can use any name in packet hook script (ReceiveFunction/SendFunction - you can find examples in packethooks.txt).
Note: You must define a "program" named scriptname in the file scriptname. This program should perform any substantive initialization for supporting the individual hooks in the file. Return 1 to install the hooks, or 0 to disable. This will be run only once on startup.
CheckSkill: params: CharRef character, Int skillid, Int difficulty, Int pointvalue. When called: UO.EM::CheckSkill() is called. Return: true/false for skill use success.
OpenSpellbook: params: CharRef character. When called: A Character uses a spellbook object. Used to override normal spellbook behavior.
GetBookPage: not implimented
CombatAdvancement: params: CharRef character, WeaponRef weapon, CharRef opponent. When called: Whenever a character attacks another, before hit is determined. Used to override normal combat skill advancement.
ParryAdvancement: params: CharRef character, WeaponRef weapon, CharRef opponent, ItemRef opponent_shield. When called: A Character attacks another whom wields a shield, before parry success is determined. Used to override 'parry' skill advancement.
Attack: params: CharRef character, CharRef opponent. When called: A Character attacks another. IMPORTANT: completely overrides core handling of combat, including the above advancement hooks. You must handle all of combat yourself in a script if you use this hook (determining hits, applying damage, destroying ammo, skill advancement, etc). Since it is called every attack, this is a very CPU expensive hook to impliment.
Pushthrough: params: CharRef character, Array of CharRefs in destination tile. When called: on EVERY move of EVERY character. Return: true if walk ok, false to block walk. Used to override core behavior for walking through tiles with other mobiles on them. Since this critical script is called so often, it is a very CPU expensive one to impliment.
SpeechMul: params: CharRef character, Array of speechtokens. When called: When someone says a speech.mul keyword (one or more).
ReceiveFunction: params: CharRef character, Packet byref packet. When called: When the server receives a packet by client. Return: 0 if you wish POL to perform its normal data processing on the packet (if any default packet handler exists for this packet ID), or 1 if you wish POL to do no processing on the packet (i.e. your script handled it fully).
SendFunction: params: CharRef character, Packet byref packet. When called: When the server will send a packet to the client. Return: 0 if you wish POL to perform its normal data processing on the packet (if any default packet handler exists for this packet ID), or 1 if you wish POL to do no processing on the packet (i.e. your script handled it fully). You MUST NOT use the SendPacket or SendAreaPacket methods on the passed-in packet with SendFunction. Rather, edit the packet as you wish, and return 0. POL will send the packet as normal. You may create and send a different packet (NOT the same Packet ID, else the send functions will loop) from within this function, but note the sending order will be created packet, then hooked packet (if you return 0).
Examples
//Pushthrough hook example    
//syshook.cfg defines: 
SystemHookScript pushhook.ecl
{
	Pushthrough Pushthrough
}
//in pushhook.src:
use uo;
program PushthroughHook()
	return 1;
endprogram

exported function Pushthrough(walker, obstructors)
	//print(walker.name);
	//foreach mob in obstructors   //note, obstructors is an array of char refs
	//	print(mob.name);
	//endforeach
	
	if(GetVital(walker,"Stamina") < GetVitalMaximumValue(walker,"Stamina"))
		return 0;
	else
		return ConsumeVital(walker,"Stamina",1000);
	endif
endfunction
Related Config Files
syshook.cfg
uopacket.cfg



TextCommandScript
program textcommand(character, text, uc_text, langcode)
Parameters:
NameType
characterCharacter ref activating this script
textString after command name
uc_texta Unicode array of the text string typed after the command (exist if client used unicode speech)
langcode3-character string, representing the client's language code, i.e. 'ENU', 'DEU', 'RUS', etc.(exist if client used unicode speech)
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a player character 'speaks' a command string, i.e. '.online'
Where Does It Live?
The 'program' in a .src file, in a command level subdir of a package or /scripts/textcmd
To Define
Place the script in a command level subdir or /scripts/textcmd, or a package after defining the command level path in cmds.cfg.
Explanation
This script allows a player to activate a script, according to their command level. I.e. 'admin' level can activate admin and below (gm, seer, etc), but a GM could not activate 'admin' commands.
Lots of things can be done with this script type, including creating objects, destroying them, showing gump menus, teleporting, or anything that the core functions allow!
'text' is all the text after the command name. I.e. '.createstack 0xEED 100' would make 'text' be '0xEED 100'. This is a great place to use SplitWords (note result is still a string, so use Cint() if expecting integers).
Only one text command script may be active on a player at a time.
Unicode array: array of integers representing unicode characters
Examples
// a teleport script. Should be entered with x y z numbers after the name.    
use uo;
program textcmd( character, text )
    var arr := SplitWords( text );
    MoveCharacterToLocation( character,Cint(arr[1]),Cint(arr[2]),Cint(arr[3]) );
endprogram
Related Objects
Character
Related Config Files
cmds.cfg



UnEquipScript
program unequipscript(character, item)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
itemItem Ref
Return values
1 if the item should be unequipped, 0 to disallow unequipping.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When the item is being unequipped by character, either by client dragging or script function, after the unequiptest.ecl check is passed.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/control
To Define
In the item's itemdesc.cfg entry, the 'UnEquipScript' property defines the location of the unequip script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/control. Also, setting item.unequipscript allows you to change the script.
Explanation
This script allows side effects to be triggered as a result of the item being unequipped by a character.
Also can be used to disallow unequipping, by the return value.
Doesn't make sense for items that cannot be equipped, like walls or doors and such.
Examples
use uo;
program my_example_equipscript(character, item, startup)
    var cursed := GetObjProperty(item, "cursed");
    if(cursed == 1)
        SendSysmessage(character,"That item is cursed! Gwuahahahaha!!");
        return 0;
    else
        return 1;
endprogram
Related Objects
Character
Item
Related Config Files
itemdesc.cfg
Related Script Types
UnEquipScript
equiptest.ecl
unequiptest.ecl



UseScript
program usescript(character, item)
Parameters:
NameType
characterCharacter Ref
itemItem Ref
Return values
Return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a client double clicks on an item with a defined use script.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/items
To Define
In the item's itemdesc.cfg entry, the 'Script' property defines the location of the double-click script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/items. Also item.usescript is writable in the same format.
Explanation
This interactive script is called when a client double clicks on an item. This script is then attached to the character (meaning, no other script may be attached to the character until this script exits or calls Detach()). If the itemdesc.cfg entry also defines 'RequiresAttention 1' then using that item will cause the player to unhide.
By default the player needs to have line-of-sight to the item. Use the 'UseRequiresLOS' property in the itemdesc.cfg entry to change this per-item template.
By default ghosts may not use items. Use the 'GhostsCanUse' property in the itemdesc.cfg entry to change this per-item template.
The default maximum distance away from the item to use it is 2 or the defined 'DefaultDoubleclickRange' in servspecopt.cfg. To override this, use the 'DoubleclickRange' property in the itemdesc.cfg entry to change this per-item template.
Can be used to override the default double-click behaviors of Containers, Maps, etc.
Doesn't work with Multis.
Examples
use uo;
use util;
program my_example_usescript(character, item)
    PrintTextAbove(item, character.name + " used me!");
    item.color := RandomInt(50);
endprogram
Related Objects
Character
Item
Related Config Files
itemdesc.cfg
servspecopt.cfg



WalkOnScript
program walkonscript(character, item, lastx, lasty, lastz)
Parameters:
NameType
characterCharacter Ref
itemItem Ref
lastxCharacter's previous integer world coordinate
lastyCharacter's previous integer world coordinate
lastzCharacter's previous integer world coordinate
Return values
Return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a character moves onto this item.
Where Does It Live?
The 'program' in a .src file, in a package or /scripts/items
To Define
In the item's itemdesc.cfg entry, the 'WalkOnScript' property defines the location of the walk-on script. This is in package format ':pkgname:scriptname', or if just 'scriptname' in the same package, or /scripts/items.
Explanation
This interactive script is called when a client moves on an item (walk or teleports). This script is NOT attached to the character.
Doesn't work with Multis.
Examples
use uo;
use util;
program my_example_walkonscript(character, item, lastx, lasty, lastz)
    PrintTextAbove(item, "Ouch! " + character.name + ", don't step on me!");
    MoveItemToLocation( item, lastx, lasty, lastz );
endprogram
Related Objects
Character
Item
Related Config Files
itemdesc.cfg



boat.ecl
program boatcontrol(boat)
Parameters:
NameType
boatBoat Ref
Return values
Return value ignored
Scheduler Type
Normal
Default Priority
1
When Is It Called?
Immediately after the item is created (includes boot-up).
Where Does It Live?
The 'program' in the boat.src file, only in /scripts/misc
To Define
Always called when a boat is created/started.
Explanation
This script acts as a control script for a boat. Use it for navigation commands (e.g. the tillerman control script), boat decay, etc.
Examples
use uo;
use os;
program my_example_boatscript(boat)
    RegisterForSpeechEvents(boat.tillerman, 5);
    var who;
    while(boat) //exit loop if boat is destroyed
        ev := wait_for_event(120);
        if(ev)
            who := ev.source;
            PrintTextAbove(boat.tillerman, who.name + " is a scurvy dog for saying: " + ev.text);
        endif
    endwhile
endprogram
Related Objects
Boat
Related Script Types
ControlScript



chrdeath.ecl
program chrdeath(corpse, ghost)
Parameters:
NameType
corpsePlayer corpse ref
ghostCharacter Ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
1
When Is It Called?
When an Player Character is killed.
Where Does It Live?
The 'program' in the chrdeath.src file, only in /scripts/misc (only one should exist in the system)
To Define
This script is called for all Players.
Explanation
This script allows side effects to be triggered as a result of Player death, like unmounting players off their mount, allowing ghosts to report their murderer, Auto-Resurrect choices, etc.
Examples
use uo;
program my_example_chrdeath(corpse,ghost)
    Broadcast(ghost.name + "'s death cry is heard throughout the realm!");
    //useful stuff here...
endprogram
Related Objects
Corpse
Character
Related Script Types
death.ecl



dblclickother.ecl
program dblclickother(character, mobile_clicked)
Parameters:
NameType
characterCharacter ref
mobile_clickedCharacter ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a player double clicks another player or npc. Will not run if the npc has the double click event enabled.
Where Does It Live?
The 'program' in dblclickother.src file, only in /scripts/misc
To Define
If the compiled file exists it is automatically called on doubleclick.
Explanation
This script allows an alternate behavior other than the default 'open paperdoll' behavior.
Examples
Related Objects
Character



dblclickself.ecl
program dblclickself(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a player character double clicks on himself or herself. Not called with the "open paperdoll" client macro.
Where Does It Live?
The 'program' in dblclickself.src file, only in /scripts/misc
To Define
If the compiled file exists it is automatically called on doubleclick.
Explanation
This script allows an alternate behavior other than the default 'open paperdoll' behavior. Useful for things like dismounting.
Examples
use uo;
include "include/client";
program dblclickself( me )
	var mount := GetEquipmentByLayer( me, LAYER_MOUNT );
	if (!mount)
		OpenPaperdoll( me, me );
		return;
	endif
endprogram
Related Objects
Character



death.ecl
program death(corpse)
Parameters:
NameType
corpseNPC corpse ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
1
When Is It Called?
When an NPC is killed.
Where Does It Live?
The 'program' in the death.src file, only in /scripts/misc (only one should exist in the system)
To Define
This script is called for all NPCs.
Explanation
This script allows side effects to be triggered as a result of NPC death, like unmounting players off their dying mount, playing death sounds, etc.
This script is common for all NPCs, and is called for each.
Examples
use uo;
program my_example_death(corpse)
    PrintTextAbove(corpse,"ARRRRGH");
    PlaySoundEffect(SFX_VICTORY); //fake constant
endprogram
Related Objects
Corpse
NPC
Related Config Files
npcdesc.cfg
Related Script Types
chrdeath.ecl



equiptest.ecl
program equiptest(character, item, startup)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
itemItem Ref
startupInteger 0/1 if item is being equiped on startup
Return values
1 if the item can be equipped, 0 to disallow equipping.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When the item is being equipped by character, either by client dragging or script function.
Where Does It Live?
The 'program' in the equiptest.src file, in a package or /scripts/misc (only one should exist in the system)
To Define
Explanation
This script allows side effects to be triggered as a result of the item being equipped by a character.
This script is common for all items, and is called for each. useful for equip checks that are the same for all items, so the code does not need to be replicated in all EquipScripts.
Examples
use uo;
program my_example_equiptest(character, item, startup)
    var firstletter := lower(character.name[1]);
    if(firstletter == "t")
        SendSysmessage(character,"Sorry, character name starting with 
                       't' can't equip any items, for some reason.");
        return 0;
    else
        return 1;
endprogram
Related Objects
Character
Item
Related Config Files
itemdesc.cfg
Related Script Types
EquipScript
UnEquipScript
unequiptest.ecl



help.ecl
program help(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a player presses the "Help" button on the paperdoll.
Where Does It Live?
The 'program' in help.src file, only in /scripts/misc
To Define
Automatically called if file exists.
Explanation
This script type handles help button on the paperdoll. Useful for implimenting a help gump or staff paging system.
Examples
use uo;
program help( character )
    SendSysmessage(character,"You're helpless.");
endprogram
Related Objects
Character



logoff.ecl
program logoff(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
After the linger time expires after a client logs off.
Where Does It Live?
The 'program' in logoff.src file, in /scripts/misc or any package
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows the scripter to run cleanup code after a character exits the world. Useful for stuff like cleaning up summoned NPCs, etc.
Examples
use uo;
program logoff( character )
	Broadcast(character.name + " exited the world." );
endprogram
Related Objects
Character
Related Script Types
logon.ecl
reconnect.ecl
logofftest.ecl



logofftest.ecl
program logofftest(character)
Parameters:
NameType
characterCharacter ref
Return values
Integer value returned is number of seconds to have the character 'linger' in the world.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When a client logs out.
Where Does It Live?
The 'program' in logofftest.src file, only in /scripts/misc
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows the scripter to control how long the character lingers in the world after logoff.
Examples
use uo;
program logofftest( character )
	if(character.cmdlevel > 0)
	    return 0;
	else
	    return 300;
	endif
endprogram
Related Objects
Character
Related Script Types
logon.ecl
reconnect.ecl
logoff.ecl



logon.ecl
program logon(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When a client logs into the game server.
Where Does It Live?
The 'program' in logon.src file, in /scripts/misc or any package
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows code to run when the player logs in. Can be used for welcome messages, etc.
This script runs critical, so be careful how much code you run!
Examples
use uo;
program logon( character )
	SendSysmessage(character, "Welcome to POL.");
	Broadcast( character.name + " has entered the world.");
endprogram
Related Objects
Character
Related Script Types
reconnect.ecl
logofftest.ecl
logoff.ecl



oncreate.ecl
program oncreate(character, skillids)
Parameters:
NameType
characterCharacter ref
skillidsArray of the 3 integer skill IDs chosen.
Return values
return value ignored
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When a new player character is created.
Where Does It Live?
The 'program' in oncreate.src file, only in /scripts/misc
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows the scripter to run code when a new character is created. Useful for giving out starting equipment, etc.
Examples
use uo;
include "include/startEqp";
program oncreate( character )
	CreateStartingEquipment(character, skillids);
endprogram
Related Objects
Character
Related Script Types
OnDeleteScript



reconnect.ecl
program reconnect(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When a client re-logs into the game server before his/her character is removed from the world (5 minutes default).
Where Does It Live?
The 'program' in reconnect.src file, in /scripts/misc or any package
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows code to run when the player logs in after having recently logged off.
Examples
use uo;
program reconnect( character )
	Broadcast( character.name + " has reconnected.");
endprogram
Related Objects
Character
Related Script Types
logon.ecl
logofftest.ecl
logoff.ecl



skillwin.ecl
program skillwin(character)
Parameters:
NameType
characterCharacter ref
Return values
return value ignored
Scheduler Type
Normal
Default Priority
100
When Is It Called?
When a player character requests the skills scroll gump to be displayed.
Where Does It Live?
The 'program' in skillwin.src file, only in /scripts/misc
To Define
If the compiled file exists it is automatically called.
Explanation
This script allows an alternate behavior other than the default skills window behavior. Useful for implimenting your own skills gump for your custom shard.
Examples
use uo;
program skillwin( character )
	if(character.cmdlevel > 0)
	    SendSkillWindow( character, character );
	else
	    SendMySkillGump( character );
	endif
endprogram
Related Objects
Character



start.ecl
no prototype, exists as inline code at global scope
Return values
return value ignored
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
Once, during server start.
Where Does It Live?
As inline code outside any function scope in start.src file, in any package and in /scripts
To Define
If the compiled file exists in /scripts or an enabled package it is automatically called.
Explanation
This script allows the scripter to run code when the server starts, for housekeeping or starting background scripts like NPC spawners.
Examples
use uo;
print("my package starting..");
//etc, your startup code! I'm so bad at examples.



unequiptest.ecl
program unequiptest(character, item, startup)
Parameters:
NameType
characterCharacter Ref, or uninitialized, see below
itemItem Ref
startupalways false
Return values
1 if the item can be unequipped, 0 to disallow unequipping.
Scheduler Type
Run To Completion
Default Priority
critical
When Is It Called?
When the item is being unequipped by character, either by client dragging or script function.
Where Does It Live?
The 'program' in the unequiptest.src file, in a package or /scripts/misc (only one should exist in the system)
To Define
Explanation
This script allows side effects to be triggered as a result of the item being unequipped by a character.
This script is common for all items, and is called for each. useful for unequip checks that are the same for all items, so the code does not need to be replicated in all UnEquipScripts.
Examples
use uo;
program my_example_unequiptest(character, item, startup)
    var cursed := GetObjProperty(item, "cursed");
    if(cursed == 1)
        SendSysmessage(character,"That item is cursed! Gwuahahahaha!!");
        return 0;
    else
        return 1;
endprogram
Related Objects
Character
Item
Related Config Files
itemdesc.cfg
Related Script Types
EquipScript
UnEquipScript
equiptest.ecl




If you know if any information is incorrect on these pages, mail your corrections to shinigami@gmx.net

Copyright ©2003-2011 David Carpman and Shinigami, all rights reserved. DO NOT REPRODUCE, MIRROR, ALTER, SPINDLE, MUTILATE, OR SIT ON.