Effects
Effects apply modifications to entities when skills are cast or hit. Every skill can define two effect lists: cast-effects (applied to the caster when the skill is cast) and target-effects (applied to each entity affected by the skill). Effects are looked up in EffectFactory.REGISTRY by type; unknown types are logged as errors and skipped.
Effect types
AstralSkill ships six registered effect types:
Type | Purpose |
|---|---|
| Set target fire ticks (applies to any entity) |
| Apply a Minecraft potion effect (LivingEntity only) |
| Set entity velocity (supports local yaw-relative or world-axis directions, plus pull-toward-caster) |
| Dispatch a console command with per-target placeholders |
| Send powder-snow freeze packet to player for a duration |
| Destroy the blocks in a sphere around the skill location |
Most effect parameters are PlaceholderWrapper<T> fields, so they accept placeholder expressions (e.g. %player_name%, or custom placeholders a caller registers such as %level%) resolved against the skill's PlaceholderContainer at apply time.
Fire effect
Sets the target's fire ticks (the fire bar visible to other players). Applies to any entity.
Parameters:
Name | Type | Default | Description |
|---|---|---|---|
|
|
| Fire duration in ticks |
Example: cast-effect (caster on-cast) and target-effect (hit enemy)
Potion-effect
Applies a Minecraft status effect (e.g., minecraft:nausea, minecraft:darkness, minecraft:strength). Only affects LivingEntity (not items, arrows, etc.); other entity types are silently skipped. The effect type is resolved by namespaced key via Bukkit's Registry.MOB_EFFECT.
Parameters:
Name | Type | Default | Description |
|---|---|---|---|
| String | (required) | Namespaced effect key (e.g., |
|
|
| Effect duration in ticks (1 tick ≈ 50ms; 20 ticks = 1 second) |
|
|
| Effect amplifier (level I = 0, level II = 1, etc.) |
| boolean |
| If |
| boolean |
| If |
| boolean |
| If |
Example: potion effect with amplifier
Example: darkness potion from mob attack
Velocity effect
Sets an entity's velocity. Supports four modes: local yaw-relative direction, world-axis direction, pull toward caster, and combinations of these.
Local velocity — relative to the target's facing direction (yaw-only; pitch is ignored; local Y is always world-up):
local-x— rightward motion perpendicular to facinglocal-y— upward motion (world Y)local-z— forward motion along facing direction
World velocity — absolute Cartesian axes:
world-x,world-y,world-z— velocity components in world coordinates
Pull toward caster — pulls the target toward the entity that cast the skill:
pull-strength— magnitude of the pull forcepull-y— additional upward velocity (for arcing motion)pull-horizontal— iftrue, ignore vertical distance (horizontal-only pull)
Parameters:
Name | Type | Default | Description |
|---|---|---|---|
|
|
| Local rightward velocity component |
|
|
| Local upward velocity component |
|
|
| Local forward velocity component |
|
|
| World X-axis velocity component |
|
|
| World Y-axis velocity component |
|
|
| World Z-axis velocity component |
|
|
| Magnitude of pull toward caster |
|
|
| Extra upward velocity added during pull (for arc) |
|
|
| If |
Example: forward dash (local-z)
Command effect
Dispatches a console command. The command is resolved through the skill's placeholder container and executed immediately or on a delay. Two per-target placeholders are injected: %uuid% (target's UUID) and %name% (target's display name).
Parameters:
Name | Type | Default | Description |
|---|---|---|---|
|
| (required) | Console command to execute; |
|
|
| Delay in ticks before executing (0 = immediate, else scheduled via |
Example: shield resource grant on cast
Example: attack speed boost with delay
Freezing-visual effect
Sends a powder-snow freeze packet to the player (entity data field 7 = 140) then resets it after a delay. Creates a brief freeze-screen effect without applying actual Freeze status. Players only (non-player entities are skipped); uses PacketEvents for packet dispatch.
Parameters:
Name | Type | Default | Description |
|---|---|---|---|
|
|
| Duration in milliseconds before resetting the visual |
Example: freeze visual on mage ability
Break-block effect
Destroys the blocks in a sphere around the position the skill fired at. Effects always run on the main thread, so touching blocks here is safe.
How a block is removed depends on the caster:
A player caster, with
break-as-casterleft on — each block goes throughPlayer#breakBlock, so the server runs the normal player-break path: aBlockBreakEventis fired and land-protection plugins can cancel it block by block.Any other caster, or
break-as-caster: false— the block is removed directly (breakNaturally()/setType), which fires no event and is therefore invisible to protection plugins.
break-as-caster also falls back to a direct break when the caster is a player who is not in the world being edited.
Parameters:
Name | Type | Default | Description |
|---|---|---|---|
|
|
| What the sphere is centred on. |
| Vector | — | World-space offset added to the origin (e.g. |
|
|
| Sphere radius in blocks. |
|
|
| Hard cap on blocks destroyed per application. |
|
|
| Break through the caster with |
|
|
| Drop the block's items. Ignored while breaking as the caster — the held tool decides. |
|
|
| Update neighbouring blocks. Only used with |
|
|
| Also break blocks with no break time (bedrock, barrier, end portal frame, …). |
| List | — | When set, only blocks matching these entries are broken. |
| List | — | Never break these. Applied after the whitelist. |
|
|
| Log the resolved origin, every effective setting, and what happened to each block. |
The volume is a sphere, measured from each block's centre to the skill position, even though the loop walks the enclosing cube. Blocks outside the world's height range are skipped.
Block filters
Each whitelist/blacklist entry is either a block material (CHEST, minecraft:stone — case- and namespace-insensitive) or the token TILEENTITY (also accepted as TILE_ENTITY/BLOCK_ENTITY), which matches every block holding a block entity: chests, barrels, shulker boxes, hoppers, furnaces, spawners, signs, beacons, decorated pots, and so on. Blacklisting it is the one-liner for "don't destroy anything that stores something".
Filters are parsed once at load: an entry that is neither a block material nor that token fails the skill at load time with a message naming it, rather than silently widening what the skill may destroy.
Nothing breaking? Set debug: true and cast it once. Every application then prints the resolved origin and block coordinates, all effective settings, and one line per block with the reason it was skipped (air, blacklisted, not in whitelist, unbreakable, or Player#breakBlock returned false when a protection plugin cancelled the BlockBreakEvent), followed by a totals line.
Effect execution and ordering
Cast-effects run when the skill is triggered, applied to the caster (may be
nullfor non-entity triggers).Target-effects run for each entity that the skill affects (projectile hits, laser hits, impact radius, etc.), applied to the affected entity.
Within each list, effects run top-to-bottom in YAML order.
Unknown effect types are logged and skipped; the skill continues running.
Placeholder resolution
All effect parameters typed as PlaceholderWrapper<T> (duration, amplifier, command, millis, etc.) resolve through the skill's PlaceholderContainer, which includes:
AstralCore placeholders registered by the caller/consumer for the caster (e.g. player-scoped
%player_name%, or custom placeholders like%level%registered by AstralClasses/AstralMobs before casting)Per-effect injected placeholders (e.g.,
%uuid%,%name%in command effects)
Note: a top-level placeholders: map sometimes seen at the root of a skill file is not part of this resolution chain — it has no corresponding field on the skill schema and is not parsed.