Library Token/ja: Difference between revisions
mNo edit summary |
m (Taustin moved page library Token/ja to Library Token/ja without leaving a redirect) |
||
(9 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
{{Languages|Library Token}}{{DISPLAYTITLE: | {{Languages|Library Token}}{{DISPLAYTITLE:ライブラリートークン|ライブラリートークン}}{{Translation}} | ||
<div style="color:gray">Introduced in MapTool version | =ライブラリートークン= | ||
__TOC__ | |||
<div style="color:gray">Introduced in MapTool version 1.3b46, the Library Token is a special token type that acts as a library of properties and trusted macros that may be accessed and called by other macros. </div> | |||
MapToolバージョン1.3b46で導入された、ライブラリートークンは他のマクロからアクセスし呼び出すことが出来る特性値と承認マクロを収蔵するライブラリーを持つ特殊なトークン種別である。 | |||
== | ==ライブラリートークンの命名== | ||
<div style="color:gray">All library tokens must have a name in the format "Lib:''name''", to indicate that they are to serve as a Library Token and not a "normal" token. Example library token names might be:</div> | <div style="color:gray">All library tokens must have a name in the format "Lib:''name''", to indicate that they are to serve as a Library Token and not a "normal" token. Example library token names might be:</div> | ||
ライブラリートークンの名前は必ず「Lib:''名前''」の書式であり、このトークンがライブラリートークンであり通常のトークンではないことを示している。ライブラリートークン名の例は次の通り: | |||
*Lib:test | *Lib:test | ||
Line 14: | Line 16: | ||
*Lib:gamemaster | *Lib:gamemaster | ||
== | ==ライブラリートークンを作成する== | ||
<div style="color:gray">To create a Library Token, do the following:</div> | <div style="color:gray">To create a Library Token, do the following:</div> | ||
ライブラリートークンを作成するには、次の手順になる: | |||
<div style="color:gray"> | <div style="color:gray"> | ||
Line 24: | Line 26: | ||
# Rename it with a name in the format '''Lib''':''name'' (''e.g.'', '''Lib:DnD''', '''Lib:GameRules''', etc.). | # Rename it with a name in the format '''Lib''':''name'' (''e.g.'', '''Lib:DnD''', '''Lib:GameRules''', etc.). | ||
# Right click on the token and make sure that '''Visible to Players''' is checked. | # Right click on the token and make sure that '''Visible to Players''' is checked. | ||
# Set the token type to NPC (upper right corner of the Token Configuration dialog). | # Set the token type to NPC (upper right corner of the Token Configuration dialog). | ||
</div> | </div> | ||
# | # キャンペーンのマップ上にトークンを配置する。この地図がプレイヤーに表示されている必要はない。 | ||
# 名前を'''Lib''':''name''の書式に変更する(例:'''Lib:DnD'''、'''Lib:GameRules'''など)。 | # 名前を'''Lib''':''name''の書式に変更する(例:'''Lib:DnD'''、'''Lib:GameRules'''など)。 | ||
# トークン上で右クリックし、'''プレイヤーに表示'''が有効になっていることを確認する。 | # トークン上で右クリックし、'''プレイヤーに表示'''が有効になっていることを確認する。 | ||
# | # トークン種別をNPCに設定する。(トークン設定ダイアログの右上) | ||
<div style="color:gray">After that, you have a Library Token. Note that you cannot have two library tokens with the same name in the same campaign (even if they're on different maps!). </div> | <div style="color:gray">After that, you have a Library Token. Note that you cannot have two library tokens with the same name in the same campaign (even if they're on different maps!). </div> | ||
以上でライブラリートークンの完成だ。同一キャンペーン内で、同じ名前持つライブラリートークンを複数持つことができないことを覚えておくように(それぞれが違うマップにあっても、だ!)。 | |||
<div style="color:gray">Once again, the requirements are:</div> | <div style="color:gray">Once again, the requirements are:</div> | ||
繰り返しになるが、必要条件を挙げておく: | |||
<div style="color:gray"> | <div style="color:gray"> | ||
* The library token must be visible to players (make sure Visible to Players is set in the right-click context menu). | * The library token must be visible to players (make sure Visible to Players is set in the right-click context menu). | ||
* The library token need not be on the "Token" layer (you can keep it on the "Hidden" layer to hide it from players, although "Visible to Players" must still be set to true). | |||
* The library token must have a name in the format "Lib:''name''" | * The library token must have a name in the format "Lib:''name''" | ||
* The library token must be present on ''only one'' map in the campaign file. | * The library token must be present on ''only one'' map in the campaign file. | ||
</div> | </div> | ||
* | * ライブラリートークンはプレイヤーに表示していなければならない(右クリックメニューの「プレイヤーに表示(Visible to Players)が有効になっていることを確認)。 | ||
* | * ライブラリートークンは「トークン・レイヤー」にある必要はない(『秘匿』レイヤーに置くことでプレイヤーから隠すことは可能だが、その場合でも『プレイヤーに表示』は有効にしておかなければならない)。 | ||
* | * ライブラリートークンは「Lib:''名前''」の書式でなければならない。 | ||
* ライブラリートークンはキャンペーン・ファイルに''ひとつだけ''存在することができる。 | |||
== | ==ライブラリートークンと承認マクロ== | ||
<div style="color:gray"> | ライブラリートークンは下記の条件を満たすことで[[Trusted Macro|承認マクロ]]の実行、あるいは承認マクロ関数として使用することが出来る: | ||
* ライブラリートークンが'''いずれのプレイヤーにも所有権がない'''、もしくは | |||
# | * ライブラリートークン上のマクロが、'''プレイヤーが編集できない'''場合。 | ||
ライブラリートークンがこれらの条件を1つでも満たさないのであれば、''承認マクロを実行することはできない''。これによりプレイヤーが望む''承認されない''マクロのための個人的なライブラリトークンをプレイヤーが作ることが出来るようになり、その一方で、プレイヤーに権限が与えられていないトークンやキャンペーン要素を変更したり操作したりすることを防ぐことにもなる。 | |||
==ライブラリートークンマクロ== | |||
<div style="color:gray">Library token macros are created and edited like macros on any token. Macros on a library token may be called using the [[Macros:Branching_and_Looping#MACRO_Option| [MACRO(): ]]] roll option. Since Library token macros are trusted, they may perform operations not available to regular tokens. | |||
</div> | </div> | ||
ライブラリートークン・マクロはトークンのマクロと同じように記述する。ライブラリートークンのマクロはロール・オプション:[[Macros:Branching_and_Looping/ja#MACRO_Option| [MACRO(): ]]]を使用することが多い。ライブラリートークンマクロは承認されるので、通常のトークンがなしえない操作を行うことができる。 | |||
==ライブラリートークン特性値== | |||
ライブラリートークンの特性値は {{func|setLibProperty}} と {{func|getLibProperty}} を使用して値の設定と読み出しが可能だ。 | |||
{{func|getLibProperty}} はキャンペーン特性値の初期値を返す事は無く、ライブラリトークンに値が設定されていない場合は空文字列を返す。これは想定していない初期値を使用することによる意図しない用法のエラーを防ぐことに役立つ。 | |||
===『libversion』特性値 === | |||
<div style="color:gray">The special 'libversion' property can be set on a library token to be output with <code>getInfo("client")</code>. The library token's name and the libversion will be a key/value pair in the nested "library tokens" object of the resulting {{func|getInfo}} JSON object. The libversion property value will be displayed 'as-is'; any macro code in libversion will be displayed instead of processed.</div> | |||
特殊な 'libversion' 特性値はライブラリトークンに設定でき、<code>getInfo("client")</code> で出力する事ができる。ライブラリトークンの名称と libversion はキーと値のペアとして、 {{func|getInfo}} が返すJSONオブジェクトの一部として入子状の "library tokens" オブジェクトとして得られる。この libversion 特性値の値は『そのまま』表示される; マクロコード上の libversion は処理されることなく表示される。 | |||
<div style="color:gray">To edit libversion, you can either add libversion to the Library Token's property list in the Campaign Preferences and then edit the token's properties directly, or set it via the chat panel or a macro using the {{func|setLibProperty}} function.</div> | |||
libversion を編集するには、キャンペーン設定のライブラリトークンの特性値一覧に libversion を追加し、ライブラリトークンの特性値を直接編集する、或いはチャット・パネルもしくはマクロにおいて {{func|setLibProperty}} 関数を使う。 | |||
<div style="color:gray">When creating and improving upon a library token as a 'plugin' others use in their games, updating libversion with new releases is good practice. You may consider using [https://semver.org/ Semantic Versioning] to help give version numbers meaning for your users.</div> | |||
ライブラリートークンを、ゲーム内で他から使用する『プラグイン』として作成し機能強化する場合、libversion も更新する事が良い習慣だろう。ほかのユーザーにとって解りやすいバージョン番号を決めるには [https://semver.org/lang/ja/ セマンティックバージョニング(意味付けされたバージョン付け)] を参考にすると良いだろう。 | |||
==ライブラリートークンを onCampaignLoad で起動する== | |||
<div style="color:gray">Most users will find it worthwhile to add an [[onCampaignLoad]] macro to your Lib token that will use {{func|defineFunction}} to make your Lib macros accessible like the built-in macro functions and recognized by the macro editor.</div> | |||
多くのユーザーは、[[onCampaignLoad]] マクロに、{{func|defineFunction}} を使い自分のライブラリーマクロを追加する事が便利である事に気付くだろう({{func|defineFunction}} はマクロを組み込みマクロ関数と同じように使う事ができるように、そしてマクロエディターで強調表示するために使用する)。 | |||
==ライブラリートークンのURI接続== | |||
<div style="color:gray">As of version 1.10.0 the properties and macros on Lib:Tokens can be accessed via a URI from within MapTool. URI access can be enabled for a Lib:Token from the token edit dialog.</div> | |||
バージョン1.10.0において、ライブラリートークン上の特性値とマクロは、MapTool 内で URI を通して使用することが出来る。ライブラリートークンのURIによる接続を有効にするには『トークン編集』ダイアログを使用する。 | |||
[[File:LibTokenURI.png|500px]] | |||
<div style="color:gray">Once this has been enabled you will be able to access the macros and properties on the Lib:Token with</div> | |||
これを有効にすると、下記の様にライブラリートークン上のマクロや特性値を参照する事ができるようになる | |||
< | * lib://''<トークン名称>''/macro/''<macro name>'' | ||
* lib://''<トークン名称>''/property/''<property name>'' | |||
= | <div style="color:gray">Where ''<token name>'' is the token after the lib: part, for example lib://myjs/macro/scripts/script1.js would point to the a macro named scripts/script1.js on the token lib:myjs. | ||
These URIs can be used in the following places. | |||
* script tags for including JavaScript in frame5/dialog5/overlay | |||
* link tags for including CSS in frame5/frame/dialog5/dialog/overlay | |||
* As an argument to the {{func|js.evalURI}} macro function. | |||
* As an argument to the {{func|html.dialog}} / {{func|html.dialog5}} macro functions. | |||
* As an argument to the {{func|html.frame}} / {{func|html.frame5}} macro functions. | |||
* As an argument to the {{func|html.overlay}} macro function. | |||
</div> | </div> | ||
''<トークン名称>''はトークン名称の lib: の後の部分である。つまり lib://myjs/macro/scripts/script1.js であれば、lib:myjs トークンの scripts/script1.js と言う名称のマクロを示している。 | |||
これらのURIは下記の場所で使用することが出来る。 | |||
* frame5/dialog5/overlay 内のJavaScriptを含む『script』タグ | |||
* frame5/frame/dialog5/dialog/overlay 内のCSSを含む『link』タグ | |||
* {{func|js.evalURI}} マクロ関数の引数。 | |||
* {{func|html.dialog}} / {{func|html.dialog5}} マクロ関数の引数。 | |||
* {{func|html.frame}} / {{func|html.frame5}} マクロ関数の引数。 | |||
* {{func|html.overlay}} マクロ関数の引数。 | |||
'''注記:''' | |||
<div style="color:gray">Since the WebView component does its own internal caching which cant be influenced by the usual methods in the JVM for turning off caching of certain URI a work around needed to be introduced. To ensure that JavaScript/css picks up the latest version the query string cachelib=false needs to be used and the code will do some finagling to ensure it turns into a URL that wont be cached for example </div> | |||
WebViewコンポーネントは、独自の内部キャッシュを使用しており、特定のURIのキャッシュを無効化するJVMの通常の方法では影響を受けないため、迂回する方法を導入する必要があった。JavaScript や CSS が最新版を確実に取得できるようにするには、クエリ文字列 cashelib=false を使用する必要があり、コード上でキャッシュしない事を確実にするには次のように調整する必要がある。 | |||
lib://Test/macro/test/test.js?cachelib=false | |||
==参考記事== | |||
* [[Token|MapTool Tokens]] | |||
* [[Token Types]] | |||
* [[Image_Token|Image Token]] | |||
* [[TokenTool Quickstart|TokenTool QuickStart Guide]] | |||
* [[Introduction_to_Tokens|Introduction to Tokens]] | |||
* {{func|getAllowsURIAccess}} | |||
* {{func|setAllowsURIAccess}} | |||
{{Languages|Library Token}} | {{Languages|Library Token}} | ||
[[Category:Token]] | [[Category:Token]] |
Latest revision as of 23:59, 9 May 2023
ライブラリートークン
MapToolバージョン1.3b46で導入された、ライブラリートークンは他のマクロからアクセスし呼び出すことが出来る特性値と承認マクロを収蔵するライブラリーを持つ特殊なトークン種別である。
ライブラリートークンの命名
ライブラリートークンの名前は必ず「Lib:名前」の書式であり、このトークンがライブラリートークンであり通常のトークンではないことを示している。ライブラリートークン名の例は次の通り:
- Lib:test
- Lib:combat
- Lib:gamemaster
ライブラリートークンを作成する
ライブラリートークンを作成するには、次の手順になる:
- Drag a new token on to one of the maps in your campaign.
- Rename it with a name in the format Lib:name (e.g., Lib:DnD, Lib:GameRules, etc.).
- Right click on the token and make sure that Visible to Players is checked.
- Set the token type to NPC (upper right corner of the Token Configuration dialog).
- キャンペーンのマップ上にトークンを配置する。この地図がプレイヤーに表示されている必要はない。
- 名前をLib:nameの書式に変更する(例:Lib:DnD、Lib:GameRulesなど)。
- トークン上で右クリックし、プレイヤーに表示が有効になっていることを確認する。
- トークン種別をNPCに設定する。(トークン設定ダイアログの右上)
以上でライブラリートークンの完成だ。同一キャンペーン内で、同じ名前持つライブラリートークンを複数持つことができないことを覚えておくように(それぞれが違うマップにあっても、だ!)。
繰り返しになるが、必要条件を挙げておく:
- The library token must be visible to players (make sure Visible to Players is set in the right-click context menu).
- The library token need not be on the "Token" layer (you can keep it on the "Hidden" layer to hide it from players, although "Visible to Players" must still be set to true).
- The library token must have a name in the format "Lib:name"
- The library token must be present on only one map in the campaign file.
- ライブラリートークンはプレイヤーに表示していなければならない(右クリックメニューの「プレイヤーに表示(Visible to Players)が有効になっていることを確認)。
- ライブラリートークンは「トークン・レイヤー」にある必要はない(『秘匿』レイヤーに置くことでプレイヤーから隠すことは可能だが、その場合でも『プレイヤーに表示』は有効にしておかなければならない)。
- ライブラリートークンは「Lib:名前」の書式でなければならない。
- ライブラリートークンはキャンペーン・ファイルにひとつだけ存在することができる。
ライブラリートークンと承認マクロ
ライブラリートークンは下記の条件を満たすことで承認マクロの実行、あるいは承認マクロ関数として使用することが出来る:
- ライブラリートークンがいずれのプレイヤーにも所有権がない、もしくは
- ライブラリートークン上のマクロが、プレイヤーが編集できない場合。
ライブラリートークンがこれらの条件を1つでも満たさないのであれば、承認マクロを実行することはできない。これによりプレイヤーが望む承認されないマクロのための個人的なライブラリトークンをプレイヤーが作ることが出来るようになり、その一方で、プレイヤーに権限が与えられていないトークンやキャンペーン要素を変更したり操作したりすることを防ぐことにもなる。
ライブラリートークンマクロ
ライブラリートークン・マクロはトークンのマクロと同じように記述する。ライブラリートークンのマクロはロール・オプション: [MACRO(): ]を使用することが多い。ライブラリートークンマクロは承認されるので、通常のトークンがなしえない操作を行うことができる。
ライブラリートークン特性値
ライブラリートークンの特性値は setLibProperty() と getLibProperty() を使用して値の設定と読み出しが可能だ。
getLibProperty() はキャンペーン特性値の初期値を返す事は無く、ライブラリトークンに値が設定されていない場合は空文字列を返す。これは想定していない初期値を使用することによる意図しない用法のエラーを防ぐことに役立つ。
『libversion』特性値
getInfo("client")
. The library token's name and the libversion will be a key/value pair in the nested "library tokens" object of the resulting getInfo() JSON object. The libversion property value will be displayed 'as-is'; any macro code in libversion will be displayed instead of processed.特殊な 'libversion' 特性値はライブラリトークンに設定でき、getInfo("client")
で出力する事ができる。ライブラリトークンの名称と libversion はキーと値のペアとして、 getInfo() が返すJSONオブジェクトの一部として入子状の "library tokens" オブジェクトとして得られる。この libversion 特性値の値は『そのまま』表示される; マクロコード上の libversion は処理されることなく表示される。
libversion を編集するには、キャンペーン設定のライブラリトークンの特性値一覧に libversion を追加し、ライブラリトークンの特性値を直接編集する、或いはチャット・パネルもしくはマクロにおいて setLibProperty() 関数を使う。
ライブラリートークンを、ゲーム内で他から使用する『プラグイン』として作成し機能強化する場合、libversion も更新する事が良い習慣だろう。ほかのユーザーにとって解りやすいバージョン番号を決めるには セマンティックバージョニング(意味付けされたバージョン付け) を参考にすると良いだろう。
ライブラリートークンを onCampaignLoad で起動する
多くのユーザーは、onCampaignLoad マクロに、defineFunction() を使い自分のライブラリーマクロを追加する事が便利である事に気付くだろう(defineFunction() はマクロを組み込みマクロ関数と同じように使う事ができるように、そしてマクロエディターで強調表示するために使用する)。
ライブラリートークンのURI接続
バージョン1.10.0において、ライブラリートークン上の特性値とマクロは、MapTool 内で URI を通して使用することが出来る。ライブラリートークンのURIによる接続を有効にするには『トークン編集』ダイアログを使用する。
これを有効にすると、下記の様にライブラリートークン上のマクロや特性値を参照する事ができるようになる
- lib://<トークン名称>/macro/<macro name>
- lib://<トークン名称>/property/<property name>
These URIs can be used in the following places.
- script tags for including JavaScript in frame5/dialog5/overlay
- link tags for including CSS in frame5/frame/dialog5/dialog/overlay
- As an argument to the js.evalURI() macro function.
- As an argument to the html.dialog() / html.dialog5() macro functions.
- As an argument to the html.frame() / html.frame5() macro functions.
- As an argument to the html.overlay() macro function.
<トークン名称>はトークン名称の lib: の後の部分である。つまり lib://myjs/macro/scripts/script1.js であれば、lib:myjs トークンの scripts/script1.js と言う名称のマクロを示している。 これらのURIは下記の場所で使用することが出来る。
- frame5/dialog5/overlay 内のJavaScriptを含む『script』タグ
- frame5/frame/dialog5/dialog/overlay 内のCSSを含む『link』タグ
- js.evalURI() マクロ関数の引数。
- html.dialog() / html.dialog5() マクロ関数の引数。
- html.frame() / html.frame5() マクロ関数の引数。
- html.overlay() マクロ関数の引数。
注記:
WebViewコンポーネントは、独自の内部キャッシュを使用しており、特定のURIのキャッシュを無効化するJVMの通常の方法では影響を受けないため、迂回する方法を導入する必要があった。JavaScript や CSS が最新版を確実に取得できるようにするには、クエリ文字列 cashelib=false を使用する必要があり、コード上でキャッシュしない事を確実にするには次のように調整する必要がある。
lib://Test/macro/test/test.js?cachelib=false
参考記事
- MapTool Tokens
- Token Types
- Image Token
- TokenTool QuickStart Guide
- Introduction to Tokens
- getAllowsURIAccess()
- setAllowsURIAccess()