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/19/2003

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:
Name | Type
attacker | Character Ref of player attacking with weapon
defender | Character Ref
weapon | Weapon Ref
armor | Armor Ref, or 0 if no armor was hit.
basedamage | Integer damage amount due to random weapon damage, strength, and tactics.
rawdamage | Integer 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:
Name | Type
connection | Aux 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

boat.ecl
program boatcontrol(boat)
Parameters:
Name | Type
boat | Boat 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

CanInsertScript
program caninsertscript(character, container, movetype, inserttype, adding_item, existing_stack, amount_to_add)
Parameters:
Name | Type
character | Character Ref, or uninitialized, see below
container | Container Ref
movetype | integer
inserttype | integer
adding_item | Item Ref
existing_stack | Item Ref
amt_to_add | integer
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;
    program my_example_caninsertscript(character, container, item)
        if(character != error)
            if(character.weight > 400)
                return 0;
            else
                return 1;
            endif
        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, 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:
Name | Type
character | Character Ref, or uninitialized, see below
container | Container Ref
item | Item Ref
movetype | Integer
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

chrdeath.ecl
program chrdeath(corpse, ghost)
Parameters:
Name | Type
corpse | Player corpse ref
ghost | Character 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

ConsoleScript
program consolescript(cmd)
Parameters:
Name | Type
cmd | command 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:
Name | Type
item | Item 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:
Name | Type
item | Item 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

dblclickself.ecl
program dblclickself(character)
Parameters:
Name | Type
character | Character 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:
Name | Type
corpse | NPC 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

DestroyScript
program destroyscript(item)
Parameters:
Name | Type
item | Item 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

EquipScript
program equipscript(character, item, startup)
Parameters:
Name | Type
character | Character Ref, or uninitialized, see below
item | Item Ref
startup | Integer 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.unequipscript 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

equiptest.ecl
program equiptest(character, item, startup)
Parameters:
Name | Type
character | Character Ref, or uninitialized, see below
item | Item Ref
startup | Integer 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

ExportedVitalsFunction
exported function vitalsfunc(character)
Parameters:
Name | Type
character | Character 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

help.ecl
program help(character)
Parameters:
Name | Type
character | Character 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

HitScript
program hitscript(attacker, defender, weapon, armor, basedamage, rawdamage )
Parameters:
Name | Type
attacker | Character Ref of player attacking with weapon
defender | Character Ref
weapon | Weapon Ref
armor | Armor Ref, or 0 if no armor was hit.
basedamage | Integer damage amount due to random weapon damage, strength, and tactics.
rawdamage | Integer 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

logoff.ecl
program logoff(character)
Parameters:
Name | Type
character | Character 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:
Name | Type
character | Character 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:
Name | Type
character | Character 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

MethodScript
exported function methodname(params,...)
Parameters:
Name | Type
item | Item 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

oncreate.ecl
program oncreate(character, skillids)
Parameters:
Name | Type
character | Character ref
skillids | Array 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
ondelete.ecl

ondelete.ecl
program ondelete(character)
Parameters:
Name | Type
character | Character 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:
Name | Type
character | Character Ref, or uninitialized, see below
container | Container Ref
movetype | Integer
inserttype | Integer
adding_item | Item Ref
existing_stack | Item Ref
amount_to_add | Integer
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, item, item_amount)
        SendSysmessage(character,"You insert " + item_amount + " "
                       + item.desc + " into the container.");
        PlaySoundEffectPrivate(character, SFX_BLAH, 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:
Name | Type
character | Character Ref, or uninitialized, see below
container | Container Ref
item | Item Ref
item_amount | Integer
movetype | Integer
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

reconnect.ecl
program reconnect(character)
Parameters:
Name | Type
character | Character 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

SkillScript
program skillscript(character)
Parameters:
Name | Type
character | Character 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

skillwin.ecl
program skillwin(character)
Parameters:
Name | Type
character | Character 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

SpellScript
program spellscript(character)
Parameters:
Name | Type
character | Caster Character ref
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.
Examples
    //example Lightning spell (#30), too simple to use directly!
    use uo;
    program lightning( character )
    	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

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.

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.
To Define
Define a system hook script in a syshook.cfg.
Explanation
The valid system hook names are: CheckSkill, OpenSpellbook, GetBookPage, CombatAdvancement, ParryAdvancement, Attack, Pushthrough
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.
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

TextCommandScript
program textcommand(character, text, uc_text, langcode)
Parameters:
Name | Type
character | Character ref activating this script
text | String after command name
uc_text | a Unicode array of the text string typed after the command (exist if client used unicode speech)
langcode | 3-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:
Name | Type
character | Character Ref, or uninitialized, see below
item | Item 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

unequiptest.ecl
program unequiptest(character, item, startup)
Parameters:
Name | Type
character | Character Ref, or uninitialized, see below
item | Item Ref
startup | always 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

UseScript
program usescript(character, item)
Parameters:
Name | Type
character | Character Ref
item | Item 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:
Name | Type
character | Character Ref
item | Item Ref
lastx | Character's previous integer world coordinate
lasty | Character's previous integer world coordinate
lastz | Character'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

If you know if any information is incorrect on these pages, mail your corrections to racalac@burdell.org

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