Where: inside a repository file, e.g.

/plugins/CollectablesCodex/collectables/notes.yml

entries:
  <entry_id_1>: { ... }
  <entry_id_2>: { ... }

Each <entry_id> defines one collectable within the repository’s namespace

Full keys are namespace:id (e.g., notes:torn_page).

Two ways to define entries

1) Base (no type) - simple behavior

You don’t need type if you just want the default behavior:

This is ideal for simple collectables (e.g., fish, artifacts) that don’t need custom logic

2) Typed entries - custom behavior

You can set a type that maps to a registered implementation in the plugin (e.g., NOTE)

Typed entries add extra fields or custom actions.

Example: NOTE opens a book UI on discover/replay

Base entry fields (no type required)

Field Type Required Default / Behavior
displayName String (MiniMessage) No Shown in menus. If omitted, use the ID or keep icons’ own names
plainDisplayName String No If omitted/blank, auto-derived from displayName (formatting stripped)
showWhenLocked boolean No true (repo-level setting can still hide entire locked entries)
allowReplay boolean No false unless you set it; if true, re-trigger replay actions
trackReplays boolean No false. If true, replays are stored in the database (for stats/history). If false, replay side-effects still run but are not persisted
replayOnClick boolean No true. If true, clicking the unlocked entry in the menu also triggers a replay (in addition to any menu click commands)
unlockedIcon ItemEntry No If name blank, auto-uses displayName
lockedIcon ItemEntry No If name blank, defaults to “<dark_gray>???”
commandsOnDiscover CommandEntry No Runs once on initial unlock (if enabled/defined)
commandsOnReplay CommandEntry No If not provided or empty, falls back to commandsOnDiscover
playerMessageOnDiscover String No Sent to the player on unlock (MiniMessage)
playerMessageOnReplay String No If missing, falls back to playerMessageOnDiscover
globalMessageOnDiscover String No Broadcast message on unloc
globalMessageOnReplay String No If missing, falls back to globalMessageOnDiscover
commandsOnMenuLeftClick CommandEntry No Runs when player left-clicks unlocked entry in the menu
commandsOnMenuRightClick CommandEntry No Runs when player right-clicks unlocked entry (fallback to left if null)
commandsOnMenuShiftClick CommandEntry No Runs when player shift-clicks unlocked entry (falls back to left if null)