sandbox.config.js の仕様

これは

Akashic の開発環境における設定ファイル、sandbox.config.js の仕様をまとめます。

Akashic で開発されたゲームの動作確認ツールとして、 Akashic Sandbox (akashic-sandbox) と Akashic-cli の serve コマンドがあります。 sandbox.config.js は、これらのツールの機能を取り扱う設定ファイルです。 sandbox.config.js を利用することで、セッションパラメータや起動引数に関わる動作確認を効率化・自動化することができます。

（セッションパラメータの詳細はニコ生ゲーム作成ガイドを参照してください）

形式

sandbox.config.js は JavaScript として実行可能なコードと、export されるモジュールとして記述されます。モジュールは以下の名前のプロパティと、対応する値を持ちます。

events
- オブジェクト (詳細は後述)
- Akashic ゲームで扱う playlog イベントの配列
- Akashic Sandbox、serve コマンドで有効
autoSendEventName
- 文字列
- events のメンバー名のいずれか
- Akashic Sandbox、serve コマンドで有効
showMenu
- 真偽値
- 開始時にデベロッパーメニューを開くかどうか
- Akashic Sandbox で有効
arguments
- オブジェクト (詳細は後述)
- ゲームに渡す起動引数
- serve コマンドで有効
client
- オブジェクト (詳細は後述)
- クライアント環境 (ブラウザなど) のための設定
- serve コマンドで有効

(注意: 旧プロパティの autoSendEvents は非推奨となり将来削除されます。代わりに autoSendEventName を利用してください。)

使い方

game.json と同じディレクトリに、以下のような JavaScript ファイルを置きます。ファイル名は sandbox.config.js とします。

var config = {
}

module.exports = config;

このファイルに以下の名前のプロパティを記述することで、各種設定を利用できます。

events

events には、Akashic ゲームで扱う playlog イベントを事前に記述することができます。特に、ニコ生ゲームを作成する場合に、セッションパラメータの動作確認を行うために利用することができます。

events は、任意のプロパティ名を持ったオブジェクトです。プロパティ名はイベント名として、開発ツールの一覧に表示されます。各プロパティは、送りたい playlog イベントの配列です。

（playlog の詳細な仕様はplaylogを参照してください）

例として、ニコニコ生放送で実行されるゲームにセッションパラメータを送りたい場合、sandbox.config.js には以下のように記述します。

var config = {
    "events": {
        "mySessionParameter": [
            [
                32, // g.MessageEventを示す0x20
                0,
                ":akashic", // プレイヤーID
                {
                    "type":"start", // セッションパラメータであることを示すstart
                    "parameters":{
                        "mode": "ranking",
                        "totalTimeLimit": 75 // タイムリミット
                    }
                }
            ]
        ]
        "myPointDownEvent": [
            [
                33, // g.PointDownEventを示す0x21
                2,
                ":akashic", // プレイヤーID
                0, // ポインターID
                100, // X座標
                100, // Y座標,
                null // エンティティID
            ]
        ]
    }
}

module.exports = config;

Akashic Sandbox では、デベロッパーメニューの Events タブからゲームにイベントを送信することができます。

Akashic Sandboxのデベロッパーメニュー

akashic serve コマンドも同じように、デベロッパーメニューの Events タブからゲームにイベントを送信することができます。

akashic serveコマンドのデベロッパーメニュー

autoSendEventName

ゲーム起動時にイベントを自動送信することができます。イベントはあらかじめ events に記述しておく必要があります。 autoSendEventName にイベント名（例えば startMyGameEvent）を記述し、Akashic Sandbox でゲームを起動すれば、イベントが自動送信されます。

var config = {
    "autoSendEventName": "mySessionParameter"
    "events": {
        "mySessionParameter": {} // 同上のため省略
    }
}

module.exports = config;

showMenu

この項目に true を指定されている場合、常にデベロッパーメニューが開いた状態で Akashic ゲームが実行されます。

var config = {
    "showMenu": true
}

module.exports = config;

arguments

arguments には、起動引数のテンプレートを記述することができます。

serve コマンドに --no-auto-start オプションを指定した場合、Akashic ゲームの実行時に渡したい起動引数を選ぶことができます。

起動引数は Akashic ゲームの起動時に渡される値です。起動引数は Akashic ゲームのエントリポイントの関数（akashic init で生成した場合、main.js から export された関数）のパラメータの第一引数の args プロパティとして渡されます。

起動引数の内容はゲームが実行される環境によって決定されます。 arguments に起動引数を記述することで、serve コマンドで各サービスの動作を確認することができます。

具体的な内容はゲームが実行されるサービスによって決まります。各サービスの動作を確認するために serve でも起動引数を指定して実行することができます。

client

client の external には、外部プラグインを記述することができます。外部プラグインは、 Akashic ゲームの実行環境によって与えられる機能です。

serve コマンドでは、自分でモック実装を用意することで、任意の外部プラグインが存在する状態のゲームを動作確認することができます。

serve の外部プラグインのモック実装を利用するには、オブジェクトを返す関数をエクスポートするファイルを用意する必要があります。例として、console.log() を実行する外部プラグインのモックを作成する場合、./plugin/pluginMock.js を以下のように記述します。

module.exports = () => ({
  return {
    foo: function () { console.log("fooooo");}
  };
});

./plugin/pluginMock.js がある状態で、 game.json と sandbox.config.js に以下の記述がある場合、 serve コマンドで実行した Akashic ゲームは g.game.external.fooPlugin を利用することができます。

game.json

{
    ...
    "environment": {
        "external": {
            "fooPlugin": "0" // この値は現状固定値です
        }
    }
}

sandbox.config.js

var config = {
    "client": {
        "external": {
            "fooPlugin": "./plugin/pluginMock.js"
        }
    }
}
module.exports = config;