Scripting for MystiTool (1.3.0.)

MystiTool のためのスクリプト作成について
by Mystical Cookie

最終更新: 2008年3月31日
現在のバージョン: MystiTool HUD 1.3.0
訳注：事実上1.0.23版と内容は変わりません。

もくじ:
- Introduction （はじめに）
- Example Scripts（スクリプトのサンプル）
- Menu System（メニューシステム）
- Backup System（バックアップシステム）
- Voice Commands（ボイスコマンド/チャットコマンド）
- Linked Messages（リンクメッセージ）
- On Attach（装着時）
- Sleep Mode（スリープモード）
- Suspending Your Scripts（オリジナルスクリプトをスリープさせる）
- Color Conversion（カラー値変換）
- Patch & Plugins Introduction（パッチとプラグイン機能の紹介）
- Patch & Plugins How To（パッチとプラグインの扱い方）


==========
Introduction （はじめに）
==========
こんにちは！ このノートカードでは、オリジナルのスクリプトを書き、 MystiTool に新しい機能を追加するための手助けをします。最初に少しばかりお話しておきたいことがあります。

1. Mystical Cookie は追加機能やプラグイン、パッチのサポートはいたしません。
2. MystiTool のためのスクリプト作成について、 Mystical Cookie に直接問い合わせることはお控えください。将来的には変わるかもしれませんが、今のところそういったことに割く時間がないのです :)
3. 他の MystiTool ユーザーと話すことができる "MystiTool Users" グループにご参加ください :)
4. MystiToolは標準的なスクリプトの通信とは違った方法をとっていますが、
今後変わるかもしれません。

MystiToolは可能な限りラグを発生させないように作られていますが、機能を犠牲にしてまで軽さを追求しているわけではありません。つまり、できるだけあなたにも美しく、ラグを起こさないようなスクリプトを書いていただきたいのです :)


============
Example Scripts（スクリプトのサンプル）
============
HUD の中に、"MystiTool Example Script 1.0" というスクリプトが入っています。

また、サンプル用のパッチ・プラグイン配布システムが MystiTool HUD の中にあります。HUD 内の "Example Patch Installer" というスクリプトを探し、 "Patches & Plugins" （パッチとプラグイン） の項以下をお読みください。


===========
Menu System（メニューシステム）
===========
プラグインによってメインの HUD のメニューにボタンを追加したり、外したりできます。追加のプラグインメニューは自動的にメインメニューの3ページ以降に現れます。

llMessageLinked(LINK_ROOT, 1983745561, "888888 plugin menu_add Button Text Here", "");
llMessageLinked(LINK_ROOT, 1983745561, "888888 plugin menu_del Button Text Here", "");

プラグインメニュースクリプトがリセットされると、LINK_SET に以下のようなリンクメッセージを送ります。
"888888 plugin menu_ping"

プラグインスクリプトは、 "menu_ping" メッセージが受け取られた場合、上記のリンクメッセージをメニューに追加しなおすはずです。

以下のコマンドはプラグインメニュースクリプトをリセットし、プラグインメニューボタンにメッセージを送るものです。
"888888 plugin menu_reset"


============
Backup System（バックアップシステム）
============
まだまとめはありません。


=============
Voice Commands（ボイスコマンド/チャットコマンド）
=============
コントローラースクリプトによって妨害されず、受理されたすべてのボイスコマンドはそのままリンクメッセージとして他のすべてのスクリプトに受け渡されます。下の "Linked Messages" （リンクメッセージ）をご覧ください。


=============
Linked Messages（リンクメッセージ）
=============
すべてのMystiTool スクリプトは、引数 integer に 1983745561 が入っている場合のみを、リンクメッセージとみなします。この integer が指定されていないと、MystiTool のスクリプトはリンクメッセージを無視してしまいます。

MystiTool のリンクメッセージのフォーマットは以下のとおりです。

cmd_channel feature_name options

区切る時はスペースで行います。縦線 ( | )ではいけません。
以下はリンクメッセージの例です。

llMessageLinked(LINK_ROOT, 1983745561, "1 scan 96", "");
llMessageLinked(LINK_ROOT, 1983745561, "1 scan remote", "");
llMessageLinked(LINK_ROOT, 1983745561, "20 flight normal", "");
llMessageLinked(LINK_SET, 1983745561, "20 mimic Mystical Cookie", "");

最初の文字列と数値は、コマンドを受け取るチャンネルを指定します。
こうしてスクリプトに、ヘルプやスクリプト使用のアウトプットを教えます。メニュー経由でコマンドが受け取られた場合には、現在設定されているボイスコマンドチャンネルが適用されます。つまり、現時点ではどのコマンドがボイスコマンドによるものなのか、どれがメニューからの入力なのかを判断することは不可能であるということです。

また、cmd_channel number が 888888 であった場合、スクリプトはリンクメッセージを 他のスクリプトから送られたものであると判断します。複数のスクリプトが入り込み、ループを起こすのを防ぐためこうしています。

次の行は機能、またはコマンド名です。すべてのスクリプトはすべてのリンクメッセージを聞きます。スクリプトはリンクメッセージに自分の持つ機能やコマンドが書かれているのを見て、それが自分に向けられたものであると認識します。

残りの行は目的のスクリプトに処理されるべき内容です。


=========
On Attach（装着時）
=========
MystiToolを装備すると、リンクメッセージが1つ送られます。

lllMessageLinked(LINK_SET, 1983745561, "888888 channel voice 1", "");

これは現在のボイスコマンドチャンネルをすべてのスクリプトに伝えるものです。


==========
Sleep Mode（スリープモード）
==========
スリープモードを解除したときに、2つのリンクメッセージが送られます。

llMessageLinked(LINK_SET, 1983745561, "888888 sleep_now", "");
llMessageLinked(LINK_SET, 1983745561, "888888 wake_now", "");

スリープしないスクリプトに、リソース消費を抑えるために最善を尽くせと命令するものです。


==================
Suspending your Scripts（オリジナルスクリプトをスリープさせる）
==================
ご自分のスクリプトに、スリープ機能を組み込むことができます。スリープ機能を導入すると、 MystiTool がスリープモードに入ったとき、あなたのスクリプトを機能停止状態にすることができます。 LSL のバグの影響で、スリープ中に MystiTool を取り外し、再装着すると完全にリセットがかかってしまうことにご注意ください。メモリーにデータを保存するタイプのスクリプトはスリープモードを追加すべきではありません。

HUD 内部に存在しないスクリプトの名前は、自動でリストから削除されます。このリストのクリーンアップ機能は sleep_add コマンドが実行されるたびに働きます。

次のコマンドは "Sleep Me 1.0" というスクリプトをスリープ機能リストに追加するリンクメッセージの例です。

"888888 sleep_add Sleep Me 1.0"

次のコマンドは "UnSleep Me 1.0" というスクリプトをスリープ機能リストから削除するリンクメッセージの例です。

"888888 sleep_del UnSleep Me 1.0"

スリープスクリプトの中にあるスクリプトのリストを見るためには、以下のチャットコマンドを使用します。

/1 sleep_list

バージョン1.0.22 以降のHUDのみが、プラグインのスリープ機能をサポートしています。


=============
Color Conversion（カラー値変換）
=============
MystiTool は 色名と（#c0c0c0 のような）RGB による値を、LSL の機能を用いてベクター値に変換することができます。これによって色の値を記録するときによく用いられるような、スクリプトのメモリーを幾分節約することができます。以下は色を青に指定する場合の、カラーベクターを求める例です。

llMessageLinked(LINK_SET, 1983745561, "888888 color_convert blue", "");
llMessageLinked(LINK_SET, 1983745561, "888888 color_convert #0000ff", "");

あなたのスクリプトは以下のいずれかのレスポンスを受け取るはずです。

llMessageLinked(LINK_SET, 1983745561, "888888 color_resp <0.00000,>", "");
llMessageLinked(LINK_SET, 1983745561, "888888 color_resp unknown", "");

注意していただきたいのは、あなたのスクリプトだけがカラー値変換のリクエストを送信しているのではないかもしれない、という点です。適切な場合には、色に関する送信を無視する必要もあるでしょう。 :)


====================
Patch & Plugins Introduction （パッチとプラグイン機能の紹介）
====================
MystiTool 1.0.20 の新機能によって、MystiTool のユーザーにパッチとプラグインを簡単に届けられるようになりました。
また、HUD メニューに新たなメニューボタンを簡単に追加する機能もあります。追加されたボタンは HUD のメニューの3ページ目に現れます。

デフォルトのスクリプトを上書きすることによって、組み込まれている MystiTool の機能を完全に置き換えてしまうことも可能です。もし書き換えを行う場合、スクリプトの数とリソース消費を抑えるために、いくつかの機能が1つのスクリプトにまとめられていることに注意してください。

一例の "patch installer" は HUD の中に入っています。
このスクリプトはサンプルスクリプトとサンプルオブジェクトをそれぞれ1個、あなたのHUDにアップロードします。また、 サンプルオブジェクトとスクリプトを削除するための "Del Example" というボタンを追加します。

一般ユーザーにとってこのプラグインはとてもシンプルで便利です。プラグインインストーラーを rez して、クリックするだけでいいのです。カスタムスクリプトを友人に分けてあげたり、オリジナルの MystiTool プラグインを販売する時に非常に役立ちます。

バージョン 1.0.20 以降の HUD のみが、このパッチとプラグインインストール機能をサポートします。


=================
Patch & Plugins How To （パッチとプラグインの扱い方）
=================
HUDの中のサンプル "patch installer" を編集して、このサンプルからオリジナルのインストーラーを作ってもかまいません。

インストールは、ユーザーに "Patch Add" （パッチを追加する）という青いポップアップダイアログを表示するところからスタートします。また、ボイスコマンドのチャンネルは 9001番を指定します。そうです、ジェスチャーのチャンネルです :)

次にHUDは 908070 チャンネルで以下の文字列を返します。

"patch_info|EndUser Name|hud_key|hud_version|hud_pin"

パッチ・プラグインインストーラーがこの文字列を受け取ると、あなたはユーザーの名前、HUD のキー、HUD のバージョン、 5分間だけ有効な "remote load script pin" を得ます。

HUD pin は5分後には無効とされます。あるいはユーザーがテレポートしたり、HUD を取り外してしまった場合も無効となります。こうなった場合には HUD は 908070 チャンネルで以下の文字列を返します。

"patch_timeout|EndUser Name|hud_key|hud_version"

パッチ・プラグインのインストールが終了すると、ユーザーには "Patch Done" （パッチ終了） のボタンのついた青いポップアップダイアログが表示されます。また、ボイスコマンドのチャンネルは 9001番を指定します。これによって HUD pin が解除され、HUD は二度と "patch_timeout" という文字列を吐かなくなります。

メイン HUD のメニューにボタンを追加することもできます。 ノートの最初の方の、 "Menu System" （メニューシステム）の項を参照してください。

あなたのスクリプトは（インストール後に）、ユーザーに（C1からC6の）カスタム HUD ボタンを追加するかどうか尋ね、自動的にあなたのコマンドをカスタムボタンに登録するようにもできます。こちらは処理後に自らを消去する別スクリプトで行うので、メインのパッチ・プラグインスクリプトがメモリーを余分に消費することを回避できます。

すでに用意されている MystiTool のリンクメッセージを経由してあなたのスクリプトを起動させることもできます。インストール後のトリガーのさせ方についてはいろいろな可能性がありますよ :)

インストールされたパッチ・プラグインスクリプトは、"Settings Backup" （設定の保存） 樽型オブジェクトを使用したバックアップや復元は不可能であることに注意してください。