Configuration

Every field in the EmakiCodex configuration files is listed below with its default value and purpose

EmakiCodex configuration is split into main settings, vanilla advancement pages, category entries, a GUI template, and language files. The four files detailed below are config.yml, codex/*.yml, gui/codex_gui.yml, and lang/*.yml -- keep their roles apart first:

• config.yml: global switches, default resource release, vanilla advancement registration, and the PacketEvents coordinate channel
• codex/*.yml: categories, entries, unlock conditions, and rewards; its category_id namespace is independent from advancements/*.yml page_id
• gui/codex_gui.yml: category-entry GUI layout and placeholders
• lang/*.yml: command, GUI, and console messages

The page and node fields of advancements/*.yml are documented in Advancements, category entries in Category GUI, and both automatic unlock paths in Triggers

config.yml

Default main configuration:

version: "1.1.6"
language: "zh_CN"
release_default_data: true
op_bypass: false

advancement:
  enabled: true
  announce_default: false
  remove_on_disable: true
  packet_coordinates: true
  triggers_enabled: true

Field reference (Required = No means the source supplies a default and the key may be omitted):

Field	Type	Required	Default	Allowed values	Description
version	string	No	1.1.6	any string	Configuration-structure marker; the internal migration constant is 1.0.14 and is not a release coordinate
language	string	No	zh_CN	file name of lang/<language>.yml	Uses lang/<language>.yml; falls back to zh_CN when blank or missing
release_default_data	boolean	No	true	true / false	When true and the files are missing, releases bundled advancements/example_page.yml, codex/example_category.yml, and related default data
op_bypass	boolean	No	false	true / false	When true, OPs bypass the command permission checks; when false, they still need the relevant permission nodes
advancement.enabled	boolean	No	true	true / false	Master switch for vanilla advancement registration; when disabled, loading and registration are skipped and /codex reload removes the plugin's registered nodes
advancement.announce_default	boolean	No	false	true / false	Default broadcast behavior when a node does not define announce
advancement.remove_on_disable	boolean	No	true	true / false	Removes registered dynamic advancements when the plugin is disabled. The /codex reload rebuild always clears the plugin namespace before registering, regardless of this switch
advancement.packet_coordinates	boolean	No	true	true / false	Injects node x / y into the client tree when PacketEvents is installed. The value is read when the packet gateway is built at enable time; changing it at runtime requires a restart
advancement.triggers_enabled	boolean	No	true	true / false	Enables automatic gameplay-trigger grants (node triggers.entries and entry unlock.triggers). When disabled, commands, API, and CoreLib actions can still grant manually

Configuration example (disable automatic triggers, keep coordinate injection):

language: "en_US"
op_bypass: true

advancement:
  enabled: true
  packet_coordinates: true
  triggers_enabled: false

Category files: codex/*.yml

Each file defines one GUI category. The filename is not the id; the category id comes from category_id. The composite entry id is always <category_id>/<entry_id>, for example example/first_blood

Shipped default excerpt (from codex/example_category.yml):

category_id: "example"
title: "<gold>Trial Codex</gold>"
icon: "minecraft-book"
order: 100

entries:
  first_blood:
    title: "<yellow>First Hunt</yellow>"
    description: "<gray>Defeat any hostile creature.</gray>"
    icon: "minecraft-iron_sword"
    hidden: false
    unlock:
      triggers:
        - event: "entity_kill"
      advancements: []
    rewards:
      attributes:
        physical_attack: 2.0
      actions:
        - "send_message text=<green>You claimed the first-hunt reward.</green>"

Field reference (every key below is available under each entry in entries):

Field	Type	Required	Default	Allowed values	Description
category_id	string	No	empty	non-blank string (normalized to an id)	Category id; the whole file is skipped when blank
title	MiniMessage string	No	category_id	MiniMessage	Category title used by the GUI tab
icon	ItemSource string	No	minecraft-book	CoreLib ItemSource shorthand	Category icon
order	integer	No	100	integer	Category-tab sort weight, ascending; ties are broken by category_id
entries	map	No	empty	keys are local entry ids	Entry definitions
entries.<id>.title	MiniMessage string	No	entry id	MiniMessage	Entry title
entries.<id>.description	MiniMessage string	No	empty	MiniMessage	Entry description
entries.<id>.icon	ItemSource string	No	minecraft-book	CoreLib ItemSource shorthand	Entry icon; a locked entry renders with the locked icon instead
entries.<id>.hidden	boolean	No	false	true / false	Whether to hide an entry while locked; false displays an unknown entry
entries.<id>.unlock.triggers	list	No	empty	trigger list	Shared event triggers, see Triggers
entries.<id>.unlock.triggers[].event	string	Yes	—	CoreLib event ID	Trigger event ID (normalized); a blank value skips that entry
entries.<id>.unlock.triggers[].condition	CoreLib condition group	No	empty	condition.type + condition.entries	Optional; omitting it means the event itself is enough
entries.<id>.unlock.advancements	list<string>	No	empty	vanilla advancement key	Any match unlocks the entry; values are trimmed and de-duplicated
entries.<id>.rewards.attributes	map<string,double>	No	empty	attribute id → double (not 0.0)	Contributes live after activation and is not snapshotted in player data; entries whose value is 0.0 are dropped, and duplicates are summed
entries.<id>.rewards.actions	list<string>	No	empty	CoreLib action line	CoreLib action lines executed once on claim; the claimed state is stored before the lines run

Keep the unlock logic in one sentence: unlock.triggers and unlock.advancements are parallel paths, and either one can move an entry to the unlocked state. Unlocking, activating, and claiming are three separate steps: unlock does not auto-activate, and activation does not run the one-time claim actions

Usage example (two entries, unlocked through a trigger and an advancement):

category_id: "example"
title: "<gold>Trial Codex</gold>"
icon: "minecraft-book"
order: 100

entries:
  first_blood:
    title: "<yellow>First Hunt</yellow>"
    description: "<gray>Defeat any hostile creature.</gray>"
    icon: "minecraft-iron_sword"
    hidden: false
    unlock:
      triggers:
        - event: "entity_kill"
    rewards:
      attributes:
        physical_attack: 2.0
      actions:
        - "send_message text=<green>You claimed the first-hunt reward.</green>"

  master_miner:
    title: "<aqua>Deep Miner</aqua>"
    icon: "minecraft-diamond_pickaxe"
    hidden: true
    unlock:
      triggers:
        - event: "block_break"
          condition:
            type: "all_of"
            entries:
              - '%block_type% == "DIAMOND_ORE"'
      advancements:
        - "emakicodex:example/first_step"
    rewards:
      attributes:
        max_health: 5.0

Language files

Language files live in lang/*.yml. The default includes:

version: "1.1.6"
general:
  prefix: "<gray>[ <gradient:#D946EF:#F59E0B>EmakiCodex</gradient> ]</gray>"
  no_permission: "<red>You do not have permission to do that.</red>"

command:
  help:
    commands:
      reload: "Reload config, re-register advancements, resync all"
      grant: "Grant an advancement to a player"
      revoke: "Revoke an advancement from a player"
      debug: "Manage debug mode"

Language text supports MiniMessage (a tag-based format for colors and styles). Run /codex reload after editing to apply it

After editing config.yml, advancements/*.yml, codex/*.yml, gui/codex_gui.yml, or lang/*.yml, run /codex reload to apply the changes. Player files under data/<uuid>.yml are preserved by reload, so you can reload without worry

Related Pages

• Advancements: the page and node fields of advancements/*.yml, the key rules and completion actions
• Category GUI: category files, GUI types, four-state progress, and reward interactions
• Triggers: vanilla triggers.entries and category unlock.triggers, available events, and condition examples
• Commands and Permissions: /codex reload, vanilla grant/revoke, and category-entry administration
• CoreLib Actions: granting, revoking, or announcing achievements from an action chain