プラグインを作ってみる
アノテーションに関する解説
MZのヘルプコメントには、たくさんの種類のアノテーションが定義されています。
この章ではアノテーションの設定内容について項目別に解説します。
プラグイン全体
プラグイン全体に関わるアノテーションは、プラグインを作成する場合は設定必須なものも多いので使い方を確実に覚えておきましょう。
| アノテーション | 説明 |
|---|---|
| @target | 固定でMZと記述します。RPGツクールMV向けに作られたプラグインと区別するために必要です。 |
| @plugindesc | プラグインのタイトルです。ここで記述した内容が管理画面の一覧に表示されます。 |
| @author | プラグインの作者です。管理画面に表示されます。 |
| @help | プラグインの詳細な使い方を解説する文章です。管理画面に表示されます。 |
| @url | プラグインの配布元URLです。管理画面にリンクとして表示されるので配布元にアクセスできるURLを指定します。 |
プラグインパラメータ
プラグインパラメータとは、プラグイン利用者が好きな値を設定できる機能です。
以下が設定例です。
* @param paramName
* @text パラメータ名
* @desc パラメータの説明
* @default
* @type number| アノテーション | 説明 |
|---|---|
| @param | パラメータの名前です。プラグインの実装部分でパラメータの内容を取得するときにプロパティ名として使われます。 パラメータ内容を定義するアノテーションの一番上に記述します。 |
| @text | パラメータの表示名です。パラメータを入力する画面に表示されます。 |
| @desc | パラメータの詳しい説明です。パラメータを入力する画面に表示されます。 |
| @default | プラグインをONにしたときに自動的に設定される値です。 パラメータを空にしたときに自動で設定される値ではないので注意してください。 |
| @type | パラメータの型情報です。ここで指定した値によって入力ダイアログのUIが変化します。 たとえば『number』を指定すると数値のみを入力できるパラメータになります。 |
| @parent | 親となるパラメータを指定できます。親子関係を持たせることで、パラメータをツリー構造にできます。 |
もっとも詳しい説明が必要なのは@typeかと思います。
@typeで指定した型によってダイアログの内容が変化するため、適切な型を指定することでプラグインがぐっと使いやすくなります。
@typeの種類は以下の通りです。
| 型の種類 | 説明 | 設定される値 |
|---|---|---|
| string | 特に制約のない通常の文字列入力項目になります。 | 入力した値 |
| multiline_string | 複数行入力可能な文字列入力項目になります。 | 入力した値 |
| file | 画像や音声などのファイル選択ダイアログになります。 ここで選択されたファイルは未使用素材削除機能の対象外になります。 |
選択ファイル名（拡張子なし） |
| number | 数値のみ入力可能な項目になります。 | 入力した値 |
| boolean | ON/OFFのラジオボタンになります。 | true/false |
| select | プルダウンリストになります。 | 選択した項目の@valueもしくは@option |
| combo | コンボボックスになります。 | 選択した項目の@option |
| actor | データベースのアクターを選択するダイアログになります。 | 選択した対象のID |
| class | データベースの職業を選択するダイアログになります。 | 選択した対象のID |
| skill | データベースのスキルを選択するダイアログになります。 | 選択した対象のID |
| item | データベースのアイテムを選択するダイアログになります。 | 選択した対象のID |
| weapon | データベースの武器を選択するダイアログになります。 | 選択した対象のID |
| armor | データベースの防具を選択するダイアログになります。 | 選択した対象のID |
| enemy | データベースの敵キャラを選択するダイアログになります。 | 選択した対象のID |
| troop | データベースの敵グループを選択するダイアログになります。 | 選択した対象のID |
| state | データベースのステートを選択するダイアログになります。 | 選択した対象のID |
| animation | データベースのアニメーションを選択するダイアログになります。 | 選択した対象のID |
| tileset | データベースのタイルセットを選択するダイアログになります。 | 選択した対象のID |
| common_event | データベースのコモンイベントを選択するダイアログになります。 | 選択した対象のID |
| switch | スイッチを選択するダイアログになります。 | 選択した対象のID |
| variable | 変数を選択するダイアログになります。 | 選択した対象のID |
| string[] | 複数の文字列を入力できるダイアログになります。 文字列以外でも後ろに[]を付与すれば全て配列扱いになります。 |
["入力値", "入力値"] |
| struct<型名> | 複数の項目をまとめて入力できるダイアログになります。 | {aaa:"入力値", bbb:"入力値"} |
structは、複数のパラメータをひとまとめにして定義するパラメータです。
型名は記号を含まない任意の文字列を指定します。
型の定義は以下の凡例のように別枠で定義します。
/*~struct~型名:
*
* @param param
* @text パラメータ名称
* @desc パラメータの説明
* @default
* ......
*/structをさらに配列にすることも可能です。
具体的な実装方法はいくつかの公式プラグインが参考になります。
指定するtypeによってはさらにアノテーションが必要になる場合があります。
| アノテーション | 対象のtype | 説明 |
|---|---|---|
| @max | number | 入力可能な数値の最大値です。 |
| @min | number | 入力可能な数値の最小値です。 |
| @decimals | number | 小数点以下の桁数です。 |
| @dir | file | ファイルダイアログを指定するときの対象ディレクトリです。 |
| @on | boolean | ONを選択したときにダイアログに表示される値です。 |
| @off | boolean | OFFを選択したときにダイアログに表示される値です。 |
| @option | select combo |
プルダウンの表示項目としてダイアログに表示される値です。 |
| @value | select | プルダウンを選択したときに実際にパラメータに設定される値です。 省略すると、@optionの値がパラメータに設定されます。 |
プラグインコマンド
MZではプラグインコマンドの仕様が一新され、コマンドや引数の定義もアノテーションでできるようになりました。
コマンド名称と引数の情報をあらかじめ定義しておけば使う側はイベントコマンドから指定するだけでコマンドを呼び出せます。
* @command COMMAND
* @text コマンド名称
* @desc コマンド説明
*
* @arg arg1
* @text 引数の名称
* @desc 引数の説明| アノテーション | 説明 |
|---|---|
| @command | プラグインコマンド名です。 実際に呼び出す際の識別子に使われます。 コマンドを定義するアノテーションの一番上に記述します。 |
| @arg | プラグインコマンドの引数名です。 引数を定義するアノテーションの一番上に記述します。 |
プラグインコマンドやその引数にも、パラメータと同様のアノテーションを指定して表示名や詳しい説明、デフォルト値や型名を指定できます。
プラグインの依存関係
MZでは、新たにプラグイン間の依存関係を定義するアノテーションが追加されました。
新たに追加されたアノテーションを利用することで、ベースプラグインなどを明示できます。
| アノテーション | 説明 |
|---|---|
| @base | ベースプラグインの名称を指定します。ベースプラグインを入れずに対象プラグインだけ入れると警告が表示されます。 |
| @orderAfter | 使う場合は上に登録する必要があるプラグインの名称を指定します。競合対策などに使用します。 |
| @orderBefore | 使う場合は下に登録する必要があるプラグインの名称を指定します。競合対策などに使用します。 |
未使用素材削除機能への対応
プラグインの中で画像を直接ロードしている場合、デプロイメントを実行するときに［未使用ファイルを除外する］にチェックを入れると、必要な画像が除外されてしまう可能性があります。
たとえば次の例は
・img/picturesフォルダのimage_1.png
・img/systemフォルダのimage_2.png
・img/exampleフォルダimage_3.png※
をそれぞれ参照するコードです。
let b1 = ImageManager.loadPicture("image_1");
let b2 = ImageManager.loadSystem("image_2");
let b3 = ImageManager.loadBitmap("img/example/", "image_3");※プラグインの記述により、既定では存在しないexampleフォルダを指定した例です
しかし、このままでは画像が削除されてしまいます。
もし、使用する画像ファイルが固定の場合は、@requiredAssetsに続けて必要なファイルを記述してください。
* @requiredAssets img/pictures/image_1
* @requiredAssets img/system/image_2
* @requiredAssets img/example/image_3| アノテーション | 説明 |
|---|---|
| @requiredAssets | デプロイメント時に削除を禁止する素材ファイルのパスを指定します。 |
プラグインパラメータでゲーム作者が指定した画像を削除対象外にする場合は、すでに説明した@type fileと@dirのアノテーションがあればOKです。
なお、前作MVにあったアノテーション@requireは廃止となりました。
メモで指定したファイルを［未使用ファイルを除外する］の対象外にするアノテーションは以下の通りです。
* @noteParam sampleImage
* @noteDir img/sample/
* @noteType file
* @noteData items| アノテーション | 説明 |
|---|---|
| @noteParam | メモの名前を指定します。 |
| @noteDir | 画像が格納されているフォルダを指定します。 |
| @noteType | 固定でfileと指定します。 |
| ＠noteData |
対象のメモが使われているデータベースです。以下の中から指定します。 maps events actors classes skills items weapons armors enemies states tilesets |