拡張ライブラリを使う

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 で利用できるパッケージの条件は、 fshttp などの 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 公式サイト を参照してください。