Selector Filters

选择器过滤器 / Selector Filters

什么能过滤 / What Can Be Filtered

只有 @p 和 @e 支持方括号过滤器。@a、@r、@s 不接受。

Only @p and @e accept bracket filters. @a, @r, @s do not.

方括号里写 键=值，多个用逗号分隔：

Inside the brackets, write key=value, comma-separated:

@p[distance=..10, gamemode=creative]
@e[type=zombie, world=world_nether]

过滤器是并列关系（AND）：所有条件都满足才匹配。

Filters combine with AND: all conditions must hold.

---

通用过滤器 / Common Filters

limit：限制数量 / limit: Cap the Count

@e[type=zombie, limit=5]        // 最多 5 个僵尸

limit=1 有特殊语义：把列表转成单个引用，效果类似 @p。

limit=1 is special: it converts the list into a single reference, similar to @p.

var zombie = @e[type=zombie, limit=1];      // 单个僵尸，可能是 null
var zombies = @e[type=zombie, limit=5];     // 列表，最多 5 个

不写 limit 就返回全部。@e 不加 limit 在繁忙服务器上很重，建议总是加上。

Without limit, everything matches. Unfiltered @e is heavy on busy servers; always add a limit.

name：精确名字 / name: Exact Name

@e[name=Steve]                  // 名字恰好是 Steve 的实体

区分大小写。

Case-sensitive.

world：所在世界 / world: World

@e[type=zombie, world=world_nether]

用世界名（world、world_nether、world_the_end 等）。

Use world names (world, world_nether, world_the_end, etc.).

type：实体类型 / type: Entity Type

只对 @e 有效，值是实体类型名（小写）：

Only for @e; value is a lowercase entity type:

@e[type=zombie]
@e[type=player]
@e[type=item]

常见值：zombie、skeleton、creeper、player、item、arrow、villager。

Common values: zombie, skeleton, creeper, player, item, arrow, villager.

---

玩家过滤器 / Player-Only Filters

下面这些只对 @p（以及 @e 里的玩家）有效：

The following apply only to @p (and to players in @e):

distance：距离范围 / distance: Distance Range

@p[distance=..10]               // 10 格以内
@p[distance=5..15]              // 5 到 15 格
@p[distance=20..]               // 20 格以外

需要执行原点。没有原点（例如在 main 直接执行）时，distance 条件会让所有候选都不匹配。

Requires an execution origin. Without an origin (e.g. running in main), distance filters everything out.

level：等级范围 / level: Level Range

@p[level=..5]                   // 等级 5 以下
@p[level=30..]                  // 等级 30 以上

gamemode：游戏模式 / gamemode: Game Mode

@p[gamemode=creative]
@p[gamemode=survival]

值：survival、creative、adventure、spectator。小写。

Values: survival, creative, adventure, spectator. Lowercase.

x、y、z：精确坐标 / x, y, z: Exact Coordinates

@e[type=player, x=100, y=64, z=200]

精确匹配（允许 0.01 的误差），不是"某个范围内的 x"。日常脚本很少用得上，因为坐标很难恰好相等。

Exact match (0.01 tolerance), not a range. Rarely useful in daily scripts since coordinates rarely match exactly.

---

范围语法 / Range Syntax

distance 和 level 支持范围：

distance and level accept ranges:

写法	含义
..10	至多 10
10..	至少 10
5..10	5 到 10
10	恰好 10

Form	Meaning
..10	at most 10
10..	at least 10
5..10	between 5 and 10
10	exactly 10

范围用两个点，不是三个。

Ranges use two dots, not three.

---

组合多个过滤器 / Combining Filters

逗号分隔，全部满足：

Comma-separated, all must hold:

@p[distance=..20, gamemode=survival, level=10..]

上例选择"20 格以内、生存模式、等级至少 10"的最近玩家。

The above selects the nearest player within 20 blocks, in survival mode, level 10 or above.

不满足任何条件的玩家/实体直接排除，不报错，只是结果为空。

Anything failing any condition is excluded; no error, just an empty result.

---

空结果 / Empty Results

@p 或 limit=1 的 @e 匹配不到时返回 null：

@p or @e[..., limit=1] returns null on no match:

player p = @p[distance=..5];
if (p == null) {
    runcmd("CONSOLE", "say 5 格内没有玩家");
    return;
}

@e 匹配不到时返回空列表（不是 null）：

@e returns an empty list (not null):

var zombies = @e[type=zombie, world=world];
if (zombies.size() == 0) {
    runcmd("CONSOLE", "say 这个世界没有僵尸");
}

null 和空列表不相等。写 if (zombies == null) 会漏掉空列表的情况。列表统一用 size() == 0 判断。

null and empty lists are different. if (zombies == null) misses empty lists. For lists, always check size() == 0.

---

常见错误 / Common Mistakes

错误一：给 @a 加过滤器

@a[type=player]         // ✗ 语法错误

@a 已经是玩家了，不需要 type，也不支持方括号。

错误二：limit=1 之后还当列表用

var z = @e[type=zombie, limit=1];
z.size();               // ✗ z 是单个引用，没有 size()

错误三：distance 但没有执行原点

int main() {
    player p = @p[distance=..10];    // 通常返回 null
}

main 里没有执行原点，distance 无法计算。@s 在事件里才有原点。

Mistake 1: Filtering @a

Not supported and a syntax error.

Mistake 2: Using limit=1 as a list

limit=1 returns a single reference.

Mistake 3: distance without an origin

No origin means all candidates fail.

---

小结 / Summary

• 只有 @p 和 @e 支持过滤器。

• 通用：limit、name、world、type。

• 玩家：distance、level、gamemode、x/y/z。

• limit=1 返回单个引用，不写 limit 返回全部。

• @e 不写过滤器开销大，总是加 limit。

• @p 未匹配返回 null，@e 未匹配返回空列表。

• Only @p and @e support filters.

• Common: limit, name, world, type.

• Player-only: distance, level, gamemode, x/y/z.

• limit=1 returns a single ref; no limit returns everything.

• Unfiltered @e is heavy; always add limit.

• @p yields null on no match; @e yields an empty list.

---

下一步 / Next Steps

下一章 [EntityRef / EntityRef] 讲怎么读写引用上的数据。这是推荐的方式，比后面的占位符更直接。

Next, [EntityRef / EntityRef] shows how to read and write data on references. This is the recommended way, more direct than the placeholders that follow.

---