プラグインを作ってみる

アノテーションに関する解説

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
combo
プルダウンを選択したときに実際にパラメータに設定される値です。
省略すると、@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 デプロイメント時に削除を禁止する素材ファイルのパスを指定します。

プラグインパラメータでゲーム作者が指定した画像を削除対象外にする場合は、すでに説明した@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