⚔️

『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ツクールMZ』の 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にNW.jsをインストール

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

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

nw.process.versions.nw

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

インストールは、VSCodeの[表示]-[コマンドパレット…]に次のように打ち込んで実行します。

NWjs install

ズラーッとバージョンが表示されるので、先程調べたバージョンを選択するとインストールが開始されます。
※ただ、Macだと『RPGツクールMZ』と同じバージョンのNW.jsはIntel版しか存在しないため、選んでもエラーが出てインストールできません。僕はosx-arm64(いわゆるAppleシリコン)の最新バージョンを代わりにインストールしました。
Intel版をインストールする方法もある気はしますが、まいっかなと思って(笑)

回線速度が速くても、そこそこ時間がかかると思うので、お茶でも淹れて「Install complete」の表示が出るまでのんびり待ちます。

豆知識

この辺の知識をどこで得たかというと。

VSCodeへの NW.jsの導入について詳しくは、蒼竜さんのページにある Visual Studio Code による RPG ツクール MZ のデバッグ PDFをダウンロードしてお読みください。

MVの説明ですが、次の記事も参考になりました。
Sanshiro さんの「Visual Studio Code」+「Chrome」で「ツクールMV」のローカルでデバッグなテクニックの紹介
みひらぎ亭さんの Visual Studio CodeでツクールMVをデバッグ～NW.js(ローカル環境)編～

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

また、記事が書かれたあと特にVSCodeがバージョンアップして、情報が古くなっているところも多くなりました(2024年7月現在)

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

launch.jsonの作成

VScode左側のプライマリーサイドバーから[虫と▷アイコン]を選び、上の[実行とデバッグ]を押して現れたリストからNWjsを選択します。
すると、プロジェクトフォルダに.vscode/launch.jsonファイルができます。
これを編集することで、デバッグ時の起動設定を変えられます。

豆知識

この辺は VSCode公式のデバッグの解説(機械翻訳)やら Chormeの起動オプションの解説を検索して調べたりします(Chormeの起動オプション一覧は公式ページにはないみたい)
Sanshiroさんの「Visual Studio Code」+「Chrome」で「ツクールMV」のローカルでデバッグなテクニックの紹介ではMVの情報ですが、Chromeを使ったVSCodeデバッグ環境の構築方法が書いてあり、参考になります。
※Debugger for Chrome は1.64.0時点では非推奨(Deprecated)となっています。これは同様の機能が VSCode本体に含まれるようになったので不要になったからです。

起動フォルダとかファイルを設定し、各種ブラウザで開く設定もできるので、Chromeで開く設定も追加しました。
僕の環境では結局、.vscode/launch.json は次のような設定になってます(2024年7月現在)

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Chrome",
            "type": "chrome",
            "request": "launch",
            "webRoot": "${workspaceFolder}",
            "file": "${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",
            "nwjsVersion": "any",
            "webRoot": "${workspaceFolder}",
            "reloadAfterAttached": true,
            "runtimeArgs": [ "${workspaceFolder}", "test" ]
        }
    ]
}

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

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

Debugger for NWjs のインストール

VScode左側のプライマリーサイドバーにある、□が四つ固まった感じのアイコンを選んで、Debugger for NWjs を検索してインストールします。

※なんかこれ、一時期必要なくなった気がするんですが、やっぱり必要っぽい(曖昧情報)

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 file) ってボタンを押してダウンロード(または[Raw] ボタン上でコンテキストメニュー開いて[リンク先を別名で保存…])
定義ファイルダウンロード(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 さえ設定しておけばいいはず。
※ VSCode のバージョンアップで d.ts定義ファイルも読み込むようになっているようで、特に設定しなくても動作します(2024年7月現在)

とはいえコア部分と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さんに教えてあげるべきかもしんない)

豆知識

ちなみに、コード保管はデフォルトでtrueになっているので、いじる必要はないんですが、settings.jsonに次の設定をしておくと確実です。

{
    "editor.quickSuggestions": true,
    "editor.suggestOnTriggerCharacters": true,
}

settings.jsonを開くには[表示]-[コマンドパレット…]から、次のコマンドを選びます。

基本設定：ユーザー設定を開く（JSON）
Preferences: Open User Settings (JSON)

コマンドの選び方は、コマンドパレットに、"Settings"とかコマンドの一部を入力すると検索されて候補が並ぶので、そこから選べばOKです。

なお、[Code]-[基本設定]-[設定…]で設定ウィンドウを開いて、"quickSuggestions" "suggestOnTriggerCharacters" で検索して出てくる設定でマウスでポチッと設定することもできます。

その他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』本体のコードからして、過去の資産とのしがらみなどもあって、割とおかしなところが散見されますしね!

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

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