Astral Realms Documentation Help

Configuration

The paper module loads four files on onEnable/loadConfiguration(): database.properties, config.yml, categories.yml, and messages.yml. All can be reloaded at runtime with /heads reload (see Commands). The master module (background catalog worker) loads its own separate database.properties and config.yml — see Catalog Import & Resolve Worker for those.

database.properties

A standard HikariCP JDBC properties file, copied out of the jar on first load — see the AstralCore database docs for the field reference. The shipped default:

jdbcUrl=jdbc:mariadb://localhost:3306/heads?useSSL=false driverClassName=org.mariadb.jdbc.Driver dataSource.user=testuser dataSource.password=test623 poolName=AstralHeads

This must point at the same heads schema the master module's worker writes into (see Catalog Import & Resolve Worker — data model); the paper module only reads/writes the heads table, never queued_heads.

config.yml

A single prices map, keyed by HeadEntity.Source (CATALOG or PLAYER), loaded into HeadsConfiguration. A Source missing from the map means heads of that source aren't for sale — the buy-head action sends not-for-sale instead of charging.

prices: CATALOG: price: 500 currency: "default" currency-display: "Default Currency" PLAYER: price: 100 currency: "astralys" currency-display: "Astralys"

Key

Type

Description

prices.<SOURCE>.price

double

Cost to buy a head of that source, charged via EconomyService#withdraw.

prices.<SOURCE>.currency

String

The EconomyService currency id to withdraw from.

prices.<SOURCE>.currency-display

ComponentWrapper (MiniMessage, placeholder-aware)

Rendered currency name, exposed as %head_currency%/ the %currency% placeholder in the head-bought message.

categories.yml

A categories map of catalog browse categories, loaded into CategoriesConfiguration (Map<String, HeadCategory>), each entry keyed by its own id. Each HeadCategory is itself a category-namespaced placeholder (see Placeholders) — category.id is matched against HeadEntity#category() (a catalog head's category column) to group heads for browsing.

categories: animals: id: animals item: material: SHEEP_SPAWN_EGG name: Animaux lore: - "A category for all things related to animals."

Key

Type

Description

categories.<key>.id

String

The category id; should match the map key and the category value on catalog heads rows.

categories.<key>.item

ItemStackWrapper

The icon (material/name/lore) rendered for this category in a menu.

The shipped default ships 10 categories: alphabet, animals, blocks, decoration, food-drinks, humanoid, humans, miscellaneous, monsters, plants.

messages.yml

Loaded via loadEnum("messages.yml", HeadsMessages.class). Every key is a MiniMessage string.

Key

Enum constant

Used by

not-for-sale

NOT_FOR_SALE

buy-head, when the head's Source has no prices entry.

not-enough-funds

NOT_ENOUGH_FUNDS

buy-head, when EconomyService#withdraw fails (insufficient balance).

head-bought

HEAD_BOUGHT

buy-head, on success. Placeholders: %head_name%, %price%, %currency%.

unexpected-error

UNEXPECTED_ERROR

Any action/command whose async pipeline fails (economy service missing, database error, menu-open failure, no HeadPlayerData loaded).

head-bought: "You have successfully purchased the %head_name% for %price% %currency%."

The paper module's MenuContainer/DialogContainer load whatever blueprints exist under this plugin's own menus/ and dialogs/ data folders (ConfigurationManager#loadFolder) — unlike categories.yml/config.yml, none are bundled as jar resources, so the heads-main and heads-list menu blueprints referenced by the commands and search-heads action must be authored on the server. See the AstralCore menu documentation for the blueprint format.

Last modified: 25 July 2026
OverviewCommands