ターゲットセレクタ
Scenamatica ターゲットセレクタについて説明しています。
概要
Scenamatica ターゲットセレクタは, エンティティやプレイヤを指定するための簡単な構文の記法です。 Minecraft のターゲットセレクタ を拡張したもので, Scenamatica による独自エンジンで解釈されます。
Minecraft ターゲットセレクタとは？
Minecraft ターゲットセレクタは, コマンドの実行者が, その対象となるエンティティ・プレイヤを選択する際に, より複雑な条件を指定するために使用されます。
アットマーク（@）のあとに母集団を指定し, その後に細かな条件を 角括弧（[]） で括って指定します。
例：
@e[type=minecraft:cow,distance=..10] ~ ~ ~
@a[tag=foo] Hello, world!
これが必要な理由
通常の Minecraft ターゲットセレクタを用いたエンティティの参照は, 通常 Bukkit API を用いてアクセスします。 しかし, Bukkit API は削除されたエンティティや, ワールドでロードされていないエンティティへのアクセスを提供しておらず, Scenamatica の一部のアクションやコンテキストのエンティティ での使用時に不都合が生じます。
そのために, Scenamatica は独自のエンティティ参照システムを導入してこれを解決するとともに, 一部の機能を拡張することによって より柔軟なエンティティの指定を可能にしています。
基本的な構文
通常の Minecraft ターゲットセレクタと同様に, @母集団の種類[引数] で指定します。
また, @母集団の種類 および [引数] は省略可能です。
引数は キー=値 の KV 形式で指定します。
詳しくは次章：セレクタの引数を参照してください。
各メタ文字間は任意の空白文字を含められます。
空白文字に該当する文字は, 半角スペースまたは \t （タブ文字）です。
母集団の種類
母集団には以下のいづれかを指定します。
@e: すべてのエンティティ@a: すべてのプレイヤ@p: （主役から）最も近いプレイヤ@r: ランダムなプレイヤ@s: アクションの主役となるプレイヤ
アクションの主役では, プレイヤに関するアクションにおいては, そのプレイヤを指します。
ほかのアクションにおいても, その主役を指す場合があります。
それらにおける主役については, 各アクションのドキュメントを参照してください。
引数の構文
セレクタの引数は, [キー1=値1, キー2=値2...] の形式で指定し, それぞれを , で区切ります。
それぞれメタ文字以外の任意の文字列を指定できます。
母集団の種類を省略した場合は, [ および ] を省略できます。
同じ階層に重複したキーを持つ引数の値は, 暗黙的にそのキーのリスト値の要素として扱われます。
これにより, @e[tag=foo,tag=bar] というセレクタは, @e[tag={foo,bar}] と同じ意味になります。
これは AND 検索（すべての条件を満たすこと）として解釈されます。
文字列値
文字列は, 任意の文字の並びです。基本的には " で囲んで表現できます。
省略した場合は, メタ文字以外の任意の文字列を指定できます。
" 自体を含めたい場合は, \" とエスケープします。
あいまい文字列
あいまい検索を行うために, 対象の文字列を正規表現で指定でき, これらの文字列を「あいまい文字列」と呼びます。
正規表現で指定する場合はマップで指定し, regex というキーを指定します。
例：
[foo={regex="bar.*"}]
上記の例は, foo の値が bar で始まる文字列を指定します。
数値
数値は任意の整数, 小数, 指数で表現できます。
例：
[foo=1]
[foo=1.0]
[foo=1e3]
範囲値
あいまい検索を行うために, 対象の数値を範囲で指定できます。
範囲で指定する場合は, 最小値と最大値を .. で連結して指定します。
また 主キー_min および 主キー_max という形式でも指定できますし,
さらに 主キー={min=最小値,max=最大値} という形式も有効です。
これらも最小値および最大値どちらかの省略が可能です。
例（fooの値について）：
[foo=最小値..]: 最小値以上の数値[foo=..最大値]: 最大値以下の数値[foo=最小値..最大値]: 最小値以上, 最大値以下の数値[foo_min=最小値,foo_max=最大値]: 最小値以上, 最大値以下の数値[foo={min=最小値,max=最大値}]: 最小値以上, 最大値以下の数値
真偽値
真偽値は, true または false で表現します。
さらに, YAML のように on または off, yes または no でも表現できます。
例：
[foo=true]
[foo=on]
[foo=yes]
[foo=false]
[foo=off]
[foo=no]
リスト
リストは, 各要素は , で区切り, 要素全体を { および } で囲んで表現します。
要素には任意の値を指定できます。
同じ階層に重複したキーを持つ引数の値は, 暗黙的にそのキーのリスト値の要素として扱われます。
これにより, @e[tag=foo,tag=bar] というセレクタは, @e[tag={foo,bar}] と同じ意味になります。
これは AND 検索（すべての条件を満たすこと）として解釈されます。
例：
[foo={bar,baz}]
[foo={1,2,3}]
[foo=1, foo=2, foo=3]
マップ
マップは, リストと同様に要素全体を { および } で囲んで表現します。
キーと値は = で区切り, 各要素は , で区切ります。
値には上記の任意の値を指定できます。
例：
[foo={bar=baz}]
[foo={1=2,3=4}]
値の否定
以下のように ! を値の先頭に付けると, その値を否定します。
[foo=!bar]
[foo=!1..5]
[foo={!bar}]
メタ文字の一覧
メタ文字は, セレクタの構文を構成する文字です。以下の文字はメタ文字として予約されているため使用できません。
使用する必要がある場合は文字列全体を " で囲うか, " についてはさらに \ でエスケープしてください。
": 文字列の開始・終了[: 引数の開始]: 引数の終了=: 引数のキーと値の区切り!: 引数の値の否定,: 引数の要素, リストの要素, マップの要素の区切り{: リストおよびマップの開始}: リストおよびマップの終了\: エスケープ文字
有効な引数の一覧
advancements
- 特別：この引数は, 母集団にプレイヤを指定した場合のみ有効です。
| キー | 型 | 説明 |
|---|---|---|
advancements | Map<String, Boolean | Map<String, Boolean>> | エンティティの進捗です。 |
進捗は次の２つの形式で指定できます。
advancements={<名前空間付きキー>=<進捗達成の真偽値>}
プレイヤが指定した進捗を達成しているかどうかを指定します。advancements={<名前空間付きキー>={<達成条件>=<真偽値>}}プレイヤが, 指定した進捗の, 指定した達成条件を満たしているかどうかを指定します。
distance(r)
エンティティとの距離を指定します。
- 特別：この引数は,
distanceとrの両方で指定できます。 - 特別：この引数の子は, マップに囲まれている必要はありません。
例として,@e[distance={dx=0,y=10,z=0}]と@e[dx=0,dy=0,dz=10]は同じ意味になります。 - 特別：この引数は, 範囲値 を直接指定できます。
例として,@e[distance=..10]と@e[distance={max=10}]は同じ意味になります。
| キー | 型 | 説明 |
|---|---|---|
distance | 倍精度浮動小数点数 | エンティティとの距離です。 |
dx | 倍精度浮動小数点数 | X 軸方向の距離です。 |
dy | 倍精度浮動小数点数 | Y 軸方向の距離です。 |
dz | 倍精度浮動小数点数 | Z 軸方向の距離です。 |
gamemode (m)
プレイヤのゲームモードを指定します。
- 特別：この引数は,
gamemodeとmの両方で指定できます。 - 特別：この引数は, 母集団にプレイヤを指定した場合のみ有効です。
| キー | 型 | 説明 |
|---|---|---|
gamemode | GameMode |[object Object] | プレイヤのゲームモードです。 |
level(l)
エンティティのレベルを指定します。
- 特別：この引数は,
levelとlの両方で指定できます。 - 特別：この引数は, 母集団にプレイヤを指定した場合のみ有効です。
| キー | 型 | 説明 |
|---|---|---|
level | 整数値 (32bit) | エンティティのレベルです。 |
location(loc)
エンティティの位置を指定します。
- 特別：この引数は,
locationとlocの両方で指定できます。 - 特別：この引数の子は, マップに囲まれている必要はありません。
例として,@e[loc={x=0,y=0,z=0}]と@e[x=0,y=0,z=0]は同じ意味になります。
| キー | 型 | 説明 |
|---|---|---|
x | 倍精度浮動小数点数 | X 座標です。 |
y | 倍精度浮動小数点数 | Y 座標です。 |
z | 倍精度浮動小数点数 | Z 座標です。 |
yaw | y_rotation | ry | 単精度浮動小数点数 | Y 軸回転です。 |
pitch | x_rotation | rx | 単精度浮動小数点数 | X 軸回転です。 |
world | NamespacedKey | ワールドです。 |
指定例
[location={x=0,y=0,z=0,yaw=0,pitch=0,world=minecraft:overworld}]
[loc={x=0,y=0,z=0,yaw=0,pitch=0,world=minecraft:overworld}]
[x=1..5,y=1..5,z=1..5,yaw=0..,pitch=..0,world=minecraft:overworld]
[x={min=1,max=5},y={min=1,max=5},z={min=1,max=5},yaw={min=0},pitch={max=0},world=minecraft:overworld]
name
エンティティの名前を指定します。
| キー | 型 | 説明 |
|---|---|---|
name | 文字列 | エンティティの名前です。 |
指定例
[name=foo]
[name={name=foo}]
[name={regex="foo.*"}]
scores
エンティティのスコアを指定します。
| キー | 型 | 説明 |
|---|---|---|
scores | Map<String, RangedNumber> | エンティティのスコアです。 |
tag(tags)
エンティティのタグを指定します。
- 特別：この引数は,
tagとtagsの両方で指定できます。
| キー | 型 | 説明 |
|---|---|---|
tag | [object Object] | [object Object][] | エンティティのタグです。 |
team
エンティティのチームを指定します。
| キー | 型 | 説明 |
|---|---|---|
team | 文字列 | エンティティのチームです。 |
空文字列を指定すると, チームに所属していないエンティティのみを選択します。
これも反転して使用できます。
例：
[team=]
[team=!]
type
エンティティの種類を指定します。
| キー | 型 | 説明 |
|---|---|---|
type | EntityType | エンティティの種類です。 |
セレクタのバッカス・ナウア記法
この構文をより機械的に理解するために, 拡張バッカス・ナウア記法で示します。
<selector> ::= <selector-type> | <selector-type> "[" <selector-arguments> "]"
| <selector-arguments> | "[" <selector-arguments> "]"
<selector-type> ::='@e' | '@a' | '@p' | '@r' | '@s'
<selector-arguments> ::= [<selector-argument> ("," <selector-argument>)*]
<selector-argument> ::= <argument-key> "=" "!"? <argument-value>
<argument-key> ::= <string>
<argument-value> ::= <string> | <number> | <ranged-number> | <boolean> | <list> | <map> | <null>
<ranged-number> ::= <number> | <number> ".." | <number> ".." <number> | ".." <number>
<boolean> ::= "true" | "false" | "on" | "off" | "yes" | "no"
<list> ::= "{" [<argument-value> ("," <argument-value>)*] "}"
<map> ::= "[" [<selector-argument> ("," <selector-argument>)*] "]"
<char> ::= any non metacharacter | "\" metacharacter
<string> ::= '"' <char>* '"' | <char>+
<number> ::= ('+' | '-')? ((<any-digit>)+ | (<any-digit>)+ '.' (<any-digit>)+)
<null> ::= null
<meta-char> ::= '"' | "[" | "]" | "=" | "!" | "," | "{" | "}"