-
Notifications
You must be signed in to change notification settings - Fork 157
Rules
The include file processes GearSwap events directly, and then calls custom functions within the general job luas to allow the job to specify when it wants to override or change the default behavior.
You should never redefine the standard event functions (eg: precast()
) within the job files. That will erase the main include's ability to provide default behavior.
Each standard event handler in the include follows a specific pattern:
- Call the
job_<event>()
function. - Handle default processing.
- Call the
job_post_<event>()
function.
For example, the precast()
handler will call job_precast()
, select the default precast set, and then call job_post_precast()
.
The job_<event>()
function allows you to set things up for the default handling that may be out of the ordinary, tell the default handler not to do any processing at all, or even just cancel the spell outright.
The job_post_<event>()
function allows you to add things on top of whatever the default set selection chose, and thus tweak the results to match things that the default isn't capable of accounting for.
In order to make this possible, four parameters are passed to each job_
function. These are:
- spell - This is the same
spell
parameter that is passed to the default event handler, containing all the available spell information. - action - This is a legacy parameter that has no use anymore. You can ignore it, but it's still present to prevent breaking old code.
- spellMap - This is the mapping that has been determined for the spell (if any).
- eventArgs - This table contains two values that are useful for controlling default behavior:
- cancel - Setting
cancel
to true preempts all default behavior, and causes the action to be cancelled. Be sure to use this rather than callcancel_spell()
directly, since otherwise the main handler may perform other actions you didn't expect. Cancelling an action is only valid in thepretarget
andprecast
event phases. - handled - Setting
handled
to true causes the main handler to skip all default actions. It will still calljob_post_<event>()
, though, along with the sameeventArgs
variable so that the post_ function can tell if thehandled
value had been set.
This basic order of processing occurs for pretarget
, precast
, midcast
, aftercast
, pet_midcast
, and pet_aftercast
event functions.
The reason for the pre, default, and post ordering for each section is to allow a logical layering of equipment at each level. If you want to special-case equipment for a certain spell, put that in the Pre section and tell the Include that you handled choosing what gear to equip. If you want the default gear to be equipped, but possibly make a small modification (eg: Orison Mitts +2 when casting a -na spell with Divine Caress active), put that in the Post section.
Others
Most other event handling functions (status_change
, buff_change
, etc) will call the job_
variant of themselves as well. If the job_
function call sets eventArgs.handled
to true, then they will likewise skip any default processing.
General
-
get_sets
- This is the default function that GearSwap calls when first loading up a lua file. When using my includes, it should only have a single instruction in it:include('Mote-Include.lua')
. All other functionality is distributed across various function calls that can each be overridden by the user in a sidecar file. -
job_setup
- This function is for defining variables and such that are necessary for the job file to function properly. None of the data in this function should be changed by the end-user unless they completely understand the consequences of doing so. -
user_setup
- This function is for defining variables that control user-specific configuration. The end user may override this function in a sidecar file in order to set up parameters that fit their needs. This function will also always be called when the user's subjob changes, so anything that might change with your subjob can also be defined or called from within here. -
file_unload
- This function is called when the job file as a whole is unloaded (such as when changing to another job). It's recommended that if you define any custom bindings inuser_setup
, that you undo the bindings infile_unload
. -
init_gear_sets
- This function is for defining all gear sets that are to be used in the lua file. It should not be used for defining miscellaneous variables and data tables, as those should be defined inuser_setup
, or possiblyjob_setup
. This is the primary function that should be overridden in the sidecar file.
Actions
As described above, player actions get a standard set of function calls:
-
job_pretarget
,job_post_pretarget
-
job_precast
,job_post_precast
-
job_midcast
,job_post_midcast
-
job_aftercast
,job_post_aftercast
-
job_pet_midcast
,job_post_pet_midcast
-
job_pet_aftercast
,job_post_pet_aftercast
Customization Hooks
Functions that allow setting or modifying values that are used in determining set lookup:
-
job_get_spell_map(spell, default_spell_map)
- Can return a custom spell map to use during set lookup. -
get_custom_wsmode(spell, action, spellMap)
- Can return a custom weaponskill mode when selecting a weaponskill set to use. -
job_handle_equipping_gear(status, eventArgs)
- This is called when the Include is about to determine which melee or idle sets to equip, either after an action, or due to various events that want to update what's currently being worn (eg:buff_change
, or a self-command). State variables and custom groups can be adjusted here so that they're in effect during set construction. -
customize_idle_set(idleSet)
- Can return a modified idle set to be equipped. Only useset_combine()
to change the contents of the set. -
customize_melee_set(meleeSet)
- Can return a modified melee set to be equipped. Only useset_combine()
to change the contents of the set.
Commands
-
handle_equipping_gear(player.status)
- Call this function if you want to force the current default (melee or idle) gear set to be equipped.
Notifications
Event notification functions:
-
job_status_change(new_status, old_status)
- For player status (Idle, Engaged, Resting, etc). The default handler will automatically callhandle_equipping_gear
. -
job_buff_change(buff, gain)
- For player gaining or losing buffs. The default handler will not attempt to update the current equipped gear. If you want gear to be updated, callhandle_equipping_gear
. -
job_pet_change(pet, gain)
- For player gaining or losing pets. The default handler will automatically callhandle_equipping_gear
. -
job_pet_status_change(new_status, old_status)
- For changes in pet statuses (Idle, Engaged, etc). The default handler will not attempt to update the current equipped gear. If you want gear to be updated, callhandle_equipping_gear
. -
job_state_change(state, new_state_value, old_state_value)
- When a state variable is changed using self-commands. The default handler will automatically callhandle_equipping_gear
.