はじめに
『Fy Mascot』は『思考エンジン』や『オプションプログラム』などのプログラムを作ることで、オリジナルのキャラクターを作ったり、機能を追加したりすることができます。プログラムの作成には、『Fy Mascot』に添付しているサンプルソースコードを参考にするとわかりやすいと思います。
サンプルソースコード
『Fy Mascot』には『思考エンジン』や『オプションプログラム』などのサンプルソースコードを添付しています。ソースコードはC言語で書かれており、Visual Studio Communityなどフリーの開発環境で誰でも自由に作ることができます。
サンプルソースコードは以下のファイルで構成されています。
- 『character.c』 … 『思考エンジン』 キャラクターのコントロールなど
- 『option.c』 … 『オプションプログラム』 プラグインや機能追加など
- 『program.c』 … 『Fy Mascot』と連動するアプリケーションなど(ウィンドウメッセージ通信)
- 『client.c』 … 別コンピュータ上で『Fy Mascot』と連動するアプリケーションなど(TCP/IP通信)
『Fy Mascot』と各種プログラムとは『GICP』というプロトコルで決められたXML形式の文字列をやりとりすることで連動させます。
『思考エンジン』と『オプションプログラム』
『思考エンジン』はキャラクターをコントロールするプログラム、オプションプログラムは『Fy Mascot』に各種機能を追加/強化するプログラムです。いずれも後述の仕様を満たしたDLL(ダイナミックリンクライブラリ)で、基本的には同じものですが用途が異なるので分けています。
『思考エンジン』や『オプションプログラム』は、『GICP』の文字列をエクスポートされたcommunication関数を使ってやりとりします。
『Fy Mascot』から『思考エンジン』や『オプションプログラム』へのGICP文字列は、各モジュールに備わったcommunication関数に対して送られ、逆に各モジュールから『Fy Mascot』へのGICP文字列は、load関数で引き渡された『Fy Mascot』に備わったcommunication関数に対して送られます。
GICP通信のメモリ管理
communication関数で通信される文字列は各モジュール間でやりとりされ、異なるモジュール内でメモリの確保や解放が行われます。通常のmallocなどの関数でメモリを確保すると異なるモジュールでは解放できないため、『Fy Mascot』では専用のメモリ関数を用意しload関数で引き渡しています。communication関数で送受信するGICP文字列のバッファは全てこの関数で確保・解放を行ってください。
『Fy Mascot』のメモリ関数は独自のメモリ管理機能を搭載しており、メモリリークやバッファオーバーフロー(プログラムが落ちない程度の軽度なもの)をログに書き出すことができます※1。
※1 メモリエラーを書き出す機能はデフォルトでOFFになっています。設定プロパティシートには設定項目がありませんが、設定ファイルを編集することで有効にすることができます。
エクスポート関数
『思考エンジン』と『オプションプログラム』は以下の関数をエクスポートする必要があります。3つのうちどれか一つでもかけている場合は不備があるとしてはじかれます。
| character.c / option.c |
 |
●load関数
load関数は『オプションプログラム』が『Fy Mascot』にロード、アンロードされた時に実行されます。第4引数以降の関数について詳しくは後述のload関数で引き渡される関数をご参照ください。
第1引数 int i_status
ロードされた場合は『1』が、アンロードされた時は『2』が入ります。
第2引数 char *lp_path
『オプションプログラム』が保存されているフォルダの絶対パスです(ANSI/Shift_JIS)。
第3引数 void *lp_reserved
現在は使われておりません。
第4引数 GICPMALLOC_FUNC malloc_func
GICP通信に利用するバッファを確保するためのmalloc関数です。
第5引数 GICPMALLOC_FUNC free_func
GICP通信に利用するバッファを解放するためのfree関数です。
第6引数 GICPCOM_FUNC com_func
GICP通信で『Fy Mascot』へGICP文字列を送る際に利用する関数です 。
第7引数 STATUS_FUNC status_func
『Fy Mascot』のステータス表示に利用する関数です。
戻り値 int
失敗した場合は0を、成功した場合は0以外を返します。
説明
『Fy Mascot』ではloadの戻り値が0の場合は不備があるものとしてロードを中止します。たとえば、必要なファイルなどを最初にチェックして不備がある場合や対応OSではないプラットホームの際に意図的に中止させたい時に有効です。 unload時は、戻り値に関わらずアンロードされます。
●communication関数
『Fy Mascot』から『思考エンジン』や『オプションプログラム』へのGICP通信がこの関数を使って行われます。『思考エンジン』や『オプションプログラム』から『Fy Mascot』への通信は、前述のload関数で引き渡された関数を利用します。
第1引数 char **lpp_buffer
GICP文字列が格納されたバッファのです。ポインタのポインタである点に注意してください。
第2引数 int *lp_length
第1引数で引き渡されたバッファのサイズです。ポインタである点に注意してください。
戻り値 int
失敗した場合は0を、成功した場合は0以外を返します。
●configuration関数
configuration関数は『オプションプログラム』の設定用プロパティシートを『Fy Mascot』の設定ダイアログから呼び出すための関数です。DialogBoxやDialogBoxParam関数でダイアログを作成します。
第1引数 HWND h_parent
『Fy Mascot』の設定ダイアログのウィンドウハンドルです。作成するシートの親ウィンドウとして指定するのに使います。
第2引数 unsigned short us_language
現在『Fy Mascot』で選択されている言語をロケールID (LCID) で指定します。ロケールIDはマイクロソフトの指定したコードで、1033が英語、1041が日本語、というように決められています。すべての言語に対応する必要はなく、対応するかどうかは製作者の自由です。
戻り値 int
失敗した場合は0を、成功した場合は0以外を返します。
load関数で引き渡される関数
『Fy Mascot』本体がエクスポートしているGICP通信用の関数などは、load関数に引数として渡されます。ここで引き渡された関数へのポインタをグローバル変数などに格納して利用します。
- malloc_func … GICP用のmalloc関数
- free_func … GICP用のfree関数
- com_func … 『Fy Mascot』へのGICP通信用
- status_func … ステータス表示用
| load関数で引き渡される関数 |
 |
●malloc_func関数
GICP文字列を格納するバッファを確保します。確保されたバッファは必ず後述の『free_func』関数を使って解放してください。
第2引数以下は前述のメモリ管理機能で使用する情報です。これらの引数にはマクロと__FILE__や__LINE__を使うと便利です。
| #define gmalloc(s) malloc_func( (s) , L"name" , __FILE__ , __LINE__ ) |
第1引数 int i_size
確保するバッファのサイズです。
第2引数 char *lp_module
関数を実行するモジュールの名前を半角英数255文字以下(ANSI/Shift_JIS)で記述します。
第3引数 char *lp_source
ソースファイルの絶対パスです。関数内でファイル名に変換されますが、__FILE__を使うことを前提に設計されているので絶対パスで引き渡してください。
第4引数 int i_line
関数が実行されたソースコード内の行数です。__LINE__を使うことを前提に設計されています。
戻り値 void *
確保されたバッファの先頭のポインタを返します。
●free_func関数
前述のmalloc_funcで確保されたバッファを解放する際に利用します。
第2引数以降はmalloc_funcと同じで、こちらもマクロと__FILE__や__LINE__を使うと便利です。
| #define gfree(p) free_func( (p) , L"name" , __FILE__ , __LINE__ ) |
第1引数 void *lp_pointer
解放するバッファのポインタ
第2引数 char *lp_module
関数を実行するモジュールの名前を半角英数255文字以下(ANSI/Shift_JIS)で記述します。
第3引数 char *lp_source
ソースファイルの絶対パスです。__FILE__を使うことを前提に設計されています。
第4引数 int i_line
関数が実行されたソースコード内の行数です。__LINE__を使うことを前提に設計されています。
戻り値 void
戻り値はありません。
●com_func関数
『Fy Mascot』への通信に使うcommunication関数です。『思考エンジン』や『オプションプログラム』にあるcommunication関数と同様の仕様となっています。
第1引数 char **lpp_buffer
GICP文字列の入ったバッファへのポインタのポインタです。バッファは『malloc_func』で確保します。
第2引数 int *lp_length
GICP文字列のバッファの長さ(終端\0を含む長さ)が格納されたint型の変数へのポインタです。
戻り値 int
通信が失敗した場合は0を、成功した場合には0以外を返します。
説明
『Fy Mascot』からGICP文字列が送られてきたら、プログラム内で適切な処理をします。そして、RETURNする際に確保されたメモリを一旦『free_func』で解放して、再度適切な大きさのメモリを『malloc_func』で確保してGICP文字列を記述します。
新たに得られたバッファのポインタとそのサイズをchar **lpp_bufferとint *lp_lengthに入れます。この為に第1引数がポインタのポインタとなり、第2引数がポインタとなっているのです。
この仕様は『思考エンジン』や『オプションプログラム』から『Fy Mascot』へ通信する場合も同様です。この為、送信した側は必ずメモリの解放をする必要があり、受信側した側は解放だけ行って確保しないような事をしてはいけません。
●status_func関数
『Fy Mascot』のステータス表示へ文字を表示させるための関数です。
第1引数 char **lpp_buffer
ステータスに表示する255バイト以下のUTF-8の文字列を引き渡します。バッファの解放などはされません。