Targeting

Skills filter which entities they affect through a targeting system based on caster type, target type, and relationship rules. The targets key determines which entities are valid, and impact-specific or projectile-specific caps determine how many of those valid targets are actually hit.

Relationship Types

The targets field accepts five relationship types, defined by the SubjectTypes enum:

Type	Selects	Aliases
`SELF`	Only the caster (by `entityId`).	lowercase `self`
`ENEMY`	Valid enemies based on caster type.	lowercase `enemy`
`ALLY`	Valid allies based on caster type.	lowercase `ally`
`ALL`	Every entity in the world (no filtering).	lowercase `all`
`ALL_BUT_SELF`	Every entity except the caster.	lowercase `all_but_self`

Configurate deserializes both uppercase and lowercase enum names, so targets: enemy and targets: ENEMY are equivalent.

Relationship Rules

The caster's entity type determines who counts as an ally or enemy:

Player caster

Enemies → mobs and other hostile entities (not other players)
Allies → other players (not mobs)

Mob/entity caster

Enemies → players (not other mobs)
Allies → other mobs and entities of the same type (not players)

In both cases, an entity cannot be an enemy to itself; SELF matches only the caster by entityId. To exclude the caster but include everything else, use ALL_BUT_SELF.

Impact Selection

Impact skills use two parameters to select which valid targets are hit:

Parameter	Type	Default	Description
`affect-limit`	integer	`-1`	Maximum entities to affect per impact. `-1` = unlimited; `0` = no entities hit (display/telegraph only).
`hit-randomly`	boolean	`false`	If `true`, randomly select up to `affect-limit` targets. If `false`, select the `affect-limit` closest targets.

Example: single-target heal

id: priest-attack-2-heal
type: impact
params:
  targets: ALLY
  affect-limit: 1
  hit-randomly: false
  heal: 35.0
  damage: 0.0
  hitbox-params:
    hitbox-type: sphere
    radius: 0.1

The impact searches for allies within the hitbox, then applies the heal to only 1 entity (closest first, since hit-randomly: false).

Example: telegraph/windup display

id: creeper-ring-red
type: impact
params:
  targets: enemy
  affect-limit: 0
  heal: 0.0
  damage: 0.0
  hitbox-params:
    hitbox-type: sphere
    radius: 0.1
  display-params:
    - display-type: particle_ring
      max-radius: 6.0
      rings: 1.0

The affect-limit: 0 means no entities are damaged, but the particle ring still renders at the impact location — a visual telegraph of where damage will occur (used by mob attacks like the creeper-ring and warden-potion-effect).

Projectile Selection

Projectile skills track which entities they pierce through:

Parameter	Type	Default	Description
`piercing-amount`	integer	`0`	Number of entities the projectile can pass through before stopping. Each entity is only hit once, tracked by UUID.

When a projectile strikes a valid target, it:

Checks if the target's UUID is in the piercedEntityIds list for this projectile.
If not, increments the entitiesPierced counter and adds the UUID.
Triggers cast-skill-on-entity for that target.
If entitiesPierced >= piercingAmount, marks the projectile as expired and stops traveling.

Example: multi-target projectile

id: priest-attack-2
type: projectile
params:
  targets: ALL_BUT_SELF
  piercing-amount: 10
  velocity: 0.5
  max-range: 256.0
  count: 1
  hitbox-params:
    hitbox-type: sphere
    radius: 0.6
  cast-skill-on-entity:
    - priest-attack-2-ally
    - priest-attack-2-enemy

The projectile travels until it has hit 10 entities, then expires. Each hit triggers one of two follow-up skills depending on whether the hit entity is an ally or enemy.

Cast Effects vs Target Effects

Skills distinguish between effects applied to the caster and effects applied to affected entities:

cast-effects → applied to the caster when the skill is cast (e.g., knockback to the caster, velocity boost, shield grant).
target-effects → applied to each entity hit by the skill (e.g., potion effects, damage, healing).

See Effects for the full reference.

Example: caster and target effects

id: knight-attack-3-impact
type: impact
params:
  targets: enemy
  damage: 100.0
  knockback: 0.0
  affect-limit: 100000
  hitbox-params:
    hitbox-type: rotated_cuboid
    hit-box-x-size: 1.5
    hit-box-y-size: 2.5
    hit-box-z-size: 6.0

cast-effects:
  - type: velocity
    params:
      local-x: 0.0
      local-y: 0.0
      local-z: 2.2
  - type: command
    params:
      command: "stats resource add %player_name% shield 40"

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

Cast effects apply to the caster: velocity boost forward and shield resource grant.
Target effects apply to each enemy hit: darkness potion effect.
Hit enemies also take 100.0 damage (specified by damage in params).

Common Patterns

Enemy damage impact

Single-target or area damage to enemies:

type: impact
params:
  targets: enemy
  damage: 50.0
  affect-limit: 5
  hit-randomly: false

Ally heal area

Heal multiple allies within range:

type: impact
params:
  targets: ALLY
  heal: 30.0
  affect-limit: -1
  hitbox-params:
    hitbox-type: sphere
    radius: 10.0

Branching projectile (ally/enemy logic)

A projectile that hits both allies and enemies, then triggers different follow-up skills:

type: projectile
params:
  targets: ALL_BUT_SELF
  piercing-amount: 2
  cast-skill-on-entity:
    - my-skill-ally-branch
    - my-skill-enemy-branch

Each follow-up skill has its own targets filter, so my-skill-ally-branch can use targets: ALLY and my-skill-enemy-branch can use targets: enemy.

Windup telegraph

Display a visual warning without dealing damage:

type: impact
params:
  targets: enemy
  damage: 0.0
  affect-limit: 0
  display-params:
    - display-type: particle_ring
      max-radius: 5.0

Used by mob attacks (e.g., creeper-ring-red, warden-potion-effect) to signal the area that will be damaged in a follow-up impact or explosion.

Last modified: 25 July 2026