WoW Addon Utilities

A collection of functions used in my World of Warcraft© addons which might hopefully prove to be useful to other addon developers as well; feel free to use these in your own addon projects.
Each LUA file of this repository is about a specific WoW topic and contains methods and constants related to that topic. See Repository contents for a complete overview.

Note: This is not an addon nor a LibStub library!  

Usage

There are multiple ways to include these utility files into your project. Here are some examples:

📦 Download and Copy

1. Download the whole package or just the file you need from this repo.

2. Extract ZIP file or copy single file into a folder inside your project's directory.

3. Add a reference to the file(s) in your addon's TOC file.

4. Use in your LUA files, eg. as follows:

   local AddonID, ns = ...
   -- 'ns.utils' holds all utilities
   -- 'ns.utils.achieve' holds all achievement related utilities, etc.

📝 Add to PKMETA File

Copy the below snippet into your .pkmeta/pkmeta.yml file:

externals:
    utils: https://github.com/erglo/wow-addon-utilities.git
    # 'utils' is the name of the folder in your project where you keep the
    # utility files; this is merely a name I chose.

🔗 Include as a Git Submodule

# Links the submodule with folder "dir_name"
git submodule add https://github.com/erglo/wow-addon-utilities.git [dir_name]
# Copies all files from the submodule into "dir_name"
git submodule update --init

♻️ Clone this Repository

git clone https://github.com/erglo/wow-addon-utilities.git

---

Repository Contents

• achievements.lua (ns.utils.achieve) - A collection of utilities handling achievements.

  • .GetWrappedAchievementInfo(achievementID, raw) → achievementInfo: table|nil
    A key-value wrapper for GetAchievementInfo().
  • .GetWrappedAchievementCriteriaInfo(achievementID, criteriaIndex, raw) → criteriaInfo: table|nil
    A key-value wrapper for GetWrappedAchievementCriteriaInfo().
  • .GetWrappedAchievementNumCriteria(achievementID, includeCompleted) → numCriteria: number, numCompleted: number|nil
    Retrieve the total and optionally the completed criteria number for given achievement.
  • 🆕 .GetAchievementLinkWithIcon(achievementInfo) → achievementLink: string
    Generate an achievement hyperlink with an icon in front of it for given wrapped achievement.
  • .IsAchievementCompleted(achievementID) → isCompleted: boolean
    Check whether given achievement has been completed.
  • .IsAssetCriteriaCompleted(achievementID, assetID) → isCompleted: boolean
    Check if the criteria of given asset has been completed for given achievement.
  • .GetAchievementCriteriaInfoList(achievementID) → criteriaInfoList: table
    Retrieve all wrapped criteriaInfo for given achievement.
  • .GetMainCategoryInfoList() → mainCategoryInfoList: table
    Retrieve a list of wrapped categoryInfo of the main achievement categories.

• currencies.lua

  • TODO - Add currency handler

• handynotes.lua (ns.utils.handynotes) - A collection of utilities for HandyNotes plugins.
  ⚠️Requires: HandyNotes

  • :GetCoordFromXY(x, y) → coord: number
    Get the HandyNotes coordinates from given x/y position numbers.
  • :GetXYFromCoord(coord) → x: number, y: number
    Get the x/y position from given HandyNotes coordinates number.
  • :GetPlayerMapCoord() → mapID: number|nil, coord: number|nil
    Get the uiMapID and the HandyNotes coordinates from the player's current position.
  • :SetMapCoordUserWaypoint(mapID, coord, chatNotifyOnError) → success: boolean
    Set a user waypoint on given map at given HandyNotes coordinates. The optional "chatNotifyOnError" informs the user additionally in chat that given map doesn't support waypoints (on screen by default).
  • :GetUserWaypointMapCoord() → mapID: number|nil, coord: number|nil
    Get the uiMapID and the HandyNotes coordinates from a user waypoint.
  • 🆕 :ClearUserWaypoint()
    Remove a previously set user waypoint.

• 🆕 libqtip.lua (ns.utils.libqtip) - A collection of wrapper for the LibQTip-1.0 library.
  ⚠️Requires: LibQTip-1.0

  • :AddBlankLineToTooltip(tooltip, ...)
    Add a new empty line to the bottom of the LibQTip tooltip.
  • :AddColoredLine(tooltip, FontColor, ...)
    Add a new line with text in given font color to the bottom of the LibQTip tooltip.
  • :AddDisabledLine(tooltip, ...)
    Add a new line with GRAY text to the bottom of the LibQTip tooltip.
  • :AddErrorLine(tooltip, ...)
    Add a new line with RED text to the bottom of the LibQTip tooltip.
  • :AddHighlightLine(tooltip, ...)
    Add a new line with 'highlighted' (white) text color to the bottom of the LibQTip tooltip.
  • :AddInstructionLine(tooltip, ...)
    Add a new line with GREEN text to the bottom of the LibQTip tooltip.
  • :AddNormalLine(tooltip, ...)
    Add a new line with 'normal' (golden) text color to the bottom of the LibQTip tooltip.
  • :SetTitle(tooltip, ...)
    Add a new header line with 'highlighted' (white) text color and a slightly bigger font size to the bottom of the LibQTip tooltip.
  • :SetColoredTitle(tooltip, FontColor, ...)
    Add a new header line with text in given font color and a slightly bigger font size to the bottom of the LibQTip tooltip.
  • :AddQuestTagTooltipLine(tooltip, tagName, tagID, worldQuestType, color, iconWidth, iconHeight, ...)
    Add a new line with given quest type tag in 'normal' (golden) text color to the bottom of the LibQTip tooltip.
  • :CopyGameTooltipTo(tooltip, FontColor)
    Copy the GameTooltip's left side text to the given LibQTip tooltip.

• 🆕 worldmap.lua (ns.utils.worldmap) - A collection of utilities for the World Map.

  • Different Enum.UIMapType constants with the pattern: ns.utils.handynotes.*_MAP_ID
  • :GetMapInfo(uiMapID) → mapInfo: UiMapDetails
    Return the map information for given map.
  • :GetMapChildrenInfo(mapID, mapType, allDescendants) → mapChildrenInfos: UiMapDetails[]
    Get the map information for each child zone of given map.
  • :GetMapInfoAtPosition(uiMapID, x, y, ignoreZoneMapPositionData) → mapInfo: UiMapDetails
    Return map information for any child map at given position on the map. Note: The argument ignoreZoneMapPositionData is optional.
  • :GetBestMapForPlayer() → uiMapID: number
    Returns the current uiMapID of the player's current location.
  • :GetPlayerPosition() → playerMapPosition: Vector2DMixin|nil
    Returns the player's current map position.
  • :IsMapTypeContinent(uiMapID) → isContinent: boolean
    Check whether the given map is a continent.
  • :SetUserWaypointXY(uiMapID, posX, posY, setActive, chatNotifyOnError) → mapPoint: UiMapPoint|nil
    Set a user waypoint on given map at given position.
  • :GetUserWaypoint() → mapPoint: UiMapPoint|nil
    Get the UiMapPoint of a previously set user waypoint.
  • :ClearUserWaypoint()
    Remove a previously set user waypoint.

---

Tools Used

• Microsoft's Visual Studio Code with ...
  • Sumneko's Lua Language Server extension
  • Ketho's World of Warcraft API extension
  • Stanzilla's World of Warcraft TOC Language Support extension
  • David Anson's Markdown linting and style checking extension
• Version control management with Git + GitHubactions-recent-changelog)
• In-game development tools (addons):
  • BugGrabber, BugSack, idTip, TextureViewer, WoWLua.
• Game libraries:
  • HandyNotes, LibQTip-1.0.

References

• Townlong Yak's FrameXML archive
• WoWpedia's World of Warcraft API
• Wowhead.com
• Matt Cone's "The Markdown Guide" → (Buy his book!)
• The Git Book
• Documentation for Visual Studio Code

---

Disclaimer

World of Warcraft© and Blizzard Entertainment© are all trademarks or registered trademarks of Blizzard Entertainment in the United States and/or other countries. These terms and all related materials, logos, and images are copyright © Blizzard Entertainment.

The tools used to create this utility collection reflect my own preferences and are not endorsed nor payed by anybody. A little credit to the developers for their great job is the least we can do.