Configuration

AstralStats reads three top-level YAML files plus a recursively-scanned blueprints/ tree. config.yml carries the two plugin-wide behaviour flags, resources.yml configures the ResourceType catalogue, and messages.yml carries the handful of player-facing strings not covered by Combat Mechanics or Stats & Modifiers. Everything reloads at runtime with /stats reload.

Data folder layout

plugins/AstralStats/
├── config.yml
├── resources.yml
├── messages.yml
└── blueprints/
    ├── attack-damage.yml
    ├── attack-speed.yml
    └── shield/
        ├── max-shield.yml
        └── shield-regeneration.yml

blueprints/ is scanned recursively — BlueprintService.load() calls ConfigurationManager#loadFolder, which walks the whole tree and loads every file ending in .yml or .yaml regardless of depth. The shield/ subfolder shipped by default is pure organisation: any nesting works, and the file name itself is never read — only the key field inside each file matters.

`config.yml`

# Combat
combat-cooldown: "10s" # Time in seconds before a player is no longer considered in combat
silent-command-success: false

Field	Type	Default	Description
`combat-cooldown`	Duration	`10s`	How long after taking damage a player is still considered `isInCombat`.
`silent-command-success`	boolean	`false`	Suppresses the success feedback on stat/modifier/resource admin commands.

Combat cooldown

CombatService records a timestamp on every hit (recordDamage) and answers isInCombat(UUID) by comparing System.currentTimeMillis() against that timestamp plus combat-cooldown. Once the cooldown elapses the entry is dropped and the player is out of combat again.

The only current consumer is resource regeneration: PlayerResource.regeneration() returns 0 whenever the owning player isInCombat and the resource's blueprint has off-combat-only: true — the shipped SHIELD resource is configured this way, so it stops regenerating for the duration of combat-cooldown after every hit. See Resources and Combat Mechanics.

Silent command success

When true, the following commands skip their success message (failure/validation messages, and /stats value's output, are unaffected):

Command	Suppressed feedback
`/stats set`	"Set stat … to …"
`/stats reset`	"Reset stat … to its base value"
`/stats modifiers add`	`modifier-added`
`/stats modifiers addtimed`/`addtemp`	"Added timed modifier … to … for …ms"
`/stats modifiers remove`	`modifier-removed`
`/stats resource add`	"Added … of resource … to player …"
`/stats resource timed`/`temp`	"Applied timed resource effect to …"

See Commands for the full subcommand reference.

Stat blueprints (`blueprints/`)

Each file deserialises to a StatBlueprint:

Field	Type	Description
`key`	Key (namespaced)	The `StatType`-shaped key this blueprint activates, e.g. `astralstats:attack_damage`. A stat only exists for players once a blueprint with its key is loaded.
`display-name`	Component (MiniMessage)	Shown wherever the stat is displayed.
`base`	double	Starting/reset value — `/stats reset` sets a player's stat back to this.
`min`/`max`	double	Clamp bounds.

Clamping only applies when min < max (StatBlueprint#hasBonds()); a blueprint with min == max (or min > max) is unbounded and the computed value passes through unclamped.

# blueprints/attack-damage.yml
display-name: "<blue>Attack Damage"
key: "astralstats:attack_damage"
base: 50
min: 0
max: 500

Shipped blueprints

File	Key	Base	Max
`blueprints/attack-damage.yml`	`astralstats:attack_damage`	50	500
`blueprints/attack-speed.yml`	`astralstats:attack_speed`	50	500
`blueprints/shield/max-shield.yml`	`astralstats:max_shield`	50	500
`blueprints/shield/shield-regeneration.yml`	`astralstats:shield_regeneration`	1	500

These four are the only StatType entries that ship with a blueprint out of the box. Every other catalogued StatType (armor, critical chance, movement speed, …) exists as an enum constant but has no effect on any player until a matching blueprint file is added under blueprints/ — see the full catalogue on Stats & Modifiers.

`resources.yml`

resources.yml deserialises to a resources map keyed by ResourceType, each value a ResourceBlueprint (off-combat-only, type, max-stat, regeneration-stat, base-value). The shipped default configures only SHIELD:

resources:
  SHIELD:
    off-combat-only: true
    type: MAXIMUM # The type of resource, can be MAXIMUM or MISSING
    max-stat: "astralstats:max_shield" # The stat that defines the maximum value of this resource
    regeneration-stat: "astralstats:shield_regeneration" # The stat that defines the regeneration rate of this resource

See Resources for the full ResourceBlueprint field reference, the MAXIMUM/MISSING/FLAT regeneration formulas, and the ResourceType catalogue.

`messages.yml`

# Modifiers
modifier-value: "The <key> modifier for <player> has a value of <value> <type> on <stat>."
modifier-added: "You gave <player> a <type> <value> <stat> modifier with key <key>."
modifier-removed: "You removed the <key> modifier from <player>."

# Reloading
reloading: "Reloading..."
reloaded: "Reloaded successfully."
reload-failed: "Reload failed."

Key	Placeholders	Notes
`modifier-value`	`<key>`, `<player>`, `<value>`, `<type>`, `<stat>`	Declared on `StatsMessages` but not currently sent by any command in this build.
`modifier-added`	`<player>`, `<type>`, `<value>`, `<stat>`, `<key>`	Sent by `/stats modifiers add`.
`modifier-removed`	`<key>`, `<player>`	Sent by `/stats modifiers remove`.
`reloading`	—	Sent immediately when `/stats reload` runs.
`reloaded`	—	Sent after `loadConfiguration()` returns successfully.
`reload-failed`	—	Sent (and the exception logged) if `loadConfiguration()` throws.

Reloading

/stats reload calls AstralStats#loadConfiguration(), which:

Re-reads config.yml into StatsConfiguration and resources.yml into ResourcesConfiguration.
Calls BlueprintService#load() to re-walk blueprints/ and merge the freshly parsed blueprints into the live Key → StatBlueprint map. This is additive — new and changed files take effect immediately, but a blueprint file that was deleted stays active (its old entry is never removed from the map) until the server restarts.
Calls StatService#reload(), which unloads and reloads every currently online player's StatContainer — so updated base/min/max/display-name values and newly-added blueprints apply to online players immediately.
Reloads messages.yml into the StatsMessages enum.

Note that resources.yml changes are not re-applied to already-connected players this way — a player's ResourceContainer is only (re)built on PlayerJoinEvent, so edits to resources.yml take effect for players who join after the reload, not for those already online.

Last modified: 25 July 2026