Introduction to Macro Writing/ja
BEGINNER
THIS IS A BEGINNER ARTICLE
マクロとは何か?
トークン・マクロのページでも言ったとおり、単にマクロと言えば、MapTool上での処理を自動化するための手段のことである。マクロは基本的にはスクリプトであり、パーザーがこれを読み取って、解釈し、正しいパーツが正しいやり方で処理されていることを保障する（例えば、ある二つの数値が与えられたとき、そのテキストをチャット・ウィンドウに出力するのではなく、両者を足し合わせる処理をマクロ・コマンドとして実行する、というように）。
当初、MapToolの中ではマクロの扱いはささやかなものだったが、今ではマクロ記述言語は非常に充実した命令や関数のセットを持っており、考えうるほとんどの処理をこなせるようになった。
知っているべきこと
マクロは、MapToolの機能や能力ををより深く―そして複雑なやり方で―利用していく手がかりとなるものだ。このガイドはまったくの初心者でもついてこられるように噛み砕いた内容になるよう心がけてはいるが、あらかじめ理解していることを前提としていることもいくつかある：
- I assume you've read the Introduction to Mapping, so you are familiar with the MapTool interface, and how to create maps, save campaign files, and put tokens on maps.
- I assume you've also read the Introduction to Tokens, so you have a basic idea how to manipulate tokens, look at their properties, and so forth.
- Finally, because macros are usually intimately connected to token properties, I assume that you have read and followed the steps in the Introduction to Properties, and created a new campaign file based on the Sample RPG ruleset created to help new users learn about MapTool. If you haven't read that guide, please do - it will help some of the examples below make a lot more sense!
- Introduction to Tokensに目を通していること。トークンの操作について基本的な概念を理解していて、そのプロパティを見るなどができる。
- マクロはトークンのプロパティと密接に関わっているのが普通なので、最終的にはIntroduction to Propertiesを読み、そのステップを実行して、Sample RPG rulesetに基づいて新しいキャンペーン・ファイルを作成している必要がある。この文書は、新しいユーザーがMapToolについて学ぶために作られたものだ。もしまだそのガイドを読んでいないのなら、ぜひそうして欲しい。そうすれば、この下で挙げている例をかなり理解しやすくなるはずだ。
このガイドの用語規約
述語や用語については一貫したものになるよう努力する。このガイドでは以下の用語を用いる：
- Macro refers to a collection of commands that are grouped together to automate a task
- Macro command will refer to any particular individual command or function you use inside a macro
- Macro language will mean the whole collection of commands, functions, and operations you can use whenever you write macros. You can see a huge array of functions at the List of Macro Functions.
- マクロとは、ある処理を自動化するための一連のコマンドを一つにまとめたものことを指す。
- マクロ・コマンドとは、一つのマクロの中に含まれていて、マクロの内部で使われている一つ一つのコマンドや関数のことを指す。
- マクロ言語とは、マクロを書くときに使うコマンド、関数、処理全体のことを指す。膨大な関数のリストがList of Macro Functionsにある。
なお、一つのマクロが別のマクロを起動することも可能だが（これを他のマクロを「呼び出す」という）、このガイドでは、マクロ・パネル上にあるボタンをクリックして起動し、そのマクロが実行されているトークンにだけ影響を及ぼすものについてのみ話すことにする。
なぜマクロを使うの？
MapToolを使うからと言って、マクロを使わなければならないなどということは全くない。MapToolの最大の目的は、友達とマップを共有し、ゲームをプレイすること（グループ内でマップを共有する方法については、Introduction to MappingとIntroduction to Game Hostingを読んで欲しい）であり、Maptoolはそれに必要な全てを提供している。マップ、トークン、そしてあなたがプレイしているキャラクターとして、あるいはプレイヤーとしてそれぞれ話し、ダイスを振り、その役割をこなすことのできるチャットツールもある。
ただ、マクロについてちょっと勉強して見る気になってくれれば、MapToolには他にもたくさんできることがある。たとえば、自動的に1d20を振ってそれに修正値を加えてくれるボタンが欲しければ、それをやるマクロを作ることもできる。攻撃を受けたあとで自分のヒットポイントの値を変えたければ、それをやるマクロを書ける。このチュートリアルではその方法を説明する。
「マクロ」と呼ばれているものはどこにあるの？
マクロはMapTool上のインターフェイスのさまざまな部分や、その内部のオブジェクトと関連している。どうやらマクロが「住み着く」ことのできる場所には、三つの種類があるようだ：
トークン・マクロ
第一の、そして最もよくある住処は、tokenだ。トークン・マクロはそのマクロが生成されたトークンと関連しており、そのトークンと一緒について回る。
トークン・マクロにアクセスできるのは、そのトークンの直接的なオーナーだけだ。つまり、オーナーでないトークンのマクロのボタンはクリック（それどころか見ることも！）できない。
キャンペーン・マクロ
キャンペーン・マクロは、キャンペーン上の特定のマクロと関連しているのではなく、そのキャンペーン全体と関連している。このマクロはトークン・マクロとあらゆる面で同じように機能するが、以下の点で違っている：
- You don't have to select a token to see the macros
- Anyone can access them and run them
- トークンを選択しなくても見ることができる
- 誰でもアクセスでき、実行できる
キャンペーン・マクロはＧＭとプレイヤーが共通の機能を扱うのにとても便利だ。実際、共通のタスクをキャンペーン・マクロとして設定しておけば、複数作る必要はないのだ（そのマクロを必要とする全てのトークンにそのマクロを書いてやる必要はない）。
グローバル・マクロ
グローバル・マクロはトークンやキャンペーンとは結びついていない。その代わりに、あなたのMapToolと結びついている。このマクロは、ゲームに接続している他の人たちからは見えないのだ。
この場所は、他の人には見られたくないタスクのためのマクロを置くのに便利だ。例えば、あなたが他のプレイヤーたちに見せたいと思ったときにだけ見せるような情報や、NPCにだけ実行させて、PCたちには実行できないようにしたいタスクなどだ。
マクロ・パネル
マクロとその居場所について、特にマクロの「ボタン」について話してきたが、疑問に思っている人もいるだろう。そのボタンはどこにあるのか、と。マクロ・ボタンは、MapTool内に表示されている４枚のマクロ・パネルの上にある。マクロ・パネルが見当たらない場合には、Windowsメニューに行き、以下の４つのウィンドウがチェックされていることを確かめて欲しい。
- Selection
- Impersonated
- Campaign
- Global
もしまだ表示されていなかったのなら、MapTool内に現れたのが見えるはずだ。右にあるスクリーンショットを見ると、グローバル・パネルにいろいろなボタンが載っているのが見えるだろう。それぞれのボタンがマクロを実行する。新しいマクロを作ると、新しいボタンが現れる。
注意 グローバル・パネルにはあなたのコンピューターと、あなたのMapToolにのみ存在するマクロが含まれている。先ほどのグローバル・パネルのスクリーンショットにあるのは私のグローバル・マクロだ。あなたのパネルにはないって？……そのうちできると思うよ。
セレクション・パネルとインパーソネイテッド・パネル
トークン・マクロを直接扱うのが、セレクションとインパーソネイテッドの二つのパネルだ。
セレクションパネルには、あなたが今選択している全てのトークン上にあるマクロのボタンが表示されている（トークンを選択するには、それをマウスでクリックすればいい）。
インパーソネイテッドパネルは何かに扮しているトークンのマクロのボタンを表示している。トークンをインパーソネイトするということは、「そのトークンのペルソナを想定する」ということだ。チャットをしていると、そのトークンが喋っているかのようにテキストが表示される、というように。あるトークンをインパーソネイトし、それから次、というようにして、今自分が誰に向いているのかを確認することもできる。
キャンペーン・パネル
このパネルには、そのキャンペーン用に設定されている全てのマクロが表示される。このマクロは誰でも見ることができるということを忘れないように。
グローバル・パネル
このパネルには、あなたが設定しているグローバル・マクロが表示されている。このマクロはあなたにしか見えない点に注意。
マクロを書く
マクロは三つの手順を踏んで作成する（ただし、それぞれの手順はさらに細かく分けられることもある）。
1. そのマクロを置きたいパネル（二つのトークン・パネルのどちらか、キャンペーン・パネル、グローバル・パネル）の上で右クリックし、Add New Macroを選ぶ。(new)というラベルの灰色のボタンが現れる。
2. そのボタンを右クリックし、Editを選ぶ。
3. マクロのコードを書き込み、名前を付け、それからOKを押す。ほら、マクロができた！
……ちょっと待て。「マクロのコード」って何だ？
先ほども言ったように、この三つのステップの中にはさらに「膨大な」ディティール、ステップ、コツ、ワザ、勝利、敗北、欲求不満、それに時には「やったー！」とか「歯軋りギリギリギリ」などが含まれることがある。そんなわけで、ここで一旦立ち止まって、簡単なマクロをステップ・バイ・ステップで見ていくことにしよう。高度なマクロがどういうものか見てみたいと言う人向けには、このwiki上にチュートリアルやハウトゥがたくさん載せてある。ただし今は、シンプルな、でも役に立つマクロの書き方をやっていこう。
イニシアティブを振る
最もシンプルなマクロは単なるテキストで、それをチャット・ウィンドウに出力するだけのものだ。実際のところ、テキストを含むマクロ（すなわち全てのマクロは）チャットウィンドウにコマンド文字列を送るもので、チャットウィンドウがその文字列を読み取って解釈している。ほとんどのプログラム言語はお約束の"Hello World!"プログラムからスタートしているから、このガイドではその定石に従わない。その代わりに、もうちょっとRPGっぽいことをしよう：あの恐ろしい「イニシアティブを振れ！」メッセージだ。
Roll for Initiative!
1. キャンペーン・パネルを選択する
2. 右クリックして、Add New Macroを選択する
3. 新しいマクロのボタンを右クリックし、それからEditをクリックする
4. Labelフィールドの中に"イニシアティブを振れ!"と入力する
5. GroupとSort Prefixのフィールドは空にしておく
6. Commandフィールドの中に以下のように入力する
イニシアティブを振れ!
7. OKをクリックする。
8. ボタンの姿が変わっているのが見えるはず。イニシアティブを振れ!という表示になっていて、それをクリックすると、驚くなかれ、なんとチャット・ウィンドウに「イニシアティブを振れ！」と表示されるではないか。
これはマクロ作成の中でも最も基本的なものだ。つまり、マクロにテキストを入れておくと、パーザーがそのテキストを読み取り、あなたがボタンを押したときにチャット・ウィンドウに送り込む、というものだ。
もう少し面白いことをやってみる
GMに「イニシアティブを振れ」と言われるのは恐ろしいが、マクロとして面白いかというと、決してそんなことはない。たぶんあなたはこう考えているだろう。「チャットでそう書けばいいんじゃないの？」と。そして事実、その質問に対する答えは「十中八九そうするだろうね」だ。だからもうちょっと手ごたえがあって、MapToolを使うべき理由と関係していることをやろう（だいたい私たちがこうしているのはプログラムを書きたいからではなく、ゲームをプレイしたいからだ）。これからこのマクロにいくつかのマクロ・コマンドを付け加えて、プレーンテキスト以外のものを入れる。マクロ・コマンドは特殊な命令であり、それを読み込んだパーザーに対して、チャット・ウィンドウにテキストを出力する以外のことをするように指図する。例えばダイスを振ったりとか、値を計算したりといった具合に。
マクロ・コマンドは必ず大カッコか（例えば、[macro command] ）、中カッコで（{macro command}）くくっておかなければならない。こうすることでパーザーはコマンドが来たことを検知できる。そうしておかないと、コマンドを他のテキストと同じものだと思って、そのままチャット・ウィンドウに表示してしまう。
ダイスを振ってみる
これは、いくつかのダイスを振って、自動的にその出目を合計してからチャット・ウィンドウに表示するという、シンプルなマクロだ。
1. 新しいマクロを作り（好きな場所に作っていい。トークン、キャンペーン・パネル、グローバル・パネルのどの上ででも）、編集ダイアログを開く（覚えてるかな。(new)というラベルのボタンの上で右クリックするんだ）
2. Labelフィールドに名前を入れる。"攻撃ロール"とか"ダイスロール"とか。
My attack roll is [1d20+7]!
3. Commandエリアの中に、次のように入力する：
私の攻撃ロールは [1d20+7]!
Chris: My attack roll is 8!
4. OKをクリックする。ステップ2でつけた名前がボタンについているのが見えるはずだ。これをクリックすると、こんな感じにチャット・ウィンドウに表示されるはずだ。
Chris: 私の攻撃ロールは 8!
MapTool がマクロの中身を読み、[1d20+7]の所まで来ると、こういう風に理解する：
- Roll a 20-sided die (or, in reality, choose a random number between 1 and 20), and
- Add 7 to that result, and
- Display the results in the chat window, inserted into the text in the right place
- 20面ダイスを振り（実際には、1から20までの値をランダムに選ぶ)
- その出目に7を足し
- その結果をテキスト内の適切な場所に挿入して、チャット・ウィンドウに表示する。
8という数字の背景が灰色になっていることに気づくだろう。その上にマウスポインタを持ってくると、"tooltip"がポップアップして、その値がどうやって得られたのかを表示してくれる。今回の場合、私は1d20で1の目を出したわけだ（ぎゃあ！クリティカル・ファンブルじゃないか！）。このtooltipが表示されない場合、MapTool Preferences#Chatの設定を確認して欲しい。特にUse ToolTips for Inline Rollsのところを。
また、おそらく"Chris"という名前も表示されていないはずだ。あなたが"Chris"という名前でない限りはね。チャット出力のこの部分は、誰がその文字列を「言った」のかを表している。トークンから出たものなら、面白くもない"Chris"なんて文字じゃなくて、そのトークンの画像と名前が表示される。
数字だけでは面白くない
マクロ・コマンドは数字と文字とを組み合わせることができる。つまり、MapToolのマクロ言語を使えば、文字列を操作できるということだ（ちなみに文字列というのは英数字の並びのことだ）。例えば、攻撃のダイスを振るときに、その攻撃対象の名前を入力して、チャット・ウィンドウに表示させることもできるということだ。
My attack roll against [target] is [1d20+7]!
あなたがやるべきなのは、攻撃ロール・マクロを次のように編集することだ：
私の [target] に対する攻撃ロールは [1d20+7]!
このマクロを実行すると、突然目の前にウィンドウが現れて、"Value for target"を入力しろと言ってくる。いったい何が起きたんだろうか？
Maptoolがこのマクロを読んでいるときに、[target]とだけ書いてあるマクロ・コマンドを見つけたんだ。MapToolは、マクロ・コマンドの中にあって引用符で囲まれていない文字列を変数名だと解釈する（変数の値は変化するかも知れない）。
さらにMapToolは、このマクロの中にはこのtargetの値が何と等しいのかが書いていないことにも気づく。プログラム言語の世界では、こういう状況のことを未定義変数という（要は、その変数と等しいものが何かを宣言していないということだ）。MapToolはこのtargetがどんな値をとるべきかを知る手段がないので、質問する！ あなたがこのポップアップ・ウィンドウに名前、数字、あるいは他の何かを入力すると、MapToolはその情報を拾って、target変数の値に割り付け、そしてマクロを終える。
Chris: My attack roll against Nasty Orcses is 23!
さっそくボックスの中に"Nasty Orcses"と入力して（引用符は入れなくていい）、OKをクリックしてみよう。チャット・ウィンドウにこんな風に表示されているはずだ：
Chris: 私の Nasty Orcses に対する攻撃ロールは 23!
ここでも、あなたがこのマクロの中に書き込んだテキストとマクロ・コマンドをパーザーが解釈し、マクロ・コマンドの部分（大カッコで囲まれている箇所だ）を、適切な情報で置き換えている。
マクロ内で変数を使う
target in the example above) in a macro, but we haven't gone into the process too deeply yet. However, variables, and their use, is really the core of macro writing, so it would be remiss of me to leave it go.これまでに変数を使ったマクロの例（先ほどのtargetなどのような）をいくつか見てきたが、その処理についてはまだ深入りしてこなかった。だが、変数とその使い方は、マクロ作成の本当の核心部分なので、これを解説しないで済ませてしまえば、怠慢と言われても仕方ないだろう。
変数とは何か？
プログラミングに慣れている人ならとっくに知っているはずのことだが、新しく足を踏み入れたばかりの人のために説明すると、マクロ言語における変数を簡単に言うと：
- A variable is a value that might change (i.e., vary) based on a token property, a calculation, or another macro command
- 変数とは、トークンのプロパティ、計算結果、他のマクロ・コマンドなどによって変化する（さまざまな値をとる）ことのある数のことである
変数の値は変化することがあるので、それについて話すためには、名前をつける必要がある（これを変数の宣言と言う。「この変数は存在するんだ！」と宣言するわけだ）。それから、その変数がその時点でとっている値を使うために、その名前をマクロ・コマンドに書いておく。MapToolはその名前をその時点での適切な値に置き換える。
こういう風に考えて欲しい。例えば、あるダイスロールが１から２０までの値をとりうるのなら、ダイスを振る必要があるときに、そこに必ず１９を入れればいいというわけにはいかない。それが１９以外の２、７、などの値でも同じだ。だからそうする代わりに、「ダイスロールの結果がどうであれ、その出目をここに入れろ」と書きたいということになる。
- Note: that doesn't mean that MapTool will substitute the correct value for your needs; it means it will substitute the value corresponding to that variable at that time. So if your program has a mistake in it, the value might end up being wrong - but MapTool doesn't understand "wrong," it just understand "this is what it says right now."
- 注意:ただし、これは必ずしもMapToolがあなたにとって正しい値に置き換えてくれるということではない。ただ、その時点でその変数と結びついた値に置き換えられるだけだ。もしあなたの書いたプログラムに間違いがあったなら、変数は正しい値をとらないだろう。しかし、MapToolにはその値が「間違っている」ことが分からない。単に「今はそういう値なんだ」と思うだけだ。
変数への代入
[h:myHP = 30]
変数に値を与えることを、その変数に値を「代入する」と呼ぶ。MapToolでは、この「代入演算子」は等号（=）だ。少々洒落すぎているように見えるかもしれないが、この等号を使って、特定の変数に特定の値を代入したことをMapToolに伝えることができる。以下は変数代入の例だ。
[h:myHP = 30]
myHP exists, and then assign it the value 30. That is variable assignment at its root - some variable equals some value. おそらくもう気が付いていると思うが、ここではmyHPという名前の変数が存在することを宣言しており、それからその変数に30という値を代入している。これが変数への代入の基本的な考え方だ。つまり、何らかの変数イコール何らかの値ということだ。
以前に、target の名前を入力した例を覚えていると思う。値を代入しなくても変数として使える例だ。これを行う場合、つまりある変数が存在することは宣言するが、その変数に値を代入しない場合、MapTool（や、実行されているマクロ）はその変数の値を尋ねてくる。ここで理解しておくべきなのは、マクロが動作を完了するには、変数に値が代入される必要があるが、その値を最初から代入しておく必要はない、ということだ。ユーザーに入力を求めることにしてもいい。
変数に値をセットしたり、その値を変えることのできる唯一の手段が代入だ。変数の値をその場で変更することはできない。ある変数の値を変更するために関数を利用するのであれば、その関数が返した値は、既存の変数か新規の関数に代入しなければならない。
いつ代入するのか
The hit does [damage] [damageType] damage, leaving you with [remainingHP] hit points!
MapToolは一つのマクロの中にあるマクロ・コマンドを先頭からひとつずつ実行していく。従って、ポップアップ・ウィンドウを出してユーザーからの入力を要求したいのでもない限り、変数の値はマクロを実行する前に代入しておかなければならない。例えば、以下のマクロ・コマンドでは：
その攻撃は [damage]点の [damageType] ダメージを与え, あなたの残りヒットポイントは [remainingHP] 点になった!
damage, damageType, and remainingHP, you'll want to make sure to give them a value before you get to that line. Maybe something like:[h:damage = 1d6+4] [h:damageType = "fire"] [h:remainingHP = 30 - damage] The hit does [damage] [damageType] damage, leaving you with [remainingHP] hit points!
damage、damageType、remainingHPといった変数の値をユーザーに入力させたいのでないのなら、そこよりも前の行で値を与えておく必要がある。たぶんこんな風に：
[h:damage = 1d6+4] [h:damageType = "fire"] [h:remainingHP = 30 - damage] その攻撃は [damage]点の [damageType] ダメージを与え, あなたの残りヒットポイントは [remainingHP] 点になった!
damage, the value "fire" to the variable damageType, and the value of the operation 30 - damage to the variable remainingHP. ご覧の通り、ここでは三つの変数について、攻撃が命中してその変数が使われる前に代入を行っている。damageには1d6+4、damageTypeには"fire"、そしてremainingHPには30 - damageという計算の結果を与えている。
damage is used when we assign a value to remainingHP - so variables can be used to set and manipulate other variables. 注意してみると、ある変数に代入する値に別の変数を使っていることが分かるだろう。変数remainingHPの値を決めるときにdamage の値が使われている。つまり、変数は他の変数にセットされる値を決めたり、操作するために使うことができる。
変数の命名規則
- No spaces: variable names can't have spaces in them, so you can't use the variable
Hit Points- it has to beHitPoints. - Special Variables: there are several "special variables" that MapTool has reserved - which means you can't use them for other purposes than what MapTool already reserves them for. You can usually tell a special variable because it has a period it's name, like
roll.countormacro.args. We'll get into those in another guide, but for now, just know that you can't create a variable with the same name as any of the variables on the Special Variables page.
変数の名前をつけるには、以下の二つの規則を守らなければならない：
- スペース禁止： 変数名はスペースを含んではならない。従って、
Hit Pointsという変数名は使えない。使うならHitPointsとすること。 - 特殊な変数名： MapToolがあらかじめ予約している"特殊な変数名"がある。特殊変数の名前には、
roll.countやmacro.argsというように、たいていピリオドがついているのですぐに見分けがつく。これについては別のガイドで詳しく説明するが、とりあえず今は、Special Variablesにあるものと同じ名前の変数は作れないと覚えて欲しい。
ゲームのレベルを上げてみる
これまでに挙げてきた例は、マクロの使い方の中でもとても基礎的なものだ。ボタンをクリックするとチャット・ウィンドウにテキストを表示するとか、マクロ内で簡単なダイス振りを行うとか、マクロの動作に必要な入力をユーザーに求めるといったものだ。
さて、それではステップアップと行こう。フォーマット・オプションや、トークンのプロパティの変更、それに繰り返し処理（同じ処理を何度も繰り返すこと）と分岐処理（ある条件や状況に応じて異なる処理をすること）の基本を見てみるとしよう。
フォーマット・オプション
マクロの出力は（チャットの出力と同じように）簡単なHTMLタグや、MapToolに組み込まれているいくつかのオプションを使ってフォーマットすることができる。まずはHTMLについてざっと見てから、Display Roll Optionsをいくつか見てみよう。
展開ロール
MapTool 1.3.b54 では、ダイスロールや計算結果の出力フォーマットのデフォルトは、単に合計値や最終的な値のみを出力するだけになっている。つまり1d20+7を振ると、チャット・ウィンドウには最終的な値と、（その上にマウスポインタを持ってくると）計算式を見せるtooltipだけが表示される。
もし必要なら、Roll Formatting のオプションを指定して、Maptoolに対して計算過程を全て表示するよう指示することもできる。これを特に展開ロールという。
My attack roll against [target] is [e:1d20+7]!
フォーマット・オプションとは、ダイスを振った結果をどう扱うのかをMapToolに指示するためのものだと考えてみて欲しい。展開した形式で出力させたければ、攻撃ロール・マクロを以下のように修正すればいい：
私の [target] に対する攻撃ロールは [e:1d20+7]!
My attack roll against Nasty Orcses is « 1d20+7 = 1 + 7 = 8 »
それからこのマクロを実行すると、チャット・ウィンドウにこんな感じで表示されるはずだ：
私の Nasty Orcses に対する攻撃ロールは « 1d20+7 = 1 + 7 = 8 »
結果ロール
My attack roll against [target] is [r:1d20+7]!
ところで、ロールの過程を他の人に知られたくない場合にはどうしたらいいだろうか？ 今のところは、どちらのオプションを使っても、全員にロールの結果が見えてしまう。これを行うには、結果ロールオプションを使えばいい。マクロの内容を以下のように編集する：
私の [target] に対する攻撃ロールは [r:1d20+7]!
My attack roll against Nasty Orcses is 11!
出力結果はこういう風になる：
私の Nasty Orcses に対する攻撃ロールは 11!
My attack roll against [target] is [r:1d20+7]!
なお、11という数字には背景色がついておらず、その上にマウスポインタを持っていってもtooltipが出てこない点に注意。結果ロールのオプションは特殊なフォーマットを全て削除し、単純なプレーンテキストのみを出力させる。"Nasty Orcses"のハイライトも消したければ、以下のようにすればいい：
私の [r:target] に対する攻撃ロールは [r:1d20+7]!
そうすれば、targetの名前にも特殊なハイライトは付かない。
秘密ロール
[h:myHP = 30]
[h:Bloodied = myHP / 2]
My bloodied value is [Bloodied].
時には、自分のマクロの出力内容を他の人に見られたくない場合がある。マクロにはあるテキストだけ表示させて、バックグラウンドで計算をさせ、その全てが分かってしまわないようにする、などだ。こうした場合、上の例にある"r:"や"e:"を"h:"に置き換えればいい。こんな具合に：
[h:myHP = 30]
[h:Bloodied = myHP / 2]
私の流血度は [Bloodied]です
- Setting the value of the variable myHP to 30, but telling MapTool to hide this calculation
- Setting the value of the variable Bloodied to the value of myHP divided by 2, but telling MapTool to hide this calculation too
- Displaying some text, and inserting the value of Bloodied in at the end of the text output.
上の例は秘密ロールが役に立つとても簡単な例を挙げてみたものだ。このマクロの中では以下のことをやっている：
- 変数myHPに30を入れるが、MapToolにはこれを表示させないようにする。
- 変数Bloodiedに変数myHPを２で割った値を入れるが、この計算も表示しないようにする。
- 変数Bloodiedの値に置き換えてテキスト出力する
If you run this macro, the output will look like:
My bloodied value is 15
このマクロを実行すると、その出力はこういう風になるはずだ：
[h:myHP = 30]
[h:Bloodied = myHP / 2]
私の流血度は 15 です
30 15 My bloodied value is 15
もし、秘密ロールのオプションを使わないなら、表示はこういう風になるはずだ：
30 15 私の流血度は 15です
余計な数値が２つ表示されているが、これはテキストを出力するよりも前の行で行われている計算によるものだ。表示させたくないなら、隠せばいい。便利だね。
HTMLフォーマット
I make an attack roll!<br>
<b>Target</b>: [r:target]<br>
<b>Attack</b>: [1d20+7]<br>
<b>Damage</b>: [1d8+5]
MapToolのマクロでは基本的なHTMLタグを使ったフォーマットにも対応している。例えば、標的の名前、攻撃ロール、ダメージ用のロール結果をそれぞれ別にして三行で表示したいのであれば、例の攻撃ロール・マクロをこんな風に編集すればいい：
攻撃ロールをするよ！<br>
<b>標的</b>: [r:target]<br>
<b>攻撃</b>: [1d20+7]<br>
<b>ダメージ</b>: [1d8+5]
I make an attack roll!
Target: Nasty Orcses
Attack: 15
Damage: 7
このマクロを実行すると、出力はこういう風になる：
I make an attack roll!
標的: Nasty Orcses
攻撃: 15
ダメージ: 7
とても単純なフォーマットだ。必要なら、テーブルにもできるし、背景色を変えたり、文字サイズを変えたりもできる。たくさんのオプションが使えるんだ。
NOTE: If you're handy with HTML, be aware that MapTool supports HTML 3.2 - so things like the <br> tag should not be closed - it's <br>, not <br/>. Additionally, MapTool supports a subset of CSS 1 in the form of in-line styles, and also style sheets in certain instances. More information on the supported CSS tags can be found at Supported CSS Styles.
注意： あなたがHTMLを上手く使いこなせるのであれば、MapToolでサポートしているのは HTML 3.2 だということに注意して欲しい。つまり、<br>タグは閉じないということだ。<br/>ではなく、<br>と書く。さらに、CSS 1 のインラインstyleといくつかのスタイルシート・インスタンスに対応している。対応しているCSSタグについての情報はSupported CSS Stylesを参照して欲しい。
トークン・プロパティを使ってみる
- Make one macro that many people or characters can use
- Minimize how much typing we have to do!
ここまで私たちが操作してきた変数は、あらかじめ値が代入されているか、実行時にMapToolが問い合わせをしてくるようなものだった。標的、攻撃、ダメージのロール結果を三行で出すようにしたフォーマット型攻撃マクロも作った。だが、変数の値をマクロの中にじかに書いていたり、必要になるたびにユーザーが入力しなければならなかった。だが、RPGのキャラクターはみんな同じものではないので、どうにかしてこれを自動化する方法を考えなければならない。そこでこうすることにする：
- マクロを複数の人やキャラクターに使えるものにする
- 入力の手間を最低限に減らす！
Introduction to Tokensの中でも話したとおり、全てのトークンにはそれぞれの「キャラクターシート」のようなものがあり、それをトークンのプロパティとして持っている。このプロパティはマクロから参照できる。つまり、例えば「1d20を振ってそのキャラクターのDexterityと足した結果を出す」マクロを書くことができるということだ。これがどれだけ便利かは分かってもらえると思う。
プロパティをセットしてみる
当然のことだが、トークン・プロパティが上手く機能するためには、まず最初に設定をしなければならない。あらかじめIntroduction to Propertiesを読んで、MapTool RPGSample Ruleset用のキャンペーン・ファイルを作っておくといいだろう。
最初のステップは、MTRPG.cmpgn（もしくは、あなたが以前にセーブしたファイル名）ファイルを開いて、（もしまだマップ上にトークンがないのなら、）マップ上にトークンをドラッグしてくることだ。何のことだか分からないというのであれば、Introduction to Mappingを読んで、マップの作成と、その上にトークンを置く方法について調べて欲しい。さて、それでは以下のステップに従う：
1. トークンをダブルクリックして、Edit Tokenダイアログを開く
2. Propertiesタグを開く
3. そこにはスプレッドシート形式の表があって、そのトークンのプロパティのうち、直接編集できるもののリストが載っているはずだ（トークンのプロパティには、他にもマクロでだけ編集できるものがあるが、今はそのことは心配しなくていい）。（もしあなたがIntroduction to Propertiesで設定したMTRPG.cmpgnを使っているのなら）そこには以下のものが並んでいるはずだ：
*Strength:1
*Dexterity:1
*Intelligence:1
*Endurance:1
*HitPoints(HP):{Endurance * 6}
*Armor(AR)
*Movement(MV):{Dexterity}
4. Strength の隣にあるセルをクリックする。カーソルが現れて、セルに入力できるようになる。このセルの中に値を入れると、そのトークンのStrengthの値になる。私は6を入れることにする。
5. Dexterity、Intelligence、Enduranceについても同じようにステップ4を繰り返す。数字は好きに決めていい（私は順に3、2、6と入れることにする）。HitPointsとMovementは自動的に計算されることに注意。
6. OKをクリックする。これでトークンのプロパティを手作業で編集したことになる。トークンをダブルクリックして再びプロパティを表示してみると、あなたが入れた値が記憶されていることが分かる。
さらに、そのトークンの上にマウスポインタを持ってくると、地図の右下に小さなポップアップが表示されて、その中にはあなたが入力したプロパティが出るはずだ。このポップアップはStatsheetと呼ばれるもので、トークンのプロパティを手早く調べることができる。これはそのトークンの「キャラクターシート」をさっと参照するのに便利だ。
マクロ内部でトークン・プロパティを参照する
さて、トークン・プロパティの設定もしたので、マクロからそれを利用してみよう。最初のマクロとして、1d20を振った後、それに7を足すのではなく、そのトークンのStrengthを足すことにしよう。
1. あなたの攻撃ロール・マクロを開く
2. 左下の隅にあるApply to Selected Tokensのチェックボックスをチェックしておく（そうでないと、どのトークンのStrengthを使っていいのか分からないからね）
I make an attack roll!<br>
<b>Target</b>: [r:target]<br>
<b>Attack</b>: [1d20+Strength]<br>
<b>Damage</b>: [1d8+5]
3. マクロを以下のように編集する：
攻撃ロールをするぞ！<br>
<b>標的</b>: [r:target]<br>
<b>攻撃</b>: [1d20+Strength]<br>
<b>ダメージ</b>: [1d8+5]
7を"Stregth"という単語で置き換えたのが分かるだろう。このStrengthは引用符で囲まれていないので、MapToolにはこれが変数であるということが理解でき、current token（つまり現在選択しているトークンのことだ）の中のStrengthという名前の変数を探してくれる。もし見つからなかったら（あるいはそのプロパティが一度も設定されていなければ）、MapToolは入力を要求してくるだろう（前にtargetの入力を求めてきたときのようにね）。もしその変数が見つかったら、マクロをを実行するときに、そのトークンのStrengthの値を入れてくれる。
I make an attack roll!
Target: Nasty Orcses
Attack: 27
Damage: 6
4. トークンを選択してから、マクロのボタンをクリックして実行する。こういう具合に出力されるはずだ：
攻撃ロールをするぞ！
標的: Nasty Orcses
攻撃: 27
ダメージ: 6
マウスポインタをロールの結果の上に持ってくると、tooltipは« 1d20 + Strength = 17 + 10 »という表示になって、マクロがStrengthの値を取り出していることが分かる点に注意して欲しい。
マクロを使ってトークンのプロパティを変更する
トークンのプロパティはマクロを使って変更することもできる。例えば、敵の攻撃がキャラクターに命中した後で、そのトークンのヒットポイントを減らしたいと考えてみる。トークンを手で編集してそのHPプロパティの値を変えることもできる。だが、HPの値からダメージの値を引いてやるマクロを作ることもできる。以下はそのやり方だ：
1. Campaignパネルの上に新しいマクロを作る
2. Labelフィールドに"Damage"と入力する
Aarrgh! I'm hit! I have [HitPoints = HitPoints - damage] hit points left.
3. Commandフィールドに、以下のように入力する：
ぎゃーす！ やられた！ 俺のヒットポイントはもう [HitPoints = HitPoints - damage] よ
4. Apply to Selected Tokensのチェックボックスをチェックする（左下の隅にある）
Aarrgh! I'm hit! I have 23 hit points left
5. OKをクリックする。このマクロを実行すると、damageの値を入力するよう要求される。私は7と入れた。そうするとこういう出力が得られるはずだ：
ぎゃーす！ やられた！ 俺のヒットポイントはもう 23 よ
そして、このトークンをダブルクリックすると、そのプロパティHPの値が23になっていることが分かる。マクロはこんな風に動作している：
- Prompt the user for a value for damage (in this example, I entered 7)
- Retrieve the value of HitPoints from the token (in this example, the value is 30, because it is equal to Endurance * 6)
- Subtract the value of damage from the value of HitPoints (30 - 7, resulting in 23)
- Set the value of HitPoints (originally 30) to the newly calculated total (23)
- Output the text and the new value of HitPoints to chat
- ユーザーにdamageの値を入力させる（この例では、私は7を入れた）
- トークンのHitPoints値を取り出す（この例では30になっているが、これはEndurance*6 で求められているからだ）
- damageの値をHitPointsの値から引く （30-7で、23になる）
- トークンのHitPointsプロパティを、元の値(30)から計算後の新しい値(23)に書き換える
- テキストとHitPointsの新しい値をチャット・ウィンドウに表示する
文字列の連結
マクロを作成するときに必須となるのは、文字列、つまり英数字の連結したもの、を組み立てる能力だ。組み立てられた文字列には操作が行われたり、チャット・ウィンドウに送り込まれたりする。マクロを作る際には、変化しない（マクロ内に「埋め込まれている」テキスト）文字列や、変化する文字列（別の言い方をすると、変数の値となっているテキスト）を使うことが頻繁にあるだろう。文字列の組み立て作業のことをしばしば「連結」と呼ぶが、これは単に「より短い文字列から長い文字列を作りだす」という意味でしかない。
マクロでこれを行うには二つの方法がある。マクロ・コマンドの外で行うものと、マクロ・コマンドの中で行う者だ。
コマンドの外で連結する
マクロは基本的に以下のように動作する：
- The parser reads through the whole macro, and separates the macro commands from the plain text
- The parser diverts those macro commands to the appropriate places to be processed (so, numbers are added up, dice are rolled, etc.)
- The processed commands are sent back to the parser, which substitutes the results of those commands in the place where each command was.
- The whole mess - plain text, and the results of the commands (now sitting in place of the actual commands) is sent to the chat window.
- パーザーがマクロ全体を読み込み、プレーンテキストとマクロ・コマンドとを切り分ける
- パーザーはそれぞれのマクロ・コマンドを適切な処理を行うべき場所に分岐させる（その先で、数値を合計したり、ダイスを振ったりする）
- 処理されたコマンドはパーザーへと送り返され、それぞれのマクロ・コマンドをその結果で置き換える
- プレーンテキストとコマンドの結果（もともとのコマンドの位置に置かれている）は一緒くたにされて、チャット・ウィンドウに送り込まれる
Attack: [1d20]
つまり、一つのマクロの中で、コマンドの結果とテキストとをいっしょに表示させたいのなら（例えば、"攻撃:"という単語の後に1d20の結果を表示するとか）、最も簡単な方法は、テキスト上の適切な位置にマクロを置けばいい。こんな具合に：
攻撃: [1d20]
[1d20] to be processed, and when it gets that result back, plug it in in place of the command, and send it off to chat. The result will be something like "Attack: 17." パーザーはこれ全体を読み込んで、コマンド[1d20]を実行させ、その結果を受け取って、コマンドのあった位置に突っ込んでから、チャットへ送り込む。結果はだいたい「攻撃: 17」みたいな感じになる。
これはテキストをチャットに送り込むときの最も真っ正直なやり方だ。つまり、表示したい変数をテキスト上の表示したい位置に置く。するとそれがチャット・ウィンドウに表示される。
コマンドの中で連結する
とは言え、大カッコの内側で文字列を使わなければならないこともある。こうした場合、文字列の置き方が少し違ってくる。まず、大カッコの中では、文字列として扱われたいものはダブルクォートかシングルクォートで括らなければならない。そうしておかないと、MapToolはそれぞれの単語が変数なのだと思ってしまう。例えばこうだ：
Correct String
[string = "This is a string"]
Incorrect String
[string = This is a string]
正しい文字列
[string = "これは文字列です"]
誤った文字列
[string = これは文字列です]
覚えておこう。カッコの外側ではクォート不要。内側なら？ クォート必須！。
では、文字列を動的に作りたい場合にはどうしたらいいだろうか？ つまり、文字列の一部は「埋め込み」で、別の一部は入力内容に基づいて作りたいといった場合は、どうしたらいいのか？ ユーザーが何を言うかは分からないので、ユーザーが入力する部分の文字列を予め作っておくことはできない。これは、ユーザーの入力と埋め込み文字列とを連結することで可能だ。これを行うには、プラス(+）の符号を使う。これを文字列どうしに対して使うと、文字列を連結して一つの長い文字列にしてくれる。
例を挙げよう： ユーザーに技能の名前を入れて欲しいとする。そしてその技能名の文字列を、予め埋め込まれている文字列と組み合わせて、別の変数に入れる。それはこんな風に実現できるだろう：
[h:existingString = "The skill name you entered is "] [h:concatString = existingString+skill+"."] [r:concatString]
[h:existingString = "あなたが入力した技能名は "] [h:concatString = existingString+skill+"."] [r:concatString]
ここで何が行われているかというと、こうなっている；
- Line 1 sets the "hardcoded" portion of the output
- Line 2 sets the concatenated string -
concatStringto equal the value ofexistingStringplus the value ofskill(which MapTool will prompt for). However, in this case, since MapTool knows thatexistingStringis a string, it will not try to add them mathematically, but just append the value ofskillafter the value ofexistingString. To be grammatically correct, we concatenate another little string on the end, this time, the period. Remember - strings inside square brackets need to be in quotes (but variable names, of course, do not!) - Line 3 displays the final value of
concatString, afterskillhas been appended to it. The output will look something like:
- １行目では出力文字列のうち、「埋め込み」部分をセットしている
- 2行目では連結された文字列を変数にセットしている。
concatStringにexistingStringとskill（ここでMapToolは入力を求めてくる）の値をプラスしたものを代入する。しかしこの場合、MapToolはexistingStringが文字列だと知っているので、数字として加算するのではなく、existingString値の後にskillの値をくっつける。文法的に正しくするために、この文字列の最後に短い文字列を付け加える。今回はピリオドだ。注意して欲しいのは、大カッコの内側にある文字列はクォートで囲まなければならない、というところだ（ただしそれが変数なら話は別だ。囲んじゃだめだよ！）。 - 3行目では、
skillが連結された後の、concatStringの最終的な値を表示する。表示内容はこんな風になるはずだ：
The skill name you entered is Archery.
あなたが入力した技能名は Archery.
これはとてもシンプルな例だが、文字列連結の基本を解説したものだ。つまり、プラス符号を使って文字列同士を「加える」ということだ。
ここから先はどこへ行こうか？
このガイドでは、MapToolのマクロ言語のポテンシャルのほんの一部に軽く触れただけだ。しかし、ここに上げられている基本的な技法を使うだけでも、使いやすくて便利で、ゲームをもっと簡単に楽しく遊べるようなマクロを作り上げることができる。今後のガイドでは、高度なマクロ・コマンドや技法を紹介する予定だ。