Utility

Mote-Utility has various utility functions that may be useful in general. These functions may be added to your job luas if you wish to take advantage of their functionality.

---

User utility functions

Change the current macro book and/or palette

set_macro_page(set,book)

This allows you to go to the specified macro set for a given macro book. The book parameter is optional, so you may also say set_macro_page(set) to only change the palette.

Recommended usage: Use it in user_setup() directly, or create a function like select_default_macro_book() where you can choose which set to go to based on your current subjob. user_setup() is called each time your subjob changes, so it's a simple location to keep subjob-specific initialization.

Change Waltz commands based on HP and TP available

refine_waltz(spell, action, spellMap, eventArgs)

This function will adjust which Curing Waltz to use based on how much HP is missing from the target, if that information is available. This function should be called from the job_precast() function in the job lua.

If you're curing yourself or someone in your alliance, the function can get an exact or estimated amount of HP the target is missing, and thus determine which Waltz to use to be most efficient in curing them.

The thresholds for curing are different for Dnc main and sub jobs, and the available Waltzes that the code can adjust the Waltz to are likewise different.

Once an efficient Waltz is chosen, it then will downgrade the Waltz based on how much TP you have available. It will choose the highest level waltz that you can afford, up to the originally determined Waltz.

If you have insufficient TP, or if you're curing yourself and aren't missing enough HP to be worth bothering with, the code will cancel the Waltz for you; you do not need to do anything in the job_precast() function where you call it from.

Cancel buffs that you're about to overwrite

cancel_conflicting_buffs(spell, action, spellMap, eventArgs)

This function will cancel various buffs that would otherwise prevent a new spell from taking effect (eg: Sneak), or an action from being used (eg: Waltz while Saber Dance is up). It should be called in the job_precast() function.

If the spell or JA about to be used cannot be cast because of recast timers, the utility function will cancel the attempt and not cancel any buffs on the player.

Cancellable buffs:

• Sneak - If using Spectral Jig, Monomi: Ichi, or casting Sneak on yourself.
• Copy Image - If casting Utsusemi: Ichi.
• Stoneskin - If casting Stoneskin.
• Saber Dance - If using a Waltz.
• Fan Dance - If using a Samba.

If the new buff gets a quick cast proc, it will probably fail to be applied because of the time it takes for the cancel to happen.

Determine if a player has any of a set of buffs

has_any_buff_of(buff_set)

Given a set (S{}) of buffs that you're interested in, determine if any of those buffs are present on the player.

Determine single vs double weather

get_weather_intensity()

Returns 0 for no weather, 1 for normal weather, and 2 for double weather.

This is used because the default world weather information doesn't distinguish between single and double weather.

Find a player in the current alliance

find_player_in_alliance(name)

Given a player's name, try to find that player in the current alliance. If found, it returns that player's info table.

Determine if your current party is made up of Trust NPCs

is_trust_party()

Determine whether your current party is made entirely of Trust NPCs. Returns true if all the players in your party are NPCs with known Trust NPC names.

Library utility functions

Change the default <st> target*

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.

Its purpose is to allow automatically adjusting which type of <st*> target code to use for the user's macro'd spells. For example, if you had a macro for /ma "Cure III" <stpc> (along with Cure IV, Cure V, etc), adjusting the control parameter would allow each macro to instead behave as /ma "Cure III" <stpt> or /ma "Cure III" <stal> without having to adjust the actual macros themselves. That way you can switch between selecting arbitrary targets, to being able to cure anyone in the alliance, to being able to cast only on your own party while in an alliance, depending on your current needs.

Similarly, for targetting mobs, it can switch between leaving a macro with a <t> targetting or instead using <stnpc>.

The behavior is determined by the value of two state variables: state.PCTargetMode and state.SelectNPCTargets. These values can be changed with GearSwap commands:

• gs c cycle targetmode will cycle through the available target modes for player targetting. Available values are default (no change is made to the macro values), stpc, stpt (note: will not change targeting for self-only spells), and stal (note: will not change targeting for party-only or self-only spells). By default, this command is bound to the Ctrl-= key.
• gs c toggle target will toggle whether or not NPC targetting will force a <t> to <stnpc>. By default, this command is bound to the Ctrl-- key.

User files can modify this behavior further by implementing the job_auto_change_target() function. The function signature is job_auto_change_target(spell, action, spellMap, eventArgs). eventArgs contains the fields handled, PCTargetMode and 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. If true, it will force .

If you do not modify the values in eventArgs, then the function will run based on the existing state values.

Set elemental gear variables

set_elemental_gear(spell)

A series of functions that will determine which, if any, elemental gear can be used for the current action. This includes:

• Elemental gorgets and belts that match the skillchain properties of an attempted weaponskill.
• Elemental magian staves for fast cast and recast.
• Elemental obis (and possibly Twilight Cape and Zodiac Ring) that match both the current spell and weather/day.

Variables may be used in your gear set constructions that will equip appropriate elemental gear items when appropriate, or default items otherwise. The variables are:

• gear.ElementalGorget
• gear.ElementalBelt
• gear.ElementalObi
• gear.ElementalCape
• gear.ElementalRing

The default equipment that will be used if no elemental properties are matched may be stored in the following variables:

• gear.default.weaponskill_neck
• gear.default.weaponskill_waist
• gear.default.obi_waist
• gear.default.obi_back
• gear.default.obi_ring

Invert a table's keys and values

invert_table(t)

Given a table, return a table where the keys are the original table's values, and the values are the original table's keys.

Event Utility Functions

The following are functions designed to handle user-registered events.

Time changes

time_change(new_time, old_time)

Making use of this function should be done by registering the function as the 'time change' event handler. This should generally be done in the job_setup function, and unregistered in the file_unload function, like so:

function job_setup()
    event_list = L{}
    event_list:append(register_event('time change', time_change))
end

function file_unload()
    event_list:map(unregister_event)
end

This function sets two boolean values: classes.Daytime and classes.DuskToDawn, determined by the time of day. If at any point either of those two values change, time_change will call the job_time_change(new_time, old_time) function, followed by a call to the update function, which will by default initiate a re-equipping of current gear.

Changes to variables that help determine what gear to wear should be done in the job_time_change function. For example:

function job_time_change(new_time, old_time)
    classes.CustomMeleeGroups:clear()
    if classes.Daytime then
        classes.CustomMeleeGroups:append('Daytime')
    end
end