Selectors Overview

选择器总览 / Selectors Overview

五种选择器 / Five Selectors

HimDSL 用选择器指向游戏里的实体。语法借自原版 Minecraft 命令，但有一些自己的规则。支持五种：

HimDSL uses selectors to point at in-game entities. The syntax borrows from vanilla Minecraft commands but has its own rules. Five are supported:

选择器	含义	返回
@p	距离最近的玩家	单个引用
@a	所有在线玩家	列表
@r	随机一名在线玩家	单个引用
@s	当前触发的实体	单个引用
@e	所有实体	列表

Selector	Meaning	Returns
@p	nearest player	single ref
@a	all online players	list
@r	a random online player	single ref
@s	the triggering entity	single ref
@e	all entities	list

这里"返回"指的是选择器在脚本里表达式的类型。后面会详细说明怎么用。

"Returns" refers to the expression's type in the script. Details below.

---

@p：最近的玩家 / @p: Nearest Player

player p = @p;

距离"执行原点"最近的玩家。执行原点通常是执行脚本的位置；在有事件上下文时，是事件发生的坐标。

The nearest player to the "execution origin". The origin is normally the script's execution location; in event contexts, it is the event's coordinates.

没有任何玩家在线时，@p 返回 null。使用前要判断：

@p returns null when no players are online. Check before use:

player p = @p;
if (p != null) {
    runcmd("CONSOLE", "say " + p.name);
}

---

@a：所有玩家 / @a: All Players

var players = @a;

返回列表，每个元素是一个玩家引用。遍历：

Returns a list; each element is a player reference. Iterate:

var players = @a;
int total = players.size();
for (int i = 0; i < total; i = i + 1) {
    var p = players.get(i);
    runcmd("CONSOLE", "say " + p.name);
}

@a 在语法上不接受方括号过滤器。这条来自语法定义，写 @a[limit=1] 会在解析阶段报语法错误，不是运行时报"未匹配"。

@a does not accept bracket filters at the syntax level. This comes from the grammar: @a[limit=1] fails at parse time, not as a runtime "no match".

需要过滤时，改用 @p[...] 或 @e[type=player, ...]（见下一章）。

When you need filtering, switch to @p[...] or @e[type=player, ...] (next chapter).

---

@r：随机一名玩家 / @r: Random Player

player p = @r;

从在线玩家中随机取一个。没有任何玩家时返回 null。

Picks a random online player. Returns null if none are online.

常见用法是抽奖、随机选人：

Common for lotteries or random selection:

player p = @r;
if (p != null) {
    runcmd("CONSOLE", "say 幸运玩家: " + p.name);
}

和 @a 一样，@r 也不接受方括号过滤器。

Like @a, @r does not accept bracket filters.

---

@s：当前触发者 / @s: The Triggering Entity

player p = @s;

指向当前上下文中"触发的那个实体"。什么时候有触发者？

Points at "the entity that triggered the current context". When is there a trigger?

• 在事件处理函数里：事件相关的玩家。

• 在 GUI 点击回调里：点击的玩家。

• 在 lambda 回调里：调用时注入的玩家。

• In an event handler: the player involved in the event.

• In a GUI click callback: the clicking player.

• In a lambda callback: the player injected at call time.

@EventHandler
void onJoin(event(PlayerJoinEvent)) {
    player p = @s;
    runcmd("CONSOLE", "say 欢迎 " + p.name);
}

在 main 里用 @s 会返回 null，因为 main 没有触发者。这是新手最常犯的错误。

@s returns null inside main because main has no trigger. This is a common beginner mistake.

---

@e：所有实体 / @e: All Entities

var entities = @e;

返回所有世界的所有实体，包括玩家、怪物、动物、掉落物、箭矢等。这是个大列表——服务器里实体很多时，遍历它可能较慢。尽量加过滤器（下一章）。

Returns every entity in every world: players, mobs, animals, items, arrows. This is a large list — iterating it on a busy server can be slow. Add filters whenever possible (next chapter).

var zombies = @e[type=zombie];
int n = zombies.size();
runcmd("CONSOLE", "say 僵尸数量: " + n);

---

选择器作为表达式 / Selectors as Expressions

选择器出现在表达式位置时，HimDSL 会立即解析成引用或列表。可以：

When a selector appears in expression position, HimDSL resolves it immediately into a reference or list. It can be:

• 赋给变量：player p = @p;

• 直接传给函数：runcmd(@s.name, "spawn");

• 作为比较的一部分：if (@a.size() > 0) { ... }

• Assigned to a variable: player p = @p;

• Passed directly to a function: runcmd(@s.name, "spawn");

• Used in comparisons: if (@a.size() > 0) { ... }

每次解析都是一次实时查询。写 @a.size() > 0 会真的去读一遍在线玩家列表，不是缓存的结果。在循环里频繁 @a 会有开销。

Every resolution is a live query. @a.size() > 0 really reads the online list, not a cached result. Frequent @a inside loops is costly.

如果需要反复使用，先存进变量：

For repeated use, store in a variable first:

var players = @a;               // 查询一次
int total = players.size();     // 用多次
// 后续都基于 players

---

小结 / Summary

• 五种选择器：@p、@a、@r、@s、@e。

• @p / @r / @s 返回单个引用，可能是 null。

• @a / @e 返回列表。

• @a / @r / @s 不接受方括号过滤器。

• @s 只在事件、GUI 回调、lambda 里有效。

• 选择器是实时查询，频繁使用先存变量。

• Five selectors: @p, @a, @r, @s, @e.

• @p / @r / @s return a single reference, possibly null.

• @a / @e return lists.

• @a / @r / @s do not accept bracket filters.

• @s works only inside events, GUI callbacks, and lambdas.

• Selectors are live queries; store in a variable for repeated use.

---

下一步 / Next Steps

下一章 [选择器过滤器 / Selector-Filters] 介绍 @p 和 @e 的方括号过滤。

Next, [选择器过滤器 / Selector-Filters] covers the bracket filters on @p and @e.

---