FFXIAH.com
Language: JP EN DE FR
users online
GearSwap Tutorial

GearSwap Tutorial (v0.1)


PART 1



GearSwap is an addon written in the Lua programming language, and uses files also written in Lua to control when and what gear to equip when performing actions in game.

This tutorial assumes that you have at least a basic comprehension of standard programming terms, such as 'functions', 'variables', 'assignment', etc. A brief introduction to the details of those things can be found on the Windower wiki here.


How do I use GearSwap?


This is a vague and ambiguous question that encompasses the "I don't even know where to begin" issue some people have when first trying to make use of GearSwap. I'll try to give a brief description of where things start.

First, install GearSwap from the addons list of the Windower launcher. That places all the GearSwap code files in the Windower/addons/GearSwap directory. At this point, GearSwap can now be loaded.

The user files that are the focus of all GearSwap discussions get placed in the GearSwap/data directory (or GearSwap/data/<charactername>).

The user files should be named to match the job each one is designed around. EG: whm.lua. The file can include the character name as well. EG: motenten_whm.lua.

The use of the character name in either the file name or the directory name allows you to organize the files by character. So you can have data/motenten_whm.lua or data/motenten/whm.lua, and either would work. The manner in which you organize them is a personal preference.

Once a job file that matches the name of the job you are using is found, it gets loaded and used. The remainder of this tutorial works on explaining the things you can put in this file to make control the game behavior the way you want it to.

How does GearSwap work?


GearSwap can be understood via two fundamental concepts: Gear Sets and Events.


Gear Sets



A gear set is exactly what you would expect -- a set of gear to be equipped. It's written using Lua tables, with an entry for each equipment slot you want to equip something in, and what piece of gear to put there.

Lua tables are one of the fundamental data types (way of storing information) used in Lua. A table is written by enclosing the data to be stored in it in between curly braces: {}
Code 
an_empty_table = {}


Here we see a gear set with a Chatoyant Staff (created using a table), which is intended to be placed in the main equipment slot:
Code 
another_table = {main="Chatoyant Staff"}


Each additional item you place in the set needs to be separated with a comma, like so:
Code 
another_table = {main="Chatoyant Staff", sub="Achaq Grip", ammo="Incantor Stone", head="Gendewitha Caubeen"}


Any of the standard gear slots can be referenced, with some variations on the names that you can use. Which one you use is entirely up to you; it doesn't make any difference except for aesthetics.

Equipment slots:

  • main

  • sub

  • range/ranged

  • ammo

  • head

  • neck

  • ear1/lear/left_ear

  • ear2/rear/right_ear

  • body

  • hands

  • ring1/lring/left_ring

  • ring2/rring/right_ring

  • back

  • waist

  • legs

  • feet



Aside from assigning the values directly, you can also combine multiple tables together using the set_combine() function. That will be discussed in more detail later.

Another important point is that tables can also contain other tables (and those tables can contain tables, and so on). As long as you don't use one of the above equipment slot names, you can name these sub-tables anything you want. They also won't interfere with any gear you have in any given gear set.

You create subtables by naming them on the lefthand side of the equals sign in one of two ways:
Code 
-- an empty table to start with
my_table = {}

-- a new table inside my_table, named "more_info"
my_table.more_info = {}

-- another way of writing that:
my_table['more_info'] = {}


You might want to use the second way if the name you're giving the sub-table contains multiple, space-separated words. For example:
Code 
-- Wrong:
my_table.Curing Waltz = {}

-- This works:
my_table['Curing Waltz'] = {}


As an aside, those lines that start with a double hyphen (--) are comments. Anything that follows a -- on a given line in the lua file will be ignored, and have no effect on your program.


The primary table that GearSwap expects you to use is named "sets", and is already created for you before your script starts (so don't redefine it). In general, you should make all of your gear sets as sub-tables of the sets table. For example:
Code 
-- put precast gear here
sets.precast = {}
sets.precast.Cure = {}

-- put midcast gear here
sets.midcast = {}
sets.midcast.Cure = {}



Events



Events are things that happened (or are about to happen). Particularly, they are things that happen that we know happened, because the main control system (GearSwap itself) told us about them. There are three primary events that you'll be interested in to begin with: precast, midcast and aftercast.

precast - Precast is the event telling us that the player issued a command, and that we're just about to send it to FFXI's servers. However before we do that, we're giving you the opportunity to set up any gear that you want to have equipped before the action is actually initiated. This is where you put your fast cast gear so that the spell receives that effect when it is cast, or gear that enhances a Job Ability that you're about to use.

midcast - Midcast is the event telling us that the player-issued command is being sent. It allows you to add on any extra gear that will be equipped after the command has begun in order to enhance the effectiveness of the action being taken. This is where you put your cure potency, or MAB for nukes, etc.

aftercast - Aftercast is the event telling us that the action has completed, typically when a spell hits the target, when a weaponskill does damage, etc. It also gets called when the spell is interrupted, if the job ability is still waiting on recast and you can't use it yet, or if you can't use the ability at all (eg: amnesia). The aftercast event lets us know when it's safe to return to 'ordinary' gear again, after performing an action.


When any of these events happen, GearSwap will try to run a function inside your lua file named after the event. If you created that matching function, it gets run at the point in time when the event happens.

A function is written like this:
Code 
function precast(spell)

end


First declare it as a 'function', then give it a name (in this case, the name of the event that's occurring), then give it a parameter list in parentheses. When you've reached the end of what the function is doing, mark it as such with 'end'.

There are some additional events that your program may want to do something with, beyond just the basic three:

  • pretarget -- This is before you try to select your target.

  • precast -- This is immediately before the action is initiated.

  • midcast -- This is immediately after the action is initiated.

  • aftercast -- This is after the action has completed or been interrupted.

  • pet_midcast -- Midcast for pet actions.

  • pet_aftercast -- Aftercast for pet actions.

  • status_change -- When your status (Idle, Engaged, Resting, etc) changes.

  • pet_status_change -- When your pet's status (Idle, Engaged, Resting, etc) changes.

  • buff_change -- When any buff you have changes (gain haste, lose protect, etc).

  • pet_change -- When you gain or lose a pet (ie: summon an avatar, release an automaton, etc).

  • sub_job_change -- When you change your subjob.



Each of these is also described in the variables.xlsx spreadsheet that gets installed with GearSwap.

There are two other special functions of interest:

get_sets -- This is called when the script file is first loaded (on login, or when changing jobs (but not sub jobs)), and is only ever run once. Put all your sets in the get_sets function, and you can then refer to them later from the other functions.

self_command -- This gets run whenever you send a command directly to GearsSwap. A self-command is indicated by having the second word be "c" (eg: //gs c toggle TP). Everything after the "c" is passed in as a string parameter, so you can choose what to do based on your own command.


Now, what can you -do- within each of these functions? Well, the primary thing you want to do is equip appropriate gear. This is done using a function that GearSwap provides called "equip". All you have to do is provide it with the set that you want to be equipped. It looks like this:
Code 
equip(my_set)



Trying it out


So now, let's write an extremely simple script, for our whm:
Code 
function get_sets()
    sets.aftercast = {main="Bolelabunga", sub="Genbu's Shield", hands="Serpentes Cuffs"}
end

function aftercast(spell)
    equip(sets.aftercast)
end


Just save the text in the file "whm.lua".

This is, in fact, a completely functional lua script. It doesn't do much, but it will work.

This script creates a set called sets.aftercast (a sub-table of sets, which you'll remember already exists) when things first load up and get_sets is called. It then equips that set on aftercast -- that is, after every action you take, it puts that set on when you're done.

Of course if we never switch out of that gear, it won't look like we're actually doing anything. So let's add a little more.
Code 
function get_sets()
    sets.precast = {hands="Gendewitha Gages"}
    sets.midcast = {main="Tamaxchi", hands="Bokwus Gloves"}
    sets.aftercast = {main="Bolelabunga", sub="Genbu's Shield", hands="Serpentes Cuffs"}
end

function precast(spell)
    equip(sets.precast)
end

function midcast(spell)
    equip(sets.midcast)
end

function aftercast(spell)
    equip(sets.aftercast)
end



So now we have three sets, and we can equip them at three points in time: Gendewitha Gages on the hands during precast for the fast cast effect, Tamaxchi and Bokwus Gloves during midcast for cure potency, and Bolelabunga and Serpentes Cuffs on aftercast so that we can idle with some refresh.


And that's it for part 1 of the tutorial. From here on, it's just details and situational gear choices.


Navigation
Part 1 - Basic Sets and Events
Part 2 - Conditionals and Testing
Part 3 - More on Conditionals
Part 4 - Tables
Part 5 - Abstractions
Part 6 - Asking the Right Questions
Part 7 - Library Tools
Author: Motenten
Date Created: 2014-04-25 17:42:27
Date Last Modified: 2017-02-11 17:29:48
Updates: 10
Bytes: 11209