Targeting and Target Selection (target)

Previous: Passive Skills　·　Next: Cooldowns, Charges, GCD, and Conflicts

target answers one question: when this skill is cast, who does QS lock for you? The locked target is passed to MythicMobs as @Target / @Trigger, and on the MM side damage{} @Target hits this target.

💡 Division of labor reminder: QS only handles "who gets selected"; how damage is dealt is up to MM + attribute plugins. A skill with no target: has no @Target, so in MM you must use @EntitiesInRadius / @Self to grab a range yourself.

🖼️ [Image placeholder] A diagram of "player casts → QS selects a target within range by mode → that target is passed to MM as @Target"　·　suggested assets/target-select.png

1. The 7 target modes (target mode)

mode	Meaning	Who it selects	Range search?
`SELF`	self (default)	doesn't actively select a target, leaves it to MM's own targeter	No
`LOOK`	crosshair raycast	casts a ray from the player's line of sight, finds the first entity as `@Target`	No (raycast)
`NEAREST`	nearest	the closest within range	✅
`FARTHEST`	farthest	the farthest within range	✅
`LOWEST_HP`	most wounded (execute)	the lowest current health within range	✅
`HIGHEST_HP`	tankiest (tank)	the highest current health within range	✅
`RANDOM`	random	a random one within range	✅

NEAREST / FARTHEST / LOWEST_HP / HIGHEST_HP / RANDOM—these 5 are range search, controlled by range, filter, and require_los. SELF selects no target; LOOK uses a raycast and takes only the first entity in the line of sight.

⚙ How range search is implemented: candidate entities come from getNearbyEntities(range, range, range), first filtered by filter, then by line of sight (require_los), then selected by mode—NEAREST = closest, FARTHEST = farthest, RANDOM = a random one; LOWEST_HP / HIGHEST_HP select the lowest / highest health only among LivingEntity (living things with health) (entities without health don't participate in the HP comparison).

2. The 5 filters (filter)

filter decides "which entities count as candidate targets," defaulting to LIVING. All filters exclude the caster themselves.

filter	Meaning
`ANY`	all entities
`LIVING`	living things (default)
`MONSTERS`	monsters only
`PLAYERS`	players only
`NOT_PLAYERS`	non-player creatures (monsters + animals, etc., excluding players)

💡 PVE skills generally use MONSTERS (won't hit teammates by mistake); PVP skills use PLAYERS.

3. range / required / require_los

Field	Default	Range	Meaning
`range`	30	1–100	search radius (blocks)
`required`	false	—	`true` = fail outright if no target is locked, shows "§c没有可用目标" and returns `CastResult.NO_TARGET`; `false` = cast anyway with no target, let MM handle it
`require_los`	false	—	`true` = only lock targets with line of sight, not through walls; `false` = can lock through walls

⚙ range is forcibly clamped to 1–100 (coerceIn(1,100) at load time): writing 150 becomes 100, writing 0 becomes 1. So range always lands between 1 and 100; out-of-bounds values don't error but are silently clamped.

⚙ required: true with no target locked → the skill fails outright, prompting the player with "§c没有可用目标" and returning CastResult.NO_TARGET. Note this target check happens before the gate (it's caught at the target-selection stage), so it never even computes cooldown / resources and never enters CD.

A note on require_los: LOOK is itself a raycast, so it inherently doesn't go through walls; require_los mainly affects range searches like NEAREST—with it on, monsters behind walls can't be locked.

4. Two ways to write it

Form A — scalar (specify only the mode, rest take defaults):

yaml

target: NEAREST                  # lock the nearest living thing, range=30, no target required

Form B — section (full control):

yaml

target:
  mode: NEAREST                  # required: who to select
  range: 6                       # search radius (blocks), default 30
  filter: MONSTERS               # filter: default LIVING
  required: true                 # can't cast if no target locked, default false
  require_los: true              # only lock targets with line of sight, default false

5. Reproduction: blade_slash's target section (standard example)

From the bundled example skills/combat/blade_slash.yml, a model of "auto-lock the nearest monster":

yaml

# auto target search: QS selects the target at cast time and passes it to MM as @Target
target:
  mode: NEAREST                 # who to select: NEAREST nearest / FARTHEST farthest / LOWEST_HP most wounded / HIGHEST_HP tankiest / RANDOM random
  range: 6                      # search radius (blocks)
  filter: MONSTERS              # only lock monsters
  required: true                # true = can't cast if no target locked (prompts "没有可用目标")
  require_los: true             # true = only lock targets with line of sight (not through walls)

6. The relationship between QS targets and MM @Target (key)

Skills with a target:: the target QS selected is passed to MM as @Target / @Trigger, and in MM you directly damage{} @Target to hit it.
Skills without a target:: MM receives no @Target and must use its own targeter like @EntitiesInRadius / @Self to grab a range.

yaml

# MM side: the skill uses the @Target QS selected
blade_slash:
  Skills:
    - damage{amount=8} @Target           # hit the monster QS locked
    - particles{p=crit;amount=15} @Target

The value (amount=8) is ultimately settled by attribute plugins like AttributePlus; QS / MM only handle who gets hit.

7. Five scenario recipes

① Lock the nearest monster (melee / single-target)

yaml

target:
  mode: NEAREST
  range: 6
  filter: MONSTERS

② Execute the wounded (focus dying monsters)

yaml

target:
  mode: LOWEST_HP                # lock the lowest health
  range: 8
  filter: MONSTERS

③ Lock the crosshair (player aims where they hit)

yaml

target: LOOK                     # first entity in line of sight, inherently not through walls

④ Must have a target (don't cast if none, save the cooldown)

yaml

target:
  mode: NEAREST
  range: 10
  filter: MONSTERS
  required: true                 # no lock → fail outright, prompt "没有可用目标", no cooldown entered

⑤ No through-wall lock (only hit what's visible)

yaml

target:
  mode: NEAREST
  range: 12
  filter: MONSTERS
  require_los: true              # monsters behind walls can't be locked

✅ Self-check list

[ ] PVE skills use filter: MONSTERS to avoid hitting teammates.
[ ] range is between 1 and 100.
[ ] Turn on required: true if you want "no cooldown wasted when there's no target."
[ ] The MM side uses @Target (when target is configured) or @EntitiesInRadius (when it isn't).
[ ] No need to agonize over LOOK and require_los together—LOOK inherently doesn't go through walls.

Targeting and Target Selection (target) ​

1. The 7 target modes (target mode) ​

2. The 5 filters (filter) ​

3. range / required / require_los ​

4. Two ways to write it ​

5. Reproduction: blade_slash's target section (standard example) ​

6. The relationship between QS targets and MM @Target (key) ​

7. Five scenario recipes ​

① Lock the nearest monster (melee / single-target) ​

② Execute the wounded (focus dying monsters) ​

③ Lock the crosshair (player aims where they hit) ​

④ Must have a target (don't cast if none, save the cooldown) ​

⑤ No through-wall lock (only hit what's visible) ​

✅ Self-check list ​

Further reading ​

Targeting and Target Selection (target)

1. The 7 target modes (target mode)

2. The 5 filters (filter)

3. range / required / require_los

4. Two ways to write it

5. Reproduction: blade_slash's target section (standard example)

6. The relationship between QS targets and MM @Target (key)

7. Five scenario recipes

① Lock the nearest monster (melee / single-target)

② Execute the wounded (focus dying monsters)

③ Lock the crosshair (player aims where they hit)

④ Must have a target (don't cast if none, save the cooldown)

⑤ No through-wall lock (only hit what's visible)

✅ Self-check list

Further reading