WoW-Pro Addon Syntax
With the WoW-Pro Recorder, you don't really need to know the syntax (the language the guide files are written in) unless you really want to. However, taking a look at this syntax can help you understand how the addon works and can help you do a better job of writing and designing guides for the addon.
Remember, if you have any specific questions about the addon's syntax, feel free to ask in chat!
- Step Types
- |ACH| – Achievement
- |ACTIVE|####| – Active Quest ID
- |AVAILABLE|####| – Available Quest ID
- |BUFF| – Unit Buff
- |BUILDING| – Building Detector
- |C|Priest,Mage,…| – Class
- |CC| – Coordinate Auto-complete
- |CHAT| – Chat
- |CN| – No Coordinate Auto-complete
- |CS| – Coordinate Auto-complete in Sequence
- |L|####| – Loot
- |LEAD| – Lead In Quest
- |LVL| – Level
- |N|…| – Note
- |NA| – Not Automatic
- |NC| – Non-Combat
- |M|55.55,55.55| – Mapping
- |O| – Optional
- |P| – Profession
- |PET| – Pet Detector
- |PRE|####| – Prerequisite
- |QG|Some text| – Quest Gossip
- |QID|####| – Quest ID
- |QO|Some Mob slain: 10/10| – Quest Objective
- |R|Orc,Troll,…| – Race
- |RANK| – Rank
- |RECIPE| – Recipe
- |REP| – Reputation
- |S| – Sticky
- |T| – Target
- |U|####| – Use
- |US| – Un-Sticky
- |Z|Zone Name| – Zone
To start with, I suggest working with a guide that has already been coded, rather than trying to start from scratch.
The leveling guides can be found in Addons\WoWPro_Leveling\Alliance (or Horde). Go ahead and open one up in your favorite simple text editor. Do NOT use Microsoft Word or a similar rich text editor - the formatting used by these programs will break your guide file.
I highly recommend the free program Notepad++, as do most addon authors - it's very powerful yet simple for beginners, with a very user-friendly interface.
Once you open up the file, you should see something like the following:
local guide = WoWPro:RegisterGuide("LudoExpDaS","Achievements","Darkshore","Ludovicus", "Neutral") WoWPro:GuideLevels(guide,20,90) WoWPro:GuideIcon(guide,"ACH",844) WoWPro:GuideProximitySort(guide) WoWPro:GuideSteps(guide, function() return [[ INSERT GUIDE CODE HERE ]] end)
In the example, where I say "INSERT GUIDE CODE HERE", you'll see many lines of code. We'll talk about those in a minute. For now, we're going to talk about the guide registration functions.
The guide registration functions are what tells the addon the overall information about the guide. It contains several important parts, as follows:
- The function
- The actual name of the function we are calling: WoWPro:RegisterGuide
- The Guide ID
- The next section, “LudoExpDaS” 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 few letters of the author’s name (Ludo for Ludovicus in this case)
- The first few letters of the guide zone or type (Exp for Explore in this case and DaS for Darkshore)
- For leveling guides, the level range in double digits (0112 for 01-12 for example) is appended.
- The zone
- Pretty self explanatory. “Darkshore” in the example. This has to be a valid zone, but can be a continent or even "Azeroth".
NOTE1: You can provide more information about the guide after a - or a (. For example, a valid zone entry would be Scarlet Enclave (Death Knight) or Durotar - Valley of Trials.
- The author
- Again pretty simple. “Ludovicus” in the example.
- The faction the guide is intended for. Can be Horde, Alliance, or Neutral.
- The guide object is returned, which you can now feed into some additional functions to more fully describe the guide.
- WoWPro:GuideLevels(guide, start_level, end_level, mean_level)
- The starting, ending and average level for the quests in the guide.
It is not what level you will end up at by doing the guide, it is the required level to get the quests even if you have XP locked down.
The start_level controls when a guide will be offered to the user. The mean level sets the "color" of the guide to indicate difficulty.
The end_level controls a warning to XP locked users that not all quests in the guide can be completed.
- WoWPro:GuideIcon(guide, icon_type, icon_reference)
- The icon to associate with the guide.
With an icon_type of "ACH", the icon_reference is the achievment number (like the "Did ## quests in Tanaris").
With an icon_type of "PRO", the icon_reference is a profession number.
With an icon_type of "ICON", the icon_reference is an icon path.
For Achievement guides, setting the correct icon_reference is doubly important, as it also sets the guide name, class and subclass from the game fucntions
- WoWPro:GuideClassSpecific(guide, class)
- Tells the system that this guide is restricted to a particular class. Used for the "DeathKnight" only starting zone.
- WoWPro:GuideRaceSpecific(guide, race)
- Tells the system that this guide is restricted to a particular race. Used for the "Goblin" or "Worgen" starting zones.
- Tells the system to sort the steps in order of proximity every time you complete a step.
- Tells the system which guide to offer as the next guide. For a neutral guide you can use two GIDs separated by a "|" for each faction (Alliance first).
- WoWPro:GuideSteps(guide, ...
- Register the function which returns the big "[[ ... ]]" quoted string of all the guide steps.
- Fancy things:
But this is really LUA code we are running, so we can do fancy things here. Look at this!
WoWPro:GuideIcon(guide,"Icon", WoWPro:GuidePickGender( "Interface\\Icons\\Achievement_Character_Dwarf_Male", "Interface\\Icons\\Achievement_Character_Dwarf_Female"))
This picks an icon for the Dwarf starting zone depending on the gender!
Finally, to the meat of the guide. Each line of code represents one step in the guide. You can have blank lines if you like to help break up the big block of code, but make sure they are COMPLETELY blank. A single space on an otherwise blank line can cause the guide to not load!
For each line, You have several fields of import. The first is the step type, represented by a single uppercase character at the front of the line followed by a space. Step types tell the addon what icon to display, and can also tell the addon how to auto-complete the step.
Right after the step type, you'll see the step text. For quests, this will be the quest name. For location-based steps (run to, fly to, hearth to, etc) this will be the zone or sub-zone name. For other steps, it can vary.
After the step text come the tags, and this is where most of the "coding" comes into play. Some tags are required, some are not. These tags help the addon know how to handle the step, whether to display a note, where to map the coordinates, and more.
Use this every time you direct the player to accept a step.
A Wanted: Dreadtalon |QID|12091|N|From the Wanted Poster just outside the door.|
- When a quest of the specified QID newly appears in the user's quest log.
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!
C Blood Oath of the Horde |QID|11983|N|Talk to the Taunka'le Refugees.|
- When the quest of the specified QID is marked (complete) in the user's quest log.
- Use a |NC| tag to mark the step as non-combat, giving it a cog icon instead of crossed swords.
- Use a |QO| tag to make the step complete based on one quest objective rather than all of them.
Use this every time you direct the player to turn in a step.
T The Flesh-Bound Tome |QID|12057|N|Back at Agmar's Hammer.| t Test Your Strength|QID|29433|M|48.06,67.05|N|To Kerri Hicks.|
- When the quest of the specified QID disappears from the user's quest log or after viewing the completion page for the quest.
- For a "T" step, if the completion criteria for the quest have not been met, the step will not be skipped. So use a C step if you need it done.
- For a "t" step, if the completion criteria for the quest have not been met, the step will be skipped. When it is completed, the "t" will step magically reappear.
These steps are all really variations on the same type – a location change.
Hearth steps will automatically provide a use button with the hearth stone on it.
H Warsong Hold |QID|11686|U|6948|
- When the subzone or zone name matches the specified one.
- Use a |CC| tag to make the step complete when the user reaches a coordinate, rather than a zone name.
- Use a |CS| tag to make the step complete when the user passes through a series of coordinates, rather than based on the zone name.
Instructs the user to set their hearthstone. Make sure to spell the town’s name exactly correctly, or it won’t auto complete correctly.
h Warsong Hold |QID|11598|N|At the innkeeper.|
- Auto-completes on the message “TOWNNAME is now your home.”
Instructs the user to get the flightpath. While convention suggests you use the subzone name as the step text, it's not required.
f Moa'ki Harbor|QID|11585|Z|Dragonblight|
- Auto-completes on the UI message "New flight point discovered". Does not require or use a subzone name.
None of these steps auto-complete on their own. They all behave exactly the same, and you should supply a tag to help them auto-complete if at all possible. Avoid the N type step as much as possible since it doesn't give the user any visual cue on what to do.
K Fjord Crows |QID|11227|L|33238 5|N|Until you have 5 Crow meat.|
- IMPORTANT: This step has no auto-completion on it's own! You'll need to supply a tag to do that. Commonly used tags include |L| and |QO|. The above example uses a |L| tag.
Use this to put a comment into the guide. Since the guide lines are in a LUA bracket quote pair, you can not use a LUA double hyphen (--) to comment out a line.
; Begin Class specific training quests for Level 3 A Steady Shot|QID|14007|M|60.26,77.54|N|From Bamm Megabomb.|Z|Kezan|C|Hunter|
When the parser encounters a comment step, it records the line, but does nothing with it. Empty lines or lines of just whitespace are discarded. Use of comments by guide writers is encouraged, particularly when you do something clever or complicated. A ; after a step also starts a comment, but is discarded by the parser. Hence, the first type of comment is visible when viewing the guide step in game if debug mode is enabled, but the second is not.
Use this to register a quest tagged treasure in the game. Many treasures in the game have a flag quest behind them that is completed upon looting the treasure.
$ Gurun|QID|34839|M|47.00,55.20|Z|Frostfire Ridge|ITEM|111955|N|And [money=120.00]|
A QID is required for this type of step. The primary item should be indicated in the ITEM tag. Any secondary rewards should be in the note.
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.
A Wanted: Dreadtalon |QID|12091|N|From the Wanted Poster just outside the door.|
- Regardless of what other tags the step has, if the addon detects that the QID quest has been turned in, this step will complete.
This tag will skip the step if the given quest is not active. I.e. you need to be on this quest, but not have completed it.
A The Grand Melee|QID|13761|ACTIVE|13717|M|76.40,19.00|N|From Airae Starseeker.|
This tag will skip the step if the given quest is not available. I.e. you need to not be on the quest or have completed it.
R Go here for Grand Melee|AVAILABLE|13717|M|76.40,18.00;76.40,19.00|N|Take this path|
This is used for quests where the NPC will ask you a question and then you need to supply an answer. In the Timeless Isle, for example, Senior Historian Evelyna has a trivia quiz. Here is am excerpt from the quiz:
A A Timeless Question|QID|33211|M|65,50.6|N|From Senior Historian Evelyna, daily.| ; This first C step "catches" until you GOSSIP with Evelyna and then goes away when it does not match the gossip C A Timeless Question|QID|33211|QG|Senior Historian Evelyna|N|Chat with Evelyna to get your question. The question will change each time you chat with her, but we have a cheat sheet.| C A Timeless Question|QID|33211|QG|assault on Icecrown|N|Mord'rethar| C A Timeless Question|QID|33211|QG|bloodied crown|N|King Terenas Menethil II| C A Timeless Question|QID|33211|QG|Broken|N|Nobundo| ... T A Timeless Question|QID|33211|M|65,50.6|N|To Senior Historian Evelyna.|
When you are interacting with an NPC between the GOSSIP_OPEN/_CLOSED states, the addon samples the text and matches it against the text in the QG tag. The match is case insensitive. If it matches, the step is not skipped, if it does not match, the step is skipped. If we are not interacting with an NPC between the GOSSIP_OPEN/_CLOSED states, then the tag has no effect.
- It does not do any auto-completion. The quest turnin will take care of it!
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 behave 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. Remember also that you can change the step text to be something other than the quest name and it won't hurt anything!
You can also list multiple quest objectives in one step, and the step will complete when all of them are complete. Just separate them with a semicolon ";".
You must use a number instead of text. The number is the ordinal of the quest of objective. The addon will use the localized text to display the goal so people playing on non-English game clients will have a better idea of what to do. (Older guides for older content may use text instead of the ordinal number, but as Blizzard has changed how they display quest objectives, this usage should be discontinued.)
C Watchtower Burned|QID|11285|QO|2|U|33472|N|Use torch on Winterskorn Watchtower.| C Bridge Burned|QID|11285|QO|3|U|33472|N|Use torch on Winterskorn Bridge.| C Dwelling Burned |QID|11285|QO|1|U|33472|N|Use torch on Winterskorn Dwelling.| C Barracks Burned |QID|11285|QO|4|U|33472|N|Use torch on Winterskorn Barracks.|
- Auto-completes when the addon detects the the QO # or the exact QO text in the QID quest's leaderboard in the user's quest log. Spelling and capitalization is very crucial here! (As mentioned above, quest text only works with older content)
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 in quest skipping logic, so please use 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) or a + (plus) in between each the quest IDs. Use one or the other, don't mix. A semicolon indicates that all of the quests have to be completed for this step to activate. A plus indicates that any of the quests can be completed for this step to activate.
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.
Note that in some quests you loot an item, but it may not appear in your bags.
If so, you need to use the right QO tag instead.
Please do not use this along with a C type step or with QO tags, as it will cause issues in the tracking display.
- Causes the step to complete when the user has the specified item in their bag.
This will create a button for the item specified so you don’t have to dig through your bags to find it.
You don't need to list this on hearth type steps, it's added automatically.
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.
A general note for the step to add additional information. 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! The addon CAN get coordinates from the in-game quest blobs, but we'd rather have our own coordinates listed.
If you have more than one coordinate, you need to specify one of the |CS|CC|CN| tags.
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.
C Galgar's Cactus|QID|4402|N|Loot Cactus Apples from Cacti|S| C Vile Familiars|QID|792|N|Kill the Vile Familiars in the north.|M|44.7,57.7| C Galgar's Cactus|QID|4402|N|Loot Cactus Apples from Cacti|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.
- |S| tagged steps auto-complete when the corresponding |US| type step becomes active, so only one will be active at a time.
Use this tag to denote a step that requires a particular level. There is also a step type, L, to denote a step that completes once the user levels up.
- For L steps, completes when the user reaches the specified level.
- For non-L steps, enable the step if the user is at least the specified level.
Alternate usage - Step - hiding:
- prepend the level with a minus "-" sign to cause the step to not display if the user is over the specified level. (|LVL|-109|)
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.
- Completes when the user completes the specified QID quest (sort of like a second QID).
Follow by the name of the mob or NPC you want the user to be able to target.
Two arguments are required: the name of the profession and its "number". There are three optional arguments that follow:
- The required form, with the name and profession number. If the toon has at least 1 in Alchemy, the step will activate.
- This adds the profession level, which defaults to 1. A "*" can be used to mean max level for the expansion, 700 today. If the toon has at least 42 (>=) in Blacksmithing, this step will activate.
- This sets the profession max level flag. A non zero value flips the sense of the profession level test. I.e. the toon would need less than 42 in Enchanting for this step to activate.
- This sets the profession max skill level. This defaults to 0. It will active the step if the current max profession level the toon could get without re-training is less than the argument. So this would require the toon to have Engineering(200).
The allowed values for the profession names and numbers are:
In addition, if the step is an "A" step and you do not have the profession, the step and QID are marked as skipped.
|CC| – Coordinate Auto-complete |CS| – Coordinate Auto-complete in Sequence |CN| – No Coordinate Auto-complete
Use either CC or CS 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.
The |CN| tag is used to indicate that a set of coordinates are just markers on the map and NO auto-complete should be done.
If a set of coordinates is used in the |M| tag, one of these three tags is required or an error message will be issued.
- Completes when the user reaches the specified coordinate or series of coordinates.
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 out 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.
- Denotes a step you only want to show when a guide is being run on RANK 1. Typical usage is for R steps when you skip content that rank 2 or 3 walks you through.
Used with the C step, this suppresses the display of the step if the player is in combat.
If a guide is marked as an auto-switching guide using WoWPro:GuideAutoSwitch(guide), this tag is used to make this particular quest as not triggering an auto-switch. This is used for things like dungeon quests or other quests that are going to hang around in your quest log for a long time and could result in many irritating offers to switch guides.
Used with the C step, this changes the icon to the Gossip icon, so you know you need to talk to someone.
Takes a set of two required arguments and up to two optional ones. Lets take an example:
- This is the minimally acceptable form. The first argument is the name of the faction and the second is the faction number. You can get faction numbers off of WowHead. Yeah, the number is all you really need, but then the guide would be unreadable. Besides, Blizzard has changed the names of factions in past patches, but preserved the faction numbers, so we feel safer in using the numbers. The third argument defaults to neutral-exalted and the fourth to 0. Explanations for them follow. This form enables the step if the reputation with "Operation: Shieldwall" is neutral through exalted.
- The third argument is a reputation or friendship range.
Reputations are: hated, hostile, unfriendly, neutral, friendly, honored, revered, exalted
Friendships are: stranger, acquaintance, buddy, friend, good friend, best friend
A reputation range is separated by a '-' like neutral-exalted. If only one element is present, like the example, it is doubled up and interpreted as friendly-friendly and means that the step is enabled only when friendly with the faction. Do not mix reputation keywords and friendship keywords or evil things will result.
- The last argument is either the reputation level or the reputation bonus detector. In the example, it specifies that you need to be friendly and at least 950 points into friendly. It will not activate for any higher levels of reputation. You use this for quests that appear at specific reputation levels instead of reputation boundries. We may in the future choose to obey the upper reputation limit as well.
- The last argument is the reputation bonus detector. In the example, it specifies that you need to be revered and not have purchased and used the "Grand Commendation of Operation: Shieldwall". This can be used in guides to prompt the user to buy the commendation at the right rep level. The last argument could also be "bonus" to detect that you have the bonus, but we did that for completeness rather than utility.
Takes a set of one required arguments and two optional ones. Lets take a few examples:
- This is the minimally acceptable form. The first argument is the number of the achievement, 6031, which you can look up in wowhead. In this form, the step completes if the whole achievement is complete.
- This is the second form. The first argument is the number of the achievement, 6031, which you can look up in wowhead. The second, specifies the step in the achievement, in this case "firing off the fireworks in Orgrimmar". In this form, the step completes if the portion of the achievement is complete.
- This is the third form. The first argument is the number of the achievement, 6031, which you can look up in wowhead. The second, specifies the step in the achievement, in this case "firing off the fireworks in Orgrimmar". The third augment is the "flip" argument. In this form, the step completes if the portion of the achievement is not complete.
- This is the fourth form. The first argument is the number of the achievement, 6031, which you can look up in wowhead. The second is set to nil, so it is equivalent to the first case. The third augment is the "flip" argument. In this form, the step completes if the whole achievement is not complete.
Buffs, those things that appear at the top, like Sayge's Dark Fortune of Strength, can be detected by this tag and cause the step to complete. Multiple buffs can be specified with the usual ';' delimited list. Example:
N Sayge's Dark Fortunes|M|52.94,75.94|BUFF|23735;23736;23737;23738;23766;23767;23768;23769|N|Sayge offers different 2 hour buffs. Pick one and elect to get a written fortune for a chance at a quest item! We pre-select based on your class.|
The PET tag takes one, two or three arguments, depending on what you are up to. The second and third arguments default to 3;false if not specified.
- In the one argument form, this tests to see if less than 3 of the indicated pet. The creature IDs are not well documented. As far as I know, the only place to get them are in the Blizzard web API or by using the WoW-Pro debug log, which lists the IDs for all the pets you have.
- In the two argument form, this tests to see if less than 1 of the indicated pet.
- In the three argument form, this tests to see if you have >= 1 of the indicated pet. A true value flips the sense of the test.
The BUILDING tag takes two or more arguments, depending on what you are up to. The first argument is ignored and is used for documentation and second and following arguments are building numbers. You can find a list of building numbers for WoD at http://wod.wowhead.com/buildings . If you have none of the buildings specified, then the step is skipped. As a special bonus, if the step does not have a |M| tag, one for the building location will be added. The addon uses the building locations on your Garrison map, so it won't be perfect, but it is pretty good.
- In the two argument form, this tests to see if you have the indicated building. In this case, a level 1 Lumberyard.
- In the three argument form, this tests to see if you have either a level 1 or level 2 lumberyard.
Two special buildings types exist:
- In this form, it tests your Town Hall level. In this case, it checks that the Town Hall (Garrison) level is exactly 2. Only one level can be tested for. Note that this form does NOT set the |M| tag.
- In this form, this tests to see if you have built no buildings. No other arguments are paid attention to!
The RECIPE tag is used with tradeskills to detect if you have a recipe in your profession "book".
B Recipe: Koi-Scented Stormray|M|71.61,48.87|P|Cooking;185|RECIPE|201503|L|133819|N|From Markus Hjolbruk.|
This detects if you have the recipe (Koi Scented Stormray Spell ID: 201503) and if not to buy it. You should include the profession tag with skill level required. The number in the |L| tag is the item id of the recipe (133819) you buy and then click to learn it.