Configuration

EmakiCodex configuration is split into main settings, vanilla advancement pages, category entries, a GUI template, and language files. This page covers config.yml, codex/*.yml, gui/codex_gui.yml, and lang/*.yml:

• 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.0.5"
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:

Field	Type	Default	Description
version	string	1.0.5	Configuration-structure marker; the internal migration constant is 1.0.14 and is not a release coordinate.
language	string	zh_CN	Uses lang/<language>.yml.
release_default_data	boolean	true	Releases bundled advancements/example_page.yml, codex/example_category.yml, and related default resources when missing.
op_bypass	boolean	false	When true, OPs bypass command permission checks; when false, they still need the relevant permission nodes.
advancement.enabled	boolean	true	Enables vanilla advancement registration.
advancement.announce_default	boolean	false	Default broadcast behavior when a node does not define announce.
advancement.remove_on_disable	boolean	true	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	true	Injects node x / y into the client tree when PacketEvents is installed. This switch only decides whether the PacketEvents listener is registered at enable time; changing it at runtime requires a restart.
advancement.triggers_enabled	boolean	true	Enables automatic triggers.entries grants. When disabled, vanilla nodes require commands, API, or CoreLib actions, and category unlock.triggers entries do not auto-unlock.

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.

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	Type	Description
category_id	string	Category id; the whole file is skipped when blank.
title	MiniMessage string	Category title used by the GUI tab.
icon	ItemSource string	Category icon.
order	integer	Category-tab sort weight, ascending.
entries	map	Entry definitions keyed by local entry id.
entries.<id>.hidden	boolean	Whether to hide an entry while locked; false displays an unknown entry.
entries.<id>.unlock.triggers	list	Shared event triggers; omitting condition means the event itself is enough.
entries.<id>.unlock.advancements	list	Vanilla advancement ids; any matching declaration unlocks the entry.
entries.<id>.rewards.attributes	map	Attribute-to-value mapping. It contributes after activation and is derived live rather than snapshotted in player data.
entries.<id>.rewards.actions	list	CoreLib action lines executed once on claim; the claimed state is stored before the action lines run.

unlock.triggers and unlock.advancements are parallel paths: either one can move an entry to the unlocked state. Unlocking, activating, and claiming are independent; unlock does not auto-activate, and activation does not run the one-time claim actions.

Language files

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

version: "1.0.5"
general:
  prefix: "<gray>[ <gradient:#F59E0B:#EC4899>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. Run /codex reload after editing.

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.

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.