CustomAchievements

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

API v3.3

AddCategory

id = CA:AddCategory(name [, parent])

Adds a custom category to the achievements list.

Arguements

name

Name of the custom category. (string)

parent

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

Returns

id

ID of the created category. (number)

AddAchievement

id = CA:AddAchievement(tbl)

Creates a custom achievement.

Arguements

tbl

Table containing the achievement/criteria data. Information on this can be found below. (table)

Returns

id

ID of the created achievement. (number)

CloneAchievement

CA:CloneAchievement(id, category)

Adds a non-custom achievement to a custom category.

Arguements

id

ID of the achievement. (number)

category

ID of the category. (number)

CompleteCriteria

CA:CompleteCriteria(id [, arg])

Forces completion of a custom criteria.

Arguements

id

If no second arguement is present, this is the criteria ID. If a second arguement is added, then this is the achievement ID. (number)

arg

(Optional) The number of the criteria within the achievement (starting at 1). (number)

CompleteAchievement

CA:CompleteAchievement(id)

Forces completion of a custom achievement.

Arguements

id

ID of the achievement (number)

Achievement Table Data

The following fields can be added to the achievement table. These are all optional unless otherwise stated:

• category - ID of the category to place this achievement in. (number)
• (Required) name - Name of the achievement. (string)
• texture - Texture path for the achievement. If left as nil then no texture will be shown. (string)
• previous - ID of the previous achievement in a chain. (number)
• save - Without any savekey, this is a string containing the name of a global variable in which you wish to store the save data. With a savekey, this is a reference to a table in which you want the data to be saved.
• savekey - The table field in which to store the achievement completion data. (string)
• key - This field is a unique ID for the achievement. It can be a string, number or even boolean value. This field is required if a "save" field is used in the achievement table.
• criteria - Table containing criteria data. See below for information on this. (table)
• description - Description of the achievement. (string)
• points - Number of achievement points the achievement is worth. (number)
• reward - The reward text shown at the bottom of the achievement. (string)
• complete - If left nil, the achievement will use the saved data for whether or not this achievement is completed. If a table is passed into this field in the format {[1] = day, [2] = month, [3] = year}, then the achievement will be completed and saved with that data.
• required - The number of criteria which must be completed to complete this achievement. If no value is given, then all the criteria must be completed. (number)
• tracked - If left nil, the achievement wil use the saved data for whether or not this achievement is being tracked. If a boolean value is passed (true/false), the tracking for this achievement will be changed.
• handler - A function which will be called everytime an achievement or criteria is completed, or when tracking is changed. The first arguement will be "achievement", "criteria" or "tracked". The second arguement will be a table of achievement/criteria data. (function)
• alert - If you do not want the alert popup to appear when the achievement is completed, then put false in this field. A nil value will result in the popup being shown. (boolean)
• guild - Indicates whether or not to send a message to guild chat when the achievement is completed. A nil value will disable this feature. (boolean)
• group* - Indicates whether or not to send a message to party/raid chat when the achievement is completed. A nil value will disable this feature. (boolean)
• emote - Indicates whether or not to send an emote when the achievement is completed. A nil value will disable this feature. (boolean)
• message - If true, it will always show a message to the player in the chat frame when the achievement completes. If false, it will never show the personal message. If nil, it will only show the message if none of the alert/guild/group/emote were successful. (boolean)

Criteria Table Data

The criteria table has numeric fields from 1 to the number of criteria in the format {[1] = {}, [2] = {}, [3] = {}}, each containing a table of data. The table of data for each criteria can contain the following fields. These are all optional unless otherwise stated:

• (Required) name - Name of the criteria. (string)
• key - This field is a unique ID for the criteria. It can be a string, number or even boolean value. This field is required if a "save" field is used in the achievement table.
• achievement - If the achievement is a meta achievement, this is the ID of the achievement which must be completed to complete this criteria. (number)
• complete - If left nil, the criteria will use the saved data for whether or not this achievement is completed. If a boolean (true/false) is passed into this field, then the criteria completion will be changed.
• value - A function which returns the value of the criteria's progress, if the criteria is using a progress bar. (function)
• required - The max value, required for a criteria to complete which is using a progress bar. (number)
• format - How the value and required value should be displayed on the progress bar, where %d is each value. (string)
• hidden - Whether or not this criteria should be displayed in the achievement. (boolean)
• specific - Indicates whether or not this criteria must be completed in order to complete the achievement, for achievements that have more criteria than required to be completed.
• objective - Function which will be run on event hooks. First arguement is a table of criteria data, second arguement is the event, and the rest of the arguements are those passed with the event. If the first return is true, the criteria will be completed. If the second return is true, the tracking frame will be updated. (function)
• events - Table containing a list of events which this criteria could be completed on. This is only needed if the criteria will be using an objective function. The table is in the format {[1] = "event", [2] = "event", [3] = "event"}. (table)
• hookframe - The frame to hook if the criteria could be completed from some sort of frame action. (frame)
• hookhandler - The hookframe's handler which the action would occur on. (string)
• securehookfunc - The function to securely hook if the criteria could be completed each time it is called. (function)
• hookscript - The objective function which is run each time the hookframe or securehookfunc are fired. The first arguement to this function is a table of criteria data, and the rest are the arguements passed into the function/frame. If this returns true, the criteria will be completed. (function)

You can pull any custom achievement data by using the blizzard api functions such as GetAchievementInfo(myAchievementID).

There is also a custom event which can be used in the events table called: "CA_ACHIEVEMENT_EARNED".