akashic-cli 利用ガイド

# これは

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 は以下のコマンドを持ちます。

  • akashic init
    • Akashic のゲームとして最低限動作するスクリプトやディレクトリを生成します。
  • akashic modify
    • game.json に記述されている、ゲームの各種メタ情報を更新します。
  • akashic scan
    • game.json に記述されている、ゲームのアセットや各種ライブラリ情報を更新します。
  • akashic serve
    • Akashic のゲームをホストするマルチプレイ動作確認用サーバを起動します。
  • akashic install
    • npm install を行い、追加されたファイルのリストを game.json に加えます。
  • akashic uninstall
    • npm uninstall を行い、削除されたファイルを game.json のリストから取り除きます。
  • akashic update
    • npm update を行い、 node_modules/ 以下の npm パッケージを更新し、ファイルに変更があれば game.json に加えます。
  • akashic export zip
    • ゲームを zip 形式に変換して出力します。
  • akashic export html
    • ゲームを単独で実行可能な HTML ファイル(と画像など)を含むディレクトリを生成します。
  • akashic stat
    • ゲームに関する情報を収集して出力します。

init 以外のコマンドは、init によって生成される game.json を操作・出力・実行します。したがって通常、ゲーム開発時にはまず akashic init を実行し、その後必要に応じて他コマンドを実行することになります。

# 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 オプション

<type> に指定できる値は、 以下の通りです。指定しない場合、 javascript が指定されたものとして扱われます。

  • javascript
  • javascript-minimal
  • javascript-shin-ichiba-ranking
  • typescript
  • typescript-minimal
  • typescript-shin-ichiba-ranking

また、<type>に github:<owner>/<repository> と指定することで GitHub (github.com) からテンプレートを取得することができます。

# javascript

下記のディレクトリ・ファイルを含む JavaScript で書かれたゲームが生成されます。

GAME_HOME
 +- image/
 +- text/
 +- audio/
 +- script/
  +- main.js
 +- game.json
 +- package.json

script/main.js を編集することでゲームの作成が可能です。 これらのディレクトリ・ファイルの詳細は  init で作られるファイル  の節を参照してください。 このゲームではサンプルとして以下のような処理が行われています。

  • スプライトの表示
  • 音を鳴らす
  • タッチイベント定義

# javascript-minimal

最低限の処理しか記述されていない空のゲームが生成されます。 script/main.js を編集することでゲームの作成が可能です。

# javascript-shin-ichiba-ranking

ニコ生ゲームのランキングに対応したゲームの雛形が生成されます。 script/main.js を編集することでゲームの作成が可能です。基本的に script/_bootstrap.js を編集する必要はありません。 このゲームでは、script/main.jsmain 関数の引数 param に以下の値が新たに付与されています。

ランキングモードに対応したニコ生ゲームの作り方については、こちらを参照してください。

# typescript

TypeScript で書かれたゲームと、ビルドに必要なディレクトリ・ファイルが生成されます。 これらをビルドすることで、game ディレクトリ以下に Akashic で動作するゲームを生成します。 ビルドの方法は、生成される README.md を参照してください。

ゲームの内容は、--type javascript を指定した場合に生成されるゲームと同一です。

# typescript-minimal

--type tyepescript と同様に、TypeScript で書かれたゲームと、ビルドに必要なディレクトリ・ファイルが生成されます。

ゲームの内容は、--type javascript-minimal を指定した場合に生成されるゲームと同一です。

# typescript-shin-ichiba-ranking

--type tyepescript と同様に、TypeScript で書かれたゲームと、ビルドに必要なディレクトリ・ファイルが生成されます。

ゲームの内容は、--type javascript-shin-ichiba-ranking を指定した場合に生成されるゲームと同一です。

# GitHub リポジトリからのテンプレート生成

--type github:<owner>/<repository> と指定した場合、GitHub からテンプレートを取得することができます。private repository など認証が必要な場合は akashic configinit.github.protocolssh に設定してください。

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 件目が削除されます。 また、保存されている値とオプションで指定された値が同じ場合は、確認のプロンプトをスキップします。

# modify

akashic modify <target>

game.json に記述されている各種メタ情報を更新します。 <target> に指定できる文字列は以下のとおりです:

  • width <new_width>
    • game.json に記述されたゲーム画面の幅を <new_width> の値(数値)で更新します。
  • height <new_height>
    • game.json に記述されたゲーム画面の高さを <new_height> の値(数値)で更新します。
  • fps <new_fps>
    • game.json に記述されたゲーム画面の FPS を <new_fps> の値(数値)で更新します。

# scan

akashic scan <target>

game.json に記述されているゲームのアセットや各種ライブラリ情報を更新します。 <target> に指定できる文字列は以下のとおりです:

  • asset <subtarget>
    • game.json に記述されたアセット情報を更新します。(<subtarget> の内容は後述)
  • globalScripts
    • カレントディレクトリの node_modules/ 以下のファイル一覧を game.json に加えます。
    • 通常使用する必要はありません。akashic install や uninstall を利用してください。

game.json のアセット情報を更新する scan asset コマンドは、もう一つの引数 <subtarget> によって更新する情報を制御することができます。

akashic scan asset <subtarget>

<subtarget> に指定できる文字列とそれぞれの動作は次のとおりです:

  • image
    • image/ ディレクトリ以下の画像素材を列挙し、アセット情報を更新します。
  • text
    • text/ ディレクトリ以下のテキスト素材を列挙し、アセット情報を更新します。
  • audio
    • audio/ ディレクトリ以下の音素材を列挙し、アセット情報を更新します。
  • script
    • script/ ディレクトリ以下のスクリプト素材を列挙し、アセット情報を更新します。
  • (なし)
    • 上記すべてを行います。
    • さらに assets/ ディレクトリ以下の全種類の素材を列挙してアセット情報を更新します。

game.json の管理しているアセット情報には、ファイルパスだけでなく以下のような情報も含まれます。 したがって素材の増減時だけでなく、これらの変更時にも scan asset コマンドを実行してください。

  • 画像素材の幅・高さ
  • (将来のバージョンにおいて) 音素材の再生時間

scan asset コマンドは、新たに追加するアセット定義に対し、type に応じて以下の初期値を与えます。 (値の詳細はgame.json の仕様を参照してください)

  • "type": "script"
    • "global": true
  • "type": "audio"
    • "systemId": "sound"

scan asset コマンドによる素材の列挙は、ディレクトリを再帰的に検索します。つまり、image/ のサブディレクトリに置かれた画像素材なども、列挙されアセット情報に登録されます。

アセット ID

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/ ディレクトリとアセットパス

assets/ ディレクトリは、上述のとおり全ての種類の素材を置くことができるディレクトリです。

また scan asset コマンドは、assets/ ディレクトリに限り、アセット ID を「ファイル名から拡張子を取り除いたもの」ではなく、ユニークな自動生成の値にします。 そのため title.ogg と title.png など、名前が重複するアセットもそのまま置くことができます。

これによって他のディレクトリよりも柔軟なフォルダ構造で素材を管理できます。

ただし ID が自動生成で不定な値になるので、ゲーム内からアセット ID でアクセスすることはできなくなります。 Akashic Engine v3 以降で利用できる ファイルパスによるアセットアクセス を利用してください。

# serve

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 が自動的に送られるなど、ニコニコ生放送に近い次のような挙動で動作します。

  • 放送者役をいちいち Join させなくてもいいように
    • 起動後、最初に開かれたブラウザウィンドウのプレイヤーを必ず Join させる
    • 「新規プレイ」ボタンでゲームを始める時も、このブラウザウィンドウのプレイヤーを Join させる
    • 「Join Me」ボタンが無効になる
  • コンテンツ起動時に与えられる引数を、ニコニコ生放送と同様のものに
    • 詳細割愛 (通常、ゲーム開発者がこの値を参照する必要はありません)

HTTPS で起動する場合は、--ssl-cert--ssl-key オプションを指定してください。 自己証明書による起動もできますが、OS やブラウザにより証明書を登録する必要などがあり得ます。

また、自己証明書での起動では、node-fetch で自己証明書によるエラーが出ますので、下記のように証明書エラーを無視する環境変数を設定して serve を起動する必要があります。

env NODE_TLS_REJECT_UNAUTHORIZED=0 akashic serve . --ssl-cert <certificatePath> --ssl-key <privatekeyPath>

# install

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 がない場合、利用しないでください。 (意図しないバージョンのパッケージが導入される可能性があります。)

# uninstall

akashic uninstall <module>

npm uninstall --save <module> を行い、削除されたファイルを game.json から取り除きます。

(install コマンド同様、game.json と同じディレクトリに package.json という名前のファイルが存在する必要があります)

# update

akashic update <module>

npm update <module> を行い、./node_modules 以下の npm パッケージを更新します。ファイルの変更は game.json に反映されます。

(install コマンド同様、game.json と同じディレクトリに package.json という名前のファイルが存在する必要があります)

<module> を指定しなかった場合、全ての npm パッケージを更新します。npm update の詳細は npm のドキュメント を参照してください。

# export zip

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 オプションを利用してください。 詳細はニコニコ生放送で遊べるゲームの作成の 投稿 を参照してください。

# export html

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 の仕様 を参照してください。

# stat

akashic stat <target> [options...]

<target> で指定された内容に関して情報を収集して出力します。現在 <target> に与えられるのは size のみです。

# ゲームの容量計算 (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 のように指定します。1KB1024B として計算されます。単位として、B, KB, MB, GB が利用でき、末尾の B は省略できます。

--raw オプションが指定されると、以下のように合計容量のバイト数のみを表示して終了します。

$ akashic stat size --raw
1657274

# init で作られるファイル

# image ディレクトリ

画像素材を配置するディレクトリ。

サポートされる拡張子は png/jpg であり、拡張子と画像フォーマットは一致している必要があります。それ以外の拡張子のファイル、または "." から始まるファイルは無視されます。

# text ディレクトリ

テキスト素材を配置するディレクトリ。

サポートされる拡張子は特に指定がないため、 "." から始まるファイル以外はすべて取り込まれます。 取り込まれないファイルを指定する方法は検討中。

# audio ディレクトリ

音楽、効果音など、音素材を配置するディレクトリ。

サポートされる拡張子は .ogg, .m4a と .aac であり、拡張子とファイルフォーマットは一致している必要があります。それ以外の拡張子のファイル、または "." から始まるファイルは無視されます。

他の素材と異なり、音素材は、ファイル名の拡張子部分のみが異なる複数のファイルをまとめて取り扱います。 ゲームの実行環境に応じて適切な形式が自動的に選択されます。 主要な実行環境をサポートするために、次のいずれかの組み合わせでファイルを置いてください。

  • Ogg Vorbis 形式 (.ogg) と M4A 形式 (.m4a)
  • Ogg Vorbis 形式 (.ogg) と AAC 形式 (.aac)

# script ディレクトリ

スクリプト素材を配置するディレクトリ。

サポートされる拡張子は.js と.json であり、拡張子とファイルフォーマットは一致している必要があります。それ以外の拡張子のファイル、または "." から始まるファイルは無視されます。

慣習として、各 Scene を実装するファイルは、このディレクトリ内に "Scene.js" という接尾辞をつけて配置される事が推奨されます(例: titleScene.js, battleScene.js)。

# main.js ファイル

ゲームの処理が記述されているファイル。

このファイルを編集することによってゲームを作成することが可能です。

# _bootstrap.js ファイル

--type javascript-shin-ichiba-ranking を指定した時(もしくは --type typescript-shin-ichiba-ranking を指定後ビルドした時)のみ作られるファイルです。 このファイルがエントリーポイントとなりますが、ゲーム開発者がこのファイルを編集することは基本的にありません。 ここで行っていることは、以下の通りです。

  • セッションパラメータの取得
  • main.js に自動的に遷移

# game.json ファイル

ゲームの各種情報を記述するファイル。

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 の仕様を参照してください。

# Node.js 開発者向けの追加情報

akashic は、install, uninstall コマンドを除き、package.json に関知しません。

ゲーム開発者は、npm install --save-dev jasmine して spec ディレクトリにテストを配置するなど、任意の開発フローを(Akashic のディレクトリ構成と衝突するなどの問題がない限り)とることができます。