getTokens/ja

Languages:  English  • 日本語

getTokens() Function

 Note: This function can only be used in a Trusted Macro

• Introduced in version 1.3b48

現在地図上の全てのトークン、あるいは指定した条件に適合する全てのトークンのIDを含んだリストを取得する。値の形式は『区切り』パラメーターに依存する。この関数はライブラリートークンのIDは返さない。 注：getTokens() が返すリストの並び順はトークンのZオーダーに準じており、最も低いZオーダーが返されるリストまたは配列の先頭になっている。

Usage

getTokens()
getTokens(delim)
getTokens(delim, conditions)

パラメーター

• delim - 返される文字列リストの値を区切るのに使われる区切り文字、初期値は","である。"json"が指定された場合は、文字列リストの代わりにJSON配列が返される。
• conditions - JSONオブジェクトで、トークンが満たすべきさまざまな条件を含む。全ての条件は任意である。
  • setStates - トークンが持つべき状態のJSON配列、または文字列としての単一の状態名。指定された状態のいずれかが真ではない値を含むトークンは、返されるリストから削除される。
  • unsetStates - トークンが持っていてはならない状態のJSON配列、または文字列としての単一の状態名。
  • npc - トークンがNPCである必要がある場合は真を指定し、そうでない場合は偽を指定する。
  • pc - トークンがPCである必要がある場合は真を指定し、そうでない場合は偽を指定する。
  • propertyType - トークン種別のJSON配列、または単一のトークン種別の文字列を指定。配列に含まれる種別のトークンのみが返される。
  • selected - トークンが選択されている必要がある場合は真を指定し、そうでない場合は偽を指定する。
  • impersonated - トークンが発言対象に設定されている必要がある場合は真を指定し、そうでない場合は偽を指定する。
  • current - トークンが現在トークンである必要がある場合は真を指定し、そうでない場合は偽を指定する。
  • owned - プレイヤーの名前を含むJSON配列。一覧されたプレイヤーのうち、1人以上が所有権を持つトークンが全て返される。または、以下のオプションの1つを含む文字列。
    • self - 現在のプレイヤーが所有しているトークン。
    • notself - 現在のプレイヤーが所有していないトークン。
    • others - 現在のプレイヤーが所有していない、任意のプレイヤーが所有しているトークン。
    • any - 任意のプレイヤーが所有しているトークン。
    • none - どのプレイヤーも所有していないトークン。
    • single - 1人のプレイヤーが所有するトークン。
    • multiple - 複数のプレイヤーが所有しているトークン。
    • byall - すべてのプレイヤーが所有しているトークン。
    • notbyall - すべてのプレイヤーが所有していないトークン。
  • visible - トークンが現在のクライアントの表示上に表示されているかどうか。真または偽を指定する。
    • visibleオプションが使用されると、TOKENレイヤー上にあり、クライアントの現在の地図表示内に表示されているトークンのみが返される。
    • これは、表示されていないマップ上の他のトークンが、特定のトークンに対して見えるかどうかをテストするものではない。canSeeToken()を参照。
    • GMは、現在のマップ表示内のすべてのトークンを見ることができる。プレイヤー（『プレイヤーとして表示』を含む）は、現在のマップ表示に表示されているトークンのみが返される。返されるトークンは、個別表示などのサーバー設定にも影響される。
  • layer - レイヤー名のJSON配列、または単一のレイヤー名の文字列。一覧されたレイヤーのいずれかにあるトークンのみが返される。デフォルトでは、トークン（Token）および秘匿（Hidden）レイヤー上のトークンが返される。
  • mapRef - トークンを取得する地図の名称。初期値は現在の地図。
  • range - 範囲の条件を持つJSONオブジェクトであり、全ての条件は省略可能。
    • token - 距離の測定の基準となるトークンのIDまたは名称。初期値は現在トークン。
      • 注: token パラメーターは、マクロリンクを呼び出す際、発言対象に設定していないのであれば、未指定または空文字にする事はできない。
    • distancePerCell - 『1マスあたりの距離』の係数を使用する場合は真を指定し、そうでない場合は偽を指定する。
    • from - トークンが基準から必要とする最小距離を指定する数値。
    • upto - トークンが基準から離れられる最大距離を指定する数値。
    • metric - 使用する距離数え方。指定されていない場合はユーザー設定の初期値が使用される。
  • area - 特定の範囲の情報を含むJSONオブジェクト。
    • token - エリアの中心に存在するトークンの名前またはIDを含む任意のフィールド。初期値では現在トークンが使用される。
    • offsets - 範囲を構成する個々のマスを指定するJSONオブジェクトのJSON配列。
      • x - token フィールドに対するセルの相対的な x 位置。マス目単位で計測される。
      • y - tokenフィールドに対するセルの相対的な y 位置。マス目単位で計測される。
  • light - 任意の照明を持つトークン（1）または光源を持たないトークン（0）を示す真偽値を指定。或いは、以下のいずれかの組み合わせで光の仕様を指定したJSONオブジェクト：
    • value - トークンが指定された照明を持っていなければならないことを示す真偽値。
    • name - 『キャンペーン設定』→『照明』タブで指定された照明の名前。
    • category - 『キャンペーン設定』→『照明』タブで指定された照明のカテゴリ。

range の設定において移動の数え方は、次の中の1つを使用できる：

• NO_GRID - マス目は無視され、トークンからの直線距離が返される。
• ONE_TWO_ONE - 最初の斜め移動はコスト1、2回目は2、以後繰り返し（正方形のマス目のみ）。
• ONE_ONE_ONE - 斜め移動のコストは1マス（正方形のマス目のみ）。
• MANHATTAN - 斜め移動のコストは2マス（正方形のマス目のみ）。
• NO_DIAGONALS - 斜め移動は許可されない（正方形のマス目のみ）。

Example

*次のコード使用して、現在の地図上にある全てのトークンのIDを出力する事ができる：

[h: ids = getTokens()]
[foreach(id, ids, "<br>"): id]

• 地図上の全レイヤー上にある全てのトークンを見つける：

[r:getTokens(",", json.set("{}", "layer", json.append("[]","TOKEN","HIDDEN","OBJECT","BACKGROUND")))]

• 選択したトークンから2マスもしくは2ヘックス以内の全てのトークンを探し出し、見つかったトークンを含んだJSON配列を返す：

[h: cond = '{ "range": {"upto":2, "distancePerCell":0, "token":"' +getSelected()+ '"}, "npc":1}']
[h: ids = getTokens("json", cond)]

• 上記の例を dead のトークンを取り除くように修正したもの：

[h: cond = '{ "range": {"upto":2, "distancePerCell":0, "token":"' +getSelected()+ '"}, "npc":1, "unsetStates":["Dead"] }']
[h: ids = getTokens("json", cond)]

• area のオプションを使用して、トークンの上下左右のマスにある死亡していない（Deadではない）トークンを得る：

[h: areaOffsets = '[ {x:1, y:0}, {x:0, y:1}, {x:-1, y:0}, {y:-1, x:0}]']
[h: area = json.set("{}", "offsets", areaOffsets)]
[h: cond = json.set("{}", "area", area, "npc", 1, "unsetState", "['Dead']")]
[h: ids = getTokens("json", cond)]

• 同じことが NO_DIAGONALS の計測方法をを用いた range オプションで実現できる：

[h: cond = '{ range: {upto:1, distancePerCell:0, metric:"NO_DIAGONALS"}, npc:1, unsetStates:["Dead"] }']
[h: ids = getTokens("json", cond)]

照明を持つトークンを得る単純な例。

[r: getTokens("json",'{"light":1}')]

物体レイヤーにある照明を持つトークンを得る。

[h: cond = json.set("", "layer",'["Object"]')]
[h: cond = json.set(cond, "light",'{"value":1}')]
[r: names = getTokens("json", cond)]

松明（torch）を持つトークン。

[h: cond = json.set("", "layer",'["Token"]')]
[h: cond = json.set(cond, "light",'{"value":1,"name":"Torch - 20","category":"D20"}')]
[r: names = getTokens("json", cond)]

Generic カテゴリーの照明を持つトークン。

[h: cond = '{ "light": {"value":1, "category":"Generic"}}']
[r: names = getTokens("json", cond)]

JSONオブジェクトや配列を手作業で作ることは良くない習慣と言えるだろう。そういったコードはバグが発生しやすい傾向にあるからだ。コードによってJSONオブジェクトを構築する事が適切なやり方である。

例：

[h: cond = '{ range: {upto:1, distancePerCell:0, metric:"NO_DIAGONALS"}, npc:1, unsetStates:["Dead"] }']

より良い作り方はこちら：

[h: cond = json.set("{}", "range", json.set("{}", "upto", 1, "distancePerCell", 0, "metric", "NO_DIAGONALS"), "npc", 1, "unsetStates", json.append("[]","Dead"))]

この2つの方法の大きな違いは、手作業で作った場合、間違ったコードを書いてしまった場合にもエラー報告が上がらず『動作している』ように見えてしまう。例えば '' や "" を使ってはいけない場所で使用したがために、条件の一部しか満たされていないということがよくある。

自動化された方法でミスをした場合は、エラーレポートが表示される可能性が高く、修正することが可能だ。もちろん、「range」の代わりに「ragne」のようなタイプミスがあってもエラーにはならない。

See Also

getTokenNames()

Version Changes

• 1.3b49 - json 区切りオプションを追加。
• 1.3b51 - conditions パラメーターを追加。
• 1.3b55 - metric オプションを conditions オプションの range オプションに追加。
• 1.3b77 - layer オプションを conditions に追加。
• 1.5.5 - propertyType オプシヨンを conditions に追加。
• 1.5.7 - light および mapName オプシヨンを conditions に追加。
• 1.5.8 - owned にさらなるオプションを追加。

Languages:  English  • 日本語