How To Contribute
Thanks for your interest in improving the WoW-Pro Addon!
There are two ways to help out with the leveling guide: testing and revising.
Testing doesn’t require anything but the newest addon files and a character of the appropriate level. Simply take detailed notes as you play through the guide and post any mistakes you find using our Bug Reporting page or in the addons Discord Server. It will be corrected next time that section is worked on.
Revising guide files requires a little knowledge of the syntax (language) the addon is written in. The language is actually pretty simple and easy to learn. This guide will provide that knowledge. Both testing and revising are needed to make this guide great, but most useful if you can edit the files yourself rather than just pointing out the mistakes.
Communication is key! Make sure you use the systems in place when helping us to test or revise the guides. This keeps people from editing the same guide at once and causing confusion! To “check out” a guide for revision, make an issue on the issue page. Use “Revising: GUIDE FILE NAME” as the subject, replacing GUIDE FILE NAME with the name (and faction, if relevant) of the file you are revising. No one else should work on this file while the person listed is editing it. If you suspect the person is no longer working on the file, leave a comment – if it’s not responded to in a few days, you can work on the file.
Syntax – This refers to the code the guide files are written in.
Step – An individual objective in the guide.
Tag – An addition to the step that adds detail and essential information.
QID – the Quest ID, a unique number the game and addons use to identify a specific quest.
You can find the addon and supporting files, along with instructions on how to download and use them, here on github, on WoW-Pro, on WoW Interface, or Curse. Familiarize yourself with the way the guide works in game before you start working on the code.
I highly recommend Notepad ++ as an editing program. It organizes things very nicely and has some basic features that help with coding, and is free to download. However, you can use the basic notepad programs that come with your computer if you prefer.
Find a guide you want to work on, that [i]no one is currently signed up for[/i]. To “check out” a guide for revision, make an issue on the issue page. Use “Revising: GUIDE FILE NAME” as the subject, replacing GUIDE FILE NAME with the name (and faction, if relevant) of the file you are revising. No one else should work on this file while the person listed is editing it. If you suspect the person is no longer working on the file, leave a comment – if it’s not responded to in a few days, you can work on the file.
First, you’ll need to find the section you want to work on in the addon files. The naming format is as follows: “002_43_44_Jame_Dustwallow_Marsh”, where the first number is just a placeholder used to help organize the guides (ignore it), the second is the starting level, the third is the ending level, followed by the author and zone name.
It is probably easiest to edit guides with WoW running in windowed mode. This is a mode for WoW that you can get to through your video options in game. I usually have one browser window open with a tab for the written guide and a tab or two for WoWhead, my Notepad++ window, and WoW all running at once, and alt+tab between them.
Now you should be ready to start editing!
As you write or revise a guide, the most important thing to realize is that the WoW-Pro addon works in steps rather than paragraphs. This can sometimes make it a little difficult to translate “paper” guides into addon form. Follow the formatting guidelines below if you get confused.
Most of the time you will be revising a guide already in place. However, if you want to create a new guide, you’ll need to start off by inputting the following code:
WoWPro_Leveling:RegisterGuide("HosBar1221", "The Barrens", "Hosho", "12", "21", "JamSto2122", "Horde", function()
return
[[
INSERT GUIDE CODE HERE
]]
end)
This will of course have to be modified to accommodate the guide you’re writing. The different portions of the register guide function are:
-
The function
The actual name of the function we are calling is changing from WoWPro:RegisterGuide to WoWPro_Leveling:RegisterGuide. -
The Guide ID
The next section, “HosBar1221” in the example, is the Guide ID (or GID). This was implemented as a means to give guides a unique ID since zones and authors and level ranges separately might overlap. The GID consists of:- The first three letters of the author’s name (Hos for Hosho in this case)
- The first three letters of the guide zone (Bar for Barrens in this case)
- The level range in double digits (1221 for 12-21 in this case. If the level is single digits, add a 0 (01 for 1, for example)
-
The zone
Pretty self explanatory. “The Barrens” in the example. This can be any text you like, and will display under the “Zone” heading in the Leveling-Guide List. -
The author
Again pretty simple. “Hosho” in the example. -
Starting level
The level (in double digits) that the guide starts at. “12” in the example. -
End level
The level (in double digits) that the guide ends on. “21” in the example -
Next GID
See GID above for an explanation of how this ID code works. This is the ID code for the next guide in sequence. In this case, the guide will automatically load Jame’s Horde Leveling Guide for Stonetalon Mountains, level 21 (“JamSto2122”).
-
Faction
The faction the guide is intended for. Can be Horde, Alliance, or Neutral.
The file should be saved as a .lua file with the name formatted like:
SectionCode_BeginningLevel_EndingLevel_Author_Zone.luaEach step in a guide must fall under one of the following types. Each step must also have it’s own line in the guide. You can separate them with blank lines (this can really help readability for people revising the guide), but make sure that those lines have NOTHING on them. It will keep the guide from loading if they have anything other than the following types of steps.
Example:
A Wanted: Dreadtalon |QID|12091|N|From the Wanted Poster just outside the door.|Use this every time you direct the player to accept a step.
Example:
C Blood Oath of the Horde |QID|11983|N|Talk to the Taunka'le Refugees and go through the text until you complete the quest.|Use this when the player is completing all of the steps of a quest at once. If you are planning to split up the quest complete steps, you can still use this type of step, but you need to add quest objective tags (|QO|) to it.
If you want to mark a complete step as being non-combat, add a |NC| tag!
Example:
T The Flesh-Bound Tome |QID|12057|N|Back at Agmar's Hammer.|Use this every time you direct the player to turn in a step.
Example:
H Warsong Hold |QID|11686|U|6948|These steps are all really variations on the same type – a location change. The step auto-completes when the subzone or zone name matches the specified one (in the example above, the step would complete when the character enters Warsong Hold). Hearth steps will automatically provide a use button with the hearth stone on it. Run steps can auto-complete when the given, specific coordinate(s), instead of the zone, is reached, using |CC| or |CS| tags (see below).
Example:
h Warsong Hold |QID|11598|N|(41.9,54.5)|Make sure to spell the town’s name exactly correctly, or it won’t auto complete correctly. Auto-completes on the message “TOWNNAME is now your home.”
Example:
f Moa'ki Harbor|QID|11585|N|(48.5,74)|Z|Dragonblight|Most of the time a flight point is fairly easy to spot, but occasionally they can be a bit out of the way. In these cases, use this step to ensure the player finds it.
Example:
K Fjord Crows |QID|11227|L|33238 5|N|Until you have 5 Crow meat.|Whenever possible add a loot or quest objective tag so that this step will auto-complete. Remember that you can use sticky steps (explained below) for times when a quest or step is completed over time as opposed to right away.
Example:
N Burn The Kur Drakkar |QID|11656|QO|The Kur Drakkar destroyed: 1/1|U|34830|N|To the north, just next to The Serpent's Maw.|Note steps are used when none of the above steps fit, always try to add some kind of tag to allow this to auto-complete. Use these as sparingly as possible, as the user won’t get a visual cue on what to do.
Example:
B Fresh Pound of Flesh |QID|11309|L|33612|N|Anton patrols along the road between New Agamand and the Ancient Lift. If he's dead, he respawns at (53,74).|I find these two to be mostly cosmetic as you can do the same job using a Note step with a Loot and Use tag.
Behaves exactly like a N step in that it must be checked off, but has a nice repair/restock icon.
This tag is REQUIRED for every step.
Even on a step that has nothing to do with any quest (e.g. Hearth steps) it is still important to have this tag there as well. Use the ID of a quest which, if completed, means the user no longer needs to complete that step.
Example:
C Watchtower Burned |QID|11285|QO|Winterskorn Watchtower Burned: 1/1|U|33472|N|The watchtower is directly to your west, burn it.|
C Bridge Burned |QID|11285|QO|Winterskorn Bridge Burned: 1/1|U|33472|N|Head behind the tower and go west to the bridge, burn it.|
C Dwelling Burned |QID|11285|QO|Winterskorn Dwelling Burned: 1/1|U|33472|N|Over the bridge, just west, is a small building, set it alight as well.|
C Barracks Burned |QID|11285|QO|Winterskorn Barracks Burned: 1/1|U|33472|N|The final structure is to the northwest, careful not to aggro the elite when you light it up.|A |QID| tag is required for this tag to function. This is used for quests where you won’t be completing all objectives at the same time or when the objective locations are very specific and static.
Please note that the addon is smart enough to know that when you use a QO tag, you want it to be have like a QO step, NOT a C step – so you can still use the C step type to get the nice icon for users to see. The quest tracker will only track the correct quest objective, and the step will auto-complete when that objective is complete.
This tag makes the step optional and will only show if the player has the quest in their quest log. Use this on an Accept step with a Use tag and it will only show if the player has the item in their bags, useful for quests that come from items. You can also use the |PRE| tag with it to only display the objective if the quest with the QID listed in the |PRE| tag has been completed.
This is used with the Optional tag to only show the step if the player has turned in the quest with the ID used in this tag. Also used in quest skipping logic, so please start using it for every quest that has a prerequisite, optional or not! You only need to use this on Accept steps, the guide will extrapolate from there.
You don’t need to include previous steps in the chain with this tag, just the most recent. However, you CAN include multiple prerequisites if it is applicable by adding a ; (semicolon) in between the quest IDs.
Used when you need to make sure the player has a specific item or amount of an item in their bags. Add the quantity after the item number with a space in between. If you only need one of an item, you do not need to specify a quantity.
This will create a movable button for the item specified so you don’t have to dig through your bags to find it. This is mandatory for every Hearthstone step (item #6948)
These will only show the step if you are playing the specified class/race. Use commas to separate entries to list more than one race or class.
These will only show the step if you are playing the specified faction.
A general note for the step to add additional information. \n provides a force line feed so that information can be seperated into seperate lines. Please try to limit these to one or two sentences.
List coordinates here. You can list multiple coordinates by separating them with semicolons (;). Make sure you list coordinates for every step! We are no longer using Lightheaded, and POI support has not been added yet (though it is planned).
Use this tag if the step goes outside the zone for the guide. IMPORTANT – if you don’t use this tag and the coordinates are not in the guide’s title zone, they will show up WRONG.
These are for do-as-you-go steps. Use |S| on the do as you go message. Use |US| on a step with the same name when you want to have the user actually complete the step.
Example:
C Galgar's Cactus Apple Surprise|QID|4402|N|Loot Cactus Apples from Cactuses|S|
C Vile Familiars|QID|792|N|Work on your other objectives on the way to the Vile Familiars in the north.|M|44.7,57.7|
C Galgar's Cactus Apple Surprise|QID|4402|N|Loot Cactus Apples from Cactuses|US|M|44.7,57.7|In this example, the user is instructed to pick up cactus apples while killing vile familiars. Once they kill all the familiars they need, the stickied cactus apple step becomes a normal step.
Use this tag to denote a step that completes once the user reaches that level. There is also a new step type, L, to denote a step that completes once the user levels up.
Use for lead in or breadcrumb type quests, followed by the QID for the quest it leads to. This step will be checked off if the user has already completed the quest it leads up to.
Follow by the name of the mob or NPC you want the user to be able to target.
Follow by the name of the profession, and optionally the level of the profession required for the step. The step will only be displayed if the character has that professions at that level.
Follow by either Male| or Female|. The step will only be displayed if the character is either Male or Female.
Followed by Faction and Faction ID (ex. Scryers;934). The step will only be displayed if you have that faction. Additional options seperated by semicolons are starting alignment and ending alignment/or faction level.
Use either of these flags with Run ( R ) in order to auto-complete the step when the coordinate (or set of coordinates), given in the |M| tag, is reached. If you are using a set of coordinates, the |CS| tag will make the step auto-complete only when the player follows the coordinates in sequence, from the first to last (final) coordinate, and the |CC| tag will make it auto-complete when the player reaches the final coordinate, regardless of the previous ones.
This tag should be used as much as possible from now on, and denotes how important a quest is. 1 is the most important and will NEVER be skipped. 3 is the least important. Vital quest chains with great XP and item rewards should be marked 1. Things that are neutral in rewards but which are convenient to do should be a 2. Things that take you out of your way and aren’t particularly rewarding should be marked a 3. Anything unmarked will be considered a 1. In general, a character with heirlooms and RAF should be able to get through the guide on a setting of 1, while a character with none of these bonuses and who doesn’t do instances or have rested would need a setting of 2. 3 is more for completionists trying to get as many quests done as possible.
The only other note to this: If you use a rank tag, you must make sure all quests following that one in a chain must have the same rank or higher. We don’t want the user to be instructed to pick up a quest that he or she has not done the prerequisites for.
More specific descriptions:
You don’t need to use it, it’s implied if no rank is listed. Never skipped no matter what setting. Use for quest chains that lead to the “final” quest in the zone. I’m not sure how the high level zones go, but for the mid level ones there is usually one quest that yields very high quality rewards and “finishes” the story for that zone. All quests leading up to and including this kind of a quest should be rank 1.
These steps are only skipped by people on the lowest completion setting. Use this for quest chains that don’t lead to the “final” quest – though NOT if there are a ton of quest chains like this. I would say as a general guideline, between 1/4 and 1/3 quests should have this tag.
Really our of the way or annoying quests with little return. I haven’t been using it too often. Something the typical user would NOT want to do, something only completionists would want to do.
Used with the C step, this suppresses the display of the step if the player is in combat.
These are some guidelines to help you keep your guide file easy to read and useful to the user.
If it’s at all possible to set a step to auto-complete, do so. Sometimes this means breaking something into multiple small steps. Try to put things in a logical order, and use the |N| note tag to remind players of other objectives. Make use of sticky steps!
Anytime you can provide an arrow for the player to follow, it greatly improves the guide. Rather than making them read a huge block of text as directions, just have them “follow the arrows” and list a series of coordinates. Try to be as exact as possible, since you want the series to flow naturally, so put the steps in places the player would naturally run. Make sure you test these series, since sometimes TomTom will jump to the nearest coordinate rather than the next in the series.
You can even use these arrows for steps you wouldn’t initially think of, such as sell/repair, hearthstone setting, flight paths, or docks/zeppelin towers. We want our users to be able to completely relax and just follow the arrows!
Try to keep it to one sentence notes when possible. The less reading, the faster leveling! Remember, use arrows instead of wordy directions. Don’t hesitate to give advice for confusing or hard to complete steps, though.
Using the |C| class tag, you can incorporate class quests into the guide wherever they would best fit. The goal is to include all necessary class quests – please note that some are definitely NOT necessary, such as the druid poison quest or the paladin sense undead quest.
Use the |O| optional tag to allow players the choice of small optional circuits. This is great for people leveling in a group who might be able to tackle mobs that are too hard for the normal leveling crowd.
Use the |U| use tag to help players complete quests without digging through their bags to locate quest items. You don’t need to provide this for hearth steps, since it is added automatically.
Using the |B| buy tag after a sell/repair step to check if the player still has the necessary item in his or her back, and provide text warning them to buy it back if the step does not auto-complete. The warning will automatically disappear once they buy it back.
Leave blank lines between steps when the location changes. This really helps when revising code.
Sticky steps are one of the most powerful features in our addon. Use them whenever the user needs to complete multiple steps in the same small area, or needs to look out for something as they go.
It’s no longer necessary to worry about quests that have the same name (such as multiple part quests) – the addon recognizes quests by their QID instead of their names. So you don’t need to put (Part 1) etc. in the step name anymore – in fact, you should NOT do this!
If you don’t do this, the coordinates will point back to the title zone. This can really lead users astray, so make sure you add the zone tags and test your guides before uploading them!
Okay, so you’ve written your guide, and now what? Play-test it.
If this is a new guide, first make sure it is inside the WoWPro_Leveling/Horde or WoWPro_Leveling/Alliance folder. Then, open up the Guides.xml file in that folder. This file is basically an index that tells the addon which guides to load. The syntax is:
<Script file="file name"/>What you need to do is add your guide into this file. That’s it, then you can fire up the game and it should load, ready for testing.
It’s often very useful to revise the guide while playing. When you make a revision, you can reload the addon without logging out by using the following macro:
/reloadOnce you have your guide up to snuff, it’s time to upload it and share it with the wow-pro community. If you are comfortable using git and would like git access, please send a private message to Ludovicus on Discord. This is the easiest way to upload your work, if you are comfortable with it.
If you aren’t that’s fine! Here’s what you can do:
- If it’s easier for you, you can also attach the file to a support post on WoW-Pro’s Discord.