『Fy Mascot』- 思考エンジンやオプションプログラムを作る

はじめに

『Fy Mascot』は『思考エンジン』や『オプションプログラム』などのプログラムを作り、オリジナルのキャラクターを作ったり、機能を追加したりすることができます。プログラムの作成には、『Fy Mascot』に添付しているサンプルソースコードを参考にするとわかりやすいと思います。

サンプルソースコード

『Fy Mascot』には『思考エンジン』や『オプションプログラム』などのサンプルソースコードを添付しています。ソースコードはC言語で書かれており、Visual C++ Expressなどフリーの開発環境で誰でも自由に作ることができます。

picture

サンプルソースコードは以下のファイルで構成されています。

『Fy Mascot』と各種プログラムとの連動は『GICP』というプロトコルで決められたXML形式の文字列をやりとりすることで行います。

GICP通信

『思考エンジン』や『オプションプログラム』と『Fy Mascot』は、『GICP』の文字列をそれぞれからエクスポートされたcommunication関数に渡すことで通信します。

通信

『Fy Mascot』から各モジュールへのGICP文字列は、各モジュールに備わったcommunication関数に対して送られ、逆に各モジュールから『Fy Mascot』へのGICP文字列は、load関数で引き渡されたcommunication関数に対して送られます。

メモリ管理

communication関数で通信される文字列はモジュール間でやりとりされ、異なるモジュール内でメモリの確保や解放が行われます。通常のmallocなどの関数でメモリを確保すると異なるモジュールでは解放できないなどの問題が発生します。この為、『Fy Mascot』では専用のメモリ関数を用意しload関数で引き渡しています。communication関数で送受信するGICP文字列のバッファは全てこの関数で確保・解放を行ってください。

『Fy Mascot』のメモリ関数では、通常のバッファの確保機能に加えて独自のメモリ管理を搭載しており、メモリリークやバッファオーバーフロー(プログラムが落ちない程度の軽度なもの)が発生するとエラーを書き出すことができます※1。

※1 メモリエラーを書き出す機能はデフォルトでOFFになっています。設定プロパティシートには設定項目がありませんが、設定ファイルを編集することで有効にすることができます。

load関数で引き渡される関数

『Fy Mascot』本体がエクスポートしている通信関数やメモリ管理関数は、『思考エンジン』、『オプションプログラム』のload関数で引数として渡されます。ここで引き渡された関数へのポインタをグローバル変数などに格納して利用します。

load関数で引き渡される関数
picture

●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

関数が実行されたモジュールの名前です(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

関数が実行されたモジュールの名前です(ANSI/Shift_JIS)。

第3引数 char *lp_source

ソースファイルの絶対パスです(ANSI/Shift_JIS)。

第4引数 int i_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』へ通信する場合も同様です。この為、送信した側は必ずメモリの解放をする必要があり、受信側した側は解放だけ行って確保しないような事をしてはいけません。

思考エンジン

『思考エンジン』はキャラクターの立ち絵やセリフをコントロールするプログラムです。

エクスポート関数

『思考エンジン』は以下の関数をエクスポートしなければなりません。3つのうちどれか一つでもかけている場合は不備があるとしてはじかれます。(この仕様は後述の『オプションプロググラム』と同一です)

character.c
picture

●load関数

load関数は『思考エンジン』が『Fy Mascot』にロード、アンロードされた時に実行されます。

第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文字列を送る際に利用する関数です 。

戻り値 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関数でダイアログを作成します。

picture

第1引数 HWND h_parent

『Fy Mascot』の設定ダイアログのウィンドウハンドルです。作成するシートの親ウィンドウとして指定するのに使います。

第2引数 unsigned short us_language

現在『Fy Mascot』で選択されている言語をロケールID (LCID) で指定します。ロケールIDはマイクロソフトの指定したコードで、1033が英語、1041が日本語、というように決められています。すべての言語に対応する必要はなく、対応するかどうかは製作者の自由です。

戻り値 int

失敗した場合は0を、成功した場合は0以外を返します。

オプションプログラム

オプションプログラムは『Fy Mascot』に各種機能を追加/強化するプログラムです。

エクスポート関数

オプションプログラムは以下の関数をエクスポートしなければなりません。3つのうちどれか一つでもかけている場合は不備があるとしてはじかれます。(この仕様は前述の『思考エンジン』と同一です)

option.c
picture

●load関数

load関数は『オプションプログラム』が『Fy Mascot』にロード、アンロードされた時に実行されます。

第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文字列を送る際に利用する関数です 。

戻り値 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関数でダイアログを作成します。

picture

第1引数 HWND h_parent

『Fy Mascot』の設定ダイアログのウィンドウハンドルです。作成するシートの親ウィンドウとして指定するのに使います。

第2引数 unsigned short us_language

現在『Fy Mascot』で選択されている言語をロケールID (LCID) で指定します。ロケールIDはマイクロソフトの指定したコードで、1033が英語、1041が日本語、というように決められています。すべての言語に対応する必要はなく、対応するかどうかは製作者の自由です。

戻り値 int

失敗した場合は0を、成功した場合は0以外を返します。