Akashic でのゲーム開発を補助するコマンドラインツール、akashic コマンドの仕様と利用法を解説します。 akashic コマンドは akashic-cli をインストールして使用することができます。この利用ガイドで解説する akashic-cli の対象バージョンは 1.0.8 以降です。
斜体は検討中の箇所です。
akashic コマンド は、Node.js 環境で動作します。各プラットフォームで、適当な方法で Node.js をインストールしてください。この利用ガイドでは、 LTS 版の Node.js 環境を前提に説明を進めます。執筆時点での LTS 版のバージョンは 8.11.3 です。
Windows や Mac のユーザであれば、Node.js の公式 Web サイト から適切なパッケージをダウンロードし、インストールすることができます。
npm install -g @akashic/akashic-cli
無事にインストールができていれば、以下のコマンドが実行できるようになっています。実行すると、akashic コマンドの簡単なヘルプが表示されます。
$ akashic
akashic
は以下のコマンドを持ちます。
node_modules/
以下の npm パッケージを更新し、ファイルに変更があれば game.json に加えます。init 以外のコマンドは、init によって生成される game.json を操作・出力・実行します。したがって通常、ゲーム開発時にはまず akashic init を実行し、その後必要に応じて他コマンドを実行することになります。
akashic init [<options>]
新しく Akashic で動作するゲームをカレントディレクトリに生成します。
このコマンドを実行すると、以下のような対話型のインターフェースが表示され、ゲーム画面の幅・高さおよびゲームの FPS を入力できます。
$ npm install -g @akashic/akashic-cli
$ cd GAME_HOME
$ akashic init
width: (320)
height: (320)
fps: (30)
また、本コマンドは、カレントディレクトリが空でない場合、エラーで失敗することがあります。 (生成されるファイル・ディレクトリが既に存在する場合、エラーでコマンドが失敗します)。
<options>
に指定可能なオプションは次のとおりです。
オプション | 短縮名 | 効果 | デフォルト値 |
---|---|---|---|
--type <type> |
-t |
<type> の値に応じたゲームが作成されます。詳細については後述します。 |
javascript |
--force |
-f |
生成されるファイル・ディレクトリが既に存在する場合でも、エラーにせず上書きします。 | 指定なし |
--yes |
-y |
対話型インターフェースを表示せずに、デフォルトの設定でゲームを生成します。 | 指定なし |
--list |
-l |
--type オプションで利用可能なテンプレートのリストを表示します。 |
指定なし |
--repository <reponame> |
-r |
テンプレートを検索できるリポジトリを指定します。 | 指定なし |
<type> に指定できる値は、 以下の通りです。指定しない場合、 javascript
が指定されたものとして扱われます。
javascript
javascript-minimal
javascript-shin-ichiba-ranking
typescript
typescript-minimal
typescript-shin-ichiba-ranking
また、<type>に github:<owner>/<repository>
と指定することで GitHub (github.com) からテンプレートを取得することができます。
下記のディレクトリ・ファイルを含む JavaScript で書かれたゲームが生成されます。
GAME_HOME
+- image/
+- text/
+- audio/
+- script/
+- main.js
+- game.json
+- package.json
script/main.js
を編集することでゲームの作成が可能です。
これらのディレクトリ・ファイルの詳細は init で作られるファイル の節を参照してください。
このゲームではサンプルとして以下のような処理が行われています。
最低限の処理しか記述されていない空のゲームが生成されます。
script/main.js
を編集することでゲームの作成が可能です。
ニコ生ゲームのランキングに対応したゲームの雛形が生成されます。
script/main.js
を編集することでゲームの作成が可能です。基本的に script/_bootstrap.js
を編集する必要はありません。
このゲームでは、script/main.js
の main
関数の引数 param
に以下の値が新たに付与されています。
param.sessionParameter
: セッションパラメータランキングモードに対応したニコ生ゲームの作り方については、こちらを参照してください。
TypeScript で書かれたゲームと、ビルドに必要なディレクトリ・ファイルが生成されます。 これらをビルドすることで、game ディレクトリ以下に Akashic で動作するゲームを生成します。 ビルドの方法は、生成される README.md を参照してください。
ゲームの内容は、--type javascript
を指定した場合に生成されるゲームと同一です。
--type tyepescript
と同様に、TypeScript で書かれたゲームと、ビルドに必要なディレクトリ・ファイルが生成されます。
ゲームの内容は、--type javascript-minimal
を指定した場合に生成されるゲームと同一です。
--type tyepescript
と同様に、TypeScript で書かれたゲームと、ビルドに必要なディレクトリ・ファイルが生成されます。
ゲームの内容は、--type javascript-shin-ichiba-ranking
を指定した場合に生成されるゲームと同一です。
--type github:<owner>/<repository>
と指定した場合、GitHub からテンプレートを取得することができます。private repository など認証が必要な場合は akashic config
で init.github.protocol
を ssh
に設定してください。
akashic config set init.github.protocol ssh # 初回のみ。認証を必要としない場合は不要。
akashic init -t github:your-orgs/your-repo
また ghe:<owner>/<repository>
と指定することで GitHub Enterprise からテンプレートを生成できます。 GitHub Enterprise の URL は akashic config
により設定できます。
akashic config set init.ghe.host your.company.com # 初回のみ
akashic init -t ghe:your-orgs/your-repo
akashic init では以下の設定を利用します。設定は akashic config
コマンドを利用して行います。
プロパティ名 | 内容 | デフォルト値 |
---|---|---|
init.repository | テンプレート配信サーバの URL。空文字列の時はサーバを利用しません。 | 空文字列 |
init.defaultTemplateType | テンプレートの種類が省略されたときに利用するテンプレート名。 | javascript |
init.localTemplateDirectory | ローカルファイルシステムでテンプレートを保存する場所。 | $HOME/.akashic-templates/ |
init.github.host | GitHub のホスト名。 | github.com |
init.github.protocol | GitHub からプロジェクトを clone する際のプロトコル。https または ssh が指定可能。 | https |
init.ghe.host | GitHub Enterprise のホスト名。 | 指定なし |
init.ghe.protocol | GitHub Enterprise からプロジェクトを clone する際のプロトコル。https または ssh が指定可能。 | https |
-t gihtub:
や ghe:
、-r
オプションで URL へアクセスする場合はプロンプトにて確認を行います。
プロンプトにて URL へのアクセスを許可した場合は、$HOME/.akashicrc
へ最大 4 件保存します。5 件目を保存する場合は、最初の 1 件目が削除されます。
また、保存されている値とオプションで指定された値が同じ場合は、確認のプロンプトをスキップします。
akashic modify <target>
game.json に記述されている各種メタ情報を更新します。 <target> に指定できる文字列は以下のとおりです:
akashic scan <target>
game.json に記述されているゲームのアセットや各種ライブラリ情報を更新します。 <target> に指定できる文字列は以下のとおりです:
game.json のアセット情報を更新する scan asset コマンドは、もう一つの引数 <subtarget> によって更新する情報を制御することができます。
akashic scan asset <subtarget>
<subtarget> に指定できる文字列とそれぞれの動作は次のとおりです:
game.json の管理しているアセット情報には、ファイルパスだけでなく以下のような情報も含まれます。 したがって素材の増減時だけでなく、これらの変更時にも scan asset コマンドを実行してください。
scan asset コマンドは、新たに追加するアセット定義に対し、type に応じて以下の初期値を与えます。 (値の詳細はgame.json の仕様を参照してください)
scan asset コマンドによる素材の列挙は、ディレクトリを再帰的に検索します。つまり、image/ のサブディレクトリに置かれた画像素材なども、列挙されアセット情報に登録されます。
Akashic コンテンツから各アセットにアクセスするには、アセットを識別する ID (アセット ID) またはファイルパス (Akashic Engine v3 以降) を利用します。
scan asset コマンドは、アセット ID として通常「ファイル名から拡張子を取り除いたもの」を登録します。
このため audio/title.ogg と script/title.js は、同じ "title" という ID となって衝突し、エラーになることに注意してください。 この制限を回避するため、 Akashic Engine v3 以降では assets/ ディレクトリ (後述) を利用できます。
またアセットのファイル名は以下の条件を全て満たす必要があります。
ユーザは game.json を直接編集して、アセット ID を任意に変更することができます。 akashic コマンドはファイルパスを基準に操作を行うため、たとえば画像素材の ID を変更した後にその画像のサイズを変更しても、適切に game.json の幅・高さ情報が更新されます。
assets/ ディレクトリは、上述のとおり全ての種類の素材を置くことができるディレクトリです。
また scan asset コマンドは、assets/ ディレクトリに限り、アセット ID を「ファイル名から拡張子を取り除いたもの」ではなく、ユニークな自動生成の値にします。 そのため title.ogg と title.png など、名前が重複するアセットもそのまま置くことができます。
これによって他のディレクトリよりも柔軟なフォルダ構造で素材を管理できます。
ただし ID が自動生成で不定な値になるので、ゲーム内からアセット ID でアクセスすることはできなくなります。 Akashic Engine v3 以降で利用できる ファイルパスによるアセットアクセス を利用してください。
akashic serve [<options>] [<path>]
<path>
ディレクトリ(省略時はカレントディレクトリ)にあるゲームをホストする、マルチプレイ動作確認用サーバを起動します。
起動後に表示される URL(デフォルトでは http://localhost:3300/
)を Web ブラウザで開いてください。
<options>
に指定可能なオプションは次のとおりです。
オプション | 短縮名 | 効果 | デフォルト値 |
---|---|---|---|
--hostname <hostname> |
-H |
起動するサーバのホスト名を指定します。 | localhost |
--port <port> |
-p |
起動するサーバのポート番号を指定します。 | 3300 |
--verbose |
-v |
詳細情報をログ出力します。 | false |
--no-auto-start |
-A |
ブラウザ画面を開いた時、コンテンツに引数を渡す起動画面を表示します。 | 指定なし |
--target-service <name> |
-s |
指定されたサービスの挙動を模擬します。(後述) | none |
--watch |
-w |
アセットディレクトリを監視し、変更時に新規プレイを作成します。 | 指定なし |
--server-external-script <filepath> |
N/A | 指定ファイルの js を評価し、アクティブインスタンスの g.game.external に代入します。 | 指定なし |
--debug-playlog <path> |
N/A | 指定した playlog.json を読み込みます(エンジン開発用、または開発中のオプションです)。 | 指定なし |
--allow-external |
N/A | sandbox.config.js からの外部アクセスを許可する URL を読み込みます。 | 指定なし |
--no-open-browser |
N/A | 起動時にブラウザを開かないようにします。 | 指定なし |
--preserve-disconnected |
N/A | サーバとの切断時に子ウィンドウを閉じないようにします。 | 指定なし |
--experimental-open <num> |
N/A | 指定数の子ウィンドウを開いて起動します。 | 指定なし |
--ssl-cert <certificatePath> |
N/A | HTTPS で起動するための SSL 証明書のパスを指定します。 | 指定なし |
--ssl-key <privatekeyPath> |
N/A | HTTPS で起動するための 秘密鍵のパスを指定します。 | 指定なし |
--cors-allow-origin <origin> |
N/A | Access-Control-Allow-Origin レスポンスヘッダーの値を指定します。 | 指定なし |
ネットワークごしに(他の PC などから)マルチプレイを行いたい場合は、 --hostname
に外部からアクセス可能なホスト名(IP アドレスなど)を指定してください。
オプション --target-service
には下記の値を指定できます。
nicolive
: ニコニコ生放送none
: なし (デフォルト値)nicolive
が指定された場合、特定の条件で JoinEvent
が自動的に送られるなど、ニコニコ生放送に近い次のような挙動で動作します。
HTTPS で起動する場合は、--ssl-cert
と --ssl-key
オプションを指定してください。
自己証明書による起動もできますが、OS やブラウザにより証明書を登録する必要などがあり得ます。
また、自己証明書での起動では、node-fetch
で自己証明書によるエラーが出ますので、下記のように証明書エラーを無視する環境変数を設定して serve を起動する必要があります。
env NODE_TLS_REJECT_UNAUTHORIZED=0 akashic serve . --ssl-cert <certificatePath> --ssl-key <privatekeyPath>
akashic install [<module>]
npm install
のラッパーコマンドです。
<module>
を与えた場合、 npm install --save <module>
を行い、また導入されたファイルの一覧を game.json に加えます。すなわち次のコマンドと概ね等価な振る舞いをします。
npm install --save <module>
akashic scan globalScripts
@akashic-extension/ で提供される Akashic 向けの拡張機能の他、任意の npm パッケージをゲームに導入することができます。
注意: Akashic は Node.js のコアモジュール(
http
,path
など)をサポートしていません。コアモジュールに依存しているパッケージを導入した場合、エラーメッセージが表示されます。この場合、npm install
は行われ、game.json も更新されますが、ゲームとして実行しようとするとエラーになります。
またブラウザ固有の機能や、ECMAScript の一部機能 (
Math.random()
のような内部状態を持つ機能など) は、 Akashic のゲームとしてはサポートされていません。それらの機能を用いる npm パッケージを導入しないでください。 (akashic コマンド はこれにエラーを出すことはできません。)
このコマンドは npm install
を行うため、game.json と同じディレクトリに package.json という名前のファイルが存在する必要があります。事前に npm init
を行うなどの方法で作成してください。
(akashic init
が提供するビルトインのテンプレートには含まれています。)
<module>
を省略した場合、単に npm install
を行います。
(package.json に依存生が記録されたパッケージが導入されます。)
game.json は更新されません。package-lock.json がない場合、利用しないでください。
(意図しないバージョンのパッケージが導入される可能性があります。)
akashic uninstall <module>
npm uninstall --save <module>
を行い、削除されたファイルを game.json から取り除きます。
(install コマンド同様、game.json と同じディレクトリに package.json という名前のファイルが存在する必要があります)
akashic update <module>
npm update <module>
を行い、./node_modules 以下の npm パッケージを更新します。ファイルの変更は game.json に反映されます。
(install コマンド同様、game.json と同じディレクトリに package.json という名前のファイルが存在する必要があります)
<module>
を指定しなかった場合、全ての npm パッケージを更新します。npm update の詳細は npm のドキュメント を参照してください。
akashic export zip [--output <fileName>]
ゲームディレクトリを zip 形式で圧縮したファイルを <fileName>
に出力します。
--output
オプションが指定されなかった場合、 ./game.zip
が指定されたかのように振る舞います。存在するファイル名・ディレクトリ名を指定した場合、エラーになります。
利用可能なオプションは次のとおりです:
オプション | 効果 | デフォルト値 |
---|---|---|
--output <fileName> |
出力するファイルを <fileName> にする |
game.zip |
--bundle |
スクリプトアセットを 1 つのファイルにまとめる | 指定なし |
--minify |
スクリプトアセットを minify する | 指定なし |
--hash-filename |
ファイル名を難読化する | 指定なし |
--no-strip |
ゲーム実行に不要なファイルを出力から除外しない | 指定なし |
--no-es5-downpile |
JavaScript を ES5 に変換しない | 指定なし |
--no-omit-empty-js |
空のスクリプトファイルを出力を省略しない | 指定なし |
--no-omit-unbundled-js |
--bundle オプションが指定されている場合でも不要なスクリプトファイルを除外しない |
指定なし |
--nicolive |
ニコ生ゲームの投稿用に出力する | 指定なし |
ニコ生ゲームに投稿する場合には --nicolieve
オプションを利用してください。
詳細はニコニコ生放送で遊べるゲームの作成の 投稿 を参照してください。
akashic export html --output <dirName> [--bundle] [--minify] [--magnify] [--no-strip]
単独でゲームを実行可能な HTML ファイル (と関連ファイル) を含むディレクトリを出力します。出力されたディレクトリの index.html を Web ブラウザで開くことで、 akashic-sandbox などの動作確認ツールなしにゲームを実行できます。
利用可能なオプションは次のとおりです:
オプション | 効果 | デフォルト値 |
---|---|---|
--output <dirName> |
出力するフォルダを <dirName> にする |
N/A |
--bundle |
スクリプトアセットやテキストアセットなど、可能なものを index.html にまとめる | 指定なし |
--minify |
スクリプトアセットを minify する | 指定なし |
--magnify |
ゲーム画面をブラウザのウィンドウサイズに合わせて拡縮するようにする | 指定なし |
--inject <fileName> |
出力 HTML の head 要素に <fileName> の内容を含める |
指定なし |
--no-strip |
ゲーム実行に不要なファイルを出力から除外しない (通常は使用しないでください) | 指定なし |
--hash-filename |
アセットファイル名を難読化する | 指定なし |
--auto-send-event-name <eventName> |
ゲーム開始時に自動的に送信されるイベント名を指定する | 指定なし |
--no-omit-unbundled-js |
不要なスクリプトファイルを除外しない | 指定なし |
--inject
オプション(akashic-cli@1.3.1
で導入)は複数指定可能です。指定した順でファイルの内容が出力されます。ディレクトリ名も指定でき、その場合はディレクトリ内の全ファイルが出力されます(順不同)。
--output
オプションに存在するファイル名・ディレクトリ名を指定した場合、エラーになります。またゲームのディレクトリ以下のパスを指定することはできません。たとえば game.json のあるディレクトリで次のように指定するとエラーになります。
$ akashic export html --output ./bundled # エラー
./bundled
ではなく ../bundled
にするなど、ゲームのディレクトリの外を指定してください。この場合、 ../bundled/index.html
を Web ブラウザで開くと、単独でゲームを実行できます。
(ゲーム実行には ../bundled/
以下のファイルがすべて必要である点に注意してください)
$ akashic export html --output ../bundled
--auto-send-event-name <eventName>
オプションを指定する場合、 sandbox.config.js
が必要となります。
sandbox.config.js
については sandbox.config.js の仕様 を参照してください。
akashic stat <target> [options...]
<target>
で指定された内容に関して情報を収集して出力します。現在 <target>
に与えられるのは size
のみです。
<target>
に size
を指定すると、ゲームの容量を計算します。ゲームの容量とはゲームを配信する際にネットワーク通信が必要なコンテンツのファイルサイズの合計のことです。
何もオプションを付けずに実行した場合、以下のように表示されます。
$ akashic stat size
image: 415.49KB (84%)
text: 25.60KB (5%)
ogg audio: 47.74KB
mp4 audio: 53.02KB (11%)
aac audio: 52.71KB
script: 641B (0%)
other: 1.44KB (0%)
game.json: 1.44KB
[ ] TOTAL SIZE (using ogg): 490.90KB (502685B)
[*] TOTAL SIZE (using mp4): 496.19KB (508096B)
[ ] TOTAL SIZE (using aac): 495.87KB (507775B)
オーディオは mp4 と aac と ogg のうち合計容量が大きいものを利用して計算します。結果表示の (87%)
の部分は全体用量に占めるそのカテゴリのファイルの割合を示しています。
game.json
, node_moduels/
以下のスクリプトは other
に分類されます。
--limit
オプションが指定されると、ゲームの容量が指定された値を超えた場合にエラーと表示され、コマンド自体の戻り値が正常終了時の 0
ではなく 1
になります。
容量は --limit 100KB
のように指定します。1KB
は 1024B
として計算されます。単位として、B
, KB
, MB
, GB
が利用でき、末尾の B
は省略できます。
--raw
オプションが指定されると、以下のように合計容量のバイト数のみを表示して終了します。
$ akashic stat size --raw
1657274
画像素材を配置するディレクトリ。
サポートされる拡張子は png/jpg であり、拡張子と画像フォーマットは一致している必要があります。それ以外の拡張子のファイル、または "." から始まるファイルは無視されます。
テキスト素材を配置するディレクトリ。
サポートされる拡張子は特に指定がないため、 "." から始まるファイル以外はすべて取り込まれます。 取り込まれないファイルを指定する方法は検討中。
音楽、効果音など、音素材を配置するディレクトリ。
サポートされる拡張子は .ogg, .m4a と .aac であり、拡張子とファイルフォーマットは一致している必要があります。それ以外の拡張子のファイル、または "." から始まるファイルは無視されます。
他の素材と異なり、音素材は、ファイル名の拡張子部分のみが異なる複数のファイルをまとめて取り扱います。 ゲームの実行環境に応じて適切な形式が自動的に選択されます。 主要な実行環境をサポートするために、次のいずれかの組み合わせでファイルを置いてください。
スクリプト素材を配置するディレクトリ。
サポートされる拡張子は.js と.json であり、拡張子とファイルフォーマットは一致している必要があります。それ以外の拡張子のファイル、または "." から始まるファイルは無視されます。
慣習として、各 Scene を実装するファイルは、このディレクトリ内に "Scene.js" という接尾辞をつけて配置される事が推奨されます(例: titleScene.js, battleScene.js)。
ゲームの処理が記述されているファイル。
このファイルを編集することによってゲームを作成することが可能です。
--type javascript-shin-ichiba-ranking
を指定した時(もしくは --type typescript-shin-ichiba-ranking
を指定後ビルドした時)のみ作られるファイルです。
このファイルがエントリーポイントとなりますが、ゲーム開発者がこのファイルを編集することは基本的にありません。
ここで行っていることは、以下の通りです。
ゲームの各種情報を記述するファイル。
akashic init --type javascript-minimal
を実行した直後は以下のような内容になっています。
(ただし width, height, fps は init で指定した値)
{
"width": 480,
"height": 480,
"fps": 30,
"assets": {
"mainScene": {
"type": "script",
"path": "script/main.js",
"global": true
}
}
}
詳細な仕様はgame.json の仕様を参照してください。
akashic は、install, uninstall コマンドを除き、package.json に関知しません。
ゲーム開発者は、npm install --save-dev jasmine して spec ディレクトリにテストを配置するなど、任意の開発フローを(Akashic のディレクトリ構成と衝突するなどの問題がない限り)とることができます。