Description only valid for v3.1 r2 and below (v3.3 description coming soon)

This AddOn library is still very new. I will be updating it soon for new functionality and a more efficient/simple API. Please only use the current versions as a test-basis if you plan to use this in your own AddOns. If you would like help/explanation on how to use this in your own AddOn, send a private message to me (Aelobin).


CustomAchievements is a WoW addon library that allows addon authors to easily create custom achievements.

CustomAchievements v3.1 API

CA:AddCategory(name [, parent])

Returns

The category ID (number)

Arguments

name

The name for the new category (string)

parent

(Optional) The category ID of the parent category (number)

CA:AddAchievement(tbl)

Returns

The achievement ID (number)
A table of criteria IDs in the same order as the tbl.criteria input table (table)

Arguments

tbl

Achievement data (table) - More information in the Advanced section below.

CA:AddAchievement(achievement, category)

Returns

The achievement ID (number)

Arguments

achievement

The ID of the achievement (number)

category

The ID of the category (number)

How to include CustomAchievements in a library or addon

Files

• download the current version of CustomAchievements
• copy the LibStub folder to your AddOn's folder
• copy the CustomAchievements.lua file to your AddOn's folder
• Add LibStub\LibStub.lua as the first file to be loaded in your AddOn's .toc file
• Add CustomAchievements.lua underneath LibStub in your AddOn's .toc file

The LibStub and CustomAchievements files can also be placed in any other folders, so long as your AddOn's .toc file points to them correctly

Code

local CA = LibStub:GetLibrary("CustomAchievements-3.1")

Instructions

• It is the responsibility of your AddOn to save the completed state/dates for your criteria/achievements, and also whether they are tracked or not. You can get this information from when your handler function runs on each change. The completed/tracked information should be set during the creation of your achievements (therefore if you wish achievements/criteria to stay complete between sessions, creating achievements should be done after your addon has fired "ADDON_LOADED" when your SavedVariables are loaded).
• There is a custom event for use only within the tbl.criteria[number].events inputs in CA:AddAchievement. It will fire when any of your achievements (or other achievements made with the same library version) are completed.

Example

local CA = LibStub:GetLibrary("CustomAchievements-3.1")

local my_category = CA:AddCategory("Test")
local target_practice = CA:AddAchievement({
    category = my_category,
    name = "Target Practice",
    description = "Target some things",
    texture = "Interface\\ICONS\\Spell_Holy_ChampionsGrace",
    options = {
        alert = true,
        guild = true,
    },
    handler = print,
    criteria = {
        {
                name = "Target Yourself",
                events = {"PLAYER_TARGET_CHANGED"},
                objective = function(event, ...)
                    return UnitIsUnit("PLAYER","TARGET")
                end),
        },
        {
                name = "Target Something Else",
                events = {"PLAYER_TARGET_CHANGED"},
                objective = function(event, ...)
                    return (not UnitIsUnit("PLAYER","TARGET") and UnitExists("TARGET"))
                end),
        },
    },
})

Advanced

Achievement data

tbl = {
    category =      ,      (number)
    name =      ,      (string)
    description =      ,      (string)
    (optional) points =      ,      (number)
    (optional) reward =      ,      (string)
    (optional) completed = {      (table)
        day =      ,      (number)
        month =      ,      (number)
        year =      ,      (number)
    },
    (optional) previous =      ,      (number)
    (optional) required =      ,      (number)
    (optional) texture =      ,      (string)
    (optional) options = {      (table)
        (optional) alert =      ,      (boolean)
        (optional) guild =      ,      (boolean)
        (optional) emote =      ,      (boolean)
    },
    (optional) tracked =      ,      (boolean)
    handler =      ,      (function)
    (optional) ref =      ,      (anything, string/number recommended)
    criteria = {      (table)
        [1] = {      (table)
                name =      ,      (string)
                events = {      (table)
                    [1] =      ,      (string)
                },
                objective =      ,      (function)
                (optional) completed =      ,      (boolean)
                (optional) hidden =      ,      (boolean)
                (optional) achievement =      ,      (number)
                (optional) ref =      ,      (anything, string/number recommended)
        },
    },
}

Handler

Achievement Arguements

my_handler(type, achievement, ref, completed)

type

"achievement" (string)

achievement

The ID of the achievement which just completed (number)

ref

The reference stored for that achievement (anything)

completed

A table containing the completion date in the format {day = number, month = number, year = number} (table)

Criteria Arguements

my_handler(type, criteria, ref)

type

"criteria" (string)

criteria

The ID of the criteria which just completed (number)

ref

The reference stored for that criteria (anything)

Tracking Arguements

my_handler(type, achievement, ref, state)

type

"tracked" (string)

achievement

The ID of the achievement which was just added/remove from tracking (number)

ref

The reference stored for that achievement (anything)

state

Whether or not the achievement is now tracked (boolean)

CA_ACHIEVEMENT_EARNED

Note: This event should only be used for your own custom achievements, although it may fire for achievements made by other AddOns too (due to library versioning).

Event Arguements

achievement

The ID of the achievement which just completed (number)

ref

The reference stored for that achievement (anything)

completed

A table containing the completion date in the format {day = number, month = number, year = number} (table)

handler

The handler which this achievement was attached to (function)