Selectors & targets

A selector answers the question "who (or what) does this effect act on?" Effects already have a sensible default target — DAMAGE hits the victim, MODIFY_HEALTH heals you — but when you want something else, you set the effect's who: key to a selector:

effects:
  # No arguments: just the @Name.
  - { POTION: { effect: STRENGTH, level: 1, duration: 200, who: "@Self" } }

  # With arguments: @Name{key=value, key=value}
  - { DAMAGE: { amount: 6, who: "@Aoe{r=6, filter=MONSTERS}" } }
  - { LIGHTNING: { damage: 4, who: "@Nearest{r=8, filter=PLAYERS}" } }

• The @Name is the selector (capitalisation is for readability; e.g. @Aoe, @NearestPlayer).
• Arguments go in { } as key=value pairs, comma-separated. Omit any you don't need — defaults apply.
• A selector starts with @, so quote it in YAML — who: "@Self".

:::tip A selector carries no behaviour of its own A selector only chooses targets; it doesn't decide how the effect runs. So an effect that "acts on the world" (like BREAK_BLOCK) wants a block selector (@Here, @Vein, @Trench), while an effect that "acts on an entity" (like IGNITE) wants an entity selector (@Victim, @Aoe, @Nearest). Pairing a block effect with an entity selector (or vice-versa) won't do anything useful. :::

Choosing the right one

• Just the player — @Self. The activating player. The default for most buffs/heals.
• The thing you hit — @Victim (combat victim) or @Attacker (who hit you, on DEFENSE).
• A crowd — @Aoe (all living entities in radius), @AllPlayers (players only). Both can be filtered and capped.
• One nearby entity — @Nearest / @NearestPlayer (closest within radius), or @EntityInSight (whatever you're looking at).
• A block — @Here (the activation block), @Block / @BlockInDistance (the block you're looking at), or the mining shapes @Vein / @Tunnel / @Trench.
• A location — @Add (an offset from the activation point), @EyeHeight (your eyes).
• By name — @PlayerFromName{name=Steve} (a specific online player).

:::note filter on area selectors @Aoe, @Nearest and friends accept a filter: ALL (everything living), PLAYERS (players only), MONSTERS (hostile mobs), or MOBS (any non-player mob). The activator is always excluded from area selectors, so you never hit yourself. :::

All selectors

@Add

The activation location offset by (x, y, z).

Argument	What to put	Required?	Default	Allowed
x	a number (decimals allowed) — x offset in blocks	optional	0	—
y	a number (decimals allowed) — y offset in blocks	optional	0	—
z	a number (decimals allowed) — z offset in blocks	optional	0	—

Example@Add{y=2}

@Allplayers

Every player within r blocks of the target, except the activator and except allies. allies: true takes allied players back, for a broadcast audience rather than a target list.

Argument	What to put	Required?	Default	Allowed
r	a number (decimals allowed) — search radius in blocks	optional	32	0 or more
allies	true or false — include allied players — set it for a broadcast AUDIENCE; a target list wants the default	optional	false	—

Example@AllPlayers{r=32}

@Aoe

Living entities within r blocks of the target, except the activator; optionally filtered, capped, and with the combat victim excluded. filter admits a + conjunction (ENEMIES+PLAYERS = hostile players only).

Argument	What to put	Required?	Default	Allowed
r	a number (decimals allowed) — radius in blocks	optional	4	0 or more
filter	one of: ALL, PLAYERS, MONSTERS, MOBS, ENEMIES, ALLIES — which entities to include; A+B keeps only what both admit	optional	ALL	ALL | PLAYERS | MONSTERS | MOBS | ENEMIES | ALLIES
limit	a whole number — max targets, nearest first (0 = unlimited)	optional	0	0 or more
exclude	one of: none, victim — remove the combat victim from the matches (Destruction hits everyone BUT the primary victim)	optional	none	none | victim

Example@Aoe{r=6, filter=MONSTERS, exclude=victim}

@Attacker

The entity that damaged the activator (for defensive effects).

Takes no arguments.

Example@Attacker

@Block

The first solid block the activator is looking at, within distance.

Argument	What to put	Required?	Default	Allowed
distance	a number (decimals allowed) — max look distance in blocks	optional	5	0 or more

Example@Block

@Blockindistance

The first solid block along the activator's line of sight, within distance.

Argument	What to put	Required?	Default	Allowed
distance	a number (decimals allowed) — max look distance in blocks	optional	30	0 or more

Example@BlockInDistance{distance=50}

@Bore

A half-width x half-height cross-section centred on the activation block, repeated depth layers into the mined face. depth=1 is a flat face; materials keeps only the listed block types and exclude-materials drops them, both written [STONE,DIRT] so the comma survives the selector body. A type on both lists is dropped. left/right/up/down override their axis's half-* for an ASYMMETRIC cross-section — the only way to reach an even width or height (left=1, right=2 is 4 blocks across).

Argument	What to put	Required?	Default	Allowed
half-width	a whole number — half the cross-section across (1 = 3 blocks wide)	optional	1	0 or more
half-height	a whole number — half the cross-section up and down (1 = 3 blocks tall)	optional	1	0 or more
depth	a whole number — layers into the face, counting the activation block's own	optional	1	1 or more
left	a whole number — blocks left of centre; -1 = half-width	optional	-1	-1 or more
right	a whole number — blocks right of centre; -1 = half-width	optional	-1	-1 or more
up	a whole number — blocks above centre; -1 = half-height	optional	-1	-1 or more
down	a whole number — blocks below centre; -1 = half-height	optional	-1	-1 or more
materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — keep only these block types (empty = every block)	optional	(empty)	—
exclude-materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — drop these block types (empty = drop none)	optional	(empty)	—

Example@Bore{half-width=1, half-height=1, depth=3, exclude-materials=[BEDROCK,OBSIDIAN]}

@Entityinsight

The living entity the activator is looking at within r blocks, or nothing. An allied player is skipped unless allies: true; mobs are never filtered.

Argument	What to put	Required?	Default	Allowed
r	a number (decimals allowed) — maximum line-of-sight distance in blocks	optional	16	0 or more
allies	true or false — include an allied player in the crosshair; the default skips one	optional	false	—

Example@EntityInSight{r=16}

@Eyeheight

The activator's eye location (their position at eye level).

Takes no arguments.

Example@EyeHeight

@Here

The activation block location itself — the default target of block effects.

Takes no arguments.

Example@Here

@Marked

Every nearby living entity the activator currently has an active MARK on.

Argument	What to put	Required?	Default	Allowed
r	a number (decimals allowed) — search radius in blocks	optional	32	0 or more

Example@Marked{r=32}

@Nearest

The single nearest living entity within r blocks (optionally filtered), except the activator. filter admits a + conjunction (ENEMIES+PLAYERS = hostile players only).

Argument	What to put	Required?	Default	Allowed
r	a number (decimals allowed) — search radius in blocks	optional	5	0 or more
filter	one of: ALL, PLAYERS, MONSTERS, MOBS, ENEMIES, ALLIES — which entities to consider; A+B keeps only what both admit	optional	ALL	ALL | PLAYERS | MONSTERS | MOBS | ENEMIES | ALLIES

Example@Nearest{r=5, filter=PLAYERS}

@Nearestplayer

The single nearest player within r blocks, except the activator and except allies.

Argument	What to put	Required?	Default	Allowed
r	a number (decimals allowed) — search radius in blocks	optional	16	0 or more
allies	true or false — include allied players; the default skips them	optional	false	—

Example@NearestPlayer{r=16}

@Playerfromname

The online player with the given exact name, or nothing if they are not online.

Argument	What to put	Required?	Default	Allowed
name	text — the exact name of the online player to target	required	—	—

Example@PlayerFromName{name=Steve}

@Self

The activating player themself.

Takes no arguments.

Example@Self

@Trench

The square of blocks perpendicular to the look direction, centred on the activation block. materials keeps only the listed block types and exclude-materials drops them, both written [STONE,DIRT] so the comma survives the selector body. A type on both lists is dropped.

Argument	What to put	Required?	Default	Allowed
radius	a whole number — half-width of the face (1 = 3x3)	optional	1	0 or more
materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — keep only these block types (empty = every block)	optional	(empty)	—
exclude-materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — drop these block types (empty = drop none)	optional	(empty)	—

Example@Trench{radius=1}

@Tunnel

The blocks directly ahead of the activation block, along the look direction. materials keeps only the listed block types and exclude-materials drops them, both written [STONE,DIRT] so the comma survives the selector body. A type on both lists is dropped.

Argument	What to put	Required?	Default	Allowed
depth	a whole number — blocks ahead along the look direction	optional	3	1 or more
materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — keep only these block types (empty = every block)	optional	(empty)	—
exclude-materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — drop these block types (empty = drop none)	optional	(empty)	—

Example@Tunnel{depth=4}

@Vein

Up to `limit` blocks contiguous with and matching the activation block (vein miner). materials restricts which struck blocks vein at all and exclude-materials names ones that never do, both written [IRON_ORE,GOLD_ORE] so the comma survives the selector body. Both gate the STRUCK block, since the fill is same-material by construction.

Argument	What to put	Required?	Default	Allowed
limit	a whole number — max blocks in the vein	optional	64	1 or more
materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — only vein these block types (empty = whatever was struck)	optional	(empty)	—
exclude-materials	a block or item name (e.g. DIAMOND, OBSIDIAN) — never vein these block types (empty = none)	optional	(empty)	—

Example@Vein{limit=32}

@Victim

The combat victim (the entity the activator hit).

Takes no arguments.

Example@Victim

See also

• Effects — what each effect does, and its default target.
• Triggers — when an effect fires (and whether a victim exists to target).