⚔️
『RPGツクールMZ』のプラグイン作成最初の一歩

2024/11/09に公開
JavaScript
入門
RPGツクールMZ
tech
『RPGツクールMZ』関連記事 目次
『RPGツクールMZ』はメーカー公式のプラグイン講座もありますし他にも入門を書かれている方もいるので今更感もありますが、うちのブログにもプラグインの入り口ぐらい用意しておいてもいいだろう、ということでプラグイン入門です。
『RPGツクールMZ』[スクリプト]の使い方基礎
『RPGツクールMZ』のJavaScript開発環境構築
このふたつの記事の内容は理解しているものとします。

要は JavaScript の基本と『RPGツクールMZ』での使い方、そして外部のテキストエディタ(ここではVS Code)の準備です。
僕が見つけたプラグイン入門講座を並べておきます。公式のもの以外は本記事を読んでわからなかった時などに、読んでみるといいかと思います。
Gotcha Gotcha Games公式(トリアコンタンさん)のプラグイン講座
んーぞーさんのRPGツクールプラグイン制作過程紹介
ムノクラさんの攻略本レベル5 プラグインの作り方
ポテトードラゴンさんのコピペから始めるMZプラグイン講座
さとさんのRPGツクールMZ プラグイン開発講座
ある程度書けるようになったら、次の記事も参考にしていいと思います。ただどれも『RPGツクールMZ』の発売前後ぐらいの記事なんで、そのまま受け取るわけにもいきませんが。ITの世界の流れは早いのじゃ。
はどはどさんのRPGツクールMZでプラグインを作る上での最低限の心得
木星ペンギンさんの自己流プラグインルール
F_さんの【RPGツクールMV】イマドキのプラグイン記述術
最近(2024年現在)だとAIによるサポートでのプログラミングも普通になりつつありますが、その辺あんまり詳しくないので今回の記事ではパスします。

多分、使いこなせればかなり楽になるとは思うんですけどね。

 用語配列…値に番号をつけて並べた値。例:[ 10, 4, 6 ] (これは値として数字を並べていますが他の値も並べられます)

添字…「そえじ」配列(を保持している変数)から値を取り出す際に使う数字。例:array[ 0 ] ( JavaScript の配列の添字は 0 から始まります)

文字列…文字を並べた値です。JavaScript 的には String です。値が文字１つに固定された配列と考えてもいいです。例: "文字列でーす"

真偽値…真(正・ON)と偽(負・OFF)の２つを取る値です。JavaScript 的には Boolean で２つの値は true と falseで表されます。『RPGツクールMZ』的にはスイッチ、他にフラグと言われることもあります。

論理演算…計算の結果として真偽値を返す演算です。値の多少を判定する条件式などが含まれます。

変数…値を保持しています。JavaScript の変数も『RPGツクールMZ』の[変数]とだいたい同じです。定義例:let variable; 以前は定義に let ではなく var を使っていましたが問題が多く、今(2022年現在)はあまり使われていません。逆に var が使われていると素人でも簡単に古いコードだと分かります。なお『RPGツクールMZ』になってコアスクリプトは var を廃止してます。

定数…変数とだいたい同じですが、一度値を設定したら変更できません。一見不便に感じますが、実は変数より便利で、実際のプログラミングでは、ほとんど変数を使う必要はありません。定義例:const constant = 1;

ワンライナー…1行で書かれるプログラム全般をワンライナーと言います。環境によって1行しか使えないこともありますし、1行どれだけ複雑な処理ができるか競う遊びという面もあります。

関数…処理をまとめたものです。『RPGツクールMZ』の[コモンイベント]とだいたい同じですが、引数と返り値があるので使い勝手が格段に良いです。また[スクリプト]イベントコマンドも複数の処理が書けるので一種の関数といえ、[変数の操作]にある[スクリプト]などには返り値があります。JavaScript は歴史的経緯があって関数の定義方法がたくさんあるのが困ったところです。定義例:function addOne( arg ) { return arg +1; };、const addOne = arg => arg + 1;

返り値…「かえりち」関数が返す値です。関数によってあったりなかったりします。

継承…クラスのプロパティ・メソッドを引き継いで、さらに機能を追加したクラスを作ることです。

大域変数…プログラムのどの領域からでも扱える変数が、大域(グローバル)変数です。

 公式講座のおさらいとりあえず、公式講座を読んで簡単なプラグインを作ってみましょう。
Gotcha Gotcha Games公式(トリアコンタンさん)のプラグイン講座
トリアコンタンさんが書いた講座なので、まず間違いない内容です。

…作りましたか？

では簡単に講座のおさらいと、引っかかりそうなところの解説をしておきます。

 プラグインの接頭辞プラグインを使ったり調べたりしていると、同じ作者のプラグインの名前の先頭(接頭辞)が決まっていることに気づくと思います。

これはどういう意味があって、何か決まりがあるのでしょうか。
似たような機能なら同じ名前のプラグインが作られプラグインフォルダに放り込んだら「上書きしますか？」みたいな注意が出てきてしまいます。
この衝突(コンフリクト)を防ぐために他のツールでは、世界で一意に決まる ID として作者が取得している URLの逆順表記(僕なら jp.tonbi) をフォルダ名に使うとかの取り決めがあるんですが、『RPGツクールMZ』に関してはそのような仕組みは一切なく衝突し放題です。
なのでプラグイン制作者側が適当に作者同士で名前が衝突しないように、接頭辞をつけてリリースするようにしたということみたいです。
豆知識URL の逆順表記は Mac の設定やライブラリフォルダであるとか、Javaのパッケージ名とかに使われています。

と言っても URL だと長くなりがちなので、会社名とかプロダクト名とかが使われていることも多く、あんまり厳密ではありません。
ちなみに僕はプラグインの接頭辞として TF_ を使っています。

TF は僕の個人サイト Tobishima-Factory の略です。

2文字では衝突しかねないので jp.tonbi. のほうがよかったかなと思ったりしてますが長いしなぁ…。
なお、接頭辞をつけるのは単純に承認欲求からではないかと言われると、そうでないとは言い切れません(笑)

 プラグインのテンプレートプラグインを作る場合に最初に書くものは決まっているので、雛形(テンプレート)を作っておくと、新しくプラグインを作るときにちょっとだけ面倒臭さが減って良いです。
僕の場合は、これです。
TF_Template.js
//=================================================
// TF_Template.js
// Version : 0.0.0.0
// For : RPGツクールMZ (RPG Maker MZ)
// ----------------------------------------------
// Copyright : Tobishima-Factory 2024
// Website : http://tonbi.jp
//
// This software is released under the MIT License.
// http://opensource.org/licenses/mit-license.php
//=================================================
/*:ja
 * @target MZ
 * @plugindesc テンプレートなので、これ自体は使いません。
 * @author とんび﹫鳶嶋工房(tonbi.jp)
 * @url https://github.com/tonbijp/RPGMakerMZ/blob/master/TF_Template.js
 * @base PluginCommonBase
 * @orderAfter PluginCommonBase
 * @================= parameter ====================
 * @param testParam @text テストパラメータ
 * @desc パラメータのテスト
 * @type number @default 1
 * @================================================
 * 
 * @================== command =====================
 * @command testCommand @text テストコマンド
 * @desc 引数のテストconsoleに出力するよ。
 *
 * @arg arg1 @text 引数1
 * @desc consoleに出力するよ
 * @type string @default 規定値
 * @================================================
 * 
 * @============ この長さに合わせるとヘルプではみ出ない =============
 * @help
 * これはテンプレートなので、このままではなんの機能も持ちません。
 */
( () => {
    "use strict";

    // パラメータを受け取る
    const pluginParams = PluginManagerEx.createParameter( document.currentScript );
    const testParam = pluginParams.testParam;
    console.log( `testParam = ${testParam}` );

    // プラグインコマンドの定義
    const COM_TEST = "testCommand";
    PluginManagerEx.registerCommand( document.currentScript, COM_TEST, function( args ) {
        const arg1 = args[ "arg1" ];
        console.log( `arg1 = ${arg1}` );
    } );
} )();
!このテンプレートは著作権を主張できる程度の中身もない(だいたい誰が作っても似たようなものになる)ので、自由に改変してお使いいただいて結構です。

 ヘッダ部分さて、頭から順に解説します。
ここ別に書式は決まってないですし、そもそも JavaScript のコメントなのでなくても動作はするんですが、プログラム(プラグイン)の基本情報としてなんか書いておかないと、色々困るんで書いてます。
//=================================================
// TF_Template.js
// Version : 0.0.0.0
// For : RPGツクールMZ (RPG Maker MZ)
// ----------------------------------------------
// Copyright : Tobishima-Factory 2024
// Website : http://tonbi.jp
//
// This software is released under the MIT License.
// http://opensource.org/licenses/mit-license.php
//=================================================
上から
ファイル名: ファイル名を書き換えてしまった場合に元の名前がわかるように、ここに書いています。
バージョン(Version): 4つ区切りのメジャー、マイナー、不具合修正、機能に変化のない変更、を採用しています。
対象ツクール(For): 対応してるツクールが明示してあると使う時に安心です。
著作権者(Copyright): いわゆるコピーライトですが、利用範囲は利用規定(ライセンス)によって決まります。
サイト(Website): これは僕の個人サイトの URL ですが、GitHub などのファイルを公開している URL もいいかと思います。
ライセンス表記: 僕は多くのプラグインも採用している MIT ライセンスを採用しています。詳しくは原文を参照してください。

 バージョンバージョンの付け方はセマンティック バージョニングと言われる3つ区切りのものがよく使われるので、そっちの方がいいかもしれません。

僕は機能に変化のない変更(コメント追加やリファクタリングなど)をやりがちなので、ひとつ増やしてます。

 ライセンスMITライセンス以外にも、BSDだったり、CCだったり、色々とライセンス形態はあります。

自分で利用規約を作るのも構わないのですが、利用者側から見ると「それを読んで理解するのが面倒」というのは、プログラムを利用しない理由としてはかなり強力かと思います。

また、自分で作ると思いもよらない問題が発生したり、厳密に適用すると利用できない規約になってしまったりするので、なかなか大変です。

本体のロンチプラグインもMITライセンスが多いので、MITを選択しておけば同じように使ってもらえます。
参考：『RPGツクールMZ』のロンチプラグインを調べてみた
MITライセンスは非常に緩いライセンスで、無断かつ条件を問わず利用・配布・改造などが可能です。

なのでたとえば「特定の宗教・思想を表現する作品には使って欲しくない」という思いが強い場合には選択できません。

使用の範囲は基本的に制限がないので、MITライセンスのプラグインは作者・非作者問わず売ることもできます。

唯一と言って良い制限は、著作者名とライセンスを必ず明示すること。プラグインの場合はこのようにコメントに書かれているので、利用者が気にする必要はありません。
逆にいうと MITライセンスのプラグインを無断で改造して公開したこと(などライセンス沿った利用)を非難するのは的外れで、MITライセンスはそういう使い方を最初から想定しています。ましてプラグイン製作者本人がそういう非難を表明するのは、意味もわからずライセンスを選択した結果なので、浅はかとしか言いようがありません。
MITライセンスは使用したことによる損害について作者が一切保証しないというライセンスなので、製作者的に気軽ですね。

もし問題があるのなら「自分で改造していいよ」というライセンスでもあるので、ある意味では利用者的にも気軽です。

 アノテーション次に書いてあるのは、同じく JavaScript のコメントです。ただし/*:で始まるコメントは『RPGツクールMZ』で解釈されて、プラグインのオプションやイベントコマンドの内容として表示されたり、その他の設定になります。

その直後に書いてある ja は日本語で記述していることを意味しています。
/*:ja
 * @target MZ
 * @plugindesc テンプレートなので、これ自体は使いません。
 * @author とんび﹫鳶嶋工房(tonbi.jp)
 * @url https://github.com/tonbijp/RPGMakerMZ/blob/master/TF_Template.js
 * @base PluginCommonBase
 * @orderAfter PluginCommonBase
 * @================= parameter ====================
 * @param testParam @text テストパラメータ
 * @desc パラメータのテスト
 * @type number @default 1
 * @================================================
 * 
 * @================== command =====================
 * @command testCommand @text テストコマンド
 * @desc 引数のテストconsoleに出力するよ。
 *
 * @arg arg1 @text 引数1
 * @desc consoleに出力するよ
 * @type string @default 規定値
 * @================================================
 * 
 * @============ この長さに合わせるとヘルプではみ出ない =============
 * @help
 * これはテンプレートなので、このままではなんの機能も持ちません。
 */
テクニックというほどのものではありませんが、アノテーションの接頭辞である@のあとに規定のもの以外の文字を書いても無視されます。

それを利用して-や=を使った区切り線を入れて見やすくしています。

@をつけていないと前のアノテーションの内容の続きと判断されるので@は必須です。

逆に言うと@が区切りなので、ここでは1行に複数の設定を入れています。

また、スペースやタブでインデント(行を右にずらす)で@の位置を調整して見やすくできるので、方法を選んで工夫してみてください。
詳細は、公式のアノテーションに関する解説をお読みください(すでに読んでいるはずですが)

非公式リファレンスの MV.PluginSettings にもアノテーションについての解説があります。ちょっと説明が違ってたりするので、公式の記述で理解できない場合の保険にどーぞ。

 プログラム本体ここでやっと、プラグインの本体です。
( () => {
    "use strict";

    // パラメータを受け取る
    const pluginParams = PluginManagerEx.createParameter( document.currentScript );
    const testParam = pluginParams.testParam;
    console.log( `testParam = ${testParam}` );

    // プラグインコマンドの定義
    const COM_TEST = "testCommand";
    PluginManagerEx.registerCommand( document.currentScript, COM_TEST, function( args ) {
        const arg1 = args[ "arg1" ];
        console.log( `arg1 = ${arg1}` );
    } );
} )();
大体のことは公式のプラグイン講座にも書いてありますが、微妙に違うので解説します。

 パラメータの受け取りまずはこのパラメータを受け取る部分です。



[プラグイン管理]ウィンドウ
    // パラメータを受け取る
    const pluginParams = PluginManagerEx.createParameter( document.currentScript );
    const testParam = pluginParams.testParam;
    console.log( `testParam = ${testParam}` );
標準ではPluginManager.parameters()メソッドを使ってイベントコマンドからの命令を受け取ります。

この時にプラグイン名が必要なんですけど、このテンプレートではPluginManagerEx.createParameter()メソッドを使ってて、これはプラグイン名は必要ありません。

なので、プラグイン名を変更しても動作するはずです。
またPluginManagerEx.createParameter()メソッドで得られたオブジェクト(ここではtestParam)に保持されている値は、型解析して適切な型に変換(キャスト)されています。

たとえば数値なら Numberクラスに変換されています。

標準のPluginManager.parameters()メソッドではすべて Stringクラスとして保持されているので、その後個々に変換処理を入れる必要があって、かなり面倒臭いのです。
受け取った値はオブジェクト(pluginParams)なので.区切りでtestParamの値を取り出しています。
PluginManagerEx.createParameter()メソッドを使うには、PluginCommonBase.jsが必要です。

アノーテーションの以下の部分で必要であることと、上に配置して欲しいことが記述してあります。
 * @base PluginCommonBase
 * @orderAfter PluginCommonBase
PluginCommonBase.jsは 'dlc/BasicResources/plugins/official' フォルダに公式のプラグインとして入っています。

標準に入れとくなら、プラグインなしでも最初からPluginManagerEx方式にしてくれよと思いますが、『RPGツクールMV』との互換とか考えたんでしょうかね？

 プラグインコマンドの受け取り次はイベントコマンドの[プラグインコマンド]で指定したコマンドとその引数の受け取り方です。



[プラグインコマンド]ウィンドウ
    // プラグインコマンドの定義
    const COM_TEST = "testCommand";
    PluginManagerEx.registerCommand( document.currentScript, COM_TEST, function( args ) {
        const arg1 = args[ "arg1" ];
        console.log( `arg1 = ${arg1}` );
    } );
} )();
標準ではPluginManager.registerCommand()メソッドを使ってイベントコマンドからの命令を受け取ります。

この時にプラグイン名が必要なんですけど、このテンプレートではPluginManagerEx.registerCommand()メソッドを使ってて、これはプラグイン名は必要ありません。それに値は変換(キャスト)されます。

またPluginManagerEx.createParameter()メソッドと同様にPluginCommonBase.jsが必要です。
ここではconst COM_TEST = "testCommand";とアノーテーションの@command testCommandでコマンドを定義したやつを、定数に代入しています。

直接createParameter()の第二引数に書いてもいいんですが、直接(リテラル)文字列を書くのは避けたいというのもありますが、定数の定義部分だけコマンドの定義部分とは別にまとめておくと一覧性が良いので採用しています。
受け取ったオブジェクト(args)からは.区切りで値を取り出してもいいのですが、ここでは添え字方式で取り出しています。
なおPluginCommonBase.jsによって使えるようになるPluginManagerExについてはプラグインのヘルプはもちろん、非公式リファレンスのPluginManagerExも参考になります。
なお、パラメータもコマンドもconsole.log()メソッドで受け取った値をコンソールに表示しているだけです。

とりあえずテンプレートをプラグインとして『RPGツクールMZ』に登録したのち実行して、F8キーで表示されるデバッグウィンドウで確認してみましょう。

そして、表示内容を書き換えて実際変わるか確かめてみると良いかと思います。
!アノーテーションなどを書き換えた場合は[ツール]-[プラグイン管理]でプラグインを選択しコンテクストメニューから[更新]をする必要があります。

また必要ならパラメータを書き換えることも忘れずに。

 最後に自分でかなり忘れてるので、再学習目的で書きました。

プラグインを作っている人はみなさん秘伝のタレ的にテンプレートを持ってるんじゃないかと思います。

自分なりのものが作れると上級者気分が味わえますし(笑)
試しにAI(ChatGPT)に『RPGツクールMZ』のプラグインのテンプレートを作ってもらったら、完全に動作するものを作ってきたので驚きました。

簡単なものならすでに作れるし、修正なしに複雑なプラグインが作れるようになるまでもうすぐって感じですね。

いずれ、ゲームそのものもAIサポートでかなりの部分が作れるようになりそうです。
レッツエンジョイ、ツクールライフ！
用語

公式講座のおさらい

プラグインの接頭辞

プラグインのテンプレート

ヘッダ部分

バージョン

ライセンス

アノテーション

プログラム本体

パラメータの受け取り

プラグインコマンドの受け取り

最後に

Discussion
