Mote gearswap docs.txt

Documentation for use of Mote-Include GearSwaps.

 ------   FILES   ------

To use my include, certain supplemental files are required.

Mote-Include.lua -- The primary include. This file is entirely rules code for handling selecting sets, and handling a predefined set of self-commands.  All user data should have been removed from it, so there should be no reason to modify it at all.  

Mote-Mappings.lua -- File used for storing spell maps and other general mappings that jobs may want access to.  This should be all data, no functions.

Mote-Utility.lua -- File for various utility functions that fall outside the general handling of gear selection and equipping.

Mote-SelfCommands.lua -- File for handling our predefined self-commands for adjusting state values (offense mode, casting mode, update, etc).

Mote-Globals.lua -- Any additional values or functions that the user wants access to globally.  The user can override this version with a user-globals.lua file.


The separation into individual files is both for code sanity (all the self-command code is difficult to wade through while you're trying to examine the main gear changing code), and so that updates won't overwrite user customizations.  It should always be safe to simply drop in new versions of the various Mote-* files.


All of these files should be in the same directory as your regular job lua files.

 --- Optional Files ---
 
To facilitate keeping local user gear sets intact while still being able to update the main file, the scripts will look for sidecar files that implement the actual gear sets, and use them instead of the sets in the main file if they're found.

Example:
Main file - whm.lua
User file - whm_gear.lua  (or playername_whm_gear.lua)

Functions:
init_gear_sets
file_unload

Within whm_gear.lua, create a function called init_gear_sets().  When first created you can copy everything from the main file's init_gear_sets() function, and then fill in your own actual gear.  file_unload() is called when the file is unloaded, if you need any custom unload logic.

These sidecar files will not be part of the repository, and thus will not be updated or modified when you keep your files updated to the latest public version.


Example code:

function init_gear_sets()
    -- Put all set definitions here, as well as any other customization that is user-specific.
end

function file_unload()
    -- Called on unload, if needed
end





 ------   SETS   ------

Sets are constructed hierarchically.  The 'sets' set is the root node.  Other broad categories of sets descend from the root node, and are named in lowercase.  Each of those groups has other descendants. Major breaking-off points, where you start specifying sets by spell name or option, are capitalized, as are final-tier options.  Explicitly known set groups:

sets
    .precast
        .FC
        .JA
        .WS
        .~type (ie: spell.type, such as .Waltz, .Jig, .CorsairShot, etc)
    .midcast
    .idle
        .Field
        .Town
        .Weak
    .engaged
    .resting
    .defense
    .Kiting


The Include then searches those general set categories for more specific versions of each group.  For example, sets.precast.FC.Cure would be the set for casting cure spells; sets.idle.Field.PDT would be the field idle set to wear when idle mode is set to PDT; sets.engaged.Dagger would be sets used for melee while wielding a dagger (nb: melee sets have more complex options).


You can add more detail to the set to be used based on a variety of factors, depending on the set category.


When specifying a subset of a major set type for precast and midcast, the Include will check for subsets in the following order:

1) Custom class.  If you define a custom class in classes.CustomClass, the Include will attempt to find that first.

2) Spell name.  It will then attempt to find a set designed for specific spells (eg: Stoneskin, Berserk).

3) Spell map.  At the bottom of the Include is a list of spell mappings, to allow various spells to all be considered a single 'type' (eg: Cure for all single-target cure spells, Minuet for all the different Minuets, etc).

4) Spell skill.  It will then check for the skill used in casting the spell (eg: EnhancingMagic, ElementalMagic).

5) Spell type.  It will then check for the general type of spell (eg: WhiteMagic, BardSong).

Note that for spell types that are abilities (eg: Waltz, CorsairShot, etc), it will further search for the spell name as a subset under the type. EG: sets.precast.Waltz['Healing Waltz'].

Also, weaponskills (whether named or part of a custom class) will search for a set refinement of the weaponskill mode (which can also be custom-specified, if desired).  EG: sets.precast.WS.Upheaval['Mighty Strikes'], sets.precast.WS.MagicalWeaponskills.Brew.



When specifying a subset of melee sets, the include will attempt to construct a set based on a chain of values, all of which are optional (if it doesn't find one value, it will continue to the next in the chain).

1) You may specify a general combat form.  This is intended for long-term effects, such as the area you're in (Adoulin, Abyssea, etc), and can take only a single value.  This is specified with state.CombatForm.

2) You may specify a specific weapon via the state.CombatWeapon variable.  For example, you might have different gear sets defined under sets.engaged.GK and sets.engaged.Polearm.

3) You may specify sets based on the state.OffenseMode value.  For example, you might default to sets.engaged.Dagger, but also have sets.engaged.Dagger.Acc when OffenseMode is set to Acc.  OffenseMode should generally be set via the self-commands (see bottom of this document).

4) You may specify sets based on the state.DefenseMode value.  For example, you might default to sets.engaged.Dagger, but also have sets.engaged.Dagger.Evasion when DefenseMode is set to Evasion.  DefenseMode should generally be set via the self-commands (see bottom of this document).

5) You may add custom 'group' values to the classes.CustomMeleeGroups list (use classes.CustomMeleeGroups.append(new_group) to add to the list and classes.CustomMeleeGroups.clear() to empty it).  These will be stacked on in the order they exist within the list.  For example, if the list contains 'HundredFists', 'Impetus', the include will continue searching from sets.engaged.HundredFists.Impetus.


A fully-defined set might be something like sets.engaged.Abyssea.H2H.Acc.PDT.HundredFists.Impetus.  However, many specification values can be considered optional, so it will fall back to the next previous set.  For example, rather than sets.engaged.H2H.Normal.Normal (no groups, H2H weapon, normal offense and defense), if H2H is your default weapon you could just as easily use just sets.engaged.



Construct your sets with that in mind, and the Include will be able to handle 95% of set selection and equipping without you needing to write any particular rules.



 ------   RULES   ------


 ---- The Basics ----
 
 --- Actions ---

The basic function calls occur for precast, midcast and aftercast, as well as pet_midcast and pet_aftercast.  The Include file handles the precast()/etc functions, and calls special versions within the job file.  These calls are made both before and after the Include file does its predefined work.  EG:

Include: precast()
        Job: job_precast()
        Include: default code
        Job: job_post_precast()

Each time these functions are called, the Include passes certain parameters:

spell: All spell information provided by GearSwap.
action: This no longer carries any information, but is passed through since it still exists within the GearSwap code.
spellMap: This is the general mapping, if any, for the spell.  EG: If the spell.name is 'Choke', the spellMap value will be 'ElementalEnfeeble'.
eventArgs: This is a means of flagging the Include that you don't wish for it to do its default processing, as well as a few other things.


eventArgs will always have a sub-field of 'handled'.  If you set eventArgs.handled = true, the Include will not perform any default processing on that time slot (such as precast).  It will still call job_post_precast (or equivalent), though.

It may also have a sub-field of 'cancel', if it's in the pretarget or precast phase.  If you set eventArgs.cancel = true, the Include will cancel the spell and quit any further processing (note: don't call cancel_spell() yourself; the include handles that).

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.


 --- Melee ---

While there is a pre/default/post section for aftercast, that's not actually where most gear handling is done for non-action equips (though you can still use it to prevent aftercast from equipping gear, by setting the usual eventArgs.handled to true).

Modifications to the aftercast gear to be equipped is done via three additional functions:

job_handle_equipping_gear(status, eventArgs)

customize_idle_set(idleSet)

customize_melee_set(meleeSet)

These functions allow you to modify the default constructed sets before they're actually equipped.  job_handle_equipping_gear can be used to set up information that may be needed in constructing the default sets (eg: setting up the CustomMeleeSet list).  The two customize functions are called after the default sets are defined.  Return the modified set at the end of those function.  Make sure not to modify the set directly, but only change it with set_combine().


 ---- Advanced ----
 
 --- States & Modes ---
 
See section on self-commands.

 --- Setting Custom Classes ---

There are (currently) four types of custom classes:

classes.CustomClass = nil
classes.CustomMeleeGroups = L{}
classes.CustomIdleGroups = L{}
classes.CustomDefenseGroups = L{}

classes.CustomClass is a single string, and needs to be set each time a spell is used if you want it used.  It gets reset at the end of the aftercast (or pet_aftercast) section each time.

The custom groups are persistant, and will remain until you change them.

CustomClass changes the primary set to search for.  Instead of 'Cure II' (the spell), or 'Cure' (the spell map), you might want to use a special set (eg: 'CureSolace').  This will be checked before any of the other standard classifications (spell name, spell map, spell skill, spell type).

The custom groups are added on to the default selected group for custom sets to use under various circumstances.  At the moment, idle and defense groups are added on to the end of the normal set hierarch, while the melee groups are added on at the beginning of the hierarchy.  I'm still considering whether to move the melee groups to the end.



 ---- Utility ----
 
Mote-Utility has various utility functions that may be useful in general.

set_macro_page(set,book) -- This allows you to go to the specified macro set for a given macro book, just giving the numbers.  The book parameter is optional.

This function is currently used in the various job files at the end of get_sets() in order to set the default macro book/set on load (eg: set_macro_page(1,20) will put you on set 1 of book 20).  You might also use throughout the rule file to adjust which macro set to be on (eg: set_macro_page(3) will change you to macro set 3 of your current book).

auto_change_target() -- This is a utility function for the main include, and shouldn't be called directly from any job files.  However it does call into job files to allow modifying its behavior.

If the job file has a job_auto_change_target function, it will call job_auto_change_target(spell, action, spellMap, eventArgs).  eventArgs contains the fields: handled, PCTargetMode, SelectNPCTargets.  Set handled to true to prevent auto_change_target from running any of its own code. Set PCTargetMode if you want to modify that behavior (values of: 'default', 'stpc', 'stpt', 'stal').  Set SelectNPCTargets to override whether or not to attempt to change target selection for moves that have enemy targets (weaponskills, steps, etc).  If true, it will force <stnpc>.  Otherwise it will leave it as originally entered.

refine_waltz(spell, action, spellMap, eventArgs) -- This function will adjust which curing waltz to use if your target is yourself, based on how much HP you're missing, and capping based on available TP.  Call it during precast() with the default values that precast is called with.  If you have too little TP, or not enough HP missing to be worth curing, it will handle cancelling the action.


get_weather_intensity() -- Returns 0 for no weather, 1 for normal weather, and 2 for double weather.

There are a few other functions in the utility file, but mainly only of interest to the needs of the main include file.



 ---- Self commands: Adjusting state ----
 
State values (ie: information about what type of state you're in, such as accuracy-focused melee, or PDT idle, or kiting, etc) are controlled via custom commands sent through GearSwap.  There are multiple ways of manipulating each state, as well as a default set of binds for the most common adjustments (available in the UserGlobals file, which you can adjust to personal preference).

Since commands are sent directly to GearSwap, there are three ways to format them depending on where it originates from:

From the command line:  //gs c <command>
From a macro: /console gs c <command>
From a bind (which goes directly to the console): gs c <command>

General command format:

toggle <field>
activate <field>
cycle <mode>
set <state> <value>
reset <resettype>


There are two types of <state>:

<field> is for boolean fields -- they can only be true or false (or on or off, if you prefer).  You can toggle them on and off, or activate them to force them on, or set them to a specific state.  A field that is reset will be turned off.

<mode> is for lists of values.  You can use cycle to increment over that list, returning to the first value after passing the end of the list.  You can use set to assign a specific value, and a reset will return it to the first value of the list.


The global togglable fields are:

Defense - for all-out defense, either physical or magical (the exact type is set with Activate)
Kiting - for wearing +movement speed above any other gear
Target - for determination of whether to force use of <stnpc> when performing actions against mobs


Fields that can be activated:
PhysicalDefense - Turn on Defense, and set it to physical
MagicalDefense - Turn on Defense, and set it to magical
Kiting - for wearing +movement speed above any other gear
Target - for determination of whether to force use of <stnpc> when performing actions against mobs



The global cyclable modes are:

OffenseMode - the offense portion of the hybrid melee set (eg: acc, crit, etc)
DefenseMode - the defense portion of the hybrid melee set (eg: evasion, pdt, etc)
CastingMode - the mode describing what type of gear to use for casting (eg: resistant, enmitydown, etc)
WeaponskillMode - a specification of a specific mode to weaponskill with (eg: acc, mod, etc)
IdleMode - the type of idling gear to use (eg: pdt, pet)
RestingMode - the type of gear to wear while resting (eg: petfighting)
PhysicalDefenseMode - the type of physical defense gear when the all-out defense mode is activated (eg: pdt, evasion)
MagicalDefenseMode - the type of magical defense gear when the all-out defense mode is activated (eg: mdt, resist)
TargetMode - the type of target selection method to use with player-targettable spells (eg: stal, stpc, stpt).  Note: predefined, you shouldn't change this.


You can also create job-specific states that get handled via this mechanism.  The Mote-SelfCommands file will call into the job file at certain points.  Note that you could just intercept the self_command and handle it all yourself, but this keeps it somewhat clean in your function definitions.

For toggles:

job_toggle(field) -- This is called when the user enters "gs c toggle <field>".  For each state you wish to toggle, check for the field value passed in, adjust it, and return a text description of the field you changed, along with its new state.  EG:

function job_toggle(field)
    if field:lower() == 'selectsteptarget' then
        state.SelectStepTarget = not state.SelectStepTarget
        return "Select Step Target", state.SelectStepTarget
    end
end


For states that can cycle through various values:

job_get_mode_list(field) -- This is called to get the list of valid values to cycle through, and the current value, to allow the cycle code to work.  The field will always be sent with the first letter capitalized and the rest lowercase.

function job_get_mode_list(field)
	if field == 'Mainstep' then
		return options.StepModes, state.MainStep
	end
end

And:
function job_set_mode(field, val)
	if field == 'Mainstep' then
		state.MainStep = val
		return true
	end
end

(Return true if a value was properly set.)




Reset works on certain general types:

Defense - turns defense off
Kiting - turns kiting off
Melee - returns OffenseMode and DefenseMode to their default (first) values
Casting - returns CastingMode to its default (first) value
Target - resets both NPC targetting and PC targetting, to turn off any overriding being done
All - resets all fields and modes to their defaults

The job file may also handle resets with its own hook:

function job_reset(resetType)
    if resetType == 'all' then
        state.MainStep = options.StepModes[1]
    end
end