Skip to content

Addon Syntax

Jump to bottom Edit New page
elidion edited this page Sep 16, 2020 · 34 revisions

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 our Discord chat.

Table of Contents

  1. Overview
  2. Step Types
  3. Tags
  4. Comments

Overview

To start with, I suggest working with a guide that has already been coded, rather than trying to start from scratch.

Opening a File to Edit

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.

[Back to top]

Anatomy of a Guide File

local guide = WoWPro:RegisterGuide("LudoExpDaS","Achievements","Darkshore","Ludovicus", "Neutral")
WoWPro:GuideLevels(guide,20,90)
WoWPro:GuideIcon(guide,"ACH",844)
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.

[Back to top]

Guide Registration Function

The guide registration functions are what tells the addon the overall information about the guide. It contains several important parts, as follows:

  1. The function The actual name of the function we are calling: WoWPro:RegisterGuide

  2. The Guide ID

    • 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.

  3. Guide Type 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:

    • achievements
    • leveling
    • professions
    • dailies
    • worldevents

  4. The zone Pretty self explanatory. “Darkshore” in the example. This does not have to be a valid zone, but if it is not, a|Z| (zone) tag must be used on every line of the guide. It controls which map will be used for mapping (which can be overwritten with a |Z| tag), and also what name the guide have in the menu (ESC>Addons>WoW-Pro>Guide List) as well as the name showing at the top of the active guide pane. A better way of changing the guide name is to use the code WoWPro:GuideName(guide, 'name here') discussed below.

    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.

  5. The author Again pretty simple. “Ludovicus” in the example.

  6. Faction The faction the guide is intended for. Can be Horde, Alliance, or Neutral.

  7. The return value The guide object is returned, which you can now feed into some additional functions to more fully describe the guide.

Guide Description Functions

  • WoWPro:GuideLevels(guide, start_level, end_level, mean_level)
    This is now Optional.
    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 functions.

  • 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.

  • WoWPro:GuideProximitySort(guide)
    Tells the system to sort the steps in order of proximity every time you complete a step.

  • WoWPro:GuideNextGuide(guide,nextGID)
    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:GuideName(guide, name)
    If you want the guide name to be something other than the zone as defined in the guide registration parameters. This is the name that will be at the top of the guide pane and show in the list of guides.

  • WoWPro:GuideNickname(guide, name)
    A nickname for the GuideID so you can call GuideNextGuide or calls to the guide in the code by a friendly readable name.

  • WoWPro:GuideSort(guide, num)
    When mean_level is equal you can specify this override to declare the order guides are sorted in the guidelist menu.

  • 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!

  • WoWPro:GuideQuestTriggers(guide, 33333,33334,33335)
    If you want a guide to autoload when a quest is accepted. Particulaly useful for holiday and other special occasion guides. The numbers are the QID's of the quests that you want to trigger the guide loading. The user will receive a dialog box giving them the options of Switch, Not Switch Now, or Not Switch Ever (for this quest).

  • WoWPro:GuideAutoSwitch(guide)
    Use Auto Switch if you want a guide to autoload when any quest from the guide is accepted. You can put the |NA| tag in to make a particular quest not cause a guide to switch. (such as for a dungeon or raid quest that the user is not likely to be completing immediately). The user will receive a dialog box giving them the options of Switch, Not Switch Now, or Not Switch Ever (for this quest).

[Back to top]

The Guide Code

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 case-sensitive 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.

[Back to top]

Step Types

A – Quest Accept

Use this every time you direct the player to accept a step.

Example:

A Wanted: Dreadtalon |QID|12091|N|From the Wanted Poster just outside the door.|

Auto-Completion:

  • When a quest of the specified QID newly appears in the user's quest log.

[Back to top]

C – Quest Complete

Use this when the player is completing a quest (or part of a quest) Example:

C Blood Oath of the Horde |QID|11983|N|Talk to the Taunka'le Refugees.|

Auto-Completion:

  • When the quest of the specified QID is marked (complete) in the user's quest log. Modifications:

  • Use a |NC| tag to mark the step as non-combat, giving it a cog icon instead of crossed swords.

  • Use a |CHAT| tag to mark the step as chat, giving it a chat icon instead of crossed swords.

  • Use a |QO| tag to make the step complete based on one quest objective rather than all of them.

    • You can also use|QO| to track each requirement of an objective count. For example if you have a quest the requires you to destroy 3 towers that are always in the same position you can you use |QO|1<1| for the first, |QO|1<2 | for the 2nd and |QO|1<3| for the last. If it shows you have 0/3 towers detstroyed you are saying, with |1<1| if Objective 1 is less than 1 (which is 0, and your progress is 0/3), likewise the final |1<3| you are saying if Objective 1 is less than 3 (your progress is 2/3 towers destroyed).

[Back to top]

T – Quest Turn-in

t – Quest Turn-in (suppressible)

Use this every time you direct the player to turn in a step. FYI Be aware, abandoning the quest will also cause T steps to autocomplete, if that happens you need to manually un-check.

Example:

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.|

Auto-Completion:

  • When the quest of the specified QID disappears from the user's quest log or after viewing the completion page for the quest.

Skipping:

  • 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.

[Back to top]

R – Run F – Fly b – Boat/Zeppelin H – Hearth P - Portal

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.

Example:

H Warsong Hold |QID|11686|U|6948|

Auto-Completion:

  • When the subzone or zone name matches the specified one.

Modifications:

  • 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.
  • also see |TZ| alternate subzone name

[Back to top]

h – Set Hearth

Instructs the user to set their hearthstone. Make sure to spell the town’s name exactly correctly, or it won’t auto complete correctly.

Example:

h Warsong Hold |QID|11598|N|At the innkeeper.|

Auto-Completion:

  • Auto-completes on the message “TOWNNAME is now your home.” TOWNNAME is the name of the subzone showing on your minimap when you are standing at this location, sometimes this is the name of the inn or something else more specific than actual townname

[Back to top]

f – Get Flight Point

Instructs the user to get the flightpath. While convention suggests you use the subzone name as the step text, it's not required.

Example:

f Moa'ki Harbor|QID|11585|Z|Dragonblight|

Auto-Completion:

  • Auto-completes on the UI message "New flight point discovered". Does not require or use a subzone name.

[Back to top]

K – Kill U – Use B – Buy r – Repair/Restock l - Loot L - Level N - Note

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.

Example:

K Fjord Crows |QID|11227|L|33238 5|N|Until you have 5 Crow meat.|

Auto-Completion:

  • 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. You can also effectively auto-complete with the use of an |ACTIVE| or |AVAILABLE| tag followed by a QID, note: -QID means when the quest is NOT active. For Note, Fly, or Run steps, using an ACTIVE tag instead of the QID will make sure that step is only active when that quest is active. Similarly, using an AVAILABLE when those steps lead you to an Accept step will complete them once the quest gets in your quest log. The only tricky thing is when an Run or Portal step is part of a quest and it involves a loading screen. Sometimes if you are lucky there is a QO tag that you may be able to use to auto-complete the step or using the zone name as the step name to complete on that basis.

[Back to top]

; - Comment Step

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.

Example:

; 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.

[Back to top]

$ - Treasure Step

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.

Example:

$ 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.

[Back to top]

* - Trash Step

Use this to delete an item in your inventory. It requires a U tag. If the item is in your inventory, you will be prompted to get rid of the item. The step will auto complete if you delete the item or cancel the delete or if you never had the item in the first place.

Example:

* Bauble Dump|QID|6608|U|6529|N|If you got a Bauble, trash it.|

[Back to top]

Tags

|QID|####| – Quest ID

Even on a step that has nothing to do with any quest (e.g. Hearth steps) it is still important to have one of these 3 tags there as well. Use the ID of a quest which, if completed, means the user no longer needs to complete that step.

Example:

A Wanted: Dreadtalon |QID|12091|N|From the Wanted Poster just outside the door.|

Auto-Completion:

[Back to top]

|ACTIVE|####| – Active Quest ID

Example:

A The Grand Melee|QID|13761|ACTIVE|13717|M|76.40,19.00|N|From Airae Starseeker.|

[Back to top]

|AVAILABLE|####| – Available Quest ID

Example:

R Go here for Grand Melee|AVAILABLE|13717|M|76.40,18.00;76.40,19.00|N|Take this path|

[Back to top]

|QG|Some text| – Quest Gossip

Example:

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.

Auto-Completion:

[Back to top]

|QO|1| – Quest Objective

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.)

Example:

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-Completion:

[Back to top]

|O| – Optional

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.

[Back to top]

|PRE|####| – Prerequisite

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.

[Back to top]

|L|####| – Loot

Note that in some quests you loot an item, but it may not appear in your bags. If so, you need to use the a 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.

Auto-Completion:

[Back to top]

|U|####| – Use

You don't need to list this on hearth type steps, it's added automatically.

[Back to top]

|C|Priest,Mage,…| – Class |R|Orc,Troll,…| – Race

[Back to top]

|N|…| – Note

[Back to top]

|M|55.55;55.55| – Mapping

If you have more than one coordinate, you need to specify one of the |CS|CC|CN| tags.

[Back to top]

|Z|Zone Name| – Zone

/wp where - tells you where you are according to the addon.

also see |TZ| alternate subzone name

[Back to top]

|S| – Sticky |US| – Un-Sticky

Example:

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.

Auto-Completion:

[Back to top]

|S!US| - Sticky without corresponding unsticky

Auto-Completion:

[Back to top]

|ITEM|######| – Item - followed by item number

[Back to top]

|LVL| – Level

Auto-Completion:

Step-Enabling:

Alternate usage - Step - hiding:

[Back to top]

|LEAD| – Lead In Quest

Auto-Completion:

[Back to top]

|T| – Target

[Back to top]

|P| – Profession

|P|Blacksmithing;164;0+42|

|P|Enchanting;333;0+42;1|

|P|Engineering;202;0+*;0;150|

The allowed values for the profession names and numbers are:

The allowed values for the Expansion variable 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.

[Back to top]

|CC| – Coordinate Auto-complete |CS| – Coordinate Auto-complete in Sequence |CN| – No Coordinate Auto-complete

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.

Auto-Completion of r/R/N steps:

Other step types will present the waypoints, but will not auto-complete when the last one is reached. Some other completion method must be used.

[Back to top]

|RANK| – Rank

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:

|RANK|1|

|RANK|2|

|RANK|3|

|RANK|-1|

[Back to top]

|NC| – Non-Combat

[Back to top]

|NA| – Not Automatic

[Back to top]

|CHAT| – Chat

[Back to top]

|V| – Use vehicle

[Back to top]

|REP| – Reputation

|REP|Operation: Shieldwall;1376|

WowHead

|REP|Operation: Shieldwall;1376;friendly|

Friendships are: stranger, acquaintance, buddy, friend, good friend, best friend

Scryers

Tillers

Gina Mudclaw

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.

|REP|Operation: Shieldwall;1376;friendly;950|

|REP|Operation: Shieldwall;1376;revered;nobonus|

[Back to top]

|ACH| – Achievement

|ACH|6031|

6031

|ACH|6031;2|

6031

|ACH|6031;2;true|

6031

|ACH|6031;;true|

6031

|ACH|6031;;;true|

6031

[Back to top]

|BUFF| – Unit Buff

Sayge's Dark Fortune of Strength

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.|

[Back to top]

|PET| – Pet Detect

|PET|6031|

|PET|6031;1|

|PET|6031;1;true|

|PET1| |PET2| |PET3| – Pet Selection

|PET1|Anubisath Idol;68659;|

|PET1|Anubisath Idol;68659;1+2+1|

|PET1|Leveling;;;|

|PET1|Leveling;;;H>200C|

The allowed values for the attributes are:

  • Health
  • Power
  • Speed
  • Family

The first letter of each pet type is the modifier

  • 1 - Humanoid
  • 2 - Dragonkin
  • 3 - Flying
  • 4 - Undead
  • 5 - Critter
  • 6 - Magic
  • 7 - Elemental
  • 8 - Beast
  • 9 - Aquatic
  • 10 - Mechanical

[Back to top]

|BUILDING| – Building Detect

http://wod.wowhead.com/buildings

|BUILDING|Lumberyard;40|

|BUILDING|Lumberyards;40;41|

|BUILDING|TownHall;2|

|BUILDING|TownHallOnly|

[Back to top]

|RECIPE| – Recipe Detect

The RECIPE tag is used with tradeskills to detect if you have a recipe in your profession "book".

usage: 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.

[Back to top]

|FLY|XXX|

  • BFA - Zandalar and Kul Tiras
  • LEGION - Broken Isles
  • WOD - Draenor
  • OLD - Everything that did not require a "Pathfinder" achievement

[Back to top]

|TZ|Subzone Name| – minimap subzone

also see R Run, etc

[Back to top]

|SPELL|Spell NickName;Spell ID#; Flip| – detects spells in character's spellbook

  • Spell NickName: The name of the spell, for humans. Not used by the addon. (required)
  • Spell ID#: the Spell ID, as available on Wowhead. (required)
  • Flip: An optional boolean to flip the detection. Defaults to false (do not flip).

Auto-completes if the spell is already known or if is learned. Warning: not all spells are detectable by this method. Blizzard is not consistent! This tests for Spells you can put on a button, essentially.

[Back to top]

Add a custom footer
Add a custom sidebar
Clone this wiki locally