First, add LibCharacterKnowledge (LCK) as a dependency in your addon's manifest:
## DependsOn: LibCharacterKnowledge>=201000
The library can be accessed via the LibCharacterKnowledge global variable, and it is recommended that you localize it for usage; for example:
local LCK = LibCharacterKnowledge
In order to minimize the impact on load screen times, LCK delays much of its initialization until 0.2s after the initial load screen has completed. Initialization itself should take 0.1s or less, so LCK should be ready for use within the first half second after the initial load screen. However, initialization will take longer (up to 5s) after the first time LCK is installed on the system or after a major game update.
Not all LCK functions require LCK's initialization to have been completed, but those that do should fail gracefully (i.e., there will be no error) if invoked prior to the completion of initialization.
If your code invokes LCK in response to user actions; for example, if you use LCK to add information to an item tooltip: You generally can ignore initialization, since it is highly unlikely the user will be interacting with the UI within the first second of the initial load screen.
If your code invokes LCK during your own startup initialization: You need to register a callback for LCK.EVENT_INITIALIZED. For example:
LCK.RegisterForCallback("InsertYourAddonNameHere", LCK.EVENT_INITIALIZED, function( )
-- do stuff
end)
Note: Callbacks for LCK.EVENT_INITIALIZED that are registered after LCK's initialization will not fire; it is thus recommended that LCK.EVENT_INITIALIZED callbacks be registered prior to the completion of the initial load screen.
Throughout this document, functions and code that require initialization to be completed will be highlighted in light blue; for example:
LCK.GetServerList( )
LibCharacterKnowledge has always tracked motif knowledge using the Lore Book system and is thus unaffected by the changes to the Achievements system. In an effort to maintain compatibility with existing APIs, the in-game API's itemStyleId is used to identify motif styles and the in-game API's ITEM_STYLE_CHAPTER_* constants are used to identify motif chapters.
The following motif-related functions are available:
LCK.GetMotifStyles( ) LCK.GetStyleAndChapterFromMotif( item ) LCK.GetMotifItemsFromStyle( styleId ) LCK.GetMotifChapterNames( ) LCK.GetMotifStyleQuality( styleId ) LCK.GetMotifKnowledgeForCharacter( styleId, chapterId, server, charId )
Example: Determining if the current character knows Crimson Oath Chests
local LCK = LibCharacterKnowledge if (LCK.GetMotifKnowledgeForCharacter(123, ITEM_STYLE_CHAPTER_CHESTS) == LCK.KNOWLEDGE_KNOWN) then -- the itemStyleId for Crimson Oath is 123 end
Example: Printing a list of the motif styles
local LCK = LibCharacterKnowledge
for _, styleId in ipairs(LCK.GetMotifStyles()) do
local items = LCK.GetMotifItemsFromStyle(styleId)
d(zo_strformat("<<1>>: <<t:2>> (<<3>> chapters)", items.number, GetItemStyleName(styleId), #items.chapters))
endItem categories
LCK.ITEM_CATEGORY_NONE -- Item is invalid (not a recipe, furnishing plan, motif, or scribing item) LCK.ITEM_CATEGORY_RECIPE -- Item is a provisioning recipe LCK.ITEM_CATEGORY_PLAN -- Item is a furnishing plan LCK.ITEM_CATEGORY_MOTIF -- Item is a motif chapter or book LCK.ITEM_CATEGORY_SCRIBING -- Item is a grimoire or script -- Localized name strings for each of the three categories LCK.ITEM_CATEGORIES[LCK.ITEM_CATEGORY_RECIPE] -- e.g., "Recipe" in English LCK.ITEM_CATEGORIES[LCK.ITEM_CATEGORY_PLAN] -- e.g., "Furnishing Plan" in English LCK.ITEM_CATEGORIES[LCK.ITEM_CATEGORY_MOTIF] -- e.g., "Motif" in English LCK.ITEM_CATEGORIES[LCK.ITEM_CATEGORY_SCRIBING] -- e.g., "Scribing" in English
Knowledge states
LCK.KNOWLEDGE_INVALID -- Not a recipe, furnishing plan, motif, or scribing item LCK.KNOWLEDGE_NODATA -- No data for this character LCK.KNOWLEDGE_KNOWN LCK.KNOWLEDGE_UNKNOWN
Callbacks
LCK.EVENT_INITIALIZED -- Fired when LibCharacterKnowledge has completed its initialization LCK.EVENT_UPDATE_REFRESH -- Fired when knowledge data has been updated, either by the character having learned something or data for other characters have been imported
Get the list of servers for which data is available ("NA", "EU", and/or "PTS"), with the current server sorted to the front:
LCK.GetServerList( )
Get the list of characters for which data is available on the selected server:
LCK.GetCharacterList( server )
If server is omitted (nil), the current server is assumed.
The return is a list of tables; each table entry has the following members:
id: character ID (string)account: @account name (string)name: character's name (string)The list of characters returned will follow the user's settings regarding priority (i.e., the order in which characters appear in this list follows the user-adjustable priority order).
Convert an integer item ID into an item link string:
LCK.GetItemLinkFromItemId( itemId )
Get the name of an item:
LCK.GetItemName( item )
item can be either an integer item ID or an item link string.
This function differs from the in-game GetItemLinkName in that the output is formatted (converted to title case and any ^ format markers are removed).
Determine the type (category) of an item:
LCK.GetItemCategory( item )
item can be either an integer item ID or an item link string.
The return is one of the LCK.ITEM_CATEGORY_* constants.
Determine whether a character knows an item:
LCK.GetItemKnowledgeForCharacter( item, server, charId )
item can be either an integer item ID or an item link string.
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
The return is one of the LCK.KNOWLEDGE_* constants.
Determine the knowledge state of an item for multiple characters; this is effectively a tracking-aware combination of LCK.GetCharacterList and LCK.GetItemKnowledgeForCharacter:
LCK.GetItemKnowledgeList( item, server, includedCharIds )
item can be either an integer item ID or an item link string.
If server is omitted (nil), the current server is assumed.
includedCharIds is a optional hash table containing characters to exempt from tracking exclusions.
The return is a list of tables; each table entry has the following members:
id: character ID (string)account: @account name (string)name: character's name (string)knowledge: one of the LCK.KNOWLEDGE_* constantsThe list of characters returned will follow the user's settings regarding priority (i.e., the order in which characters appear in this list follows the user-adjustable priority order) and tracking (i.e., characters can be omitted based on the user-adjustable tracking settings). The optional includedCharIds parameter can be used to override tracking settings for specific characters.
Determine whether a knowledge state is usable:
LCK.IsKnowledgeUsable( knowledge )
This convenience function returns true if knowledge is either LCK.KNOWLEDGE_KNOWN or LCK.KNOWLEDGE_UNKNOWN (i.e., not LCK.KNOWLEDGE_INVALID or LCK.KNOWLEDGE_NODATA).
Retrieve a list of all item IDs associated for a particular type (category):
LCK.GetItemIdsForCategory( category )
category is one of the LCK.ITEM_CATEGORY_* constants. (LCK.ITEM_CATEGORY_SCRIBING is unsupported)
The return is a list of integer item IDs.
Get the item ID of the recipe or furnishing plan that produces the specified craftable item:
LCK.GetSourceItemIdFromResultItem( resultItem )
resultItem can be either an integer item ID or an item link string.
The return is the item ID of the recipe or furnishing plan that produces resultItem; if resultItem is not craftable, the return will be 0.
Retrieve a list of style IDs with craftable motifs:
LCK.GetMotifStyles( )
The return is a list of integer style IDs; these are compatible with the itemStyleId used by the in-game API.
Determine the style ID and chapter of a motif book or chapter item:
LCK.GetStyleAndChapterFromMotif( item )
item can be either an integer item ID or an item link string.
The first returned parameter is an integer style ID (compatible with the itemStyleId used by the in-game API) and the second returned parameter is a chapter constant (one of the ITEM_STYLE_CHAPTER_* constants from the in-game API).
Retrieve a list of motif items associated with a particular style ID:
LCK.GetMotifItemsFromStyle( styleId )
styleId is an integer style ID (compatible with the itemStyleId used by the in-game API).
If there is no craftable motif associated with styleId, then the return is nil; otherwise, the return is a table with the following members:
books: a list of item IDs corresponding to the full-book versions of the motifchapters: a table whose keys correspond to the in-game API's ITEM_STYLE_CHAPTER_* constants, matched to a value corresponding to the item ID of the appropriate motif chapter; this table is empty for motifs that have no chaptersnumber: the crafting motif book number that is shown in-game (integer)achievementId: the ID of the achievement associated with this style (integer); this value is 0 if there is no achievement (e.g., if the style is exclusive to the Crown Store)crown: whether the style is exclusive to the Crown Store (boolean)Retrieve a list of localized motif chapter type names:
LCK.GetMotifChapterNames( )
The return is a list of tables, sorted alphabetically by name; each table entry has the following members:
id: one of the ITEM_STYLE_CHAPTER_* constants from the in-game APIname: the localized name of the chapter typeFor example, on the English client, the first item in the list will be { id = ITEM_STYLE_CHAPTER_AXES, name = "Axes" }
Retrieve the item quality of a motif style:
LCK.GetMotifStyleQuality( styleId )
styleId is an integer style ID (compatible with the itemStyleId used by the in-game API).
The return is one of the in-game API's ITEM_FUNCTIONAL_QUALITY_* constants, corresponding to the quality of that motif style's full book.
Determine whether a character knows a motif; this effectively wraps LCK.GetItemKnowledgeForCharacter with LCK.GetMotifItemsFromStyle:
LCK.GetMotifKnowledgeForCharacter( styleId, chapterId, server, charId )
styleId is an integer style ID (compatible with the itemStyleId used by the in-game API).
chapterId is one of the in-game API's ITEM_STYLE_CHAPTER_* constants; if it is omitted (nil), the complete motif book (ITEM_STYLE_CHAPTER_ALL) is assumed.
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
The return is one of the LCK.KNOWLEDGE_* constants. For motifs that have no chapters, the returned knowledge state is always that of the complete motif (i.e., chapterId is effectively ignored).
Determine when a character's knowledge was most recently scanned:
LCK.GetLastScanTime( server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
The return is a Unix-style timestamp.
Callbacks:
LCK.RegisterForCallback( name, eventCode, callback ) LCK.UnregisterForCallback( name, eventCode )
eventCode is one of the LCK.EVENT_* constants.
Open the LibCharacterKnowledge settings panel:
LCK.OpenSettingsPanel( )
Scribing is fully supported by traditional item-based functions such as LCK.GetItemKnowledgeForCharacter and LCK.GetItemKnowledgeList. However, it is often more useful to work with the IDs of the grimoires and scripts, and the following functions operate on these IDs.
The following functions are analogues to functions found in the in-game API, except with added server and charId parameters, and their returns are LCK.KNOWLEDGE_* constants:
-- In-game counterpart: IsCraftedAbilityUnlocked LCK.IsCraftedAbilityUnlockedByCharacter( craftedAbilityId, server, charId ) -- In-game counterpart: IsCraftedAbilityScriptUnlocked LCK.IsCraftedAbilityScriptUnlockedByCharacter( craftedAbilityScriptId, server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
The return is one of the LCK.KNOWLEDGE_* constants.
Get the maximum ID for grimoires and scripts:
LCK.GetMaxCraftedAbilityId( ) LCK.GetMaxCraftedAbilityScriptId( )
The return is an integer representing the highest valid ID of the requested type.
It is unclear how the in-game GetNumCraftedAbilities will behave if, in the future, there are gaps in the IDs, whereas these functions will unambigiously always return the highest ID, rather than the number of valid IDs.
Get the in-game item that will grant knowledge of a grimoire or script:
LCK.GetItemForCraftedAbility( craftedAbilityId ) LCK.GetItemForCraftedAbilityScript( craftedAbilityScriptId )
The return is an integer item ID.
Get the descriptions of a script:
LCK.GetCraftedAbilityScriptDescriptions( craftedAbilityScriptId )
The return is a table of descriptions; each description is itself a table where the first element is the name of the grimoire for which the description is for, the second element is the description text, and the third element is the grimoire's numeric ID.