LibCharacterKnowledge

Developer Reference

Table of Contents

  1. Getting Started
  2. Initialization
  3. Working with Motifs
  4. Constants
  5. Functions

Getting Started

First, add LibCharacterKnowledge (LCK) as a dependency in your addon's manifest:

## DependsOn: LibCharacterKnowledge>=11

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

Initialization

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 will 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( )

Working with Motifs

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))
end

Constants

Item categories

LCK.ITEM_CATEGORY_NONE   -- Item is invalid (not a recipe, furnishing plan, or motif)
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

-- 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

Knowledge states

LCK.KNOWLEDGE_INVALID -- Not a recipe, furnishing plan, or motif
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

Functions

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:

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:

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) 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.KNOWLEDGE_* constants.

The return is a list of integer item IDs.

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).

The return is a table with the following members:

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:

For 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( )