はじめに
GICPとは『Fy Mascot』で、『思考エンジン』や『オプションプログラム』と通信する際に使用しているプロトコルです。ちなみにGICPという名前は General Incantation Communicate Protcol (汎用呪文型通信プロトコル)の略で、要するによくわからん言葉(呪文)を使った通信というわけです(笑)。
他のプログラムとの通信やネットワークの通信用には、もうちょっとテキトーにしたGICP Liteというプロトコルも用意しました。
GICP
・GICPについて
GICPの概要と外部プログラムとの通信についてです。『Fy Mascot』内外の通信はすべてこのGICPの文字列で行われています。
GICPの概要
- GICPの構文･･･GICPの基本的な構文。
- GICPの文字コード･･･GICPで使用する文字コード。
- GICPの基本的な構成･･･GICPを構成する4つの要素について。
- GICP RETURN･･･GICPの返信。
外部プログラムとの通信
- GICP Lite･･･外部プログラム通信用のGICP Lite。
- NETWORK･･･TCP/IPを使ったGICP Liteの通信。
- MESSAGE･･･ウィンドウメッセージを使ったGICP Liteの通信。
・イベント一覧
『Fy Mascot』に実装されているイベントの一覧です。これらのイベントを利用して『Fy Mascot』が動作します。
INFORMATION
INFORMATIONクラスは、『Fy Mascot』からの情報を知らせたり、『Fy Mascot』経由で『思考エンジン』や『オプションプログラム』に情報を知らせたりするとき利用するクラスです。
NOTICE
NOTICEクラスは、『思考エンジン』にイベントを通知するのに利用されるクラスです。『思考エンジン』は、このイベントを元にセリフの生成を行ったりします。
- NOTICE START … 『思考エンジン』にスタートを通知する。
- NOTICE EXIT … 『思考エンジン』に終了を通知する。
- NOTICE LEFT-CLICK … 『思考エンジン』にクリックを通知する。
- NOTICE LEFT-STROKE … 『思考エンジン』になでるを通知する。
- NOTICE HEALTHCARE … 『思考エンジン』に健康指南を通知する。
- NOTICE BACKSEAT … 『思考エンジン』に着席を通知する。
- NOTICE RESOURCE … 『思考エンジン』にリソース情報を通知する。
- NOTICE INSTALL … 『思考エンジン』にインストールを通知する。
- NOTICE MESSAGEM … 『思考エンジン』に情報を通知する。
MESSAGE
『オプションプログラム』や外部プログラムから、キャラクターに情報を言ってもらう(代わりに読み上げてもらう)ために使うクラスです。
CANVAS
CANVASクラスは、『Fy Mascot』のキャンバスにセリフを表示する際に利用するクラスです。
- CANVAS-EXECUTION … セリフを表示する。
- CANVAS-FINISH … 『思考エンジン』にセリフの表示完了を知らせる。
- CANVAS-FACE … キャラクターの立ち絵を変更する。
- CANVAS-BREAK … セリフの表示を中止する。
- Canvas Script … セリフのスクリプトについて。
FUNCTION
『Fy Mascot』では、『思考エンジン』や『オプションプログラム』にエディットボックスに入力された言葉などで何かをやらせることができます。このクラスはそれらの機能を利用する際に利用されるクラスです。
- FUNCTION-GETFUNCTION … 対応している機能についての問合せる。
- FUNCTION-EXECUTION … 機能を実行する。
- FUNCTION-LIST … 対応している機能の一覧を取得する。
- FUNCTION-REQUEST … 『Fy Mascot』へ対応している機能を実行させる。
MENU
『Fy Mascot』のメニューの取得・実行に使われるクラスです。
SYSTEM
SYSTEMクラスは、主に『Fy Mascot』のシステム上の処理を行う際に利用するクラスです。
GICPの概要
『Fy Mascot』では、GICPというプロトコルで定義された文字列をやりとりして動作します。『Fy Mascot』、『思考エンジン』、『オプションプロググラム』間は関数で、『別プログラム』とはウィンドウメッセージ(WM_COPYDATA)やTCP/IPで通信を行います。
- 『思考エンジン』や『オプションプログラム』を作る … 『GICP』をやりとりする関数について (別ページ)
- NETWORK … TCP/IPで別プログラムと通信する
- MESSAGE … ウィンドウメッセージ(WM_COPYDATA)で別プログラムと通信する
・GICPの構文
GICP文字列はXMLの書式に準拠しています。この為、要素型は全て小文字とし要素同士は入れ子になっているなどの仕様を踏襲しています。世の中皆考えることは同じというか、同じくXMLの文字列を使った通信プロトコルが世の中にはずっと前からたくさん存在しているらしいです。
GICPでは設計を簡単にする為、また人が読みやすくする為に以下の制限を追加しました。
| ファイル名 | スタイル |
|---|---|
| 空要素 | GICPでは原則空要素は使いません。従って必ず開始タグと終了タグで構成されることになります。 |
| 空白 | XMLでは空白は任意の場所につけられますが、特にタグの中に不要な空白は処理に失敗する恐れがあるのでやめてください。 |
| 要素内容 | 可読性を高めるため内部処理に利用する英文字パラメータは大文字に統一するように推奨します。※1 |
| 要素名 | 同じ要素名が並ぶことは処理自体は可能ですが、検索処理がメンドーでひょっとしたら失敗するかもしれないので推奨しません。※2 |
※1あくまで内部処理に利用するパラメータに対してのことで、ユーザー入力やセリフ等はこれに含めません。
※2 属性をもうけて番号をふるのがオススメです。
GICPでは処理する側や、後からコードを見る場合を考慮してタグの省略や要素名の略字の採用などは行わない方向で設計しました。これは昨今のマシンスペック向上やネットワーク回線の高速化により文字列の送受信が若干増える程度では影響は軽微で、それよりも確実で明快な処理ができる方がいいんじゃね？という結論に至ったからです。
従って、独自に要素を追加する場合などでも、わかりやすいというコンセプトは踏襲していただけるとうれしいです。
・GICPの文字コード
『Fy Mascot』のGICPで通信される文字コードはUTF-8です。
Windowsでプログラムを作ると、この仕様がメンドーなことこの上ないのですが。。。ただ、世の中の流れがUTF-8がスタンダードになっているようなので、清水の舞台から飛び降りる思いで全面的にUTF-8で処理するようにしました。
とはいえ、文字を表示する関数以外は、ほとんどマルチバイト用の関数がそのままUTF-8でも使えます。
・基本的な構成
GICPは大きく見ると、『送り手』、『送り先』、『命令』、『パラメータ』で分類される文字列で構成されます。各要素は入れ子式に要素を分類追加することができるので、マスコットとの通信以外での利用にも耐える汎用性と拡張性を兼ね備えている、と自負しておりますw。
GICPの全ての内容は<gicp>～</gicp>に納められ、『gicp』には属性としてversionを記述します。『gicp』の中に以下の四つの要素が入ります。
- 『送り手』を記述する『master』
- 『送り先』を記述する『follower』
- 『イベント』を記述する『witchcraft』
- イベントに必要な『パラメータ』を記述する『incantation』
Master
masterは送り手を指定します。
実際は内部で使われることはあんまりないのですが、返信などがある場合に必要になります。要素には『place』と『detail』があります。
| 名前 | 場所 |
|---|---|
| MASCOT | 『Fy Mascot』本体。 『detail』には何も記述する必要はありません。 |
| CHARACTER | 『思考エンジン』。 『detail』は何も記述する必要はありませんが、『name』を設けてキャラクターを限定することもできます。この情報を利用するかどうかは『思考エンジン』によります(無視されるかも)。 |
| OPTION | オプションプログラム。 『detail』に『name』を指定します。 |
| NETWORK | TCP/IPを使ったGICP命令を受信した場合。 『detail』にはTCP/IPアドレスとポートを『address』要素に記述します。 |
| MESSAGE | ウィンドウメッセージを使ったGICP命令を受信した場合。 必要に応じて『detail』には送信元のプログラムの(受信用ウィンドウの)ウィンドウハンドルを『handle』要素に記述します。。 |
| SOMEONE | 誰か。 後述のGICP RETURNで送り先が不要な場合に利用します。 『detail』には何も記述する必要はありません。 |
Follower
followerには送り先を指定します。この内容は送り先の特定に使われます。masterと要素の内容は同じで、送り返す際はmasterの内容をそのままfollowerに指定することで送信することが可能です。送り手が存在しない場合はGICPの失敗として処理されます。
Witchcraft
witchcraftには実行するイベントを指定します。要素内容には『class』と『order』があり、『class』にはそのイベントのクラスを、『order』にはそのクラス内で有効なオーダーを指定します。クラスとオーダーを分けたのは、分かりやすくするためです。(なのでSOMETHINGクラスとか作らないでください)
オプションプログラムと『思考エンジン』など、『Fy Mascot』が対応する必要がないものに関しては、『class』と『order』ともに自由に定めることができます。※同じORDERでもCLASSが異なれば別々のものとして認識されます。
Incantation
incantationにはwitchcraftで指定されたイベントによって要素内容が変化します。基本的にパラメータなどが指定されます。
各イベントの『incantation』には『userdata』要素を追加することができ、ユーザーが任意の追加情報を付加することができます。また『userdata』要素は、不要な場合省略することもできます。
・GICP RETURN
GICPは通信が完了した際に結果をGICP文字列で返します。これをGICP RETURNと呼びます。すでに接続されているので送信元(master)も送信先(follower)も必要ないと思いますが、一応省略はしない方針なので完全なGICP文字列にして返信するようにして下さい。
※いちいち送り先を作るのが面倒な場合はplaceにSOMEONEを指定すると便利です。
『result』
『Fy Mascot』では結果を通知するのに、GICP RETURNの『incantation』の中に『result』タグを作り、そこに結果を入れて返します。
| パラメータ | コード | 場所 |
|---|---|---|
| OK | 200 | 成功 |
| CONTINUE | - | 続行 |
| BREAK | - | キャンセル、終了 (ユーザー等にキャンセルされた) |
| ERROR | 500 | エラー (少なくともGICP通信は成功している) |
| BADREQUEST | 400 | 書式エラー (不備がある、間違っている等) |
| CONFLICT | 409 | 競合 (すでに他のプログラムで利用中) |
| SECURITY | 403 | セキュリティ (セキュリティ上の理由等) |
| NOTSUPPORTED | 501 | 未サポート (GICP通信は成功している) |
※コードは後述のGICP Liteの際に利用されるリターンコードです。
ユーザーを待つ返信
GICPは受信後すぐに返信するよう規定しました。しかし、例えばユーザーに入力をしてもらう場合や処理に時間がかかるものの場合などは、すぐにGICP RETURNをすることができません。
このような場合、GICPを受信した時点で受信した旨だけを返して、返信内容が確定した時点で受け手側から再度GICPを送信するという方法をとります。ですから、このようなGICP命令は必ず、パラメータに送り手の情報を添付させる必要があります。
外部プログラムとの通信
『Fy Mascot』はTCP/IPやウィンドウメッセージを使って外部のプログラムと簡単なGICPの通信をすることができます。この場合はGICPの機能を限定して簡単に実行できるGICP Liteを送受信するようになっています。
・GICP Lite
GICPは文字列でGICP RETURNをする必要があるため、送り手が送信と受信の両方ができる必要があります。WM_COPYDATAを使ったウィンドウメッセージの通信では、文字列は片方向にしか送信できないので一手間です。そこでGICP RETURNを一つの数値のみを返すようにし、送り手『master』の情報も限定したものがGICP Liteです。
もともとウィンドウメッセージでもフルスペックのGICPを実行できるようにしていたのですが、対応アプリケーションを作る方もメンドーなことになるので機能を限定したGICP Liteを策定しました。
GICP Liteの構成
GICP Liteの送信データはGICPのそれとほぼ同じです。GICP Liteの要素は<gicplite>～</gicplite>でくくられます。『master』の『detail』の内容は引き継がれますが、『place』はサーバーによって置き換えられます。『Fy Mascot』からの通信を不要とする場合は『detail』要素は必要ありません。(宛先不明として処理されます)
サーバーはGICP Lite文字列を受信すると、『master』、『follower』、『witchcraft』、『incantation』の各要素を使ってGICP文字列を作成して『Fy Mascot』に送り、GICP RETURNのうち『result』要素のリターンコードとして返します。逆に『Fy Mascot』からサーバーに送られたGICP文字列は、サーバーでGICP Lite文字列に置き換えられて送り先に送信され、戻り値を『result』要素に入れてGICP RETURNを返します。
このような仕様になっているので、『Fy Mascot』側のプログラムは、どこから送られてきたか特に意識することなく、単にNETWORKやMESSAGEから送られてきたものとして処理することができます。
GICP Liteの戻り値
GICP Liteの戻り値はGICP RETURNの『result』から値を決めて返します。『result』要素に数値が入っていた場合はその数値が、『result』要素がなかった場合は0が返ります。『result』要素のリターンコードについては、GICP RETURNの『result』を参照してください。
・NETWORK
『Fy Mascot』ではTCP/IPを使ってGICP Liteをネットワークで送受信するサーバーを実装しています。これにより、ネットワーク上の別のパソコンにオプションプログラムのようなプログラムを実行してGICPを通信することができます。
送信する場合はポート番号に2348、IPアドレスはデスクトップ上(ローカル)ならば127.0.0.1、ネットワークならば送り先とする『Fy Mascot』が稼働しているコンピュータのIPアドレスを指定して送信します。さらに接続を維持した状態でGICP RETURNを受信します。
送信時に『master』要素の『detail』に自身のIPアドレスとポートを指定すると、『Fy Mascot』からのGICPの通信を受信することができます。受信した場合は接続を維持した状態でGICP RETURNを返信してください。
| NETWORKの『detail』の例 |
| <detail><address>127.0.0.1:2448</address></detail> |
※ 送信側のアプリケーションが同一デスクトップ上でポート番号が2448の場合の例。
・MESSAGE
『Fy Mascot』ではウィンドウメッセージのWM_COPYDATAを使ってGICP Liteをアプリケーション間で送受信するサーバーを実装しています。これにより、デスクトップ上の別のアプリケーションと手軽にGICPを通信することができます。
外部プログラムから送信する場合は、FindWindow関数を使って ウィンドウクラス名が"FyMascotSystem"のウィンドウに向けてWM_COPYDATAメッセージをSendMessageで送信します。lParamとして送るCOPYDATASTRUCTは以下のデータを入れます。
| COPYDATASTRUCT |
| ULONG_PTR dwData; //特に使いません DWORD cbData; //文字列のバッファのサイズ PVOID lpData; //文字列のバッファのポインタ |
SendMessage関数の戻り値でGICP RETURNコードを返します。送信時に『master』要素の『detail』に自身のウィンドウハンドルの値(数値)を指定することで、そのウィンドウハンドルのWM_COPYDATAで『Fy Mascot』からのGICP Liteの通信を受信することができます。プロシージャの戻り値として結果を返します。
| MESSAGEの『detail』の例 |
| <detail><handle>123456789</handle></detail> |
※ 受信するウィンドウのウィンドウハンドルが123456789の例。
NOTICE
NOTICEクラスは、『思考エンジン』にイベントを通知するのに利用されるクラスです。『思考エンジン』は、このイベントを元にセリフの生成を行ったりします。
・START
『Fy Mascot』起動イベント時に送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には、『priority』、『interval』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『interval』
| INTERVAL | 意味 |
|---|---|
| FIRSTSTART | そのキャラクターが初めて起動された。 |
| NORMAL | 通常の起動。 |
| SHORTBLANK | つい直前までそのキャラクターが実行されていた。 |
| LONGBLANK | 久しぶりにそのキャラクターが起動された。 |
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・EXIT
『Fy Mascot』で終了が選択されたときに送られます。この通知を受け取った場合、『思考エンジン』はセリフを言い終わったら必ずSYSTEM-EXITを『Fy Mascot』に送ってマスコットを終了してください※。
| 方向 | 『Fy Mascot』から送られる |
|---|
※そうしないと『Fy Mascot』が終了を選んでも終了しなくなってしまいます。
GICP
『incantation』には、『priority』、『command』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『command』
| COMMAND | 意味 |
|---|---|
| EXIT | 終了 |
GICP RETURN
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・CLICKL、CLICKR
キャラクターがクリック又は右クリックされたときに送られます。左クリックの場合CLICKLイベントが、右クリックの場合はCLICKRイベントが送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には、『priority』、『collition』と『point』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『collision』
クリックされた場所のラベル名を指定します。ラベル名はキャラクター画像の設定ファイルで記述された言葉です。
『point』
クリックされた場所の座標が入ります。『point』要素の中に『x』と『y』要素があって、そこに値が記述されます。
| 『point』 |
| <point> <x>10</x> <y>20</y> </point> |
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・STROKE
キャラクターがなでられたときに送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』、『collition』と『point』要素があり、内容はNOTICE-LEFT-CLICKと同じです。
GICP RETURN
GICP RETURNの内容もNOTICE-LEFT-CLICKと同じです。
・HEALTHCARE
パソコンが起動してから一定時間が経過したときに送られます。ユーザーの健康のために休憩をうながすために使います。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』と『hour』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『hour』
経過した時間が指定されます。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・BACKSEAT
スクリーンセーバーが解除されたときに送られます。ユーザーが席を離れていて、再びパソコンの前に帰ってきたときに声をかけるのに使います。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』と『minute』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『minute』
席を離れていた時間(分)が指定されます。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・RESOURCE
CPUやメモリの負荷が高くなったときに送られます。コンピュータの状態をみてユーザーに話しかけるのに使います。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』、『type』と『status』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『type』
どの負荷に対するものかを表します。
| TYPE | 意味 |
|---|---|
| CPU | CPUの負荷が高くなった。 |
| MEMORY | メモリの負荷が高くなった。 |
『status』
負荷のパターンが指定されます。
| STATUS | 意味 |
|---|---|
| REPORT | 負荷が一定の条件を超えた。 |
| CONTINUATION | 負荷が一定の条件を超えた状態が続いている。※ |
※現在CONTINUATIONは、typeが『CPU』の時のみ指定されます。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・TALK
『Fy Mascot』が独り言を話すために送られます。ユーザーが選んだ頻度で、『Fy Mascot』が適時このイベントを送ります。独自にタイミング機構を持っているのであれば、このイベントを無視しても問題ありません。(ただし、本体の設定項目が反映されないことになりますが)
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には、『priority』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・INSTALL
『Fy Mascot』に新しいキャラクターがインストールされるときに送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』と『status』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『status』
インストールの状態が指定されます。
| STATUS | 意味 |
|---|---|
| START | 現在はSTARTに固定されています。 |
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・NTP
『Fy Mascot』がNTP(ネットワーク・タイム・プロトコル)によるパソコンの時計の時刻合わせを行ったときにその結果を通知するために使われます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』、『attribute』と『second』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『attribute』
修正した結果が指定されます。
| STATUS | 意味 |
|---|---|
| LOSE | パソコンの時計が遅れていた。 |
| FAST | パソコンの時計が進んでいた。 |
| JUST | パソコンの時計は正確だった。 |
『second』
LOSE、FASTの場合はずれていた時間(秒)が指定されます。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・MESSAGEM、MESSAGEN、MESSAGER、MESSAGEI
『オプションプログラム』や外部プログラムから、キャラクターに何か情報を言ってもらう(代わりに読み上げてもらう)ときに送られます。送る側はMESSAGE-EXECUTIONを使って送ります。
MESSAGE-EXECUTIONの『type』が『MESSAGE』の場合は『MESSAGEM』が送られます。これはユーザーが見ているか関係なく表示します。MはMESSAGEのMです。
『type』が『INFORMATION』の場合は、送られてきた時に『MESSAGEN』が、思い出しのために定期的に『MESSAGER』が、ユーザーが表示を選択したときに『MESSAGEI』が送られます。NはNOTICEのN、RはREMINDのR、IはINFORMATIONのIです。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『priority』、『sender』、『title』と『string』要素があります。
『priority』
CANVAS-EXECUTIONのプライオリティが指定されます。
『sender』
このメッセージの送り手の名前が指定されます。
『title』
このメッセージのタイトルです。インフォメーションリストのメニューなどに使われます。
『string』
キャラクターに言ってもらうメッセージそのものです。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
INFORMATION
『Fy Mascot』からの情報を知らせたり、『Fy Mascot』経由で『思考エンジン』や『オプションプログラム』に情報を知らせたりするとき利用するクラスです。
・EXECUTION
『Fy Mascot』から、『思考エンジン』や『オプションプログラム』に情報を知らせるために送られます。例えば、セリフの発話が[始まった]/[終わった]や、ファイルがドロップされたなどの様々な情報が送られます。
また、後述のINFORMATION-REQUESTを使って、『思考エンジン』や他の『オプションプログラム』からこのイベントを送ることができます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には、『type』と『data』要素があります。終了処理の種類を指定します。
『type』
| TYPE | 意味 |
|---|---|
| STATUS | 『Fy Mascot』に何らかの状態変化があった。 |
『status』
| STATUS | 意味 |
|---|---|
| START | 『Fy Mascot』が起動した。 <status>START</status> <name>キャラクターの名前</name> |
| STATUS | キャラクターが変更された。 <status>CHARACTER-CHANGE</status> <name>キャラクターの名前</name> |
| TALK-START | セリフの表示が開始した。 <status>TALK-START</status> <script>スクリプト</script> <userdata>ユーザーデータ※1</userdata> |
| TALK-FINISH | セリフの表示が終了した。 完了 : <status>TALK-FINISH</status> <resuilt>CONTINUE</result> 中断 : <status>TALK-FINISH</status> <result>BREAK</result> <userdata>ユーザーデータ※1</userdata> |
| TALK-NAME | セリフのキャラクター名が変更された。 <status>TALK-NAME</status> <name>セリフのキャラクター名※2</name> <userdata>ユーザーデータ※1</userdata> |
| TALK-USERDATA | セリフ中のユーザーデータ。
<status>TALK-USERDATA</status> <data>セリフのユーザーデータ※3</data> <userdata>ユーザーデータ※1</userdata> |
※1 CANVAS-EXECUTIONで指定された『userdata』です。
※2 実行中のキャラクター名ではくて、セリフのキャラクター名(後述のCanvasScriptの\cで指定されたキャラクター名)です。
※3 セリフ中のユーザーデータ(後述のCanvasScriptの\uで指定されたユーザーデータ)です。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・REQUEST
『思考エンジン』や他の『オプションプログラム』から『Fy Mascot』経由でINFORMATION-EXECUTIONイベントを送ります。これにより、例えば『マイクの音声』や『ジェスチャー』などを、標準で対応している他の情報と同じようにINFORMATION-EXECUTIONイベントとして送ることができます。
| 方向 | 『Fy Mascot』に対して送る |
|---|
GICP
『incantation』は、INFORMATION-EXECUTIONと同じく『type』と『data』要素があり、その情報はそのままINFORMATION-EXECUTIONとして『思考エンジン』や『オプションプログラム』に送られます。また、INFORMATION-REQUESTに『userdata』がある場合は、それも同様にそのままINFORMATION-EXECUTIONの『userdata』として送られます。
GICP RETURN
GICP RETURNとして『result』が返りますが、内容は必ずOKになります。これは対応するオプションプログラム等が複数ある場合にリストアップする必要があるためです。(技術的には可能なので要望があれば実装しようと思います。)
MESSAGE
『オプションプログラム』や外部プログラムから、キャラクターに情報を言ってもらう(代わりに読み上げてもらう)ために使うクラスです。
・EXECUTION
『オプションプログラム』や外部プログラムから、『Fy Mascot』経由でキャラクターの『思考エンジン』に情報(メッセージ)を送ります。『Fy Mascot』から『思考エンジン』は内容を引き継いでNOTICE-MESSAGEが送られます。
送る側はこれを使って送るように、『思考エンジン』側はMESSAGE-EXECUTIONではなく、NOTICE-MESSAGEを受信するように作ります。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『type』、『sender』、『title』、『string』要素があります。また、『userdata』を追加するとそれも『思考エンジン』に送られ、『思考エンジン』がGICP RETURNに『userdata』を追加した場合はこのイベントのGICP RETURNにそのまま引き継がれます。
『type』
このメッセージの種類を指定します。これによりNOTICE-MESSAGEの動作が変わります。
| TYPE | 意味 |
|---|---|
| INFORMATION | ユーザーに見てもらいたい情報で、インフォメーションリストに追加されユーザーが選択すると表示されます。 |
| MESSAGE | 一般のメッセージで、ユーザーが読まなくてもそのまま流れます。 |
MESSAGE-EXECUTIONの『type』が『MESSAGE』の場合は『MESSAGEM』が送られます。これはユーザーが見ているか関係なく表示します。MはMESSAGEのMです。
『type』が『INFORMATION』の場合は、送られてきた時に『MESSAGEN』が、思い出しのために定期的に『MESSAGER』が、ユーザーが表示を選択したときに『MESSAGEI』が送られます。NはNOTICEのN、RはREMINDのR、IはINFORMATIONのIです。
『sender』
このメッセージの送り手の名前が指定されます。
『title』
このメッセージのタイトルです。インフォメーションリストのメニューなどに使われます。
『string』
キャラクターに言ってもらうメッセージそのものです。
GICP RETURN
GICP RETURNとして『result』が返されます。
『result』
終了ステータスとしてGICP RETURNの『result』が指定されます。
・MESSAGE-EXECUTIONの拡張
デフォルトのキャラクターに搭載された『思考エンジン』の『オモヒカネ』には、NOTICE-MESSAGEのユーザーデータ『userdata』を使ってMESSAGE-EXECUTIONイベントの機能を拡張できるようになっています。
このイベントは、本来どのアプリケーションからのものでも同じように処理するものですが、『userdata』に『extension』要素を追加しすることでアプリケーションごとにリアクションをすることができるようにしたものです。この要素がない場合、『オモヒカネ』は通常通りアプリケーションによらない一般的なリアクションをとります。
この機能は『オモヒカネ』の独自機能です。
『extension』
| 『extension』 |
| <extension> <name>アプリケーション名</name> <attribute>属性</attribute> <replace> <item no="1"><keyword>word1</keyword><newword>文字1</newword></item> <item no="2"><keyword>word2</keyword><newword>文字2</newword></item> <item no="3"><keyword>word3</keyword><newword>文字3</newword></item> </replace> </extension> |
この要素は大きく分けて、アプリケーション名、属性、そして置き換え文字で構成されます。
『name』で指定されたアプリケーション名が、そのままNOTICE-MESSAGEイベントの『param』としてスクリプトファイルの選択に使用されます。これにより、セリフスクリプトを作成すれば『思考エンジン』の修正なしで新しい『オプションプログラム』や『アプリケーション』に対応することがができます。
『attribute』には属性を記述します。ここに指定された『属性』で、スクリプトファイルの中から適切なセリフを選択させます。
必要に応じて、『replace』で置き換える言葉を記述します。上の例ではスクリプトの『replace{hour}』という部分を『7』という言葉(数字)に置き換えています。
CANVAS
CANVASクラスは、『Fy Mascot』のキャンバスにセリフを表示する際に利用するクラスです。
・EXECUTION
キャンバスにセリフを表示させます。
| 方向 | 『Fy Mascot』に対して送る |
|---|
GICP
『incantation』には、『priority』、『script』があります。
『priority』
キャンバスへの優先順位を指定します。既にキャンバスにセリフが表示されている場合は、どちらを優先するか判断する必要があります。『Fy Mascot』では双方の『priority』パラメータを比較して、どちらが優先されるかを判定しています。世のお父さんはがんばっています(笑)。
| TYPE | 意味 |
|---|---|
| WIFE | 競合相手がWIFE以外ならば優先されます。 ユーザーの操作によるものなどで指定することを想定しています。 |
| DAUGHTER | 競合相手がMEならば優先されます。 意味のある通知、伝えたい通知などに指定することを想定します。 |
| ME | キャンバスが使用中の場合は容赦なくはじかれます。 ランダムで独り言を発する場合などを想定しています。 |
優先の場合は、既に表示されていた内容はキャンセルボタンを押されたのと同じ処理をして終了させて、優先された方の内容が新たに表示されます。優先されなかった場合は表示されず、GICP RETURNの『result』要素に『CONFLICT』が入ります。
『script』
キャンバスに表示するセリフを後述のCANVAS SCRIPTで記述します。
GICP RETURN
GICP RETURNとして『result』が返されます。
『result』
終了ステータスとしてGICP RETURNの『result』が指定されます。
・FINISH
CANVAS-EXECUTIONのセリフが表示し終わったときに送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『result』要素があります。なお、CANVAS-EXECUTIONに『userdata』があった場合は、その内容もここに入れられます。
『result』
| RESULT | 意味 |
|---|---|
| COMPLETION | 最後まで表示した。 |
| BREAK | ユーザーがキャンセルボタンを押して終了した。 |
| TERMINATION | 上位プライオリティの実行など、システムによって中断された。 |
| ERROR | エラーが発生して終了した。 |
GICP RETURN
GICP RETURNとして『result』と『id』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
『id』
セリフ完了後のキャラクターの画像ファイル名(拡張子を除く)を記述します。拡張子を除くことに注意して下さい。この内容はCANVAS-FACEと同じです。
・FACE
キャンバスにセリフが表示されていないときに、キャラクターの画像を変更する場合に用いるイベントです。
| 方向 | 『Fy Mascot』に対して送る |
|---|
GICP
『incantation』には『id』要素があります。
『id』
セリフ完了後のキャラクターの画像ファイル名(拡張子を除く)を記述します。拡張子を除くことに注意して下さい。
GICP RETURN
GICP RETURNとして『result』が返ります。
『result』
終了ステータスとしてGICP RETURNの『result』が指定されます。
・BREAK
キャンバスに表示されているセリフを中断させる場合に使用します。例えば対話などでユーザーが入力を行った場合にまだ表示しているセリフを中断させて次の表示を行うことができます。
| 方向 | 『Fy Mascot』に対して送る |
|---|
GICP
『incantation』はありません。
GICP RETURN
GICP RETURNには『result』、『status』、『script』(と『userdata』)が返ります。
『result』
『result』は通常はOKとなります。
『status』
セリフの表示状態で、下の表のようになっています。
| STATUS | 意味 |
|---|---|
| HALT | セリフは表示していなかった。 |
| RUN | セリフが表示中だった。 |
『script』
『status』がRUNだった場合、『script』要素に表示中のセリフのスクリプトが記述されます。
『userdata』
『status』がRUNだった場合、表示中のスクリプト(CANVAS-EXECUTION)に『userdata』があったときはそれが追加されます。
・Canvas Script
キャンバスに表示するセリフは、それらしく表示するために『\(円マーク)』を使ったスクリプト記号をが用意されています。なお、『\』は文字としての『\』なので、C言語などのプログラム内部では'\\'と記述します。
| スクリプト記号 | 意味 |
|---|---|
| \n | 改行します。 |
| \w[数字] | 次の文字を表示するまで間をおきます。 (数字は何ミリ秒待つかを指定) |
| \e | 表示したセリフを消去します。 |
| \f[リアクション名] | リアクション(モーション)を実行します。 リアクション名は半角英数字で255文字以内です。 |
| \c[キャラクター名] | キャラクター名を変更します。 \c[$character]とするとモデル情報ファイルに書かれたキャラクター名になります。 キャラクター名は半角英数字で255文字以内です。 |
| \u[文字列] | セリフの表示がこの部分に来たタイミングで[]内の文字列を送ります。 (思考エンジンとすべてのオプションプロググラムにINFORMATION-EXECUTIONで送る) 音声読み上げ機能との連動などを想定しています。 |
| \\ | \(円マーク)を表示します。 (\\を表示したい場合は\\\\と記述) |
FUNCTION
『Fy Mascot』では、『思考エンジン』や『オプションプログラム』にテキストボックスに入力した文言で何かをやってもらうことができます。
このイベントは『オーダー』と『パラメータ』の2つで構成されています。上の例だと『LAUNCH』が『オーダー』で、『ペイント』や『メモ帳』などが『パラメータ』になります。『オーダー』はプログラムの方で決められた単語の中から選ぶ必要がありますが、『パラメータ』はユーザーの自由入力も認められます。
『Fy Mascot』は予め、『思考エンジン』と『オプションプログラム』に対してどのような『オーダー』があるのかをFUNCTION-GETFUNCTIONで取得します。ユーザーによって『オーダー』が入力されたら、今度は同じくFUNCTION-GETFUNCTIONで『パラメータ』を取得します。
『オーダー』と『パラメータ』が確定されたら、そのイベントを持った『思考エンジン』か『オプションプログラム』にFUNCTION-EXECUTIONが実行されます。
また、『思考エンジン』や『オプションプログラム』は、FUNCTION-LISTを使って『Fy Mascot』に搭載されている『思考エンジン』と『オプションプログラム』の『オーダー』一覧や『パラメータ』一覧を取得することができます。そして、FUNCTION-REQUESTによってテキストボックスに入力されたのと同じように任意の機能を実行することができます。
・GETFUNCTION
『Fy Mascot』は『思考エンジン』と『オプションプログラム』に対してどのような『オーダー』があるのかをFUNCTION-GETFUNCTIONで取得します。この結果はテキストボックスの入力支援や、他の『思考エンジン』や『オプションプログラム』が利用するためのFUNCTION-LISTに使われます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には『type』と『order』要素が指定されます。
『type』
取得する種類を指定します。
| TYPE | 意味 |
|---|---|
| ORDER | 『オーダー』を取得します。 |
| PARAM | 『パラメータ』を取得します。 |
『order』
『type』要素がPARAMの場合、どの『オーダー』のパラメーターを取得するのか指定します。
GICP RETURN
GICP RETURNとして『result』と、対応しているならば『オーダー』か『パラメータ』の一覧を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
『function』
『result』でOKを指定した場合は、メニューの項目を指定します。
| 『function』 |
| <incantation> <result>OK</result> <function> <order>パラメータ場合はそのオーダー</order> <items> <item no="1">(オーダー/パラメータ1)</item> <item no="2">(オーダー/パラメータ2)</item> <item no="3">(オーダー/パラメータ3)</item> </items> </function> </incantation> |
『result』でOKを指定した場合は、『オーダー』か『パラメータ』の一覧を記述します。『パラメータ』の場合は『order』要素が追加され、要求された『パラメータ』が何の『オーダー』の『パラメータ』なのか記述します。一覧は『items』の中の『item』で、項目は1から1つずつ増やしていきます。
『パラメータ』で任意の文字で対応する場合は、no=1に『*』を記述し以下のような形になります。WEB検索や対話などに使うことができます。
| 『function』(任意入力) |
| <incantation> <result>OK</result> <function> <order>オーダー<order> <items> <item no="1">*</item> </items> <function> </incantation> |
・EXECUTION
『Fy Mascot』のテキスト入力にリストにある『オーダー』と『パラメータ』が入力された際に、当該の『思考エンジン』や『オプションプロググラム』に対して送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には、『order』と『param』要素があります。
『order』
入力されたオーダーが指定されます。
『param』
入力されたパラメータが指定されます。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
・LIST
『思考エンジン』や『オプションプログラム』から『Fy Mascot』に搭載されている『思考エンジン』と『オプションプログラム』の『オーダー』一覧や『パラメータ』一覧を取得するために使います。
GICPとGICP RETURNは共にFUNCTION-GETFUNCTIONと同じです。
FUNCTION-GETFUNCTIONは、『Fy Mascot』が『思考エンジン』や『オプションプロググラム』などに『オーダー』や『パラメータ』の一覧を問い合わせていたのに対して、FUNCTION-LISTは『思考エンジン』や『オプションプロググラム』などの問い合わせに対して、『Fy Mascot』が『オプションプロググラム』のように振る舞って、『Fy Mascot』に搭載されている『オプションプロググラム』すべての機能の一覧を返すイベントと言えます。
| 方向 | 『Fy Mascot』に対して送る |
|---|
GICP
『incantation』には『type』と『order』要素があり、内容はFUNCTION-GETFUNCTIONと同じです。
GICP RETURN
GICP RETURNの内容もFUNCTION-GETFUNCTIONと同じです。
・REQUEST
『思考エンジン』や『オプションプログラム』から『Fy Mascot』経由でFUNCTION-EXECUTIONを送ります。これによりテキストボックスに言葉を入力したのと同じように『思考エンジン』や他の『オプションプログラム』に対してFUNCTION-EXECUTIONを送ることができます。
| 方向 | 『Fy Mascot』に対して送る |
|---|
GICP
『incantation』は、FUNCTION-EXECUTIONと同じく『order』と『param』要素があり、その情報はそのままFUNCITON-EXECUTIONとして『思考エンジン』や『オプションプログラム』に送られます。また、INFORMATION-REQUESTに『userdata』がある場合は、それも同様にそのままINFORMATION-EXECUTIONの『userdata』として送られます。
GICP RETURN
GICP RETURNとして『result』が返りますが、内容は必ずOKになります。これは対応するオプションプログラム等が複数ある場合にリストアップする必要があるためです。(技術的には可能なので要望があれば実装しようと思います。)
MENU
『Fy Mascot』のメニューの取得・実行に使われるクラスです。
・GETMENU
『Fy Mascot』がメニューを表示する際に、『思考エンジン』、『オプションプログラム』に対して追加するメニューの内容を問い合わせるために送信されます。メニューを追加する場合は、このオーダーのGICP RETURNにメニューの内容を返します。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』に指定される要素はありません。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
『menu』
『result』でOKを指定した場合は、メニューの項目を指定します。
| 『menu』 |
| <incantation> <result>OK</result> <menu> <title>Launcher</title> <items> <item no="1"><id>(ID1)</id><label>(項目名1)</label></item> <item no="2"><id>(ID2)</id><label>(項目名2)</label></item> <item no="3"><id>(ID3)</id><label>(項目名3)</label></item> </items> </menu> </incantation> |
メニューはプログラムごとにサブメニューの形で追加されます。『title』はサブメニューのタイトルになります。サブメニューの内容は『items』の中の『item』で、項目は1から1つずつ増やしていきます。『id』にメニュー項目のIDを、『label』にメニュー項目の名前を入れます。
・EXECUTION
『Fy Mascot』のメニューで、項目が選択された際に当該の『思考エンジン』や『オプションプロググラム』に対して送られます。
| 方向 | 『Fy Mascot』から送られる |
|---|
GICP
『incantation』には、『id』要素があります。
『id』
選択されたメニューのIDが指定されます。このIDはMENU-GETMENUの際に設定したメニュー項目のIDです。
※ GICP RETURNをすぐに返すため、DialogBoxなどの関数を利用する場合はスレッドを使ってください。
※ メッセージループ上でGICPが実行されているとは限らないので、CreateWindowを使う際にもスレッドと独自のメッセージループを用意するようにしてください。
※スレッドを使うので、ウィンドウが開いた状態でオプションプログラムがアンロードされた場合の処理にも注意してください。
GICP RETURN
GICP RETURNとして『result』を返します。
『result』
終了ステータスとしてGICP RETURNの『result』を指定します。
SYSTEM
『Fy Mascot』のシステム上の処理を行う際に利用するクラスです。
・EXIT
『Fy Mascot』を終了させるイベントです。『incantation』には、『command』要素があります。
| 方向 | 『Fy Mascot』へ送る |
|---|
GICP
終了処理の種類を指定します。
『command』
| COMMAND | 意味 |
|---|---|
| EXIT | 終了 |
GICP RETURN
GICP RETURNとして『result』が返されます。
『result』
終了ステータスとしてGICP RETURNの『result』が指定されます。
・PARAM
『Fy Mascot』の各種パラメータを取得・設定するイベントです。『incantation』には『order』、『param』、『data』要素があります。
| 方向 | 『Fy Mascot』へ送る |
|---|
GICP
『order』
パラメータを取得するか、設定するかを指定します。
| ORDER | 意味 |
|---|---|
| GETPARAM | パラメータを取得する |
| SETPARAM | パラメータを設定する |
『param』
取得・設定するパラメータを指定します。
| PARAM | 意味 |
|---|---|
| WINDOW-POSITION | 『Fy Mascot』の位置(座標)を取得・設定する |
『data』
パラメータを設定する場合(SETPARAM)に、設定する内容を指定します。取得の場合(GETPARAM)は必要ありません。
| PARAM | 内容 |
|---|---|
| WINDOW-POSITION | <rect> <left>左</left> <top>上</top> <right>右</right> <bottom>下</bottom> </rect> |
GICP RETURN
GICP RETURNとして『result』が返されます。
『result』
終了ステータスとしてGICP RETURNの『result』が指定されます。
『data』
パラメータを取得した場合(GETPARAM)に、取得した内容を指定します。設定の場合(SETPARAM)は必要ありません。内容はGICPの『data』と同じです。