目标选择器(Target Selector)可在无需指定确切的玩家名称或UUID的情况下在命令中选择任意玩家与实体。目标选择器变量可以选择一个或多个实体,目标选择器参数可以根据特定条件筛选目标。
请注意,Java版和基岩版的目标选择器有较大的区别,部分语法仅适用于两者之一。
目标选择器变量[]
变量 | 功能 |
---|---|
@p |
距离最近的玩家 |
@r |
随机玩家 |
@a |
所有玩家 |
@e |
所有实体 |
@s |
命令的执行者 |
@n |
存活的实体在java1.21+版中,使用 |
@c |
自己的智能体 |
@v |
所有智能体 |
@initiator |
与NPC交互的玩家 |
目标选择器变量用于指定待选目标的大致分类。共有8种变量:
@p
[]
- 选择最近的玩家。在服务器控制台中输入,默认基准点为世界出生点。若有多个最近的玩家,与基准点距离完全相同,会选择其中最晚进入服务器的玩家。
type
参数不适用于@p
。
- 在基岩版中,
@p
只选择活着的玩家。
@r
[]
- 选择一名随机玩家。
- 在基岩版中,
@r
只选择活着的实体。
@a
[]
- 选择所有玩家,无论死活。
@e
[]
@s
[]
- 只选择唯一一个实体:该命令的执行者,包括已死亡玩家。若命令执行者为命令方块或服务器控制台执行命令,则此选择器不会选中任何东西。
@c
[]
- 选择自己的智能体。
[仅教育版]
@v
[]
- 选择所有的智能体。
[仅教育版]
@initiator
[]
- 选择当前与NPC交互的玩家。
[仅基岩版和教育版] - 对于NPC内置的命令界面,有一个特有的选择器变量为
@initiator
,它可以选择当前与该NPC进行交互(例如打开NPC对话框、使用NPC按钮和关闭NPC对话框)的玩家。如果该选择器用于外置命令,则不会报错,但不会选择到任何玩家。
目标选择器参数[]
通过坐标 | |
---|---|
参数 | 选择标准 |
x , y , z
|
坐标 |
distance r 、rm |
距离 |
dx , dy , dz
|
体积尺寸 |
通过记分板参数 | |
参数 | 选择标准 |
scores
|
记分项分数 |
tag
|
记分板标签 |
team |
队伍名称 |
通过实体种类 | |
参数 | 选择标准 |
name
|
实体名称 |
type
|
实体类型 |
family |
族 |
predicate |
谓词 |
通过实体数据 | |
参数 | 选择标准 |
x_rotation rx 、rxm |
垂直旋转角度 |
y_rotation ry 、rym |
水平旋转角度 |
nbt |
实体的NBT标签 |
hasitem |
物品 |
通过玩家数据 | |
参数 | 选择标准 |
level l 、lm |
经验等级 |
gamemode m |
游戏模式 |
advancements |
进度 |
haspermission |
权限 |
通过其他特性 | |
参数 | 选择标准 |
limit 、sort c |
数量 |
在使用目标选择器之后,可以用参数限定所要选择的群组。当使用@a
或@e
时,待选目标从全体筛选成特定的少数。当使用@p
或@r
时,参数将从完整的待选列表缩小到被筛选后的待选列表。当使用@s
时,命令执行者只有在所有参数都满足时才会被选择,否则命令将执行失败。
在目标选择器变量之后附加键值对构成的逗号分隔,并包含在方括号中:
@<变量>[<参数>=<值>,<参数>=<值>,…]
参数和值区分大小写
坐标[]
[x=<值>,y=<值>,z=<值>]
— 在世界中定义一个位置。
- 这个位置将成为目标选择器执行位置(不修改命令执行位置),这意味着
@p
所选择的目标可能发生改变。 - 如果其中任意参数未定义,则默认使用命令执行位置的坐标。
- 可用于
distance
参数或dx
、dy
和dz
参数,以平移选择范围。 - 坐标可以是整数或像
12.34
这样的小数(具体为双精度浮点数)且不会进行中心校正(center-corrected),这意味着x=0
不再自动更正为x=0.5
。波浪号可用于此参数[仅基岩版]。
- 示例:
@p[x=0,y=0,z=0]
— 选择距离世界中心点最近的玩家。@e[c=3,x=~10,z=~10]
— 从往东南方向延伸14.14米的位置开始,选择距离最近的3个实体。[仅基岩版]
距离[]
[distance=<值>]
— 根据到某点的欧几里得距离过滤目标。只允许使用非负数。[仅Java版] [r=R]
— 只选择所有小于R个方块的目标执行命令。[rm=RM]
— 只选择所有大于RM个方块的目标执行命令。[仅基岩版]
- 如果位置参数未定义,则相对于命令执行的位置计算。注意,距离参数是一个空间参数,它不能跨维度选择目标。
distance
支持使用范围表示,以定义球形区域:@e[distance=10]
— 选择所有距离执行位置等于10个方块的实体。@e[distance=10..12]
— 选择所有距离执行位置大于等于10,且小于等于12个方块的实体。@e[distance=5..]
— 选择所有距离执行位置大于等于5个方块的实体。@e[distance=..15]
— 选择所有距离执行位置小于等于15个方块的实体。
- 示例:
体积尺寸[]
[dx=<值>,dy=<值>,dz=<值>]
— 选择所有位于一定长方体区域内部的目标。体积定义为从基准点开始,向“X”方向(东方)延伸dx格(包括基准点本身,下同),向“Y”方向(上方)延伸dy格,并向“Z”方向(南方)延伸dz格。如果只指定了其中的部分参数,那么剩余的参数默认为0。
- 区域选取规则与结构方块中的储存模式中的结构大小相似。
- 这可以解释为先创建两个坐标(x, y, z)和(x+dx, y+dy, z+dz),组成一个长方体,再保持长方体的西北下角不变,将长方体的三边分别向东、南、上方向(即三个坐标轴的正方向)延伸1格,得到一个体积为
(|dx|+1)×(|dy|+1)×(|dz|+1)
的长方体。最后选择碰撞箱或脚部坐标与其重叠的所有实体。如果位置参数未定义,则相对于命令执行的位置计算。这三个参数允许任何值,包括负数。 - 注意,体积尺寸参数是一个空间参数,它不能跨维度选择目标。
- 可以将通过按距离来选择与按体积来选择组合在一起, 在这种情况下,命令将选择在两个区域的重叠内的实体(在基准点的某个半径范围内,且不在定义的体积之外)。
- 示例:
@e[x=1,y=2,z=3,dx=4,dy=5,dz=6]
— 选择和方块坐标区域(1, 2, 3)至(5, 7, 9)(或以数学表达式表示,范围是{(x,y,z)|x∈[1,6),y∈[2,8),z∈[3,10)})有重叠的所有实体。@e[x=1,y=2,z=3,dx=0,dy=0,dz=0]
— 选择和方块坐标区域(1, 2, 3)有重叠的所有实体。@e[x=0,y=0,z=0,dx=-1,dy=-2,dz=-3]
— 选择和方块坐标区域(0, 0, 0)至(-1, -2, -3)有重叠的所有实体。@a[x=0,y=0,z=0,dx=-0.5,dy=0,dz=0.5]
— 选择实际坐标满足区域{(x, y, z) | x∈[-0.5, 1), y∈[0, 1), z∈[0, 1.5)}的所有玩家。@s[y=320,dy=0]
— 如果自己位于世界最高点,且X、Z坐标和命令执行坐标相同,则选择自己。
记分项分数[]
[scores={<记分项>=<值>,...}]
— 根据指定目标的分数过滤目标。
- 所有的记分项都放在一个单独的标签中,并这个标签中分别列出分数选择器。此选择器支持使用范围,在基岩版中,还可使用不等号(=!)。
- 示例:
@e[scores={myscore=10}]
— 选择所有记分项myscore分数为10的目标。@e[scores={myscore=10..12}]
— 选择所有记分项myscore分数为10到12之间(包含)的目标。@e[scores={myscore=5..}]
— 选择所有记分项myscore分数为5及以上的目标。@e[scores={myscore=..15}]
— 选择所有记分项myscore分数为15及以下的目标。@e[scores={myscore=!10}]
— 选择所有记分项myscore分数不为空(即存在),且不为10的目标。[仅基岩版] @e[scores={foo=10,bar=1..5}]
— 选择所有记分项foo分数为10,且记分项bar分数为1到5之间(包含)的目标。
记分板标签[]
参见:命令/tag
[tag=<标签名>]
— 选择所有有标签“标签名”的目标。[tag=!<标签名>]
— 选择所有没有标签“标签名”的目标。[tag=]
— 选择所有没有标签的目标。[tag=!]
— 选择所有有标签的目标。
- 允许使用多个参数。被选择的实体必须满足所有的参数条件。
- 示例:
@e[tag=a,tag=b,tag=!c]
— 选择所有拥有标签a和b,但没有标签c的目标。@r[tag=a]
— 选择一个有标签a的随机玩家。
队伍名称[]
参见:命令/team
此特性为Java版独有。
[team=<某队伍>]
— 选择所有属于队伍“某队伍”的目标。[team=!<某队伍>]
— 选择所有不属队伍“某队伍”的目标。[team=]
— 选择所有不属于任何队伍的目标。[team=!]
— 选择所有属于任意队伍的目标。
- 示例:
@a[team=red]
— 选择所有属于red队伍的玩家。@e[team=red,team=blue]
是非法的,因为一个实体只能加入一个队伍。
实体名称[]
[name=<某名称>]
— 选择所有名字为“某名称”的目标。[name=!<某名称>]
— 选择所有名字不为“某名称”的目标。
- 这是一个字符串,包含空格时应当用双引号括起。不能是JSON文本。
- 示例:
@e[name=!Steve]
— 选择不叫“Steve”的目标。@e[name=""]
— 选择所有没有名字的实体(例如:箭矢、掉落方块、猪)。
实体类型[]
[type=<实体类型>]
— 选择所有特定的实体类型的目标。[type=!<实体类型>]
— 选择所有不是特定的实体类型的目标。
- 实体类型必须使用有效的实体ID或实体标签
[仅Java版]。如果实体ID的命名空间为 minecraft
则可以省略命名空间。在Java版中,实体ID或标签区分大小写。 - 当与
@r
一起使用时,原本用来选择玩家的命令也可以被用来选择其他实体。[仅基岩版]
- 示例:
族[]
主条目:族
此特性为基岩版独有。
[family=<族>]
— 选择属于指定的族的实体。[family=!<族>]
— 选择不属于指定的族的实体。
- 给定的实体的族可以是任何字符串,但不包括命名空间。这些实体的族在实体类型的族行为组件中定义,且单个实体可以属于多个族。
- 原版行为包使用的默认值包括:
- 更广泛的大型族(例如
mob
、inanimate
、monster
、undead
) - 更具体的小型族(例如
zombie
、skeleton
) - 单个生物的族(例如
wandering_trader
、enderman
、creeper
) - 与生成事件有挂钩的族(例如
farmer
、baby_turtle
)
- 更广泛的大型族(例如
- 示例:
谓词[]
此特性为Java版独有。
[predicate=<命名空间ID>]
— 选择所有匹配该谓词的目标。[predicate=!<命名空间ID>]
— 选定所有不匹配该谓词的目标。
- 示例:
@a[predicate=example:test_predicate]
— 选择所有匹配谓词example:test_predicate的玩家。@e[predicate=!minecraft-wiki:smart_entity]
— 选择所有不匹配谓词minecraft-wiki:smart_entity的实体。
垂直旋转角度[]
[x_rotation=<值>]
— 根据指定目标的垂直旋转角度过滤目标。[仅Java版] [rx=RX]
— 仅选择所有最大垂直旋转角度为RX的目标。[仅基岩版] [rxm=RXM]
— 仅选择所有最小垂直旋转角度为RXM的目标。[仅基岩版]
- 更具体地说,是旋转高度与地平线的夹角,以度为单位。垂直旋转值从-90(垂直向上)向上增加,之后增加到0(水平),最后增加到90(竖直向下)(因此垂直旋转值随着向下旋转而增加)。
- 在Java版中,此选择器支持范围。
- 示例:
- Java版
@e[x_rotation=0]
— 选择所有看向地平线的目标。@e[x_rotation=30..60]
— 选择所有看向地平线偏下30°至60°(包含)的目标。@e[x_rotation=45..]
— 选择所有看向地平线偏下45°及更低的目标。@e[x_rotation=..0]
— 选择所有看向地平线偏上的目标。
- 基岩版
@e[rxm=45]
— 选择所有看向地平线偏下45°及更低的目标。@e[rxm=-60,rx=60]
— 选择所有看向与地平线夹角在60°及以内的目标。
水平旋转角度[]
[y_rotation=<值>]
— 根据指定目标的水平旋转角度过滤目标。[仅Java版] [ry=RY]
— 仅选择最大水平旋转为RY的目标。[仅基岩版] [rym=RYM]
— 仅选择最小水平旋转为RYM的目标。[仅基岩版]
- 其角度以正南(或正Z轴方向)为基准顺时针旋转。水平旋转值从-180(面向正北)开始,到-90(面向正东),再到0(面向正南),再到90(面向正西),最后到180(再次面向正北)。
- 在Java版中,此选择器支持范围。
- 示例:
- Java版
@a[y_rotation=0]
— 选择所有看向正南的玩家。@a[y_rotation=45]
— 选择所有看向南偏西45°的玩家。@a[y_rotation=96]
— 选择所有看向西偏北6°的玩家。@a[y_rotation=-90..0]
— 选择所有看向正东和正南之间(包含)的玩家。@a[y_rotation=-90..90]
— 选择所有看向正东和正西之间(包含)的玩家,区域穿过正南。@a[y_rotation=0..]
— 选择所有不看向南方(包含)和东方之间的玩家。
- 基岩版
@a[rym=0,ry=90]
— 选择所有看向正西和正南之间(包含)的玩家。@a[rym=-135,ry=-135]
— 选择所有看向西偏北45°的玩家。@a[ry=0]
— 选择所有看向正南和正北之间(包含)的玩家,区域穿过正东。
实体的NBT标签[]
此特性为Java版独有。
[nbt=<NBT>]
— 选择具有指定NBT的所有目标。NBT结构以其命令定义编写。
- 示例:
@a[nbt={OnGround:1b}]
— 选择所有站在地上的玩家。@e[type=sheep,nbt={Color:0b}]
— 选择所有白色的绵羊。@e[type=item,nbt={Item:{id:"minecraft:slime_ball"}}]
— 选择所有黏液球物品实体。@e[nbt={Tags:["a","b"]}]
与@e[tag=a,tag=b]
的效果相同。后者更简单,且减少了CPU的负载。
- 注意:当匹配字符串内的命名空间ID时,不得省略其命名空间。
- 因此
@e[type=item,nbt={Item:{id:"slime_ball"}}]
找不到任何东西,因为 id字段始终包含一个已经被转换的命名空间ID字符串。
- 因此
物品[]
此特性为基岩版独有。
[hasitem={<参数1>=<值1>,<参数2>=<值2>,...}]
— 根据指定目标的物品栏过滤目标。[hasitem=[{<参数A>=<值A>,...},{<参数B>=<值B>,...}]]
— 选择所有物品栏满足项目A条件和项目B条件的目标。
- 根据指定目标的物品栏是否满足条件过滤目标。
hasitem
参数在一个目标选择器中不能重复使用,但可以在参数中指定多个条件项目。 hasitem
给定的值必须用{}
框起来,如果条件项目多余一个则必须用,
将各个项目隔开,并用[]
框起来。- 条件项目中可以重复使用相同的参数,但后来添加的参数会覆盖掉之前的,所以它只会使用最后一个参数中的值。
- 条件项目中所有可用参数:
item
data
quantity
- 可选,限制范围内的所有槽位中符合条件的物品的总和数量,此参数支持使用范围及不等式(=!)。如果未定义,则默认为
1..
。 - 当此参数的值为
0
,则选择所有没有符合条件的物品的目标。当此参数的值为0..
,则当前条件项目不做过滤。 - 物品栏中空气的数量始终是0个。
- 可选,限制范围内的所有槽位中符合条件的物品的总和数量,此参数支持使用范围及不等式(=!)。如果未定义,则默认为
location
- 可选,指定要检测的物品栏,此参数的值必须是一个有效的物品栏。如果未定义,则检测目标的所有物品栏。
- 即便指定目标没有指定的物品栏,当前条件项目仍然会对该目标进行过滤。这意味着如果
quantity
的值的范围包括0
,该目标将被当前条件项目选中。
slot
- 可选,使用时必须使用
location
参数,用于指定要检测的槽位范围,此参数支持使用范围及不等式(=!)。如果未定义则默认为slot=0..
。
- 可选,使用时必须使用
- 示例:
@e[hasitem={item=apple}]
— 选择所有拥有苹果的实体。@a[hasitem={item=stone,quantity=192,location=slot.hotbar,slot=0..2}]
— 选择所有工具栏前3格填满石头的玩家。@a[hasitem=[{item=diamond,quantity=3..},{item=stick,quantity=2..}]]
— 选择所有同时拥有至少3颗钻石和2根木棍的玩家。
经验等级[]
[level=<值>]
— 根据指定目标的经验等级过滤目标。这将自动过滤非玩家目标。[仅Java版] [l=L]
— 只选择所有经验等级低于L的目标(包含)。[仅基岩版] [lm=LM]
— 只选择所有经验等级高于LM的目标(包含)。[仅基岩版]
- 此选择器支持使用范围。
[仅Java版]
- 示例:
- Java版
@a[level=10]
— 选择所有10级的玩家。@a[level=10..12]
— 选择所有10级与12级之间(包含)的玩家。@a[level=5..]
— 选择所有至少为5级的玩家。@a[level=..15]
— 选择所有至多为15级的玩家。
- 基岩版
@a[lm=10,l=15]
— 选择所有10级与15级之间(包含)的玩家。
游戏模式[]
[gamemode=<游戏模式>]
— 选择所有处于指定游戏模式的目标。[仅Java版] [gamemode=!<游戏模式>]
— 选择所有不处于指定游戏模式的目标。[仅Java版] [m=M]
— 选择所有处于指定游戏模式的玩家。[仅基岩版] [m=!M]
— 选择所有不处于指定游戏模式的玩家。[仅基岩版]
- 游戏模式的值可以为
spectator
、adventure
、creative
、survival
和default
[仅基岩版]。 - 这将自动过滤非玩家目标。
- 在基岩版中,M可以为全称,也可以是数字(0=生存模式,1=创造模式,2=冒险模式)或缩写(s=生存模式,c=创造模式,a=冒险模式,d=默认模式)。
- 示例:
进度[]
此特性为Java版独有。
- 从Java版1.13开始,目标选择器支持
advancements
参数,取代/advancement test
。参数名称是进度的IDadvancements
后接一组用中括号包含来的键值对,其中键为进度或条件的名称,值为true或false或表示进度的各条件的键值对。
- 示例:
@a[advancements={story/form_obsidian=true}]
— 选择所有已达成进度“冰桶挑战”(minecraft:story/form_obsidian)的玩家。@a[advancements={story/form_obsidian=false}]
— 选择所有未达成进度“冰桶挑战”(minecraft:story/form_obsidian)的玩家。@a[advancements={story/obtain_armor={iron_helmet=true}}]
— 选择所有装备过铁头盔的玩家。选择时玩家不一定正在装备铁头盔,也不一定需要达成进度“整装上阵”(minecraft:story/obtain_armor)。@a[advancements={story/follow_ender_eye=true}]
与@a[advancements={story/follow_ender_eye={in_stronghold=true}}]
的效果相同。
权限[]
此特性为基岩版独有。
[haspermission={<权限>=<状态>,...}]
— 根据指定目标的权限(可通过/inputpermission
命令修改)过滤目标。这将自动过滤非玩家目标。
- 示例:
@a[haspermission={camera=enabled}]
— 选择已启用相机视角权限的玩家。@a[haspermission={movement=disabled}]
— 选择已禁用移动权限的玩家。@a[haspermission={camera=disabled,movement=enabled}]
— 选择已禁用相机视角权限且启用移动权限的玩家。
数量[]
- 当使用
@p
和@r
变量时,此参数默认为1。对它们使用limit
[仅Java版]或 c
[仅基岩版]参数时会增加选择最近或随机目标的数量。当使用 @a
或@e
变量时,此参数会限制目标数量。 - 当满足条件的目标少于指定的数量时,不影响命令的执行。
- 注意,数量参数与距离参数和体积尺寸参数不同,数量参数可以跨维度选择目标。
- 当输入的值为负值时,目标的顺序会被反转。举例来说,
@p[c=-3]
会回传3个最远的目标,而且,如果所有目标距离都一样远,@e[c=-3]
会选择3个刚加载/生成的目标。[仅基岩版]
[limit=<值>,sort=(nearest|furthest|random|arbitrary)]
— 选择指定数量的目标,并指定优先级。[仅Java版] sort=nearest
— 将目标由近到远排序。(@p
的默认排序方式)sort=furthest
— 将目标由远到近排序。sort=random
— 将目标随机排序。(@r
的默认排序方式)sort=arbitrary
— 将目标按生成时间由远到近排序。(@a
和@e
的默认排序方式)
- 示例:
玩家类型与单类型[]
玩家类型[]
某些命令参数需要玩家类型选择器,某些需要实体类型选择器,实体类型无其他限制,可以使用任何有效的选择器。
玩家类型选择器仅包括如下内容:
- 使用
type=player
的@e
- 使用
type=player
或不使用type
参数的@a
、@p
、@r
若命令参数需要,输入的却不是,在Java版中,将无法解析;在基岩版中,可以解析,但运行失败。
单类型[]
此特性为Java版独有。
某些命令参数需要单类型选择器,某些需要多类型选择器,多类型无其他限制,可以使用任何有效的选择器。
单类型选择器仅包括如下内容:
- 使用
limit=1
的@a
、@e
- 不使用
limit
参数的@s
- 使用
limit=1
或不使用limit
参数的@p
、@r
若命令参数需要,输入的却不是,将无法解析。
历史[]
Java版 | |||||
---|---|---|---|---|---|
1.4.2 | 12w32a | 加入了目标选择器。 | |||
1.8 | 14w02a | 加入了目标选择器@e 。 | |||
14w03a | 目标选择器加入了dx 、dy 和dz 参数。 | ||||
1.9 | 16w02a | 目标选择器参数m 接受游戏模式的全称及其缩写,如a 和adventure ,且可以将其反选,如@a[m=!a] 。 | |||
1.11 | 16w38a | 移除了隐式目标选择器参数(如@e[167,28,454,5] 现在必须写成@e[x=167,y=28,z=454,r=5] )。
| |||
无效的目标选择器(如@e[Type=creeper] 、@e[asdf=nonexistent] 和@e[malformed] )现在会产生错误,而不再被静默忽略。 | |||||
1.12 | 17w16b | 加入了目标选择器@s ,用于选择命令执行者。 | |||
1.13 | 17w45a | 在目标选择器中加入了nbt 。
| |||
对目标选择器参数进行了大幅度修改。 | |||||
1.15 | 19w38a | 加入了目标选择器参数predicate 。 | |||
携带版Alpha | |||||
0.16.0 | build 1 | 加入了命令功能以及目标选择器。 | |||
基岩版 | |||||
1.16.100 | 1.16.100.55 | 加入了目标选择器参数family 。 | |||
1.17.10 | 1.17.10.22 | 加入了目标选择器@initiator 。 | |||
1.18.30 | 1.18.20.21 | 加入了目标选择器参数hasitem 。 | |||
1.19.80 | 1.19.80.21 | 加入了目标选择器参数haspermission 。 |
参见[]
版本 | |||||||
---|---|---|---|---|---|---|---|
开发周期 |
| ||||||
技术 |
| ||||||
多人游戏 | |||||||
游戏订制 |
版本 |
| ||||||
---|---|---|---|---|---|---|---|
开发 |
| ||||||
技术性 | |||||||
多人游戏 | |||||||
特色功能 |
语言