# Creating a guide

Every user guide needs to be registered with the Guide Viewer for it to display. This can be done in two ways:

1. Creating a stand-alone "guide addon".

1. If you have written addons before, just skip the basics here :)
2. Create a new directory under `\Interface\Addons`, naming it - for example - MyGuide.
3. Create a file in there, naming it `MyGuide.toc`, containing - basically - this: `## Interface: 30300
   ## Title: My Guide For Something
   ## Dependencies: ZygorGuidesViewer
   MyGuide.lua`
4. Create another file, name it `MyGuide.lua`, and paste this into it:

       ZygorGuidesViewer:RegisterGuide("My Leet Guides\\My First Guide",[[
       	author me@myself.com
       	step
       		Do some very secret unspecified something :)
       	step
       		Keep playing...
       ]])

5. Edit this to your likings.
6. Start WoW, open the ZygorGuidesViewer window, hover at the title and click the guide selection button - your guide should be visible in the drop-down list.

Now all you need is keep writing the guide, and reloading the game's UI to reload the guide.

This method is by far the easiest and best way to create and distribute your guides - it has one major drawback, however. According to Blizzard's policies, you are not allowed to sell addons of any kind. Distribution of a commercial guide in this form could probably be considered violating their terms. Stay safe.

2. Including data in the addon's folder

1. Prepare a guide according to the syntax described above and below.
2. Save it as `Guide01.lua` (through `Guide40.lua`) in the `ZygorGuidesViewer\Guides` folder.
3. Re-launch the game. Your guides should be available for selection.

# Guide format

A guide consists of a series of steps, being displayed one at a time, often having step options assigned.
Each step may contain up to 20 lines, consisting of various tags separated with a pipe character (`|`).
Additionally, some global options may be set.

Spaces/tabs at beginnings and ends of lines are ignored. Whole empty lines are ignored as well. You can include comments, starting with`//` until the end of line (C-style).

The resulting structure looks like this:

`global option
global option
`step` // comment
step option
step option
tag|tag|tag
tag|tag|tag
`step`
step option
step option
tag|tag|tag
tag|tag|tag
`

# Global options:

defaultfor race
  Makes this guide loaded by default when starting a character of a specific race. Death Knights are considered a race, for convenience. Examples: `defaultfor Human`, `defaultfor DeathKnight`.
author email, name...
  Sets the author's credentials. Used in generated bug reports.
description text
  Sets the description used in the guide's details in the addon's main settings screen.
startlevel level
  Use this level as default for the first steps of the guide. Steps use levels to determine what's obsolete; set to 80 to never obsolete your steps.
next guide title
  Designates guide title to follow this guide. Note: full title needed, multi-folder path and all.
daily
  Marks the guide as a "dailies" guide, enabling periodic resetting of daily-marked quests.

# Steps:

Each step starts with a`step` word, alone in a line. This marker is followed by step options and lines.

# Step options:

These pertain to one step, setting its properties.

Option | Description | Example
--- | --- | ---
map name | Sets a default map for this (and subsequent) step's waypoints. Use it if you prefer your waypoint markers to have only coordinates. | `map Elwynn Forest`
level level | Indicates that the step should be completed at level level. Optional. If no level is set for a step, the previous step's level is used, or the guide's startlevel setting. Note: the ding tag sets the level as well. | `level 12`
title text | Sets the title of the waypoint pertaining to the step. May be overridden by a line-specific `title` tag. Optional. | `title Entrance to the mine`
only race/class... | Designates the step as being valid only for a specific race/class. Any combination of races/classes, separated with commas. A race starting with ! means 'NOT'. As the races are OR-ed together, multiple NOTs don't make sense. Note: the last line in the example restricts the step to Gnomes of any class, Dwarven Paladins, and Mages of any race - not to Gnomish-or-Dwarven Paladins-or-Mages. | `only Human Warrior only Warrior,Priest,Warlock only !Human only Gnome,Dwarf Paladin,Mage`
only if condition | Sets a raw scripted condition for the step's availability. Condition is a simple Lua expression. Available shorthands: `rep("Faction")` -- returns standing with a faction (locale-safe). Compare using >,<,==,>=,<=,~= with one of the predefined values named after standings: Neutral,Honored,Exalted... Case-sensitive. `skill("Profession")` -- returns skill in profession. any other Lua expression -- evaluates and if it returns non-nil, the step is available. | `only Human Warrior only if rep("Stormwind")==Exalted only if skill('Herbalism')>0 only if UnitName("player")=="Tinkywinky"`

# Step lines:

Completable lines. Each step line is intended to either require the player to perform some action, or just provide advice. If a line contains one of the "completable" tags, it becomes a completable line. A line containing only "descriptive" actions or tags, or forced into incompletability (using the |n tag), will just be displayed for the player to read.

Completion condition. The first completable tag on a line decides its completion condition. Other tags in the line can only enhance the completable tag's behaviour. Or, they can make no sense at all. Tags are separated using the '|' pipe character. Example:
`'Hearth to Ironforge|goto Ironforge,12.3,45.6|use Hearthstone##6948|noway` This would read as: "Display a descriptive instruction; then, use goto completion upon reaching Ironforge; add a usable item icon with Hearthstone on it; finally, make this line not show a waypoint arrow.

Waypoints. A goto tag, or a ' ("text") tag with a coordinate pair in its contents, will automatically create a mapnote and a waypoint for it. The mapnote's title can be set using the title step option, or individually for the line using the title line tag. A line with coordinates can be clicked to force a waypoint to this location to be displayed.

Indentation. Step lines can be prepended with multiple '`.`'s (periods) to indent them visually. Example: `goto 12,34
.talk Mountain King
..accept Into the Hall` Result: `Go to 12,34
Talk to Mountain King
Accept `Into the Hall'`

# Tags

## Simple actions:

' text
  Provides a descriptive instruction for the player, in full-text form. This action overrides the default display that other actions might provide for this line.
  Also, if a proper coordinate pair is found in the text, a mapnote and a waypoint is generated and this tag works like a goto tag and follows its completability.
  Can be written as 'text (no space) or even with no tag and just text, as long as the first word is not a valid tag.
  Incompletable.
    Not by itself, anyway. Can be made completable by coupling with any completable tag.
  Parameters:
    text - what gets displayed.
  Examples (equivalent):
    `' Click the boxes on the ground.
    'Click the boxes on the ground.
    Click the boxes on the ground.
    Click the boxes at 12.3,58.1
    Go south to 12.3,58.1|c
    `
  Displayed as:
    `Click the boxes on the ground.
    Click the boxes on the ground.
    Click the boxes on the ground.
    Click the boxes at 12,58.
    Go south to 12,58.
    ` Note: the last line completes when the player arrives at the coordinates, not when anything is clicked.
goto map,x,y or map or x,y or x, y,dist or map,x,y,dist
  Instructs the player to go to the specified location. If coordinates are specified, a mapnote/waypoint will be created for the line. If multiple goto lines are present, multiple mapnotes will be created, as well as a proper queue of waypoints.
  Completable:
    When the player reaches the specified coordinates - or just the zone, if only that was given.
    If `goto` is the only line in a step, or a step consists solely of `goto` lines, it is by default completeable. Incompletable otherwise. If completable, `goto` tags are by default "`sticky`".
  Parameters:
    map - map name. Optional; it is assumed to be the last one used, or the one set by `map`, or the player's current zone.
    x,y - coordinate pair, either simple (12,34) or with decimal precision (12.5,34.7 or 12.56,34.78). Optional if you're specifying map and the line should only direct the player to move to another map.
    dist - distance from target to trigger completion, if the line is completable. Optional; default: 0.2
  Examples:
    `goto Elwynn Forest,12,34
    goto 12.56,34.78
    goto 12.56,34.78,0.7`
  Displayed as:
    `Go to Elwynn Forest 12,34
    Go to 13,35
    Go to 13,35
    ` Note: coordinates are always rounded to XX,YY for less cluttered display. Detection radius is not displayed.
talk npc_name##id
  Instructs the player to talk to an NPC.
  Incompletable.
  Parameters:
    npc_name - name of the NPC. Optional if an ##id is given.
    ##id - NPC id number, matching Wowhead and the NPCs file. Enables localization and overrides npc_name. Recommended.
    dist - distance from target to trigger completion, if the line is completable. Optional; default: 0.2
  Example:
    `talk Brann Bronzebeard`
  Displayed as:
    `Talk to Brann Bronzebeard`
accept quest##id
  Instructs the player to accept a quest.
  Completable:
    Completed when the player has the quest in their log, or has already completed it.
    Impossible (grayed) when the player has not completed a known pre-requisite.
    Note: for "instant" quests (completing immediately) use the instant tag.
  Parameters:
    quest##id - quest title and Wowhead-style quest ID. Actually quest hardly matters and could be skipped completely.
    quest (3)##id - write multi-part quests with the same title like this. The title gets overwritten, but the (3) part number is extracted before that happens, and gets appended as "(part 3)" afterwards.
  Example:
    `accept Into the Realm of Shadows
    accept Washed Ashore (2)##4681`
  Displayed as:
    `Accept `Into the Realm of Shadows'
    Accept `Washed Ashore' (part 2)`
turnin quest##id
  Instructs the player to turn in a completed quest.
  Completable:
    Completed when the player completes or has already completed the quest.
  Parameters:
    see `accept`.
  Example:
    `turnin Into the Realm of Shadows
    turn in Washed Ashore (2)##4681`
  Displayed as:
    `Turn in `Into the Realm of Shadows'
    Turn in `Washed Ashore' (part 2)`
goal count goalname
  Instructs the player to complete count of quest goals named goalname. REQUIRES q.
  Completable:
    Only when linked to a quest objective with q, pointless otherwise.
    Complete if a quest objective reaches count, even if it's not enough to complete the quest. Or if the linked quest is complete.
  Parameters:
    count - optional; defaulting to the amount required by the quest. Also, will be reduced if it exceeds the quest requirement.
    goalname - optional; quest goal is fetched from the linked quest anyway.
  Example:
    `goal Samuel's Remains Buried |q 123/1
    goal 12 Stillpine Captive Freed |q 9544/1`
  Displayed as:
    `Samuel's Remains Buried: 0/1
    Stillpine Captive Freed: 0/8` Note: The quest The Prophecy of Akida##9544 requires only 8 Stillpine Captives freed, freeing 12 would not be possible, so the value is adjusted.
kill count mob##id
  Instructs the player to kill count of the specified mob (in singular form). Mob must be present in the NPCs files for localization. Using count>1 or adding a + after the id shows a plural form.
  Note that the quest must expect explicitly killing the specified mob; if a quest requires not the kill itself, but bringing back a dropped item, it's better to mark kill actions as non-completeable using `n` and follow them with get tags.
  Completable:
    Only when linked to a quest objective with q.
  Parameters:
    count - optional; defaulting to the amount required by the quest. Also, will be reduced if it exceeds the quest requirement.
    mob - useless; name is gathered from the NPCs file anyway.
  Example:
    `kill 7 Young Nightsaber##1234
    kill Winterfin Murloc##1235+`
  Displayed as:
    `Kill 7 Young Nightsaber
    Kill Winterfin Murlocs`
get count item
  Instructs the player to pick up count of the specified object (written in singular form) as a quest goal. REQUIRES q.
  Completable:
    As linked to a quest objective with q.
  Parameters:
    count - optional; defaulting to the amount required by the quest. Also, will be reduced if it exceeds the quest requirement.
    item - useless; item name is gathered from the linked quest anyway.
  Example:
    `get 8 Tough Wolf Meat
    get Powers of the Void`
  Displayed as:
    `Get 8 Tough Wolf Meat
    Get Powers of the Void`
collect count item##id
  Requires of the player to have count of the specified item in their inventory. If ##id is given (and should be), item name is overridden by the game. Use + after the ##id to make it plural.
  Completable:
    The player has at least count of the specified item in their bags.
  Parameters:
    count - optional; defaulting to 1.
    item - must have the ##id component to be able to complete.
  Example:
    `collect 2 Croase Thread##2320+
    `
  Displayed as:
    `Collect 2 Coarse Threads
    `
buy count item##id
  Works just like collect, except that it's displayed differently and is future by default for convenience.
  Completable:
    See collect.
  Parameters:
    See collect.
  Example:
    `buy 1 Gyrochronatom |q 714/1
    `
  Displayed as:
    `Buy 1 Gyrochronatom
    `
fpath flightpath
  Instructs the player to learn the specified flightpath from a flight master.
  Completable:
    When the player knows the flight path. A flight path is 'known' when it was shown on the flight map when the guide was running. It is 'unknown' then the map was displayed and did not have that flight path shown. Otherwise, it's undecided and thus deemed unknown for now.
  Parameters:
    flightpath - name of the flight path.
  Example:
    `fpath Stormwind
    `
  Displayed as:
    `Get the Stormwind flight path.`
home location
  Instructs the player to set their home location to location.
  Completable:
    The player changes their home location to anywhere new. For technical reasons.
  Parameters:
    location - name of the home location.
  Example:
    `home Ironforge
    `
  Displayed as:
    `Set home location to Ironforge`
ding level
  Requires the player reach a level before proceeding. Instructs them to grind a bit, if they're too low-level.
  All steps after this one have the specified level suggestion (no need to use the level step option).
  Completable:
    The player reaches or exceeds the level.
  Parameters:
    level - guess.
  Example:
    `ding 10
    `
  Displayed as:
    `You should now be level 10.
    If you're not, grind a little until you are. (58%)`
havebuff name
  Requires the player to have a specific spell effect active on them. Opposite of nobuff.
  Completable:
    The player has the buff/debuff active on them.
  Parameters:
    name - might be the buff name (unadvised: locale-dependent) or the texture name (much better: locale-independent).
  Example:
    `' Take control over the Eye |havebuff Spell_Shadow_UnholyFrenzy`
nobuff name
  Requires the player NOT to have a specific buff active. Opposite of havebuff.
  Completable:
    The player does NOT have the buff/spell active on them.
  Parameters:
    name - might be the buff name (unadvised: locale-dependent) or the texture name (much better: locale-independent).
  Example:
    `'Make sure you don't have Animal Blood on you. |nobuff Ability_Seal`
invehicle
  Requires the player to be in a vehicle. Opposite of outvehicle.
  Completable:
    The player is in a vehicle.
  Example:
    `' Get into the tank |invehicle`
outvehicle
  Requires the player NOT to be in a vehicle. Opposite of invehicle.
  Completable:
    The player is out of their vehicle.
  Example:
    `' Get off the horse |outvehicle`
rep faction,standing
  Dictates the player to achieve a specific reputation with a faction.
  Completable:
    The player has at achieved or exceeded the reputation requirement.
  Example:
    `.' Kill Magrams until you are friendly with the Gelkis |rep Gelkis Clan Centaur,Friendly`
condition Lua expression
  Completes the line using any Lua expression.
  Completable:
    Expression evaluates to true. If the expression returns two values, the second value indicates possibility of completion at all. Three values? Third indicates progress.
  Example:
    `.' Earn at least 1 gold |condition GetMoney()>10000`

## Clickable icons:

use item##id
  Instructs the player to use an item, providing a clickable icon if they have the item in their bags.
  Incompletable.
  Parameters:
    item - must have the ##id component to show the icon.
  Example:
    `use Blood Elf Plans##24414
    `
  Displayed as:
    `[X] Use Blood Elf Plans
    `
cast spell##id
  Instructs the player to cast a specific spell, providing a clickable icon if they have the spell in their spellbook.
  Incompletable.
  Parameters:
    spell - must have the ##id component to show the icon.
  Example:
    `cast Gift of the Naaru
    `
  Displayed as:
    `[@] Cast Gift of the Naaru
    `
petaction number or name
  Provides an icon to invoke the number'th action on the pet/summon action bar.
  Incompletable.
  Parameters:
    number or name - number counting from the left, or name of ability, or name of texture displayed. Number or texture is advised, as they're universal while ability names are not localizable.
  Example:
    `' Use your Collect Data ability |petaction Collect Data
    `
  Displayed as:
    `[@] Use your Collect Data ability
    `
script Lua code
  Executes a Lua script line when the player clicks the provided icon.
  Incompletable.
  Parameters:
    Lua code - any valid Lua code to be executed. Watch out for non-combat commands!
  Example:
    `' Leave the vehicle |script ExitVehicle()
    `
  Displayed as:
    `[@] Leave the vehicle
    `

## Modifiers:

`q` quest_id or quest_id`/`objective_num
  This links the line with a quest or quest objective and causes it to become completable in reference to the quest or objective. Basically the most important tag of them all.
  Completable:
    When linking to a quest (with no objective number), this marks the line as follows:
    - quest complete -> line complete,
    - quest incomplete but currently active -> line incomplete but completable,
    - quest not in log -> line incompletable.
    When linking to a quest and objective, this marks the line as follows:
    - quest or objective complete -> line complete,
    - objective incomplete but quest currently active -> line incomplete but completable and displaying completion progress,
    - quest not in log -> line incompletable.
  Parameters:
    quest_id - links to the quest only,
    quest_id`/`objective_num - links to the objective. This causes translation of kill, get, goal and collect parameters, unless they're using their own ##id numbers.
  Examples:
    `get 8 Disaessed Walf Plet |q 33/1
    collect 5 Flask of Oil##814 |q 103 |future`
  Displayed as:
    `
    Get 8 Diseased Wolf Pelt (0/8)
    Collect 5 Flasks of Oil (1/5)
    ` Note: the player seems to have only 1 Flask of Oil, but they completed quest ##103 already.
n
  This marks the line as `n`ot completable, even if by default it would have been completable. Display is not affected, but the line's objective is neither tracked or required to complete the step.
  Example - kill a mob that is not a quest objective, but get the quest item from its corpse:
    `kill Defias Messenger##550 |n
    get A Mysterious Message##1381 |q 142/1`
  Displayed as:
    `Kill Defias Messenger
    Get A Mysterious Message
    `
c
  This marks the line as `c`ompleteable, even if by default it would be incompletable.
  Useful mostly with ' or goto tags.
  Example - explicitly require the player to visit several waypoints in sequence:
    `'Enter the caves at 11.8,22.2|n
    goto 13.4,25.1|c
    goto 15.1,28.3|c`
  Displayed as:
    `Enter the caves at 12,22
    Go to 13,25
    Go to 15,28
    `
noway
  Prevents any waypoints to be created by this line. Useful when you do want to detect instant arrival somewhere (using `goto` or `'`/`at`), and a waypoint arrow would only confuse the player.
  Example - several ways to instruct the player to hearth home:
    `'Hearth to Ammen Vale
    'Hearth to Ammen Vale|at Azuremyst Isle,84.3,43.0,0.5
    'Hearth to Ammen Vale|at Azuremyst Isle,84.3,43.0,0.5|noway`
  Displayed as:
    `
    Hearth to Ammen Vale -- bad: not detected
    Hearth to Ammen Vale (at 84,43) -- bad: waypoint suggests walking
    Hearth to Ammen Vale
    `
sticky
  Forces its line to remain complete even if the objectives are no longer met.
  Useful for auto-completing steps with multiple mutually exclusive objectives completed in sequence. "Sticky" lines remain complete until the step is changed.
  Example - transform an item into another:
    `collect Battle-worn Sword##38607 |sticky
    ' Click the Battle-worn Sword in your bags |use Battle-worn Sword##38607
    get Runebladed Sword |q 12619/1`
  Displayed as:
    `
    Collect 1 Battle-worn Sword (0/1)
    Click the Battle-worn Sword in your bags
    Get Runebladed Sword (1/1)
    ` The first line remains complete, even though the player no longer has the Battle-worn Sword (count shows 0/1).
future
  Signifies that if the line is linked to a quest, only mark it as complete when the quest is complete, but NOT mark it as impossible when the player is not on that quest (as would have been done otherwise).
  This allows for collection of quest-important objects when not on that quest yet, but have the line marked green if the quest was already done.
  Example - collect an object for a future quest:
    `collect 5 Flask of Oil##814 |q 103 |future`
  Displayed as:
    `
    Collect 5 Flasks of Oil (0/5)
    `
noobsolete
  Forces to never obsolete the quest that is mentioned in the line (by either accept, turnin or q). Useful for class quests that you want the player to complete regardless of their level.
  Example:
    `accept Devourer of Souls##1716 |noobsolete`
daily
  Marks the quest referenced in the line (by either accept, turnin or q) as a daily quest. This results in periodic resetting of the quest's completion status in daily guides.
  Example:
    `accept Devourer of Souls##1716 |noobsolete`
instant
  Causes the referenced quest to be identified by its title, not by its number. This is necessary for some "instant completion" quests, which never have a corresponding turnin line.
  Example:
    `accept Mage Training##9290 |instant`
`or` , `or` count
  Invokes "or" logic on all the lines marked with this tag on the current step. One or count completed lines complete them all. Or-lines do not cause implied completion of any non-or lines on the step!
  Examples:
    `accept Static Quest##20000
    'Accept one of the following:
    accept First Random Quest##20001 |or
    accept Second Random Quest##20002 |or
    accept Third Random Quest##20003 |or` This step is completed by accepting Static Quest##20000 and any of the remaining random quests. `'Accept two of the following:
    accept First Random Quest##20001 |or 2
    accept Second Random Quest##20002 |or 2
    accept Third Random Quest##20003 |or 2` This step is completed by accepting TWO of the Random Quests.
`only` raceclass...
  Displays the line only when the player's race and/or class matches the requirement. Works exactly like the only step option, just for one line.
  Example:
    `..accept A Special Surprise##12742 |only Human
    ..accept A Special Surprise##12743 |only NightElf`
`only if` condition
  Displays the line only when the scripted condition is met. Works exactly like the only if step option, just for one line.
  Example:
    `info Don't forget to harvest the Ancients for herbs. |only if skill('Herbalism')>0`
title
  Used in a waypointed line, sets the title of the mapnote created by this line. This overrides the step-wide title tag.
  Example - guide the player through several named waypoints:
    `'Enter the castle |goto 11,22 |title Castle entrance
    'Go up the stairs to 13,14 |title Upstairs
    goto 15,18 |title Throne room`
at
  This is just an alias for the `goto` tag.
  Example - pinpoint kill locations:
    `kill 5 Blackwing Guards|at 12,34`

## Other tags:

tip text
  Adds an inline information line. According to the player's preferences, this might be displayed as a tooltip for the line.
  Example:
    `Kill 3 Smelly Murlocs |tip They're wandering around here.`
autoscript Lua code
  Causes instant execution of the code upon reaching the step containing this line, as long as the line is displayed (see only if. Useful for loops, conditional jumps etc.
  Example:
    `Kill 3 Smelly Murlocs |tip They're wandering around here.`
info text
  Adds an information line. Just like text, just displayed with a different font/color.
  Example:
    `info Watch out for the wandering guards.`

Advanced examples: ' Kill Smelly Joe that wanders around|kill Smelly Joe kill Smelly Joe|' Kill Smelly Joe that wanders around kill Smelly Joe|Kill Smelly Joe that wanders around Kill Smelly Joe that wanders around Create a descriptive line that completes upon killing a mob. All are equivalent - the third line as well, as „Kill” (capitalized) is not a valid tag, and thus is treated as „text”, again overriding normal display for the kill command. ' Go outside of the house|goto 34.5,12.8,0.1|c Go outside of the house (has waypoint) A descriptive, completeable, „go to” line with a precise destination. ' Climb to 12.8,34.3|c A descriptive, completeable, „go to” line with a precise destination. goto Elwynn Forest,12.3,45.6|c kill 6 Stalker 'Chop 5 trees|goal 5 Trees chopped|goto 22,34 only Draenei Warrior,Human Paladin Just a bunch of different options.