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)
Installation Guide
- Exit "World of Warcraft" completely
- Download the mod you want to install
- Make a folder on your desktop called "My Mods"
- Save the .zip/.rar files to this folder.
- If, when you try to download the file, it automatically "opens" it... you need to RIGHT click on the link and "save as..." or "Save Target As".
- Extract the file - commonly known as 'unzipping'
Do this ONE FILE AT A TIME!
- Windows
- Windows XP has a built in ZIP extractor. Double click on the file to open it, inside should be the file or folders needed. Copy these outside to the "My Mods" folder.
- WinRAR: Right click the file, select "Extract Here"
- WinZip: You MUST make sure the option to "Use Folder Names" is CHECKED or it will just extract the files and not make the proper folders how the Authors designed
- Mac Users
- StuffitExpander: Double click the archive to extract it to a folder in the current directory.
- Verify your WoW Installation Path
That is where you are running WoW from and THAT is where you need to install your mods.
- Move to the Addon folder
- Open your World of Warcraft folder. (default is C:\Program Files\World of Warcraft\)
- Go into the "Interface" folder.
- Go into the "AddOns" folder.
- In a new window, open the "My Mods" folder.
- The "My Mods" folder should have the "Addonname" folder in it.
- Move the "Addonname" folder into the "AddOns" folder
- Start World of Warcraft
- Make sure AddOns are installed
- Log in
- At the Character Select screen, look in lower left corner for the "addons" button.
- If button is there: make sure all the mods you installed are listed and make sure "load out of date addons" is checked.
- If the button is NOT there: means you did not install the addons properly. Look at the above screenshots. Try repeating the steps or getting someone who knows more about computers than you do to help.
Translations
When you download a mod, please be sure that the mod is compatible with your translation of wow. Some mods only work on the US versions, while some only work on some of the various European versions. These variations are called "Localizations".
TOC Numbers (Out of Date Mods)
When Blizzard patches WoW, they change the Interface number. This means that all mods will be "out of date" unless or until the author releases a new version for that interface. Some people go into the .toc files and update the numbers themselves, but this is STRONGLY advised against as it will cause problems locating possible incompatibilities addons. When you log into WoW after a patch, you DO NOT have to delete your interface directory. All you have to do is simply tell WoW to ignore the interface numbers and load all the mods anyway. All you have to do is, while at the "character select" screen, look in the lower left corner and click on the "addons" button. A window will pop up listing all your installed mods.
If you look in the upper left corner of that window there should be a box that says "Load Out of Date AddOns". You want to CHECK this box. Now simply go into WoW normally and all your mods should load. As of the 1.9 patch, you will have to do this after EVERY patch/update that Blizzard posts! If you encounter any problems with a mod after a patch, please be sure to let the author of the mod know so they can fix it.
See also: About "Out Of Date AddOns"
Mac Support
WoW addons are not platformed based. As such, they can be used on either Mac or PC. You can extract both .zip and .rar files on a Mac using StuffitExpander.
Directory Structure
World of Warcraft
|_ Interface
|_AddOns
|_*AddonName*
|_ *AddonName*.toc
|_ *AddonName*.xml
|_ *AddonName*.lua
|_ (possibly others as well)...
