Configuration

AstralScrolls reads its configuration through AstralCore's Configurate-backed configuration manager: config.yml (item templates + rarities), a blueprints/ folder of scroll definitions, and messages.yml. Everything is reloaded together with /scrolls reload — see Commands.

Installation

Drop AstralScrolls-<version>.jar into plugins/.
Install its hard dependency, declared in plugin.yml under depend — the server refuses to start AstralScrolls without it:
Dependency
Why
AstralCore
Configuration/action framework, placeholders, the scrolls item-supplier namespace, ACF command registration.
Start the server once to generate plugins/AstralScrolls/config.yml, messages.yml, and a blueprints/ folder pre-seeded with example.yml.

Dependency	Why
AstralCore	Configuration/action framework, placeholders, the `scrolls` item-supplier namespace, ACF command registration.

`config.yml`

Deserializes into MainConfiguration.

YAML key	Java field	Type	Description
`scroll-item`	`scrollItem`	`ItemInfo` (`name` + `lore`)	Display template applied to an incomplete scroll's `ItemStack` every time its progress changes.
`completed-item`	`completedItem`	`ItemInfo` (`name` + `lore`)	Display template applied once a scroll's goal is met, replacing `scroll-item`'s display.
`rarities`	`rarities`	`Map<String, RarityBlueprint>`	Every rarity, keyed by its id (the map key, not a field inside the block). See `rarities` below.
`completion-actions`	`completionActions`	`PaperActionList` (nullable)	Actions run for every scroll of every rarity when it completes, in addition to `ScrollCompletedEvent` firing. Skipped entirely if omitted or empty. Not present in the shipped default file.

ItemInfo (scroll-item/completed-item) has two sub-keys, both optional and both rendered against a placeholder container carrying only the completing/updating Scroll (%scroll_*% — see Placeholders):

Sub-key	Type	Description
`name`	`ComponentWrapper`	Overrides the item's display name. Skipped if unset.
`lore`	`ComponentWrapperList`	Overrides the item's lore, line by line. Skipped if unset or empty.

`rarities`

Each entry deserializes through RarityTypeSerializer, which reads the map key as the rarity's own id and the rest of the block as an ItemStackWrapper (material, plus any other item-stack field) for the scroll's base appearance:

YAML key	Java field	Type	Description
(map key)	`id`	String	The rarity's id — used by `/scrolls give`, the `scrolls:<id>` item-supplier namespace, and `ScrollBlueprint.RequirementValues` map keys in blueprint files.
`display-name`	`displayName`	`Component` (MiniMessage)	The rarity's display name, exposed as `%rarity_displayName%`/`%scroll_rarity_displayName%`.
`color`	`color`	`TextColor` (hex or named)	Primary accent color for the rarity, exposed as `%rarity_color%`/`%scroll_rarity_color%`.
`sub-color`	`subColor`	`TextColor`	Secondary accent color, exposed as `%rarity_subColor%`/`%scroll_rarity_subColor%`.
(item-stack fields)	`itemStack`	`ItemStackWrapper`	The base `ItemStack` built for a scroll of this rarity, before `scroll-item`/`completed-item` overrides name/lore.
`rewards`	`rewards`	`Map<String, RewardGroup>`	The weighted reward pool rolled by `/scrolls rewards` and on redemption. Map key is a free-form group id (not otherwise referenced).

Each rewards entry is a RewardGroup:

YAML key	Java field	Type	Description
`chance`	`chance`	double	Relative weight in a `RandomCollection<RewardGroup>` draw — not a percentage; weights are summed across every group in the rarity and one is drawn proportionally.
`actions`	`actions`	`PaperActionList`	Actions run when this group is drawn (`/scrolls rewards`, or redeeming a completed scroll).

scroll-item:
  material: "paper"
  name: "%scroll_rarity_color%<bold>Scroll %scroll_rarity_displayName%"
  lore:
    - "<text_color><type> %scroll_rarity_subColor%%scroll_current%/%scroll_total% <text_color>%scroll_context%"

completed-item:
  material: "paper"
  name: "%scroll_rarity_color%<bold>Scroll %scroll_rarity_displayName%"
  lore:
    - "<white>Right-click to claim your reward"

rarities:
  common:
    display-name: "<#d5d5d5><bold>Common"
    color: "#d5d5d5"
    sub-color: "#dddddd"
    material: "PAPER"
    rewards:
      1:
        chance: 90
        actions:
          - "[console] eco give %player_name% default 750"
      2:
        chance: 10
        actions:
          - "[console] give %player_name% scrolls:uncommon"

`blueprints/` folder

One or more scroll definitions per file; the plugin ships a single example, blueprints/example.yml. The filename doesn't matter — each file deserializes to a ScrollsConfiguration (a blueprints: map of <free-form-id> → ScrollBlueprint), and every blueprint across every file is pooled together at runtime. See Blueprints & Goals for the full schema.

Loading happens through AstralCore's folder loader, on enable and on /scrolls reload:

this.plugin.configurationManager()
        .loadFolder(dataFolder, ScrollsConfiguration.class, c -> c.serializers(serializers))
        .forEach(configuration -> this.blueprints.addAll(configuration.blueprints().values()));

`messages.yml`

See Messages for the full key list, including the goal-type-name labels used inside %scroll_type%.

Reloading

/scrolls reload calls AstralScrolls#loadConfiguration() — the same method run on enable — which reloads blueprints/ (ScrollService#load), then config.yml, then messages.yml, in that order. It does not re-register listeners or the scrolls item-supplier namespace, both of which are set up once in onEnable.

Last modified: 25 July 2026

Configuration

Installation

config.yml

rarities

blueprints/ folder

messages.yml

Reloading

`config.yml`

`rarities`

`blueprints/` folder

`messages.yml`