Script Naming Conventions

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
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License