⚔️

『RPGツクールMZ』のJavaScript開発環境構築

2021/03/18に公開

JavaScript

JavaScriptとかプラグインとか

プラグイン作れたら、なんでもできるのになー、いいなー。
って思いますよね。

なんでもできるってこたぁないんですが、楽しいのでこちらの沼にいらっしゃい、ずぶずぶ。

まずプラグインを作る前に、『RPGツクールMZ』[スクリプト]の使い方基礎](https://zenn.dev/tonbi/articles/f2953b2c017188)から一連の記事を読んで、[スクリプト]コマンドから JavaScript(以後JS)を実行する方法でいろいろ遊んでみるといいと思います。

では、色々やりきったら戻ってきてください。
グッバイアディオスさよーならー!

もう「プラグイン作る、今日作る！」ぐらいの勢いになっている方は、公式ページにあるトリアコンタンさんが書かれた RPGツクールMZ プラグイン講座を読むと良いでしょう。

さぁ、とりあえずなんかプラグイン作りましたか?
作ったのなら、さらに使いやすい環境を整えていきましょう。

JSリファレンスいろいろ

とにかく探索には地図が必要です。プログラミングの場合はリファレンスですね。

公式に RPGツクールMZ Core API に『RPGツクールMV』の JSリファレンスがあるのですが、解説文が英語ですし全体からするとちょっとだけしか書いてないので、あまり役に立ちません。
上記のプラグイン講座の [最速JavaScript講座]-[コアスクリプト関数の利用]-[RPGツクールMZ スクリプトリファレンス] のところでPDFが公開されています。
これも全部のリファレンスが入ってるわけではありませんが、この情報だけでもいろんな機能のプラグインが作れます。
またgoogleドキュメント版 RPGツクールMZ スクリプトリファレンスが、別途用意してあります。

そして本題なのですが、公式のリファレンスが拡充されるのを待ちきれずに作った RPGツクールMZ 非公式JavaScriptリファレンスを強力にお勧めします。
個人的には、これなしでプラグインを書く気が起きません。
『RPGツクールMZ』の全クラスの解説が日本語で書かれていて、クラスごとに1ページが割り当てられており、関連クラスにはリンクが貼られ、クラスの継承関係を書いたクラスツリーも完備。
さらに『RPGツクールMV』からの変更点の記述もあるので、MVである程度慣れていた人にも優しい作りです。
『RPGツクールMZ』でプラグイン作る日本人、全員シノゴノ言わずにブックマークするが良いです。
スマートフォンやタブレット端末などをお持ちの方は、そちらでブックマークしておくのもパソコンの画面を取られないで便利かと思います。

ちなみに、JavaScript本体のリファレンスはプラグイン講座にも書いてありますが、MDNのJSリファレンスがメチャメチャに充実しているので、まずこれをブックマークするがよろしい。
また、現代の JavaScript チュートリアルは古いJSを覚えて二度手間になってしまうことが防げるので、JS入門に良いと思います。
karino2さんの算数で挫折した人向けのJavaScript入門はMV用ですがツクール向けJS入門なのでプラグイン作りにはあんまり必要ない感じのところはすっ飛ばしてあり、お手頃です。

Visual Studio Code のセットアップ

良いコードは良いエディタから!
というわけでコードエディタなんですが、よくJS入門には「JSはメモ帳でも書けます」とか書いてあったりしますが、それは「足を使えば移動できます」って言ってるようなものなので、徒歩で力つきる前に交通機関(コードエディタ)を使いましょう。

具体的には、マイクロソフトの無料コードエディタ『Visual Studio Code(以後VSCode)』を使います。
VSCodeを使う理由は「僕が開発に使ってるから」で、それ以外の理由は特にありません。
使ってるもの解説しますよね、フツー。
この記事を書いた時のバージョンは、1.54.3です。結構頻繁にバージョンアップされていて、インタフェースやその他機能が変わっちゃうので、適度に勘を働かせて使いこなしましょう(雑解説)
[2022-02-10]追記:1.64.0を元に多少内容を改修しました。また紹介しているサイトの情報も古くなっているので、その辺りに留意して読む必要があります。

ちなみに単に『Visual Studio』と言ったらマイクロソフトの統合開発環境を指すので、『Visual Studio Code』の略称として『Visual Studio』と書いたら全く意味が通じなくなってしまうのでご注意ください。
『JavaScript』を『Java』って略したら全く別のもの指すみたいなもんですね。重ね重ねご注意!

VSCodeのワークスペースの設定

ようこそ画面から[フォルダーを開く]を選択。
または左上のファイルアイコンか[表示]-[エクスプローラー]メニューでエクスプローラーを開いて、[フォルダーを開く]ボタンを押す。
そしてファイルダイアログで『RPGツクールMZ』で作ったプロジェクトフォルダを選択します。
するとエクスプローラーにフォルダとファイルの状態が表示されます。

VSCodeはフォルダを[ワークスペース]として設定し、そこを作業領域として開発するのが基本です。
フォルダを開いたら [ファイル]-[名前を付けてワークスペースを保存]メニューで、ワークスペースの設定ファイルを保存します。
例えば 'プロジェクト名.code-workspace' というファイルです。
このファイルを置く場所はどこでもいいんですが、先ほど[フォルダーを開く]で開いたフォルダに置いとくのが無難なところかなと思います。

次回からは保存した 'プロジェクト名.code-workspace' ファイルを開くことで、ワークスペースの状態(諸々の設定など)が再現できます。
なお最近使ったワークスペースは、ようこそ画面や[ファイル]-[最近使用した項目]メニューからも開けます。
ワークスペースには '.vscode' というフォルダが作られます。これは最初に '.' がついていて通常のOSのファイル操作では見えません。VSCodeからは見えて操作できるので、心配無用です。
この .vscodeフォルダに、次に書くテスト設定の launch.json が置かれます。

VSCodeのテスト設定

VSCodeを使えば、JSプログラムをしているエディタ上から『RPGツクールMZ』の[テストプレイ]メニューとほぼ同様にテストプレイができます。
なんとプロジェクトを作ってしまえば、プラグイン作成に『RPGツクールMZ』本体いらないのです。便利ですね!
あ、プラグインの設定するときには本体が必要でした(笑)

ざっくり言うと『RPGツクールMZ』は、NW.jsというパソコン上でブラウザを介さずにJSを動かすシステムを利用しています。
これを VSCodeとは別途ダウンロードして、ゲームのファイルをVSCodeからNW.jsに渡せるように、VSCodeの設定をします。
その際にダウンロードするバージョンは、『RPGツクールMZ』で使う NW.js のバージョンに合わせます。
NW.js のバージョンはテストプレイウィンドウでF8でコンソールを開いて、次のコードを打ち込みます。

nw.process.versions.nw

すでに『RPGツクールMZ』が持ってるNW.jsアプリケーションをもう一回ダウンロードするの無駄な感じしますが、このくらいの無駄は、回線速度とストレージサイズに余裕がある昨今、気にすんな!

VSCodeへの NW.jsの導入について詳しくは、蒼竜さんのページにある Visual Studio Code による RPG ツクール MZ のデバッグ PDFをダウンロードしてお読みください。
MVの説明ですが、みひらぎ亭さんの Visual Studio CodeでツクールMVをデバッグ～NW.js(ローカル環境)編～も参考になります。

個人的には、書いてある通りやっても、途中でエラーで止まって焦りました。
どうも以前にインストールしたVSCodeの拡張ファイル(Debugger for NWjs)が壊れてたみたいです。
しかも、拡張ファイルマネージャでuninstallしても削除されないみたいだったので、エラーで表示されたファイルパスを頼りに拡張ファイルを削除して、再インストールしたら動くようになりました。

この辺がプログラミングの恐ろしいところですね。
「書いてある通りやってるのに動かない」ということに、頻繁に遭遇します。
大抵は「書いてある通りやってないから動かない」のですが、やってる本人にとってはどっちも一緒です。
それで心折れない猛者だけがプログラミング技術を手にするのです!!
ちなみに僕は、いろんなプログラミング環境に手を出しては挫折の山を築いています。わははははー。
幸いツクールは『ツクール公式フォーラム』があります。
わからないことは、使用OSやアプリ、パソコンの環境、自分で行ってみたこと、想定した結果、想定通り進まなかった箇所など、必要な情報を添えて質問すれば、なんか親切な人が答えてくれます。ありがたやー。

NW.js ではなくて各種ブラウザで開く設定もできるので、Chromeで開く設定も追加しました。
この辺は VSCode公式のデバッグの解説(機械翻訳)やら Chormeの起動オプションの解説を検索して調べたりします(Chormeの起動オプション一覧は公式ページにはないみたい)
Sanshiroさんの「Visual Studio Code」+「Chrome」で「ツクールMV」のローカルでデバッグなテクニックの紹介ではMVの情報ですが、Chromeを使ったVSCodeデバッグ環境の構築方法が書いてあり、参考になります。
※Debugger for Chrome は1.64.0時点では非推奨(Deprecated)となっています。これは同様の機能が VSCode本体に含まれるようになったので不要になったからです。
僕の環境では結局、.vscode/launch.json は次のような設定になってます。
※以前は "url" の部分がローカルファイルを指定する "file" で動いていたのですが、どうも方針が変わったようです。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Chrome",
            "type": "pwa-chrome",
            "request": "launch",
            "webRoot": "${workspaceFolder}",
            "url": "${workspaceRoot}/index.html",
            "runtimeArgs": [
                "--allow-file-access-from-files",
                "--remote-debugging-port=9222",
                "--autoplay-policy=no-user-gesture-required"
            ]
        },
        {
            "name": "Launch NWjs",
            "type": "nwjs",
            "request": "launch",
            "webRoot": "${workspaceFolder}",
            "reloadAfterAttached": true,
            "runtimeArgs": [
                "${workspaceFolder}",
                "test"
            ]
        }
    ]
}

nameの項目を見ればわかりますが、上の方が Chrome、下が NW.js 用の設定です。
NW.js の設定は、package.json にも書かれているので、少し launch.json の記述が少ないです。

なお、このテスト起動では VSCodeの豊富なデバッグ機能も使えるのですが、その辺を説明すると大変な分量になるんで割愛。
環境設定の部分でもないですしね。

VSCode インテリセンス

インテリセンス(IntelliSense)はたぶんマイクロソフト用語だと思います。マイクロソフト以外だとオートコンプリートとか呼ばれてたりします。
ある程度コードを書いたら、残りの部分を自動で書いてくれる機能で、プログラムを解析して書かれている変数とか関数の名前を提案してくれますし定義情報も表示してくれるので、カーソルキーで選んでTabで決定!
打ち込む分量も減るし、打ち間違いも減るしで、たいへんありがたい機能です。
またコード上の変数や関数をマウスオーバーすれば、その定義情報をツールチップに表示してくれます。ちょー便利!!
ただコードに JSDoc のコメントがなかったり、ファイルが別れていたりすると、正確に解析してくれません。

で、それを補完するための定義ファイルが、LunaTechsDev さんによって作られています。ありがたいですね。

解説は英語フォーラムにある LunaSense - RPGMakerMV/MZ Intellisense(機械翻訳) を読んでください。
VSCode 以外に『Sublime Text』や『Atom』といったエディタで使えるらしいです。
また『RPGツクールMZ』のスクリプトだけでなく、利用されている描画ライブラリの PIXI.js にまで対応しています。
ただし、アニメーションライブラリの Effekseer にまでは対応してないみたいです。

内容はそんな複雑なことは書いてないんですが、いちおう簡単に日本語で書いておきます。

定義ファイルダウンロード(Github) ページを表示
[lunalite-pixi-mz.d.ts] ってファイル名のリンクをクリック
ページの右上あたりに [Download] ってボタンを探す(もしかしたら[Raw]かもしれない)
[Download] ボタン上でコンテキストメニュー開いて[リンク先を別名で保存…]
定義ファイルダウンロード(Github) ページに戻る
同様に[jsconfig.json] をダウンロード
プロジェクトフォルダにダウンロードしたファイルを移動
jsconfig.json を環境に合わせて修正

という感じ(以上は翻訳ではなく、僕の理解で書いています)

元のフォーラムの記事ではjsフォルダに置くように書いてあって、jsconfig.jsonはJSが置いてあるフォルダに置くのが基本みたいだけど、NW.js では jsconfig.json と package.json は同じ階層に置くのが普通みたいなので、僕はそうしてパスを適当に書き換えてます。
この辺は「お好みで!」

ただ、LunaSense の jsconfig.json のパスの記述は全体的に何でそうなってんだかよくわかんないんですよね。
plugins_dev ってなんだろ、ってところからよく分からない。たぶんお好きなフォルダに書き換えてね、ぐらいの意味で書いてあると思います。
なので、VSCode公式の jsconfig.jsonの解説(機械翻訳) を参考にしつつ、お好きに書き換えました。

compilerOptions については target に es6 を設定しておけば、ECMAScript6相当のJSの文法で書かれていると認識してくれるんで、このままでいいはず。
とくに書かなくても jsconfig.json ファイル以下のフォルダにある jsファイルを検知してくれるみたいなんで、include には jsファイルではない lunalite-pixi-mz.d.ts さえ設定しておけばいいはず。

とはいえコア部分とlib(のPIXI.js)については lunalite-pixi-mz.d.ts で定義されているので、それらのJSファイルをサーチすると二重登録になって無駄。
と思ったんだけど js/*.js を登録しておくと F12(初期値)で定義箇所に飛べるので便利と気づいて追加。
あと、js/plugins/*.js を指定。
なお jsconfig.json があるフォルダを示す ./ は無くてもいいみたい。

excludeにはサーチから外すフォルダ(ファイルじゃないよ)を書くんだけど、include を書いたんでこっちは使う必要ありません。
よくわからんところは自分の解釈でテキトーに書き換える勇気というか蛮勇。それがプログラマには必要だと思います。「いやいや、よく分かってから書きかえなさいよ」というのももっともですが(笑)

MVでの導入事例ですが、しぐれんさんの VScodeで入力補完をフル活用するプラグインの書き方を参考にするといいと思います。

現在、僕のところの jsconfig.json は次のようになっています。

{
  "compilerOptions": {
    "target": "es6",
  },
  "include": [
    "js/*.js",
    "js/plugins/*.js",
    "lunalite-pixi-mz.d.ts",
  ]
}

lunalite-pixi-mz.d.ts はけっこうMVの説明が残っているようで、RPGMakerMVって説明書いてある箇所がたくさんありますが…まぁ気にしないで脳内でMZに置き換えていきましょう(製作者のLunaTechsDevさんに教えてあげるべきかもしんない)

その他VSCodeについて

VSCodeの拡張ファイルには色々と便利なものがあるので、お好みで色々入れれば良いと思います。
拡張ファイルは VSCodeウィンドウ左側のブロックっぽいアイコンで開くところで、検索してインストールできます。
とりあえず、MS公式の『Japanese Language Pack for Visual Studio Code』を入れて、メニューなど日本語化しておくのもいいでしょう。
オススメは『Bracket Pair Colorizer 2』で、コードの対応したカッコを同じ色に色付けしてくれます。
説明を読んだ感じでは「だから何」ぐらいな感じですが、これが思いのほかコードが読みやすくなります。
[2021-09-08]追記 : VSCode v.1.60 で標準機能になりました。
これは便利、VS Codeの設定を変更しよう！v.1.60のアップデートで、ブラケットのカラー化にネイティブ対応とか見て設定するといいと思います。
他にもテキトーに色々入れているんですが、もはや何のために入れたかわからなかったりして(笑) あんまり説明できません。

またVSCode自体はこの記事でもちょこちょこ出てきた VSCode公式のヘルプや、@IT Insider.NET 全記事一覧から VSCode や JS の記事を探して読むと良いかと思います。
それから、zennにもkaraage0703さんが書いたVS Codeエディタ入門があるので、参考になるかと思います。

プラグイン開発の手始めに

まずはプロジェクトを作ったときに入っているプラグインを読んでみる。
次に『RPGツクールMZ』本体と同じフォルダにある、dlc/BasicResources/plugins/ にある公式・準公式のプラグインを見てみる。
僕はまだ PluginCommonBase.js しか読んでません!! 読んでないのに勧めるのダメじゃん(笑) !

えー読んでないのに言うのもなんですが「これ書き方おかしくないかな」って思うようなコードは「大抵おかしいです」(笑)
『RPGツクールMZ』本体のコードからして、過去の資産とのしがらみなどもあって、割とおかしなところが散見されますしね!

不穏な言葉で締めてしまいましたが… エンジョイ! ツクールライフ！

追記:
本体付属のプラグインについてはざっと確認しました。