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 five registered effect types:

Type	Purpose
`fire`	Set target fire ticks (applies to any entity)
`potion-effect`	Apply a Minecraft potion effect (LivingEntity only)
`velocity`	Set entity velocity (supports local yaw-relative or world-axis directions, plus pull-toward-caster)
`command`	Dispatch a console command with per-target placeholders
`freezing-visual`	Send powder-snow freeze packet to player for a duration

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
`duration`	`PlaceholderWrapper<Integer>`	`3`	Fire duration in ticks

Example: cast-effect (caster on-cast) and target-effect (hit enemy)

id: explosive-touch
type: impact
cast-effects:
  - type: fire
    params:
      duration: 5s
target-effects:
  - type: fire
    params:
      duration: 5s

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
`effect`	String	(required)	Namespaced effect key (e.g., `minecraft:nausea`, `darkness`)
`duration`	`PlaceholderWrapper<Integer>`	`3`	Effect duration in ticks (1 tick ≈ 50ms; 20 ticks = 1 second)
`amplifier`	`PlaceholderWrapper<Integer>`	`0`	Effect amplifier (level I = 0, level II = 1, etc.)
`ambient`	boolean	`false`	If `true`, effect particles are subtle
`hide-particles`	boolean	`false`	If `true`, particles are not shown; the implementation inverts this to `show-particles` in the PotionEffect constructor
`show-icon`	boolean	`true`	If `true`, effect icon appears on player HUD

Example: potion effect with amplifier

id: explosive-touch
type: impact
cast-effects:
  - type: potion-effect
    params:
      effect: "minecraft:nausea"
      duration: 5s
      amplifier: 1
      hide-particles: true
target-effects: []

Example: darkness potion from mob attack

id: warden-potion-effect
type: impact
target-effects:
  - type: potion-effect
    params:
      effect: darkness
      amplifier: 1
      duration: 100

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 facing
local-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 force
pull-y — additional upward velocity (for arcing motion)
pull-horizontal — if true, ignore vertical distance (horizontal-only pull)

Parameters:

Name	Type	Default	Description
`local-x`	`PlaceholderWrapper<Double>`	`null`	Local rightward velocity component
`local-y`	`PlaceholderWrapper<Double>`	`null`	Local upward velocity component
`local-z`	`PlaceholderWrapper<Double>`	`null`	Local forward velocity component
`world-x`	`PlaceholderWrapper<Double>`	`null`	World X-axis velocity component
`world-y`	`PlaceholderWrapper<Double>`	`null`	World Y-axis velocity component
`world-z`	`PlaceholderWrapper<Double>`	`null`	World Z-axis velocity component
`pull-strength`	`PlaceholderWrapper<Double>`	`null`	Magnitude of pull toward caster
`pull-y`	`PlaceholderWrapper<Double>`	`null`	Extra upward velocity added during pull (for arc)
`pull-horizontal`	`PlaceholderWrapper<Boolean>`	`null`	If `true`, ignore vertical distance when pulling

Example: forward dash (local-z)

id: knight-attack-3-impact
type: impact
cast-effects:
  - type: velocity
    params:
      local-x: 0.0
      local-y: 0.0
      local-z: 2.2

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
`command`	`PlaceholderWrapper<String>`	(required)	Console command to execute; `%uuid%` and `%name%` are injected per-target
`delay`	`PlaceholderWrapper<Long>`	`0`	Delay in ticks before executing (0 = immediate, else scheduled via `Bukkit.getScheduler().runTaskLater()`)

Example: shield resource grant on cast

id: knight-attack-3-impact
type: impact
cast-effects:
  - type: command
    params:
      command: "stats resource add %player_name% shield 40"

Example: attack speed boost with delay

id: mage-attack-4-dummy
type: dummy
cast-effects:
  - type: command
    params:
      command: "stats modifiers addtimed %player_name% astralclass:attack_speed_boost astralstats:attack_speed PERCENTAGE 150 4000"
      delay: 0

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
`millis`	`PlaceholderWrapper<Integer>`	`20`	Duration in milliseconds before resetting the visual

Example: freeze visual on mage ability

id: mage-attack-4-dummy
type: dummy
cast-effects:
  - type: freezing-visual
    params:
      millis: 4000

Effect execution and ordering

Cast-effects run when the skill is triggered, applied to the caster (may be null for 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.

Last modified: 25 July 2026