First, add LibCharacterKnowledge (LCK) as a dependency in your addon's manifest:
## DependsOn: LibCharacterKnowledge>=301000
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 may 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( )
Item 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 learning something or by importing data for other characters
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( ) LCK.GetFilteredServerList( )
The current server will always be included, even if there are no characters on the current server (if the user has disabled everyone on the current server), and the current server will always appear first in the list. Furthermore, the Filtered variant will exclude foreign servers for which all characters are disabled. For example, if you are currently on the EU server and there is data for one character from NA, but that character is disabled in the settings, then GetServerList will return { "EU", "NA" } while GetFilteredServerList will return { "EU" }.
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).
Get the name and account associated with a character ID:
LCK.GetCharacterNameAndAccount( server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
The first and second returned parameters are, respectively, the character name the @account name of the specified character. nil is returned if this information is unavailable.
Convert an integer item ID into an item link string:
LCK.GetItemLinkFromItemId( itemId, linkStyle )
If linkStyle is omitted, LINK_STYLE_DEFAULT is assumed.
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 base-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, accountFilter )
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.
accountFilter is an optional parameter to restrict the results to the specified account(s). It can either be a string representing a single account or a hash table of one or more accounts.
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.
If both includedCharIds and accountFilter are specified, the former will take priority. I.e., characters specified by includedCharIds will always appear, even if their associated account is filtered out by accountFilter.
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.
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.
Read a character's effective priority and tracking settings:
LCK.GetRawCharacterSettings( server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
If return is a table containing the effective enablement state, priority, and category tracking states for the specified character, or nil if the character does not exist.
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( )
Not available on console
Crafting motifs are supported by item-based functions such as LCK.GetItemKnowledgeForCharacter and LCK.GetItemKnowledgeList, as well as a number of motif-specific functions that operate with style IDs. In an effort to maintain compatibility with existing APIs, the base-game API's itemStyleId is used to identify motif styles and the base-game API's ITEM_STYLE_CHAPTER_* constants are used to identify motif chapters.
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))
endRetrieve 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 base-game API.
Determine the style ID and chapter of a motif item or a motif Lore Book:
LCK.GetStyleAndChapterFromMotif( item ) LCK.GetStyleAndChapterFromBookId( bookId )
item can be either an integer item ID or an item link string.bookId is an integer item ID used by the base-game Lore Book APIs.
The first returned parameter is an integer style ID (compatible with the itemStyleId used by the base-game API) and the second returned parameter is a chapter constant (one of the ITEM_STYLE_CHAPTER_* constants from the base-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 base-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 base-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 chaptersbookIds: a table whose keys correspond to the base-game API's ITEM_STYLE_CHAPTER_* constants, matched to the Lore Book bookId of that particular chapter or book; the full-book version will be identified by ITEM_STYLE_CHAPTER_ALL.number: 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 by the order in which chapters are listed in achievements; each table entry has the following members:
id: one of the ITEM_STYLE_CHAPTER_* constants from the base-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 base-game API).
The return is one of the base-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 base-game API).
chapterId is one of the base-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 if a Lore Book is known by the current character:
LCK.IsBookIdKnownByCurrentCharacter( bookId )
bookId is an integer item ID used by the base-game Lore Book APIs.
This is a convenience function that is effectively equivalent to select(3, GetLoreBookInfo(GetLoreBookIndicesFromBookId(bookId))).
For characters other than the current character, use LCK.GetMotifKnowledgeForCharacter in conjunction with LCK.GetStyleAndChapterFromBookId.
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 base-game API, except with added server and charId parameters, and their returns are LCK.KNOWLEDGE_* constants:
-- Base-game counterpart: IsCraftedAbilityUnlocked LCK.IsCraftedAbilityUnlockedByCharacter( craftedAbilityId, server, charId ) -- Base-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 base-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.
Trait research mostly operate with craftingSkillType, researchLineIndex, and traitIndex and is not supported by "traditional" functions such as LCK.GetItemKnowledgeForCharacter.
The following functions are analogues to functions found in the base-game API, except with added server and charId parameters:
-- Base-game counterpart: GetMaxSimultaneousSmithingResearch LCK.GetMaxSimultaneousSmithingResearchForCharacter( craftingSkillType, server, charId ) -- Base-game counterpart: GetSmithingResearchLineTraitInfo LCK.GetSmithingResearchLineTraitInfoForCharacter( craftingSkillType, researchLineIndex, traitIndex, server, charId ) -- Base-game counterpart: GetSmithingResearchLineTraitTimes LCK.GetSmithingResearchLineTraitTimesForCharacter( craftingSkillType, researchLineIndex, traitIndex, server, charId ) -- Base-game counterpart: CanItemLinkBeTraitResearched LCK.CanItemLinkBeTraitResearchedByCharacter( itemLink, server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
Their returns should match their base-game API counterparts; they do not use any of the LCK constants.
Note: For research that is pending completion on a different character (in-progress with zero or negative time remaining), LCK.GetSmithingResearchLineTraitInfoForCharacter's known return field will be true, and LCK.GetSmithingResearchLineTraitTimesForCharacter's timeRemainingSecs return field will be a number less than or equal to zero.
Get the name, icon, and other information about a trait:
LCK.GetTraitInfo( craftingSkillType, researchLineIndex, traitIndex ) LCK.GetTraitInfo( traitType ) LCK.GetTraitList( )
LCK.GetTraitInfo returns trait information for a single trait; the trait can be specified either via the three standard research indices or via a single traitType.
LCK.GetTraitList returns a table containing every researchable trait, keyed by each trait's traitType.
The information for each individual trait is a table in the following format:
-- Sample output of LCK.GetTraitInfo(CRAFTING_TYPE_BLACKSMITHING, 1, 1)
{
traitType = ITEM_TRAIT_TYPE_WEAPON_POWERED,
traitTypeCategory = ITEM_TRAIT_TYPE_CATEGORY_WEAPON,
traitItemIndex = 2, -- Compatible with the base-game API's traitItemIndex
name = "Powered", -- Localized name of the trait
itemName = "Chysolite", -- Localized name of the trait material
icon = "/esoui/art/icons/crafting_runecrafter_potion_008.dds", -- Icon representing the trait material
}Get a list of the values of craftingSkillType that support research:
LCK.GetSmithingResearchTradeskillTypes( )
Returns the following table: { CRAFTING_TYPE_BLACKSMITHING, CRAFTING_TYPE_CLOTHIER, CRAFTING_TYPE_WOODWORKING, CRAFTING_TYPE_JEWELRYCRAFTING }
Get craftingSkillType, researchLineIndex, and traitIndex from an itemLink:
LCK.GetSmithingResearchFromItemLink( itemLink )
Returns craftingSkillType, researchLineIndex, and traitIndex if the item specified by itemLink has a researchable trait, otherwise nil is returned.
Reminder: Reconstructed and retraited items do not have researchable traits.
Get the knowledge state and time remaining of a trait:
LCK.GetSmithingResearchStatusForCharacter( craftingSkillType, researchLineIndex, traitIndex, server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
The returns are knowledgeState and timeRemainingSecs. knowledgeState is one of the LCK.KNOWLEDGE_* constants. timeRemainingSecs is either the number of seconds remaining for ongoing research for this trait or nil if there is no ongoing research for this trait.
Note: For research that is pending completion on a different character (in-progress with zero or negative time remaining), the knowledgeState return field will be LCK.KNOWLEDGE_UNKNOWN, and the timeRemainingSecs return field will be a number less than or equal to zero.
Get the knowledge state and time remaining of a trait for multiple characters; this is effectively a tracking-aware combination of LCK.GetCharacterList and LCK.GetSmithingResearchStatusForCharacter:
LCK.GetSmithingResearchStatusForCharacters( craftingSkillType, researchLineIndex, traitIndex, server, includedCharIds, accountFilter )
If server is omitted (nil), the current server is assumed.
includedCharIds is a optional hash table containing characters to exempt from tracking exclusions.
accountFilter is an optional parameter to restrict the results to the specified account(s). It can either be a string representing a single account or a hash table of one or more accounts.
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_* constantsremaining: the number of seconds remaining for ongoing research for this trait or nil if there is no ongoing research for this traitThe 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.
If both includedCharIds and accountFilter are specified, the former will take priority. I.e., characters specified by includedCharIds will always appear, even if their associated account is filtered out by accountFilter.
Note: For research that is pending completion on a different character (in-progress with zero or negative time remaining), the knowledge field will be LCK.KNOWLEDGE_UNKNOWN, and the remaining field will be a number less than or equal to zero.
Get the number of known traits for a research line:
LCK.GetSmithingResearchLineKnownTraitCountForCharacter( craftingSkillType, researchLineIndex, 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 the number of completed traits for this research line, or 0 if the research line is invalid or if the character does not exist.
Note: For research that is pending completion on a different character (in-progress with zero or negative time remaining), this function will count the trait as completed.
Get the researchability status of a trait:
LCK.CanTraitBeImmediatelyResearchedByCharacter( craftingSkillType, researchLineIndex, traitIndex, server, charId )
If server is omitted (nil), the current server is assumed.
If charId is omitted (nil), the current character is assumed.
false.true.Note: For research that is pending completion on a different character (in-progress with zero or negative time remaining), this function will consider the trait as completed and the research slot as free.
Get a list of all ongoing research across all tracked characters:
LCK.GetAllActiveResearchItemsList( )
The return is a list of tables, sorted by time remaining; each table entry has the following members:
server: "NA", "EU", or "PTS"id: character ID (string)account: @account name (string)name: character's name (string)craftingSkillTyperesearchLineIndextraitIndexduration: seconds total (integer)remaining: seconds remaining (integer)Note: Research that is pending completion on a different character (in-progress with zero or negative time remaining) will appear in the results.
Please refer to LibCharacterKnowledge: Saved Variables.