Cast Types

The type field in a skill determines its implementation and runtime behavior. Each type has a fixed set of required parameters in the params block; the init() method throws an error if params is empty. Six types are available: dummy, projectile, laser, impact, auto_cast, and n_cast.

Type selection and params structure

id: my-skill
skill-root: cast
type: projectile          # Selects the Skill subclass
params:
  velocity: 2.0           # Type-specific parameters
  max-range: 50.0
  # ... more params ...

Each type expects specific keys in params. The sections below document every parameter, its type, and default value.

Dummy

Purpose: Inert skill that does not interact with the world. Fires cast-effects and target-effects only. Useful for stat bursts, command execution, or passive triggers.

Minimal params: params must be non-empty; use a placeholder key such as u: u to satisfy this requirement.

Parameter	Type	Default	Description
(any key)	Any	—	Required: params must not be empty. A dummy skill ignores its contents.

Example: stat burst

id: mage-attack-4-dummy
skill-root: cast
type: dummy
params:
  u: u

cast-effects:
  - type: command
    params:
      command: "stats modifiers addtimed %player_name% astralclass:attack_speed_boost astralstats:attack_speed PERCENTAGE 150 4000"
  - type: freezing-visual
    params:
      millis: 4000

The dummy type is most useful as a leaf skill triggered by other types (e.g., from a projectile's cast-skill-on-entity).

Projectile

Purpose: Launches one or more projectiles with physics simulation, collision detection, and optional visual display and sound.

Projectiles update their position every update-rate ms, check for hits every hit-update-rate ms, and update their display every display-update-rate ms. On collision (entity hit, block hit, or max-range reached), the skill can trigger downstream skills via cast-skill-on-entity, cast-skill-on-block, or cast-skill-on-miss.

Parameter	Type	Default	Description
`velocity`	Float	—	Speed at which the projectile travels (units/ms).
`drag`	Float	—	Linear drag coefficient applied each tick, slowing the projectile over time.
`gravity`	Float	—	Downward acceleration applied each tick (negative y direction).
`count`	Integer	—	Number of projectiles to launch per activation.
`horizontal-angular-variation`	Float	0	Max horizontal (yaw) angle in degrees for trajectory variation. Set to 360 for full spread.
`vertical-angular-variation`	Float	0	Max vertical (pitch) angle in degrees for trajectory variation.
`force-pitch`	Float	(none)	If set, overrides the vertical angle of the projectile direction in degrees.
`enforce-force-pitch`	Boolean	false	If `true`, applies `force-pitch` override even if the caster is looking in a different direction.
`max-range`	Float	—	Maximum distance the projectile can travel before disappearing (in blocks).
`update-rate`	Integer	—	Milliseconds between each position update. Lower values = smoother movement but more CPU.
`hit-update-rate`	Integer	—	Milliseconds between hit checks. Must be >= `update-rate`.
`display-update-rate`	Integer	—	Milliseconds between display updates. Must be >= `update-rate`.
`hit-update-sub-steps`	Integer	0	Extra sub-steps inserted between the previous and current position on each hit update, for high-speed projectiles (total checks per hit update = this value + 1). Improves hit accuracy at the cost of CPU.
`first-hit-update-delay`	Integer	0	Milliseconds to delay the first hit check after cast, preventing self-hits.
`stop-on-block`	Boolean	false	If `true`, the projectile stops when it hits a block. If `false`, it passes through.
`piercing-amount`	Integer	0	Number of entities the projectile can pierce through after the first hit before stopping (`0` = stop after hitting a single entity). A negative value causes the projectile to stop on its very first hit as well, since the hit counter is incremented before the comparison.
`targets`	SubjectTypes	—	Filter for valid targets (e.g., `enemy`, `ally`, `all`). See Targeting.
`hitbox-params`	ConfigurationNode	—	Collision shape for entity hits. See Hitbox Shapes.
`hitbox-blocks-params`	ConfigurationNode	—	Collision shape for block hits. If unset, `hitbox-params` is used for both.
`cast-sound`	SoundConfiguration	(none)	Sound played when the skill is cast.
`travel-sound`	SoundConfiguration	(none)	Sound played while the projectile is in flight.
`travel-sound-interval`	Integer	(none)	Milliseconds between successive travel sound plays.
`impact-sound`	SoundConfiguration	(none)	Sound played on entity or block hit.
`display-params`	List[ConfigurationNode]	—	List of visual representations (particles, item displays, etc.). See Displays.
`cast-skill-on-entity`	List[String]	(empty)	Skill ids to trigger when the projectile hits an entity.
`cast-skill-on-block`	List[String]	(empty)	Skill ids to trigger when the projectile hits a block.
`cast-skill-on-miss`	List[String]	(empty)	Skill ids to trigger when the projectile reaches `max-range` without hitting anything.

Example: mage projectile

id: mage-attack-3-projectile
skill-root: cast
type: projectile
params:
  targets: enemy
  display-params:
    - display-type: particle
      type: trial_spawner_detection
      count: 5
      offset:
        x: 0.2
        y: 0.2
        z: 0.2
      extra: 0.0
    - display-type: item_display
      item: black_concrete
      glow: true
      color:
        r: 255
        g: 0
        b: 0
      scale:
        x: 0.3
        y: 0.3
        z: 0.3
  cast-sound:
    sound:
      - entity.tnt.primed
      - item.bundle.drop_contents
    volume: 1.0
    pitch: 1.0
  travel-sound-interval: 1000
  
  update-rate: 50
  hit-update-rate: 50
  display-update-rate: 50
  hit-update-sub-steps: 16
  first-hit-update-delay: 0
  
  velocity: 3.5
  drag: 0.02
  gravity: 0.06
  count: 1
  max-range: 128.0
  hitbox-params:
    hitbox-type: sphere
    radius: 0.6
  hitbox-blocks-params:
    hitbox-type: sphere
    radius: 0.01
  stop-on-block: true
  piercing-amount: 0
  cast-skill-on-block:
    - mage-attack-3-impact
  cast-skill-on-entity:
    - mage-attack-3-impact

Spread patterns with angular variation

Combine count with horizontal-angular-variation and vertical-angular-variation to produce spread patterns:

# 8-way horizontal spread (360 degrees)
count: 8
horizontal-angular-variation: 360
vertical-angular-variation: 0

This configuration fires 8 projectiles, each rotated 45° in yaw.

Laser

Purpose: Fires an instantaneous beam from the caster's position in a straight line, with no gravity or drag. A special case of projectile that forces fixed physics and timing.

Laser behaves like projectile but forces the following:

drag: always 0
gravity: always 0
update-rate: always 1 ms
display-update-rate: always 1 ms
hit-update-rate: always 2 ms

All projectile parameters are accepted; physics parameters are ignored.

Parameter	Type	Default	Notes
(projectile params)	—	—	Laser accepts all projectile keys except `drag` and `gravity`, which are fixed at 0.
`velocity`	Float	—	Beam extension speed (simulates travel distance for hit checking).
`max-range`	Float	—	Maximum beam length in blocks.
`targets`	SubjectTypes	—	Target filter. See Targeting.
`hitbox-params`	ConfigurationNode	—	Beam collision shape. See Hitbox Shapes.
`cast-skill-on-entity`	List[String]	(empty)	Skills to trigger when the beam hits an entity.
`cast-skill-on-block`	List[String]	(empty)	Skills to trigger when the beam hits a block.

Example: laser beam

id: mage-attack-1-laser
skill-root: cast
type: laser
params:
  targets: enemy
  display-params:
    - display-type: particle
      type: ash
      count: 4
      location-offset:
        x: 0.0
        y: -0.5
        z: 0.0
      offset:
        x: 0.1
        y: 0.1
        z: 0.1
      extra: 0.0
    - display-type: particle
      type: dust
      count: 2
      location-offset:
        x: 0.0
        y: -0.5
        z: 0.0
      offset:
        x: 0.2
        y: 0.2
        z: 0.2
      color:
        r: 250
        g: 35
        b: 13
      extra: 0.0
  cast-sound:
    sound:
      - entity.evoker.cast_spell
    volume: 0.4
    pitch: 1.0
  
  hit-update-sub-steps: 1
  first-hit-update-delay: 0
  
  velocity: 0.3
  count: 1
  max-range: 256.0
  hitbox-params:
    hitbox-type: sphere
    radius: 0.6
  hitbox-blocks-params:
    hitbox-type: sphere
    radius: 0.01
  stop-on-block: true
  cast-skill-on-entity:
    - mage-attack-1-impact
  cast-skill-on-block:
    - mage-attack-1-impact-2

Impact

Purpose: Instantaneous area-of-effect that deals damage, healing, or knockback to all entities within a hitbox at a fixed position. No projectile flight or collision detection.

The impact executes once: it resolves all valid targets within its hitbox, applies effects (damage, heal, knockback), and can chain to downstream skills via cast-skill-on-hit or cast-skill-on-miss.

Parameter	Type	Default	Description
`damage`	Float	—	Raw damage to apply to hit entities.
`damage-type`	String	(none)	Free-form tag describing what kind of damage this is — see below.
`heal`	Float	—	Raw healing to apply to hit entities.
`knockback`	Float	—	Knockback strength applied to hit entities (horizontal component).
`knockback-vertical-multiplier`	Float	1.0	Multiplier for the vertical component of knockback.
`apply-knockback-from-caster-position`	Boolean	false	If `true`, knockback direction is calculated from caster → entity. If `false`, knockback is applied in the impact's direction.
`affect-limit`	Integer	-1	Maximum number of entities affected by this impact (-1 for unlimited).
`hit-randomly`	Boolean	false	If `true`, randomly selects entities up to `affect-limit`. If `false`, selects closest entities.
`targets`	SubjectTypes	—	Filter for valid targets. See Targeting.
`hitbox-params`	ConfigurationNode	—	Collision shape and volume. See Hitbox Shapes.
`world-offset`	Vector	(0, 0, 0)	Fixed offset in world-space (X = east, Y = up, Z = south).
`local-offset`	Vector	(0, 0, 0)	Offset relative to the direction vector (X = right, Y = up, Z = forward).
`force-pitch`	Float	(none)	If set, overrides the pitch (vertical angle) of the impact direction.
`enforce-force-pitch`	Boolean	false	If `true`, applies `force-pitch` override.
`impact-sound`	SoundConfiguration	(none)	Sound played when impact occurs.
`display-params`	List[ConfigurationNode]	—	Visual representations. See Displays.
`cast-skill-on-hit`	List[String]	(empty)	Skills triggered once the impact resolves, unless the miss branch below was taken. Because of this, if `cast-skill-on-miss` is left empty, `cast-skill-on-hit` can still fire even when no entity was actually hit (e.g. `affect-limit: 0`).
`cast-skill-on-miss`	List[String]	(empty)	Skills to trigger instead of `cast-skill-on-hit` when no valid targets are found and this list is non-empty.

`damage-type`

A free-form string with no meaning to the engine — it is not a Bukkit DamageType. Setting it makes the impact fire a SkillDamageEvent on the main thread just before each entity is damaged, carrying the resolved tag, so other plugins can key resistances, immunities or shields off it and cancel or rescale the hit.

params:
  damage: 12
  damage-type: "fire"

A skill without a damage-type damages silently, exactly as it always has — no event is fired. The damage itself is dealt as GENERIC, with the caster set as both the direct and the causing entity (which is what credits the kill and what the damage indicators read).

Example: knight impact

id: knight-attack-3-impact
skill-root: cast
type: impact
params:
  targets: enemy
  hitbox-params:
    hitbox-type: rotated_cuboid
    hit-box-x-size: 1.5
    hit-box-y-size: 2.5
    hit-box-z-size: 6.0
    local-offset-z: 3.0
    local-offset-y: -0.5
  display-params:
    - display-type: particle
      type: smoke
      count: 1
      location-offset:
        x: 0.0
        y: 0.5
        z: 0.8
      apply-offset-in-direction: true
  impact-sound:
    sound:
      - entity.arrow.hit_player
    volume: 1.0
    pitch: 1.0
    play-at-caster: true
  force-pitch: -0.5
  enforce-force-pitch: true
  heal: 0.0
  damage: 100.0
  knockback: 0.0
  knockback-vertical-multiplier: 1.0
  apply-knockback-from-caster-position: false
  affect-limit: 100000
  hit-randomly: false

Auto Cast

Purpose: Schedules a sequence of sub-skills to execute on staggered delays (in milliseconds). Useful for multi-hit combos, charge-up sequences, or periodic pulses.

Activation calls update() once, which schedules all sub-skills in elements with their respective delays. The caster's eye location and facing direction are used for each sub-skill cast.

Parameter	Type	Default	Description
`elements`	List[AutoCastElement]	—	Ordered list of sub-skills and their delays.
`repeat`	Integer	0	Number of extra full passes through `elements` after the first (0 = execute once, 1 = execute twice).

AutoCastElement structure:

Field	Type	Default	Description
`skill`	String	—	Skill id to cast.
`delay`	Integer	250	Milliseconds to wait before casting this skill (cumulative from the start of the sequence).

Example: creeper windup sequence

id: creeper-windup
skill-root: cast
type: auto_cast
params:
  elements:
    - skill: creeper-ring-white
      delay: 0
    - skill: creeper-ring-white
      delay: 165
    - skill: creeper-ring-white
      delay: 165
    - skill: creeper-ring-white
      delay: 165
    - skill: creeper-ring-white
      delay: 165
    - skill: creeper-ring-yellow
      delay: 165
    - skill: creeper-ring-yellow
      delay: 165
    - skill: creeper-ring-yellow
      delay: 165
    - skill: creeper-ring-yellow
      delay: 165
    - skill: creeper-ring-yellow
      delay: 165
    - skill: creeper-ring-red
      delay: 165
    - skill: creeper-ring-red
      delay: 165
    - skill: creeper-ring-red
      delay: 165
    - skill: creeper-ring-red
      delay: 165
    - skill: creeper-ring-red
      delay: 165
    - skill: creeper-explosion
      delay: 190

Note: delays are cumulative. Each element's delay is the wait time from the start of the sequence, not the gap from the previous element.

N Cast

Purpose: Rotates through a sequence of skills on each activation, cycling to the next skill in the list every time the n_cast skill is triggered.

On each activation, the n_cast skill looks up the current rotation index for the caster (tracked per skill-id in NCastSkillCache) and casts skills[index]. The index is incremented and wrapped around. The rotation timeout is configurable.

Parameter	Type	Default	Description
`skills`	List[String]	—	Ordered list of skill ids to cycle through.
`max-delay-between-iterations`	Long	10000	Milliseconds; if a caster does not activate this n_cast for longer than this duration, the rotation index resets to 0.

Example: knight combo rotation

id: knight-attack-1-cast
skill-root: cast
type: n_cast
params:
  skills:
    - knight-attack-1-1
    - knight-attack-1-2
    - knight-attack-1-3
  max-delay-between-iterations: 4000

Each time knight-attack-1-cast is triggered, it casts the next skill in the sequence: knight-attack-1-1, then knight-attack-1-2, then knight-attack-1-3, then back to knight-attack-1-1. If 4 seconds pass without an activation, the rotation resets.

The placeholder %n-cast-index% is registered in the skill's placeholder container during execution, allowing effects or downstream skills to react to the current rotation state.

Timing and update loops

All millisecond-based timing (update-rate, hit-update-rate, display-update-rate, delays) is executed by the skill shard engine, which processes each shard's update loop independently. Precision depends on server load; all timings are "at least X ms" (may be slightly later under load).

For projectiles: hit-update-rate and display-update-rate cannot be lower than update-rate; setting either lower is logged as a warning.

For hit accuracy at high speeds (low velocity + high max-range), increase hit-update-sub-steps to subdivide each hit check into finer intervals.

Cross-references

Hitbox shapes: Hitbox Shapes — Detailed collision volume configs for hitbox-params
Displays: Displays — Particle and visual effect configurations
Targeting: Targeting — Entity filter syntax for targets
Developer API: Developer API — Java API for custom aim-solving and skill casting

Last modified: 25 September 2026