The script naming conventions are an important part of this project. We follow these conventions to find scripts quickly and reduce errors and confusion. There are four classifications of scripts, and each will have it's own naming convention. These classifications are spell scripts, module event handlers, other scripts that are not area-specific, and area-specific scripts.
It should be noted that there is actually a fifth classification of scripts; namely, tag-based scripts for items. Since the naming convention for tag-based scripts is a standard that was set by Obsidian Entertainment, names for such scripts will not be discussed in this document.
The maximum length of any script's name is 32 characters.
Spell Scripts
There are two types of spell scripts — impact scripts and area-of-effect scripts. These are detailed below.
Impact Scripts
The most basic type of spell script is the impact script, which is what gets executed when a spell hits its target. All spells have an impact script, the name of which is unique throughout a campaign.
Spell scripts that are custom made for this project shall be prefixed with the letters "sd" followed by an underscore. (This prefix comes from the initials of "Shattered Dreams," the title of our module.) This is to be followed by another prefix, which indicates the type of spell that the script is for. The second prefix shall be taken from the following table.
Spell Type | 2nd Prefix |
Spell | s0 |
Special (Spell-like) Ability | s1 |
Feat-based Spell | s2 |
The above prefix is also followed by an underscore, which is then followed by an identifier to be chosen by the scripter.
The following is an example of a custom spell impact script.
sd_s2_stinkcorpse
Area-of-Effect Scripts
Spells that create an area of effect, such as auras and clouds, may need one or more area-of-effect scripts. The names of these scripts are taken from the name of the impact script of the spell, with the addition of an underscore followed by one of the following suffixes.
AOE Event | Suffix |
On Enter | a |
On Heartbeat | b |
On Exit | c |
The following is an example of an area-of-effect script.
sd_s2_stinkcorpse_a
Module Event Handlers
Each module may only have at most one script per module event. The name of each module event handler shall be the same across all modules. These names are given in the following table.
Module Event | Script Name |
On Acquire Item | mod_acquire |
On Activate Item | mod_activate |
On Client Enter | mod_enter |
On Client Leave | mod_leave |
On Cutscene Abort | mod_cutscene_abort |
On Heartbeat | mod_hb |
On Module Load | mod_load |
On Module Start | mod_start |
On PC Loaded | mod_pc_load |
On Player Death | mod_death |
On Player Dying | mod_dying |
On Player Equip Item | mod_equip |
On Player Level Up | mod_levelup |
On Player Respawn | mod_respawn |
On Player Rest | mod_rest |
On Player Unequip Item | mod_unequip |
On Unacquire Item | mod_unacquire |
On User Defined Event | mod_user_def |
Other Scripts That Are Not Area-Specific
Aside from spell scripts and module event handlers, there may be other scripts that are not specific to any particular area. These scripts include but are not limited to generic action or conditional scripts for conversations, include files, and creature event handlers. These scripts may be categorized according to scope. Scripts that may be used in any module throughout the campaign are global or campaign scripts. Those that are specific to a module are module scripts. The first character of scripts that are not specific to any area (aside from spell scripts and module event handlers) will always be one of the following letters, depending on the scope of the script.
g = global (campaign) script
m = module script
The above letter shall be followed by an underscore, which is then followed by another prefix. Depending on what the script will be used for, the second prefix shall be one of the following.
Script Type | 2nd Prefix |
Include File | inc |
Conversation Action Script | a |
Conversation Conditional Script | c |
Creature Event Handlers | n |
Door Event Handlers | d |
Store Event Handlers | s |
Placeable Event Handlers | p |
Trigger Event Handlers | t |
Encounter Event Handlers | e |
The above prefix shall be followed by an underscore, which in turn, is followed by an identifier to be chosen by the scripter. The names of event handlers shall furthermore be followed by an underscore after the identifier, after which a two-letter suffix shall be appended. (See below.)
For example, a handler for the On Physically Attacked event for an NPC companion named Drizzt may be named as follows:
g_n_drizzt_at
Area Specific Scripts
Area specific scripts are for any script related to an event, creature, cutscene, etc. that take place in a single area. The standard formula is as follows:
NN_O_ID_SX
NN: The area identifier. Each area will begin with a two digit area identifier. See Area Naming Conventions.
O: A single letter is attached to indicate the script's type. This letter shall be one of the following:
Script Type | 2nd Prefix |
Conversation Action Script | a |
Conversation Conditional Script | c |
Area Event Handlers | r |
Creature Event Handlers | n |
Door Event Handlers | d |
Store Event Handlers | s |
Placeable Event Handlers | p |
Trigger Event Handlers | t |
Encounter Event Handlers | e |
ID: A short amount of text to quickly identify the scripts purpose. There is no standardization of this identifier.
SX: The suffix of the script. Each event has it's own two-letter suffix.
Example: In the area 01_inn we have a character tagged "jim" with a perception event script. So we would name this script 01_n_jim_pe
Script Suffixes
The names of event handlers (other than the ones for modules) shall always have suffixes that indicate the type of event being handled. These suffixes are as follows.
Event | Suffix | Object Type |
On Blocked | bl | Creature |
On Click/On Clicked/On Left Click | cl | Door, Placeable, Trigger |
On Client Enter | ce | Area |
On Close/On Closed | cd | Door, Placeable, Store |
On Conversation | co | Creature, Door, Placeable |
On Damaged | da | Creature, Door, Placeable |
On Death | de | Creature, Door, Placeable |
On Disarm | ds | Door, Placeable, Trigger |
On End of Combat Round | er | Creature |
On Enter/On Entered | en | Area, Encounter, Trigger |
On Exhausted | eh | Encounter |
On Exit | ex | Area, Encounter, Trigger |
On Fail To Open | fo | Door |
On Heartbeat | hb | Area, Creature, Door, Encounter, Placeable, Trigger |
On Inventory Disturbed | id | Creature, Placeable |
On Lock | lo | Door, Placeable |
On Melee Attacked/On Physically Attacked | at | Creature, Door, Placeable |
On Open | op | Door, Placeable, Store |
On Perception | pe | Creature |
On Rested | re | Creature |
On Spawn In | sp | Creature |
On Spell Cast At | sc | Creature, Door, Placeable |
On Trap Triggered | tt | Door, Placeable, Trigger |
On Unlocked | ul | Door, Placeable |
On Used | us | Door, Placeable |
On User Defined | ud | Area, Creature, Door, Encounter, Placeable, Trigger |