Overview

AstralSkill is the shared skill-scripting engine for AstralRealms — a YAML-driven DSL that defines the skill file format and provides the runtime for executing skills. The plugin ships no gameplay content of its own; instead, it is consumed by other products (AstralClasses for ability triggers, AstralMobs for mob attacks) that reference skills by id and cross-link to the skill documentation.

What is a skill?

A skill is one YAML file in the skills/ folder with a structure defined by the WrappedSkill record:

Field	Type	Description
`id`	String	Unique identifier for the skill (the id field, not the filename, is the skill key)
`skill-root`	Root enum	Skill category: `cast`, `toggle`, `passive`, or `misc`
`type`	Type enum	Skill implementation: one of six hardcoded types (see Cast Types)
`tags`	Set[String]	Custom classification tags (e.g., `fire`, `ice`, `magic`) for grouping and filtering
`requirement-list`	RequirementList	Optional list of conditions that must pass before the skill can be cast
`params`	YAML Object	Type-specific parameters (projectile velocity, impact radius, dummy payload, etc.)
`cast-effects`	Effect[]	Effects applied to the caster when the skill is cast
`target-effects`	Effect[]	Effects applied to entities hit by the skill

Example: fire-spark skill

id: fire-spark
skill-root: cast
tags:
  - fire
  - magic
type: projectile
params:
  display-type: particle
  targets: enemy
  velocity: 1.0
  max-range: 20.0
  cast-skill-on-entity: explosive-touch
cast-effects:
  - type: fire
    params:
      duration: 5s
  - type: potion-effect
    params:
      effect: "minecraft:nausea"
      duration: 5s
      amplifier: 1
      hide-particles: true

The six skill types

Skills are categorized by implementation. Each type has a fixed structure and behavior pattern:

Type	Purpose
`dummy`	Inert skill that applies cast/target effects but does not interact with the world
`auto_cast`	Periodically self-triggers on an interval (no player cast required)
`n_cast`	Rotates through a sequence of skills in order
`projectile`	Launches moving projectile(s) with collision detection and visual display
`laser`	Fires continuous beam with line-of-sight targeting and hit detection
`impact`	Instant area-of-effect damage/healing applied at a target location

See Cast Types for the full config specification of each type.

Loading and initialization

Skills are loaded from the plugin's skills/ folder and all its subfolders recursively, regardless of nesting depth. The loading flow is:

Discovery — SkillService.smartLoad() (called during plugin enable and on /skill reload) scans skills/ and deserializes all .yml files into WrappedSkill instances
Indexing — Each skill is indexed by its id field (not filename); duplicate ids overwrite silently
Initialization — Each skill's init() method parses its params into the concrete Skill subclass matching its type, and loads effects
Thread startup — Shard update loops begin processing active skill instances

Errors during initialization are logged per skill and do not halt plugin startup; the failed skill simply becomes unavailable at runtime.

Async execution: sharded update engine

Skills run on a multi-threaded shard architecture, not the main Bukkit thread:

Shard count — Configurable via skill-service.threads in config.yml (default: ⌊CPU cores / 2⌋, minimum 1)
Routing — Each caster (entity) is routed to a fixed shard by their UUID hash, ensuring thread safety without locks
Budget — Each shard has a 1ms per-tick budget; ticks exceeding this threshold are logged (tuned by skill-service.warn-threshold-ms and skill-service.warn-min-overrun-percent)
Metrics — Access performance counters via /skill metrics, which reports per-shard tick counts, overruns, peak latency, and active skill counts

Skill composition and chaining

Skills can trigger other skills through chaining:

Projectile/Laser — Cast another skill on entity hit (cast-skill-on-entity) or on block hit (cast-skill-on-block)
Impact — Cast another skill on hit (cast-skill-on-hit) or on miss (cast-skill-on-miss)
N_cast — Automatically rotate through a sequence of skills, stepping through them on each cast
Auto_cast — Periodically auto-trigger on an interval configured in params

Placeholder-driven values

Most numeric/string/boolean fields in params and effect params are PlaceholderWrapper values, so they accept either a literal (velocity: 1.0) or a placeholder expression (velocity: "%level% * 0.5") that is resolved at cast time against the PlaceholderContainer passed into the cast call. If the caster is a Player and no container is supplied, AstralCore builds a player-scoped container automatically (e.g. %player_name%); consumers such as AstralClasses or AstralMobs can register their own custom placeholders (e.g. %level%) into that container before casting.

Some example skill files under skills/ also carry a top-level placeholders: map (e.g. level: 1). This key has no corresponding field on the skill schema, so it is not parsed or resolved by AstralSkill — it has no effect on skill behavior.

Public API

Other plugins access the skill runtime through the SkillAPI static facade:

SkillService skills = SkillAPI.service();
Optional<WrappedSkill> skill = skills.findById("fire-spark");

See Developer API for the full service interface.

Topic	Link
Skill file structure and loading	Skill Files
The six skill types and their params	Cast Types
Target filters and selection	Targeting
Effect types and configuration	Effects
Display (particles, sounds, visuals)	Displays
Hitbox shapes for collision detection	Hitbox Shapes
Configuration and plugin settings	Configuration
Commands for debugging and metrics	Commands
Integrating skills in custom plugins	Developer API

Last modified: 25 July 2026

Astral Realms Documentation Help