Contribution Guidelines
Pull requests are the preferred way of contributing. Github has a nice article about this. Be sure to read it. Generally, you can follow these steps :
- Create a dedicated branch based on latest master for your pull request.
- Commit on this branch, or add commits by cherry-picking them.
- Submit the pull request.
- Once your branch is merged, you can delete it.
- If master changes before your branch is merged, do not merge master into it, rebase.
- Do not comment code, remove it. It is Git's job to keep track of history.
- Keep the changes per commit as minimal as possible, or make several commits.
- In class files, do not forget to increase the revision number (the number just after the patch number).
- Use only tabulations (width 4) to indent. Do not insert spaces in between tabulations.
- Use spaces to align similar items on consecutive lines.
- Align numbers to the right; spaces between initial indent and numbers are allowed in this case.
- Always remove trailing whitespaces.
- Always keep an empty line at the end of the file.
- Order the spells by number (this helps spot duplicates).
- Simple numbers go first, then nested lists.
- Keep similar lines together.
- Use inline comments in class files.
- Put the spell name in the comment behind the spell id.
- Put the specialization(s) for which the spell is available after the spell name, unless the spell is shared among all specs of the given class.
- For non-baseline spells, put the source (talent, pvp, artifact) in the comment.
Example
lib:__RegisterSpells("HUNTER", 80000, 1, { -- 1 is the revision number
COOLDOWN = { -- ascending number order
781, -- Disengage -- indent with tabs, align with spaces
19434, -- Aimed Shot (Marksmanship) -- numbers aligned to the right
109304, -- Exhilaration -- baseline, all specs
120360, -- Barrage (Marksmanship talent) -- single-spec talent
198670, -- Piercing Shot (Marksmanship talent) -- simple numbers go first
212431, -- Explosive Shot (Marksmanship talent)
257044, -- Rapid Fire (Marksmanship)
INTERRUPT = { -- nested lists come after
147362, -- Counter Shot (Beast Mastery, Marksmanship) -- two specs baseline
187707, -- Muzzle (Survival)
},
},
}Every class file calls __RegisterSpells which takes 7 arguments:
-
lib- the LibPlayerSpells object -
class- the English class name (as the second return value ofUnitClass) (string) -
interface- the interface version (as the fourth return value ofGetBuildInfo) (number) -
revision- the revision number for the spell data (number) -
spells- the spell list (table) -
providers- the mappings between the spells and their providers (table) -
modified- the mappings between the spells and the modified spells (table)
The interface argument should represent the game version for which the spell data was collected.
The revision argument should be incremented every time you make your changes public.
The spells argument is a table containing the spells grouped into categories (see Grouping Spells).
The providers argument is a table which holds information about the provider spells (see Providers).
The modified argument is a table which lists the modified spells (see Modified Spells).
A spell can belong to one or more of the following categories (in CAPS on the image): 
The grouping can be done like
[147362] = 'COOLDOWN INTERRUPT' -- Counter Shot (Beast Mastery, Marksmanship)or
COOLDOWN = {
INTERRUPT = {
147362, -- Counter Shot (Beast Mastery, Marksmanship)
},
}or even
COOLDOWN = {
[147362] = 'INTERRUPT', -- Counter Shot (Beast Mastery, Marksmanship)
}or a combination of the above.
The order in which the groups are listed is irrelevant.
A combination of the second and third variant is generally the best for grouping multiple spells.
Dispels and crowd control spells must always enlist their respective superordinate group:
[3355] = 'CROWD_CTRL INCAPACITATE' -- only specifying INCAPACITATE is not enough!All spells listed under AURA or DISPEL must provide one targeting group:
DISPEL = {
[ 370] = 'HARMFUL MAGIC', -- Purge removes magical effects from enemies
[51886] = 'HELPFUL CURSE COOLDOWN', -- Cleanse Spirit removes curses from allies (and has a cooldown)
}Every spell under the AURA group is listed by its aura id and must accordingly have an associated buff or debuff in-game. All other spells are listed by their actual spell id.
Those are the spells that make other spells available. E.g. 3355 is the aura id of "Freezing Trap", but the actual spell id of "Freezing Trap" is 187650. This makes 187650 the provider spell for 3355 as it is the only way for the player to apply the "Freezing Trap" debuff. This type of relation is held in the providers table passed to __RegisterSpells as an auraID - spellID pair like so:
[3355] = 187650 -- Freezing TrapIf there are multiple providers for a given aura, you can enclose them in a table:
[auraID] = {
spellID_1,
spellID_2,
}Every spell from the spells list that has no corresponding entry in the providers table should be considered its own provider, meaning the aura id and the spell id coincide. An example here is "Trueshot", where both the buff and the spell itself have the same id - 193526, so there is no need to list "Trueshot" explicitly in the providers table.
Sometimes certain abilities modify others. E.g. the "Posthaste" buff is applied by "Disengage" but only when the "Posthaste" talent has been selected by the player. This type of relation is held in the modified table passed to __RegisterSpells in the same manner provider spells are listed in the providers table (auraID - spellID pair):
[118922] = 781, -- Posthaste (Marksmanship talent) -> DisengageThe main focus of LibPlayerSpells is to provide information for display addons like AdiButtonAuras, so they know how to map certain auras to certain buttons on your action bars. In the case of "Posthaste" AdiButtonAuras will know to show the duration of the "Posthaste" buff on the action button for "Disengage". But let's consider the Marksmanship hunter passive ability "Trick Shots" (spell id 257621). Technically it modifies "Multi-Shot" - when "Trick Shots" is known, "Multi-Shot" could apply the "Trick Shots" self buff (aura id 257622). However this buff is consumed by either "Aimed Shot" or "Rapid Fire", so it is more beneficial to display "Trick Shots" duration on its consumers instead of on the modified spell. For this reason the mapping in the modified table could be done this way:
[257622] = { -- Trick Shots (Marksmanship)
19434, -- Aimed Shot
257044, -- Rapid Fire
},A rule of thumb for this kind of scenario could be:
- if the aura applied by the modified spell is consumed by other spells, list them as the modified spells
- if the applied aura is not consumed, but rather modifies other spells for its entire duration, list the modified providing spell only
- if uncertain, list both the consumers and the modified spell (display addons could provide end users with an option to toggle the aura information per button)
local lib = LibStub('LibPlayerSpells-1.0')
if not lib then return end
lib:__RegisterSpells('HUNTER', 80000, 1 {
AURA = {
PERSONAL = {
257622, -- Trick Shots (Marksmanship)
},
},
}, {
-- map aura to provider(s)
[257622] = 257621, -- Trick Shots (Marksmanship)
}, {
-- map aura to modified spell(s)
[257622] = { -- Trick Shots (Marksmanship)
19434, -- Aimed Shot
257044, -- Rapid Fire
},
})This tells that "Trick Shots" (257622) is a self-buff provided by 257621 (the "Trick Shots" passive ability) and it modifies both "Aimed Shot" and "Rapid Fire". It is not a cooldown because neither "Multi-Shot" (the ability which actually applies the buff) nor the passive "Trick Shots" have a cooldown.
You can use the "Debugging Tooltip" option of AdiButtonAuras to display spell ids in tooltips in-game. Data is then gathered manually which can be time consuming depending on your knowledge of the class. Use AdiButtonAuras to verify it generates the rules correctly.