拡張ライブラリを使う

Akashic Engine に限らず、Node.js では、npm コマンドを利用して自作のパッケージを公開したり、既に公開されているパッケージをダウンロード・インストールすることができます。 Akashic Engine の拡張ライブラリは npm パッケージとして実装できます。ゲーム開発者は npm の仕組みを使うことで、拡張ライブラリを自由に公開・利用することができます。

既に公開されている拡張ライブラリとしては、トゥイーンアニメーションライブラリの akashic-timeline や高機能版テキスト描画エンティティの akashic-label などが挙げられます。

# Akashic コンテンツに拡張ライブラリを追加する

拡張ライブラリは、akashic コマンドの akashic install を利用することでゲームに追加できます。

例えば、コンテンツから akashic-timeline (パッケージ名は @akashic-extension/akashic-timeline) を利用したい場合、game.json の置かれているディレクトリで以下のコマンドを実行します。

akashic install @akashic-extension/akashic-timeline

akashic install コマンドは、内部的に npm install --save -save-exact を実行することで、拡張ライブラリを node_modules ディレクトリにダウンロード・インストールします。さらに、インストールされた拡張ライブラリの情報(ファイルパスなど)を game.json に書き込みます。これは、Akashic コンテンツでは、予めすべてのリソースへのパスが game.json に書き込まれている必要があるためです。これによりコンテンツ内から require() を使って拡張ライブラリを読み込めるようになります。

例として、 akashic-timeline の拡張ライブラリをコンテンツに追加すると、game.json には以下のような記述が追加されます。

"globalScripts": [
    "node_modules/@akashic-extension/akashic-timeline/lib/ActionType.js",
    "node_modules/@akashic-extension/akashic-timeline/lib/Easing.js",
    "node_modules/@akashic-extension/akashic-timeline/lib/Timeline.js",
    "node_modules/@akashic-extension/akashic-timeline/lib/Tween.js",
    "node_modules/@akashic-extension/akashic-timeline/lib/index.js"
],
"moduleMainScripts": {
    "@akashic-extension/akashic-timeline": "node_modules/@akashic-extension/akashic-timeline/lib/index.js"
}

コンテンツからは、以下のようにして拡張ライブラリを読み込めます。

const tl = require("@akashic-extension/akashic-timeline");

akashic-timeline の実際的な使い方は ドキュメント を参照してください。

拡張ライブラリが不要になった場合、 akashic uninstall コマンドを使うことで、拡張ライブラリをコンテンツから削除することができます。

akashic uninstall @akashic-extension/akashic-timeline

このコマンドは、 npm uninstall を実行して拡張ライブラリを削除したのち、game.json から関連する情報を削除します。

誤って npm install コマンドで拡張ライブラリをインストールした場合は、 npm uninstall コマンドで拡張ライブラリを一度アンインストールし、その後 akashic install コマンドで再インストールしてください。

（拡張ライブラリを再インストールしてもインストールしたライブラリを正常に利用できない場合、一度 node_modules ディレクトリを削除して、インストール済みの拡張ライブラリ全体を再インストールしてください。）

# Akashic 向け拡張ライブラリではないパッケージの利用

akashic install コマンドは、Akashic 向けの拡張ライブラリではない npm パッケージもインストールできます。たとえば、シミュレーションゲームで敵キャラクタの移動ルートを決めるために「グラフ探索アルゴリズムを実装した汎用のライブラリパッケージ」を導入して使う、というようなことができます。

ただし、Akashic Engine はそのようなパッケージの動作を保証してはいません。 Akashic Engine で利用できるパッケージの条件は、 fs や http などの Node.js コアモジュールを利用していないこと、 Math.random() を利用していないことです。また、原則的に DOM を利用することもできません。これらは Akashic Engine の動作に意図しない影響を及ぼすため、利用しないでください。

# 注意

akashic install を用いる必要があるのは、「コンテンツの実行時に必要な npm パッケージ」だけであることに注意してください。

実行時に必要ない npm パッケージは、 akashic install ではなく npm install を利用してください。例えば、TypeScript や Browserify などのビルドツールは、通常実行時には利用されません(コンテンツから require() されません)。これらを akashic install してしまうと、不要なファイルが game.json に書き込まれてしまい、ロードに時間がかかる、コンテンツが実行時エラーを起こすなどの問題が生じる場合があります。

ある npm パッケージがコンテンツ実行に必要なのか、ビルドに必要なのかは、package.json の dependencies と devDependencies のどちらに記述するかの違いとして考えることができます。一般には、package.json の dependencies に記述されるものは akashic install を、それ以外は npm install を実行してインストールしてください。 package.json の仕様については、 こちら に詳しい説明があります。

# npm について

npm コマンドの詳細な使い方については、 npm 公式サイト を参照してください。