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.
`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.

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 July 2026