Core Configuration

Database (`database`)

Key	Default	Description
`file`	`ascension.db`	SQLite filename
`pool-size`	`4`	Connection pool
`wal`	`true`	WAL mode
`backup-before-migrate`	`true`	Backup before schema upgrade
`backup-retention`	`10`	Kept backup copies

Ranks (`ranks.*`)

Per rank (E → MONARCH):

display-name, color, chat-prefix
required-xp, max-mana, shadow-capacity
mana-regen-multiplier

Mana (`mana`)

Key	Default	Description
`regen-per-tick`	`0.5`	Mana per pulse
`regen-interval-ticks`	`20`	Pulse interval

Hunter abilities (`hunter-abilities`)

Invisibility and flight limits per rank tier. Permissions: ascension.ability.invisibility.*, ascension.ability.flight.* — see Core permissions.

Key	Default	Description
`staff-only`	`true`	When `true`, `/asc fly` and `/asc invis` require `ascension.admin` or `ascension.ability.staff` before rank/tier permissions apply — hunter rank alone does not unlock them.

Skill definitions (skills.skills), /skillshop entries (skills.shop.entries), per-level passive tuning (skills.passive-effects), active tuning (skills.active), points per rank-up. Re-buying an owned passive levels it up at skills.shop.level-cost-multiplier (default 1.6) scaling. Used by AscensionSkills. See AscensionSkills for the full skill catalog.

Achievements (`achievements`)

Achievement definitions for /achievements GUI. Progress stored in SQLite.

VFX (`vfx`)

Global gate for every data-driven particle effect across the suite (weapon/tool hits, shadow auras, mob & boss combat, skill casts, cosmetics).

Key	Default	Description
`vfx.enabled`	`true`	Master on/off for all catalog effects
`vfx.density`	`1.0`	Particle-count multiplier, clamped `0.0`–`2.0` (0 disables; lower on busy servers)

Per-effect catalogs live in each plugin's own config (gates.yml vfx:, shadows/skills config.yml vfx:, Core cosmetics.vfx).

Cosmetics (`cosmetics`)

Purchasable particle auras & trails for /cosmetics (Core gold), plus rank-unlock auras from C → MONARCH. Purely visual.

Key	Default	Description
`cosmetics.enabled`	`true`	Enable the cosmetics system + `/cosmetics`
`cosmetics.tick-interval`	`4`	Ticks between cosmetic renders (min 2)
`cosmetics.catalog.<id>`	—	A cosmetic: `type` (aura/trail), `name`, `material`, `price` (gold), `vfx-id`, `lore`, optional `unlock-rank`
`cosmetics.vfx.<id>`	—	The particle spec for a cosmetic (same layer format as other `vfx:` sections)

Rank unlock auras (`unlock-rank`)

When unlock-rank is set (e.g. C, S, MONARCH), the cosmetic is granted free when the hunter reaches that rank (also synced on join / opening /cosmetics). It cannot be bought with gold. Ships with one aura per rank from C → MONARCH:

ID	Name	Unlock
`rank_c_aura`	Verdant Sigil	C
`rank_b_aura`	Emerald Crown	B
`rank_a_aura`	Gilded Halo	A
`rank_s_aura`	Solar Mantle	S
`rank_ss_aura`	Crimson Dominion	SS
`rank_national_aura`	National Banner	NATIONAL
`rank_monarch_aura`	Monarch's Presence	MONARCH

Economy (`economy`)

Shop items (economy.shops, each with a category for the /ascshop tabs), gate entry fees (gate-entry-fees), sell prices, craft recipes, shadow-capacity upgrades. Used by AscensionEconomy even though keys live in Core config.

Leaderboards (`leaderboards`)

Powers /rankings and the %ascension_top_*% / %ascension_position_*% placeholders. Boards are computed by a cached async refresher — never synchronous SQL on command.

Key	Default	Description
`enabled`	`true`	Master switch
`top-count`	`10`	Entries shown per board (1–45)
`refresh-seconds`	`300`	Async recompute interval (min 15)

Boards: Top Hunters, Most Gate Clears, Fastest Clears, Shadow Army, Top Guilds.

Rank-up exams (`rank-up.exam`)

When enabled, reaching an XP threshold makes a Hunter exam-eligible instead of auto-promoting; they must clear a solo exam gate (/asc exam). Requires AscensionGates to register the exam service — otherwise ranks auto-promote as before.

Key	Default	Description
`enabled`	`false`	Off by default (non-breaking)
`ranks`	`[C, B, A, S, SS, NATIONAL, MONARCH]`	Ranks that require an exam (E→D stays automatic)
`time-limit-minutes`	`30`	Exam time limit
`retry-cooldown-minutes`	`60`	Cooldown after a failed exam

Staff (`staff`)

Section	Description
`staff.roles`	Helper/Mod/Owner labels + `ascension.staff.*` permissions
`staff.show-chat-labels`	`true`/`false` — show the staff group label before the hunter rank in chat. Set `false` if another plugin already shows the group prefix.
`staff.show-tab-labels`	`true`/`false` — show the short staff group label in the TAB list.
`staff.chat-labels` / `staff.tab-labels`	Per-role staff group labels for chat and TAB
`staff.chat.rank-prefixes`	Per-rank chat tags
`staff-mode`	Staff visibility options

Permissions (`permissions`)

Key	Description
`provider`	`auto`, `luckperms`, `yaml`, `bukkit`
`mappings`	Permission aliases
`yaml-fallback.groups`	Default groups when no LuckPerms

Action bar (`action-bar`)

Key	Default	Description
`enabled`	`true`	Master switch
`show-stats`	`false`	Rank/mana/XP on action bar
`format`	…	`{rank}`, `{mana}`, `{xp_pct}`, etc.

Built-in scoreboard when enabled: true. Default enabled: false — use SimpleScore.

Resource pack (`resource-pack`)

Key	Description
`enabled`	Build pack on enable
`merge-modelengine-pack`	Include ModelEngine assets (required for shadow models)
`public-host` / `host-port`	Pack download URL
`apply-on-join`	Send pack on join
`redownload-command-enabled`	Allow `/resourcepack`

Chat (`chat`)

channels.enabled — /ch system
channels.prefixes — ! guild, @ party, # staff
use-renderer — Paper display name + rank colors (Essentials integration)

Guide books

Key	Description
`guide-book`	Player handbook (`/asc guide`)
`admin-guide-book`	Staff handbook (`/asc admin guide`)

Built-in defaults (empty pages: []) include a clickable Contents page after the cover — tap a topic to jump to that section. Custom pages in YAML use plain text only (no auto-index).

Leave pages: [] to use built-in JAR content.

First join (`first-join`)

Key	Default	Description
`first-join.give-guide-book`	`true`	Give the player the Hunter Handbook once, only on their very first join. Players who have joined before are never re-given it.

System window (`system-window`)

The Solo-Leveling-style System status window opened with /system (aliases /status, /sys). Shows live rank, EXP, HP, mana, shadow capacity and gold, with buttons to the other Ascension menus, plus floating blue System pop-ups for milestone moments.

Key	Default	Description
`system-window.enabled`	`true`	Master switch for the `/system` window.
`system-window.title`	`&b&l⟪ SYSTEM ⟫`	GUI title (supports `&`/`§` colour codes).
`system-window.open-sound`	`true`	Play a short chime when the window opens.
`system-window.buttons.quests`	`true`	Show the Quests button (`/quest ranks`).
`system-window.buttons.skills`	`true`	Show the Skills button (`/skills`).
`system-window.buttons.shadows`	`true`	Show the Shadow Army button (`/shadows`).
`system-window.buttons.cosmetics`	`true`	Show the Cosmetics button (`/cosmetics`).
`system-window.buttons.rankings`	`true`	Show the Rankings button (`/rankings`).
`system-window.notifications.enabled`	`true`	Master switch for floating System pop-ups.
`system-window.notifications.duration-ticks`	`60`	How long each pop-up stays (20 ticks = 1s).
`system-window.notifications.sound`	`true`	Play a chime alongside each pop-up.
`system-window.notifications.on-rank-up`	`true`	Pop-up when a player ranks up.
`system-window.notifications.on-shadow-extract`	`true`	Pop-up when a player extracts a shadow.

Buttons are hidden automatically if the target command/plugin is not installed. Players can mute their own pop-ups for the session with /system notifications off.

Messages (`messages`)

Key	Description
`rank-up`	Template with `{rank_colored}`
`not-enough-mana`	Skill mana error