This issue is intended to document the steps to submit a pull request for new buffs, be it mechanic buffs from encounters or profession buffs. If submitting new profession buffs, only full profession coverage will be accepted (i.e., you can't submit a PR for half a profession's buffs, even if those buffs are not commonly used).
Buffs are only acceptable if they display a buff icon in the game's standard buff bar or if they display a distinct visual effect on screen (e.g., the teleport AoEs on Vale Guardian showing a bright screen border).
To submit a PR, the following two pieces must be included:
An update to <repo>\GW2Clarity\src\BuffsList.inc.
The new buff icons, if any, in <repo>\GW2Clarity\assets\atlas.
Buffs List
The BuffsList.inc file follows a simple format: one buff is described each line, surrounded by braces, with a comma separator between each. Don't forget the trailing comma on each entry!
Headings
Headings are the simplest: just write the heading in between double quotes:
{ "This is a heading" },
The heading will be associated with every buff that follows it, until a new heading is defined. The buffs will then be sorted alphabetically by Clarity in each section, so no need to worry about writing them in any specific order.
Buffs
Buffs themselves have a few more parameters. Every buff will start by its ID: this can be found on the wiki, but take great care: the ID of the skill and its buff are different! For example, Skelk Venom has an ID of 21778 (you can hover on the "Game link" chat code to see it), but Skelk Venom (effect) is the actual buff that is applied and its ID is 21780 (this is the ID we want).
In some cases, a buff may have multiple associated IDs (e.g., a skill is modified by a trait but remains the same skill from a user standpoint). You can describe this by writing multiple IDs in braces, e.g. { { 1, 2 }, ... },.
The second buff parameter is always the display name. This will be shown in the menus. If the name itself has double quotes (most often shouts), escape them with a backslash: "\"Sic 'Em!\"".
The third parameter is optional and is the name of the original texture stored in the atlas folder (see next part). By default, Clarity will determine the texture's name by converting the display name to lowercase and replacing spaces and double quotes with underscores (` and"to_`). However, certain special characters are not allowed in file names, and there are instances where multiple buffs reuse the same icon. For these scenarios, you can manually input the texture's name here.
The final parameter (which can be third or fourth depending on whether the texture name is present) is also optional and indicates the maximum number of stacks that the game uses. For instance, Bleeding stacks to a maximum of 1500, while Might stacks to 25 and Alacrity stacks to 1. If you do not know the maximum, omit this parameter and Clarity will put no cap (but remember that any number of stacks above 25 is simply displayed as ">25").
The process to prepare an icon for use is then as follows:
Rename it as appropriate (see last section on the atlas name). For our example, this would be skelk_venom.png.
In your image editor of choice, trim any black or transparent border around the image.
Still in the image editor, resize the image to 32x32.
Save it in <repo>\GW2Clarity\assets\atlas.
If the image name does not follow the automatic pattern, don't forget to update the name in the buffs list entry!
Submission
Once you have generated both the buffs list and the atlas images, you can make a PR. I will quickly review the changes to make sure they look fine, and then activate the CI pipeline to generate a build. You can then use this build to immediately test your changes and see if they work, and make changes as necessary. Alternatively of course, you can develop, build and test locally if you are familiar with C++ and have a working Visual Studio 2022 installation.
Since testing would be hard to demonstrate, I will be working on a good faith basis: once you have run testing and have verified that all of your submitted buffs work, please let me know in the PR and I will merge it in.
If this long-winded process interests you and you want to help: thank you. I hope to see your PR in the near future!
This issue is intended to document the steps to submit a pull request for new buffs, be it mechanic buffs from encounters or profession buffs. If submitting new profession buffs, only full profession coverage will be accepted (i.e., you can't submit a PR for half a profession's buffs, even if those buffs are not commonly used).
Buffs are only acceptable if they display a buff icon in the game's standard buff bar or if they display a distinct visual effect on screen (e.g., the teleport AoEs on Vale Guardian showing a bright screen border).
To submit a PR, the following two pieces must be included:
<repo>\GW2Clarity\src\BuffsList.inc.<repo>\GW2Clarity\assets\atlas.Buffs List
The
BuffsList.incfile follows a simple format: one buff is described each line, surrounded by braces, with a comma separator between each. Don't forget the trailing comma on each entry!Headings
Headings are the simplest: just write the heading in between double quotes:
{ "This is a heading" },The heading will be associated with every buff that follows it, until a new heading is defined. The buffs will then be sorted alphabetically by Clarity in each section, so no need to worry about writing them in any specific order.Buffs
Buffs themselves have a few more parameters. Every buff will start by its ID: this can be found on the wiki, but take great care: the ID of the skill and its buff are different! For example, Skelk Venom has an ID of
21778(you can hover on the "Game link" chat code to see it), but Skelk Venom (effect) is the actual buff that is applied and its ID is21780(this is the ID we want).In some cases, a buff may have multiple associated IDs (e.g., a skill is modified by a trait but remains the same skill from a user standpoint). You can describe this by writing multiple IDs in braces, e.g.
{ { 1, 2 }, ... },.The second buff parameter is always the display name. This will be shown in the menus. If the name itself has double quotes (most often shouts), escape them with a backslash:
"\"Sic 'Em!\"".The third parameter is optional and is the name of the original texture stored in the atlas folder (see next part). By default, Clarity will determine the texture's name by converting the display name to lowercase and replacing spaces and double quotes with underscores (
` and"to_`). However, certain special characters are not allowed in file names, and there are instances where multiple buffs reuse the same icon. For these scenarios, you can manually input the texture's name here.The final parameter (which can be third or fourth depending on whether the texture name is present) is also optional and indicates the maximum number of stacks that the game uses. For instance, Bleeding stacks to a maximum of 1500, while Might stacks to 25 and Alacrity stacks to 1. If you do not know the maximum, omit this parameter and Clarity will put no cap (but remember that any number of stacks above 25 is simply displayed as ">25").
Some examples:
{ 9113, "Virtue of Courage" },{ { 9220, 46554 }, "Signet of Resolve" },{ 740, "Might", 25 },{ 10497, "50% Magic Find Boost", "magic_find_boost" },{ { 34912, 34925 }, "Statue Fixated", "fixated", 1 },Atlas
The second part of the process is adding the buff icons to the addon. The simplest way to do so is to copy the icons from the wiki. Taking the Skelk Venom (effect) example, you can get the icon image URL (https://wiki.guildwars2.com/images/7/75/Skelk_Venom.png).
The process to prepare an icon for use is then as follows:
skelk_venom.png.<repo>\GW2Clarity\assets\atlas.Submission
Once you have generated both the buffs list and the atlas images, you can make a PR. I will quickly review the changes to make sure they look fine, and then activate the CI pipeline to generate a build. You can then use this build to immediately test your changes and see if they work, and make changes as necessary. Alternatively of course, you can develop, build and test locally if you are familiar with C++ and have a working Visual Studio 2022 installation.
Since testing would be hard to demonstrate, I will be working on a good faith basis: once you have run testing and have verified that all of your submitted buffs work, please let me know in the PR and I will merge it in.
If this long-winded process interests you and you want to help: thank you. I hope to see your PR in the near future!