- AIScript
- AttackHitScript
- AuxServiceScript
- BoatScript
- CanDeleteScript
- CanInsertScript
- CanRemoveScript
- CharProfileScript
- ChatButtonScript
- ChrDeathScript
- ConsoleScript
- ControlScript
- CreateScript
- CustomHouseCommitScript
- DblClickItemScript
- DblClickOtherScript
- DblClickSelfScript
- DeathScript
- DestroyScript
- EnterScript
- EquipScript
- EquipTestScript
- ExportedVitalsFunction
- GuildButtonScript
- HelpScript
- HitScript
- LeaveScript
- LogoffScript
- LogoffTestScript
- LogonScript
- MethodScript
- OnCreateScript
- OnDeleteScript
- OnInsertScript
- OnRemoveScript
- PopUpMenuScript
- QuestButtonScript
- ReconnectScript
- SkillScript
- SkillWinScript
- SpellScript
- StartScript
- SyshookScript
- TextCommandScript
- UnEquipScript
- UnEquipTestScript
- UseScript
- VirtueButtonScript
- WalkOnScript
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 | |
program MainHitScript(attacker, defender, weapon, armor, basedamage, rawdamage) // // Cheat checker // if ( attacker == defender ) ApplyRawDamage(attacker, 1000); elseif ( attacker.hidden || defender.hidden ) return 0; elseif ( !attacker.npctemplate ) if ( !attacker.warmode ) basedamage := CInt(basedamage/2); rawdamage := CInt(rawdamage/2); endif endif endprogram | |
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 |
BoatScript | |
---|---|
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 |
CanDeleteScript | |
---|---|
program candelete( character, deleteby ) | |
Parameters: | |
Name | Type |
character | Character Ref |
deleteby | Integer |
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: | |
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; 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: | |
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 |
CharProfileScript | |
---|---|
program CharProfile(character, of_who, mode, uctext) | |
Parameters: | |
Name | Type |
character | Character ref |
of_who | Character ref |
mode | Integer |
uctext | Unicode character array |
Return values | |
return value ignored | |
Scheduler Type | |
Normal | |
Default Priority | |
100 | |
When Is It Called? | |
On Profile opening and update request | |
Where Does It Live? | |
The 'program' in charprofile.src file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
if mode==0 (request) uctext is 0 | |
Examples | |
use uo; program CharProfile(character, of_who, mode, uctext) if (mode == 0) print("Request"); SendCharProfile(character, of_who, "Core test Title", CAscZ("Core test"), of_who.getprop("Profile")); else print("Update"); of_who.setprop("Profile",uctext); endif endprogram | |
Related Objects | |
Character |
ChatButtonScript | |
---|---|
program ChatButton(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 "Chat" button. | |
Where Does It Live? | |
The 'program' in questbutton.src file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
This script type handles chat button. No chatsystem only catches the pressing. | |
Examples | |
use uo; program ChatButton( character ) SendSysmessage(character,"You clicked the Chatbutton."); endprogram | |
Related Objects | |
Character |
ChrDeathScript | |
---|---|
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 |
CustomHouseCommitScript | |
---|---|
program custom_house_commit( who, house, elements ) | |
Parameters: | |
Name | Type |
who | Character ref, who is committing the house design |
house | House ref, the house being committed |
elements | Array of struct{graphic,xoffset,yoffset,z}, the custom house elements (excluding doors and teleporters) |
Return values | |
return value ignored | |
Scheduler Type | |
Normal | |
Default Priority | |
1 | |
When Is It Called? | |
After client presses the commit button. | |
Where Does It Live? | |
The 'program' in customhousecommit.ecl file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
To accept the changes call new method house.acceptcommit(chr,1) or house.acceptcommit(chr,0) to drop them. Unless you drop changes explicitly, the changes will be implicitly accepted. | |
Main purpose should be calculation of cost (with delta support for later changes), link establishing of houseteleporters (0x181D - 0x1828) and adding a signhanger/sign if you didnt added it during multifoundation buildup. | |
Doors and Teleporters are added to house components as normal items before this script is called, without any special treatment so dont forget to add scripts/itemdesc entries | |
The core does not perform any validity checks on the elements, it's up to the script ensure that all house elements and components are valid graphics/objtypes. | |
Examples | |
Related Objects | |
Character | |
House | |
Array | |
Struct |
DblClickItemScript | |
---|---|
program dblclickitem(character, item_clicked) | |
Parameters: | |
Name | Type |
character | Character ref |
item_clicked | Item ref |
Return values | |
return value ignored | |
Scheduler Type | |
Normal | |
Default Priority | |
100 | |
When Is It Called? | |
When a player double clicks a item. | |
Where Does It Live? | |
The 'program' in dblclickitem.src file, only in /scripts/misc | |
To Define | |
If the compiled file exists it is automatically called on doubleclick. | |
Explanation | |
Examples | |
Related Objects | |
Character |
DblClickOtherScript | |
---|---|
program dblclickother(character, mobile_clicked) | |
Parameters: | |
Name | Type |
character | Character ref |
mobile_clicked | Character 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 | |
use uo; use os; use npc; program core_dblClickSelf(who, clicked) if ( HasPDGraphic(clicked) ) return OPenPaperDoll(who, clicked); endif return 0; endprogram function HasPDGraphic(clicked) case ( clicked.graphic ) 400: return 1; break; // Male 401: return 1; break; // Female 402: return 1; break; // Male ghost 403: return 1; break; // Female ghost 987: return 1; break; // GM robe endcase return 0; endfunction | |
Related Objects | |
Character |
DblClickSelfScript | |
---|---|
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 |
DeathScript | |
---|---|
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 | |
ChrDeathScript |
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 destroy 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: | |
Name | Type |
mobile | Character Ref |
region_name | String |
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: | |
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.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 | |
EquipTestScript | |
UnEquipTestScript |
EquipTestScript | |
---|---|
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 | |
UnEquipTestScript |
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 |
GuildButtonScript | |
---|---|
program GuildButton(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 "Guild" button on the paperdoll. | |
Where Does It Live? | |
The 'program' in guildbutton.src file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
This script type handles guild button on the paperdoll. Useful for implimenting a guild gump. | |
Examples | |
use uo; program GuildButton( character ) SendSysmessage(character,"You clicked the Guildbutton."); endprogram | |
Related Objects | |
Character |
HelpScript | |
---|---|
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 |
LeaveScript | |
---|---|
program leavescript(mobile, region_name) | |
Parameters: | |
Name | Type |
mobile | Character Ref |
region_name | String |
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 |
LogoffScript | |
---|---|
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 | |
LogonScript | |
LogoffTestScript | |
ReconnectScript |
LogoffTestScript | |
---|---|
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 | |
LogonScript | |
LogoffScript | |
ReconnectScript |
LogonScript | |
---|---|
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 | |
ReconnectScript | |
LogoffScript | |
LogoffTestScript |
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 |
OnCreateScript | |
---|---|
program oncreate(character, skillids, profession) | |
Parameters: | |
Name | Type |
character | Character ref |
skillids | Array of the 3 integer skill IDs chosen. |
profession | Integer |
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, skillids, profession ) CreateStartingEquipment(character, skillids); endprogram | |
Related Objects | |
Character | |
Related Script Types | |
OnDeleteScript |
OnDeleteScript | |
---|---|
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 | |
OnCreateScript |
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, 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: | |
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 |
PopUpMenuScript | |
---|---|
program PopUpMenu(who, what) | |
Parameters: | |
Name | Type |
who | Character ref, who requested the pop-up menu |
what | Object, reference to the item or mobile clicked |
Return values | |
return value ignored | |
Scheduler Type | |
Normal | |
Default Priority | |
1 | |
When Is It Called? | |
When a player single clicks an item, another player or an npc and UOFeatureEnable 0x08 is set. | |
Where Does It Live? | |
The 'program' in popupmenu.ecl file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
Use this script to send the pop-up menu with SendPopUpMenu(). | |
Examples | |
use uo; program popupmenu(who, what) print(who.name + " requested popup of " + CStr(what)); var menu := array{}; menu[10] := 3000484; menu[20] := struct{ cliloc := 3000487 }; menu[30] := struct{ cliloc := 3000488, disabled := 1 }; menu[40] := struct{ cliloc := 3000501, color := 0x1f }; var ret := SendPopUpMenu( who, what, menu ); print("Menu response:" + CStr(ret)); endprogram | |
Related Objects | |
Character |
QuestButtonScript | |
---|---|
program QuestButton(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 "Quest" button on the paperdoll. | |
Where Does It Live? | |
The 'program' in questbutton.src file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
This script type handles quest button on the paperdoll. Useful for implimenting a quest gump. | |
Examples | |
use uo; program QuestButton( character ) SendSysmessage(character,"You clicked the Questbutton."); endprogram | |
Related Objects | |
Character |
ReconnectScript | |
---|---|
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 | |
LogonScript | |
LogoffScript | |
LogoffTestScript |
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 attributes.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 attributes.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 | |
attributes.cfg |
SkillWinScript | |
---|---|
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, spell_id) | |
Parameters: | |
Name | Type |
character | Caster Character ref |
spell_id | Integer |
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 |
StartScript | |
---|---|
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 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, HitMiss, OnCast, CanDecay, Ouch, CanDie, UnHide, CloseCustomHouse, WarmodeChange, CanTrade | |
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 for every attack, this is a very CPU expensive hook to implement. | |
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 the default core behavior of blocking the movement if a tile is already occupied by another mobile. NOTE: The client also performs pushthrough checks (for some realms) and must be patched if you only want server-side checks. Since this critical script is called so often, it should be kept short. | |
SpeechMul: | |
params: CharRef character, Array of speechtokens, String complete msg. When called: When someone says a speech.mul keyword (one or more). | |
HitMiss: | |
params: CharRef character, CharRef opponent. When called: Hitchance check fails | |
OnCast: | |
params: CharRef character, Int SpellID. When called: When char casts a spell (including macros) before all checks. Return: 0 if you wish POL to perform the checks and casting, 1 if you want to handle it fully scriptside. | |
CanDecay: | |
params: ItemRef item. When called: When item should decay. Return: 0 core decay will ignore item and continue on the cycler, 1 core decay will handle the item as normal. | |
Ouch: | |
params: CharRef mobile, Int lastx, Int lasty, Int, lastz. When called: When mobiles falls at least 22 tiles. | |
CanDie: | |
params: CharRef mobile. When called: When mobiles is about to die. Return: 0 core stops death, 1 core will continue. | |
UnHide: | |
params: CharRef mobile. When called: When mobiles is about to unhide. Return: 0 stops the char from unhiding, 1 core will continue. | |
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). | |
CloseCustomHouse: | |
params: CharRef mobile, MultiRef multi. When called: When mobiles quits house editing. Return: Ignored. | |
WarmodeChange: | |
params: CharRef mobile, Integer new_status. When called: When mobile changes the warmode. Return: Ignored. | |
CanTrade: | |
params: CharRef mobile, CharRef drop_on, ItemRef item. When called: When dropping an item on a character or when trying to add an item to a tradewindow. Return: 0 disallow trade, 1 core will continue. | |
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: | |
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 | |
EquipTestScript | |
UnEquipTestScript |
UnEquipTestScript | |
---|---|
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 | |
EquipTestScript |
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 |
VirtueButtonScript | |
---|---|
program VirtueButton(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 doubleclicks the "Virtue" (pentagram) button on the paperdoll. | |
Where Does It Live? | |
The 'program' in virtuebutton.src file, only in /scripts/misc | |
To Define | |
Automatically called if file exists. | |
Explanation | |
This script type handles pentagram button on the paperdoll. Useful for implimenting any kind of gump. | |
Examples | |
use uo; program VirtueButton( character ) SendSysmessage(character,"You doubleclicked the Pentagram."); endprogram | |
Related Objects | |
Character |
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 |