Skill Handlers API

Skill handlers provide core functionality for spell casting, damage, knockback, and mana systems.

Spell Handler

Comprehensive spell casting system with cooldowns, charges, warmup, and channeling.

Spell

Main spell execution handler.

string

required

Unique spell identifier

name

string

default:"Unknown"

Display name for the spell

type

string

default:"Unknown"

Spell category/type for classification

damage

number

Base damage value

spell_cooldown

number

default:"1"

Cooldown duration in seconds

warmup

number

default:"0"

Warmup/cast time in seconds

charges

integer

default:"0"

Number of charges (0 = no charge system)

charge_cooldown

number

default:"3"

Time to regenerate one charge in seconds

charge_delay

number

default:"0"

Delay before charge regeneration starts

critical_chance

number

default:"0.01"

Critical hit chance (0.0-1.0)

critical_damage

number

default:"0"

Critical damage multiplier bonus

displaycd

boolean

default:"true"

Show cooldown messages

debug

boolean

default:"false"

Enable debug output

Spell Lifecycle Hooks

onChannelStart

metaskill

default:"channel-start_fx"

Executed when channeling begins

onChannelTick

metaskill

default:"channel-tick_fx"

Executed each tick during channeling

onCast

metaskill

default:"channel-cast_fx"

Executed when spell is cast

onInterrupt

metaskill

default:"[]"

Executed on any interrupt

onForceInterrupt

metaskill

default:"channel-force_interrupt-default"

Executed on forced interrupt (stun, etc)

onManualInterrupt

metaskill

default:"[]"

Executed on manual interrupt (player cancel)

onCooldownCast

metaskill

default:"[]"

Executed when cast while on cooldown

onCooldownEnd

metaskill

default:"[]"

Executed when cooldown expires

Channeling System

spell-channel Handles spell warmup/casting time.

Creates terminable aura with type=channel
Shows boss bar with cast progress
Summons channel_indicator display entity
Checks for interrupts (force_interrupt, manual_interrupt)
Sets caster.cast_fatigue after successful cast

Interrupt Variables:

caster.force_interrupt

boolean

Set to true to force interrupt (e.g., stun)

caster.manual_interrupt

boolean

Set to true for manual interrupt (e.g., casting another spell)

Charge System

spell-charges-cast Handles spells with multiple charges.

Tracks charges in caster.<id>-charges
Decrements charge on cast
Initiates recharge delay
Regenerates charges over time

spell-charges_regen Regenerates spell charges.

Only runs when charges < max_charges
Shows boss bar with charge count and timer
Calls itself recursively until full

Cooldown Management

spell-cooldown Applies cooldown aura.

Creates aura with type=cooldown
Updates caster.<id>-cd variable each tick
Shows boss bar with cooldown timer
Triggers spell-cooldown_end on expiration

spell-reset_cooldown Resets cooldown instantly.

Removes cooldown aura
Triggers COOLDOWN_RESET modifier event
Clears cooldown variable

Modifier Handler

Dynamic modifier system for stacking buffs/debuffs.

modifier

Adds a modifier to the caster.

modifier_name

string

required

Unique name for this modifier

metaskill

required

Operation/skill to execute

trigger

string

default:"PRECAST"

Trigger event: PRECAST, CAST, DAMAGE, PRE_DAMAGE, COOLDOWN_END, CRITICAL_DAMAGE, WEAPON_HIT, ABILITY_HIT

priority

integer

default:"1"

Execution priority (1-7, higher = earlier)

1: LOWEST
2: LOW
3: MEDIUM
4: HIGH
5: SPELL SELECT
6: SPELL EXECUTION
7: MONITOR

stacks

integer

default:"1"

Stack count for the modifier

modifier-trigger

Executes all modifiers for a trigger event.

trigger

string

required

Trigger event to execute

update

boolean

default:"false"

Force update of modifier list

modifier-remove

Removes modifiers by name.

modifier_name

string

required

Name of modifier to remove

modifier-clear

Removes all modifiers from caster.

Example

blazingsun_apply:
  Skills:
  - skill:modifier{
      modifier_name="Blazing Sun";
      o=blazingsun_modifier;
      trigger=PRECAST;
      priority=7;
      stacks=3
    } @self

blazingsun_modifier:
  Skills:
  - variableMath{var=damage;equation='x*20'}
  - variableMath{var=warmup;equation='x*0.2'}
  - setvar{var=caster.blazing_sun;val=<caster.var.blazing_sun>-1}
  - skill{s=modifier-remove;modifier_name=Blazing Sun} ?varinrange{var=caster.blazing_sun;val=<1}

Damage Core

Advanced damage system with hit tracking and modifiers.

damage

Standard damage skill.

damage

number

required

Damage amount

damage_source

string

default:"NONE"

Source of damage (for modifiers)

damage_type

string

Type of damage (defaults to damage_source)

immune

integer

default:"5"

Immunity ticks after hit

damage_id

string

default:"default"

Identifier for hit tracking

damageMod

metaskill

default:"[]"

Skill to modify damage before applying

preHit

metaskill

default:"[]"

Skill executed before damage

onHit

metaskill

default:"[]"

Skill executed after damage

damage-weapon

Weapon damage with WEAPON tag.

Same parameters as damage
Triggers WEAPON_HIT modifier event
Tags damage as tag=WEAPON

damage-ability

Ability damage with stagger effect.

Same parameters as damage
Applies suspension and stagger
Triggers ABILITY_HIT modifier event
Tags damage as tag=ABILITY

Hit Tracking

Variables:

hit_list

list

List of UUID strings for entities hit by this skill

hit_count

integer

Number of entities hit

targeted

string

UUID of current target

Damage Indicator

damage_indicator Displays floating damage numbers.

Creates text display projectile
Scales based on damage percent
Flies toward caster with drag
Uses <placeholder.damage_text> for formatting

Knockback Core

Advanced knockback system with directional control.

knockback

Applies knockback to entities.

number

default:"0"

Horizontal knockback velocity

kby

number

default:"0"

Vertical knockback velocity

origin

location

Origin point for knockback direction

vertical

boolean

default:"true"

Apply vertical component

Variables

knockback_direction

location

Direction target for knockback (set with setvarloc)

Example

knockback_away:
  Skills:
  - setvarloc{var=knockback_direction;val=@forward{f=20;lockpitch=true}}
  - skill:knockback{kb=12;origin=@selflocation;vertical=false} @ENO{r=12}

Melee Core

Melee combat system with moveset integration.

Melee

Main melee handler.

damage

number

Base melee damage (defaults to caster.damage)

Auto-detects hit types:

Sweep: Normal hit (moveset index 1)
Weak: Weak attack (attack cooldown < 0.9)
Sprint: Sprint attack
Critical: Critical hit
Uppercut: Crouching hit
Aerial: Air attack

Knockback Types

knockback-melee_weak

kb=1.25, kby=0.75 (ground)
kb=1.25, kby=-0.75 (air)

knockback-melee_strong

kb=1.5, kby=0.75 (ground)
kb=1.5, kby=-0.75 (air)

knockback-melee_critical

Same as weak but with crit sound

knockback-melee_uppercut

kb=1.25, kby=1.6 (launches upward)

Mana Charge

Mana charge/resource system.

mana_charge

Adds or removes mana charge.

mana

number

required

Mana to add (positive) or remove (negative)

Variables

caster.mana_charge

number

default:"0"

Current mana charge

caster.mana_charge_max

number

default:"100"

Maximum mana charge

caster.mana_charge_decay

number

Mana decay per tick (10% of max per second)

mana_charge-decay

Automatic mana decay system.

Decays when not channeling
Removes mana_charged aura when depleted
Updates action bar display

Other Handlers

setRandomID

Generates random ID for hit tracking.

setRandomID:
  Skills:
  - setvar{var=randomid;val="<caster.uuid>_<random.-65536to65536>";type=STRING}

summon_handler

Initializes summoned entities.

Sets owner UUID and name
Sets parent relationship
Initializes combat state
Updates name display

spell_cast-defaults

Default stat mapping for spells. stat_map-default Sets up default spell parameters:

spell_power, damage, critical stats
mana costs, charges
warmup, cooldowns
velocity, spread, range, radius
knockback_modifier, status_duration

Default VFX:

channel-start_fx: Sound effects for channeling
channel-tick_fx: Particle effects during channel
channel-cast_fx: Cast completion effects

Skills

Items & Mobs

Spell Handler

Spell

Spell Lifecycle Hooks

Channeling System

Charge System

Cooldown Management

Modifier Handler

modifier

modifier-trigger

modifier-remove

modifier-clear

Example

Damage Core

damage

damage-weapon

damage-ability

Hit Tracking

Damage Indicator

Knockback Core

knockback

Variables

Example

Melee Core

Melee

Knockback Types

Mana Charge

mana_charge

Variables

mana_charge-decay

Other Handlers

setRandomID

summon_handler

spell_cast-defaults

Build docs developers (and LLMs) love

Skills

Items & Mobs

​Spell Handler

​Spell

​Spell Lifecycle Hooks

​Channeling System

​Charge System

​Cooldown Management

​Modifier Handler

​modifier

​modifier-trigger

​modifier-remove

​modifier-clear

​Example

​Damage Core

​damage

​damage-weapon

​damage-ability

​Hit Tracking

​Damage Indicator

​Knockback Core

​knockback

​Variables

​Example

​Melee Core

​Melee

​Knockback Types

​Mana Charge

​mana_charge

​Variables

​mana_charge-decay

​Other Handlers

​setRandomID

​summon_handler

​spell_cast-defaults

Build docs developers (and LLMs) love

Spell Handler

Spell

Spell Lifecycle Hooks

Channeling System

Charge System

Cooldown Management

Modifier Handler

modifier

modifier-trigger

modifier-remove

modifier-clear

Example

Damage Core

damage

damage-weapon

damage-ability

Hit Tracking

Damage Indicator

Knockback Core

knockback

Variables

Example

Melee Core

Melee

Knockback Types

Mana Charge

mana_charge

Variables

mana_charge-decay

Other Handlers

setRandomID

summon_handler

spell_cast-defaults