Skip to content
Kinematics edited this page May 26, 2014 · 2 revisions

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.

Process order

Each standard event handler in the include follows a specific pattern:

  1. Call the job_<event>() function.
  2. Handle default processing.
  3. 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:

  1. spell - This is the same spell parameter that is passed to the default event handler, containing all the available spell information.
  2. 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.
  3. spellMap - This is the mapping that has been determined for the spell (if any).
  4. eventArgs - This table contains two values that are useful for controlling default behavior:
  5. cancel - Setting cancel to true preempts all default behavior, and causes the action to be cancelled. Be sure to use this rather than call cancel_spell() directly, since otherwise the main handler may perform other actions you didn't expect. Cancelling an action is only valid in the pretarget and precast event phases.
  6. handled - Setting handled to true causes the main handler to skip all default actions. It will still call job_post_<event>(), though, along with the same eventArgs variable so that the post_ function can tell if the handled 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.

Functions of Interest

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 in user_setup, that you undo the bindings in file_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 in user_setup, or possibly job_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 use set_combine() to change the contents of the set.
  • customize_melee_set(meleeSet) - Can return a modified melee set to be equipped. Only use set_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 call handle_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, call handle_equipping_gear.
  • job_pet_change(pet, gain) - For player gaining or losing pets. The default handler will automatically call handle_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, call handle_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 call handle_equipping_gear.
Clone this wiki locally