表示モード

game.json の仕様 ​

これは ​

Akashic のゲームにおいてメタ情報などを取り扱う設定ファイル、game.json の仕様をまとめます。対象バージョンは akashic-engine@1.11.2 以降です。

game.json とは ​

game.json は、Akashic のゲームのメタ情報などを取り扱う JSON 形式の設定ファイルです。主に以下のような情報を取り扱います。

  • ゲーム画面のサイズ
  • ゲームの FPS
  • ゲーム内で利用する各種素材のファイルパスや ID

これらに加えて、画像素材のサイズのような補助的な情報も取り扱います。

各種素材(アセット)のファイルパスや画像のサイズなどは、手動で記述・維持しにくいので、 game.json を生成・管理するツールとして akashic-cli が提供されています。 akashic-cli の詳細は リファレンス » akashic-cli を参照してください。

形式 ​

妥当な game.json の内容は一つのオブジェクトです。それは以下の名前のプロパティと、対応する値を持ちます。

キー名必須値内容
"width"必須数値画面の幅 (ピクセル)
"height"必須数値画面の高さ (ピクセル)
"fps"必須数値ゲームの FPS (秒間フレーム数)
"assets"必須オブジェクトゲーム内で利用するアセットの定義
"main"必須文字列エントリポイントのスクリプトのパス
"globalScripts"省略可文字列の配列スクリプトアセット定義の短縮表記
"renderers"省略可文字列またはオブジェクトの配列ゲームが利用するレンダラーの設定
"defaultSkippingScene"省略可文字列早送り中の描画方法
"defaultLoadingScene"省略可文字列デフォルトのローディングシーンの設定
"environments"省略可オブジェクトこのゲームが実行環境に要求する条件
"maxPoints"省略可数値ゲーム内で受け取る最大同時タップ数
"moduleMainScripts"省略可オブジェクト(廃止予定) require() 解決のためのモジュールのエントリポイントのテーブル
"moduleMainPaths"省略可オブジェクトrequire() 解決のためのモジュールのエントリポイントのテーブル

次の JSON は、妥当な game.json の一例です:

json
{
  "width": 320,
  "height": 240,
  "fps": 30,
  "assets": {
    "main": {
      "type": "script",
      "path": "script/main.js",
      "global": true
    }
  },
  "main": "./script/main.js"
}

この game.json は、画面サイズが 320x240 で FPS が 30 の、 "script/main.js" というゲームスクリプト一つだけを使うゲームであること、またエントリポイントはその "./script/main.js" であることを定義しています。

width ​

width は、ゲーム画面の幅 (ピクセル) です。

height ​

height は、ゲーム画面の高さ (ピクセル) です。

fps ​

fps は、ゲーム画面の秒間フレーム数 (FPS) です。 1 以上 60 以下の整数でなければなりません。

assets ​

assets は、アセット定義のテーブルです。

game.json のオブジェクト中、 assets の値は、オブジェクトでなければなりません。そのオブジェクトの各キーはアセット ID、値はその ID のアセット定義です。

アセット ID は、ゲーム開発者が任意に設定できる文字列です。アセット ID は「半角英数字、アンダースコア "_"、ドル記号 "$"」のみで構成され、かつ「英字で始まっている」必要があります。あるシーンで読み込んだアセットは g.Scene#assets オブジェクトから参照できます。アセット ID はこのオブジェクトのキーとして利用されます。すなわち、アセット ID が "foo" のアセットは、scene.assets["foo"] のような形で参照することができます。

TIP

ただし現実的には akahsic scan asset コマンドが自動的に設定するため、ゲーム開発者が直接指定することは稀でしょう。 assets/ ディレクトリを利用していない場合、ファイル名が衝突した場合には自力で編集する必要がありえます。

アセット定義 は、オブジェクトであり、少なくとも以下の値を持つことができます:

キー名必須値内容
"type"必須文字列アセットの種類。次のいずれか: "image", "audio", "text", "script", "vector-image", "binary" (ただし "binary" は試験中)。
"path"必須文字列アセットのパス。game.json のあるディレクトリからの相対パス (スラッシュ区切り) 。
"global"省略可真理値グローバルアセットであるか否か (省略された場合、偽) 。

global の値が真に設定されたアセットは、グローバルアセット になります。通常のアセットはシーン単位で管理されるため、 g.Scene のコンストラクタでそのアセット ID を指定して読み込む必要があります。一方グローバルアセットは、シーンに関係なく常に利用可能なアセットになります。通常のアセットが g.Scene#assets から参照できるのに対して、グローバルアセットは g.Game#assets から参照できます。

TIP

なお Akashic Engine v3 以降では、より柔軟な API を提供する g.Scene#asset, g.Game#asset (s がないことに注意) も利用できます。

type の値によっては、アセット定義にさらに追加の制約や必須プロパティが存在します。

type: "image" ​

画像アセットの定義です。

"path" の拡張子は .png, .jpg, .jpeg のいずれかでなければなりません。

次のプロパティが追加で存在します。

キー名必須値内容
"width"必須数値画像の幅 (ピクセル)。
"height"必須数値画像の高さ (ピクセル)。
"slice"省略可オブジェクト
または配列		切り出す領域。指定された場合、画像ファイルの指定領域だけを画像アセットとして使う。
値は { x, y, width, height } (すべて数値) のオブジェクトか、 [x, y, width, height] (すべて数値) の配列。

type: "audio" ​

音声アセットの定義です。

"path" の値はファイルパスから 拡張子を取り除いたもの でなければなりません。 また対応するファイルの拡張子は .ogg, .m4a または .aac でなければなりません。

次のプロパティが追加で存在します。

キー名必須値内容
"systemId"必須文字列音声の種類。 "music" (BGM、ループ再生される) または "sound" (効果音、ループ再生されない) 。
省略された場合、 "sound" 。
"duration"必須数値再生時間。単位はミリ秒。
"loop"省略可真理値ループ再生を行うか。省略時は "systemId" から決まるため、通常ゲーム開発者が指定する必要はない。
"offset"省略可数値再生開始位置。単位はミリ秒。省略された場合、 0 。ただしループ再生するアセットでの動作は保証されない。
"hint"省略可オブジェクトエンジンに与える音声ファイルのヒント情報。

hint は次のプロパティを指定できるオブジェクトです。

キー名必須値内容
"streaming"省略可真理値ストリーミング再生が適しているアセットであるか否か。
"extensions"省略可配列ファイルの拡張子の配列 (拡張子には . を含む)。省略された場合、 [".ogg", ".aac"] 。特に .m4a を利用する場合は必須。

オーディオアセットは他と異なり、ファイルパスに拡張子を書かないことに気をつけて下さい。 音素材に関して、拡張子以外の部分が同名のファイル (e.g. "audio/foo.ogg" と "audio/foo.m4a" など) は、それぞれ同じ内容であることが期待されます。 これはエンジンが、ゲームの各実行環境で再生可能な形式のファイルを自動的に選択して再生するためです。

INFO

厳密には、"systemId" の初期値は "sound" 固定ではなく、g.Game#defaultAudioSystemId で制御できます。 必要になることはまずないでしょう。

type: "text" ​

テキストアセットの定義です。

固有の制約や追加のプロパティはありません。

type: "script" ​

スクリプトアセットの定義です。

"path" の拡張子は .js でなければなりません。

次のプロパティが追加で存在します。

キー名必須値内容
"preload"省略可真理値他のアセットよりも優先して読み込むかどうか。真であるアセットは、エントリポイントよりも先行して読み込まれる。preload 同士の優先順位は不定。
"exports" (試験中)省略可配列このアセットが公開する変数名の配列。指定された場合、 module.exports の対応するキーが上書きされる。

type: "vector-image" ​

ベクタ画像アセット (試験中) の定義です。

次のプロパティが追加で存在します。

キー名必須値内容
"width"必須数値画像の幅 (ピクセル)。
"height"必須数値画像の高さ (ピクセル)。

main ​

akashic-engine@1.2.0 で導入。

main は、ゲームのエントリポイントとなるスクリプト( main スクリプト )を指定する値です。

指定されたスクリプトは、アセット定義 (assets) でグローバルなスクリプトアセットとして定義されていなければなりません。エンジンはグローバルアセットの読み込み後、この値で require() を呼び出し、その戻り値をエントリポイントとみなして実行します。 (require() する関係上、アセット定義の path と異なり、相対パスは "./" で始める必要がある点に気をつけて下さい。)

main スクリプトは、次の仕様を満たす関数をエクスポートする必要があります。

  • 引数 param: g.GameMainParameterObject を受け取り、値を返さない ((param: g.GameMainParameterObject) => void)
  • 呼び出された時、 g.Game#pushScene() によるシーンの追加など、ゲームの初期化処理を行う

INFO

akashic-engine@1.2.0 以降の v1 系および v2 系エンジンでは、後方互換性のため main を省略することができます。指定されていない場合、以下のような内容の main スクリプトが与えられたかのように振る舞います。

js
module.exports = function (param) {
  if (!param.snapshot) {
    var mainSceneFun = require("mainScene");
    g.game.pushScene(mainSceneFun());
  } else {
    var snapshotLoader = require("snapshotLoader");
    snapshotLoader(param.snapshot);
  }
};

この場合、assets は少なくとも "mainScene" という名前のキーを持つ必要があります。アセット ID "mainScene" を持つアセットは、type が "script" で global は true、すなわちグローバルなスクリプトアセットでなければなりません。

この挙動は akashic-engine@3.0.0 で削除されました。

(上の例では require()にアセット ID を渡していることに気をつけてください。 akashic-engine の提供する require()は、Node.js などのそれと異なり、game.json に存在するアセット ID を(優先的に)解決します。これは歴史的経緯によるものです。上の例では説明のために使っていますが、この動作の利用は非推奨です。)

globalScripts ​

akashic-engine@0.1.0 で導入。

globalScripts は、スクリプトアセットの短縮記法です。これは akashic install/uninstall のために用意された値です。通常ゲーム開発者が編集する必要はありません。

存在する場合、globalScripts はファイルパスの配列でなければなりません。ファイルパスは game.json のあるディレクトリからの相対パスで、拡張子が ".js" または ".json" である必要があります。

ここに書かれたファイルパスは、アセット ID を持たないグローバルなスクリプトアセット (".js" の場合) またはテキストアセット (".json" の場合) として読み込まれます。 (アセット ID を持たないアセットは通常、定義も利用もできませんが、スクリプトアセットおよび JSON であるテキストアセットに限っては require() によってファイルパスで参照することができます)

renderers ​

akashic-engine@1.0.3 で導入。

renderers は、利用するレンダラーを指定するリストです。 値は文字列 (レンダラー識別子) の配列である必要があります。 エンジンはリストを先頭から探索し、最初に見つかった利用可能なレンダラー実装を利用します。

サービスや実行環境により特に制限がなければ、以下のレンダラー識別子が利用できます。

レンダラー識別子内容
"canvas"(ブラウザでは) CanvasRenderingContext を利用する実装
"webgl"(ブラウザでは) WebGL を利用する実装。
file:// スキームでは動作しない。
"auto"環境ごとのデフォルトのレンダラー実装

どのレンダラーでも原則同じ描画結果になりますが、一部の機能はレンダラーによって利用できないことがあります。

game.json に renderers を定義しなかった場合は "renderers": ["auto"] を指定した場合と等価になります。

WARNING

"webgl" は file:// スキームでは動作しません。

特に akashic export html で出力した HTML を、そのまま Web ブラウザで表示すると file:// になるので注意してください (エクスプローラでダブルクリックして開いた場合など) 。 HTTP サーバでホストして http:// や https:// でアクセスする場合は問題ありません。

defaultLoadingScene ​

defaultLoadingScene は、グローバルアセット読み込み中のローディングシーンなど、デフォルトのローディングシーンについての設定です。 akashic-engine@1.11.2 では "default" または "none" を指定できます。 "default" を指定または省略時はエンジンに用意されているデフォルトのローディングシーンを表示します。 "none" を指定するとそれらのローディングシーンを非表示にできます。

akashic-engine@3.0.0 で "compact" が導入されました。 "compact" を指定すると背景が透過になり、プログレスバーが画面中央ではなく右下の方に小さく表示されます。

defaultSkippingScene ​

defaultSkippingScene は、早送り中の描画についての設定です。 akashic-engine@3.4.0 では "fast-forward", "indicator", "none" を指定できます。 "fast-forward" を指定、または省略した場合は早送り中のゲーム状態をそのまま描画します。 "indicator" を指定すると早送り中はエンジンに用意されている専用のスキッピングシーンを描画します。 "none" を指定すると早送り中の描画を非表示にできます。

environment ​

akashic-engine@2.0.0 で導入。

environment は、ゲームを実行する環境やエンジンに対する要求を指定するためのオブジェクトです。オブジェクトのキーは要求の種類、値は要求内容です(必要なバージョンなど)。

次の値が利用できます。

キー値説明
"sandbox-runtime""1","2" または "3"akashic sandbox や akashic serve でゲームを実行する際、実行するエンジンのバージョンを決定するために利用されます。
Akashic Engine v3 系で作成しているゲームの場合は "3" を、v2 系の場合 "2" を指定してください。省略された場合、 "1" として解釈されます。
"nicolive"オブジェクトニコ生ゲームとして登録する場合の設定。詳細は ニコ生ゲームを作ろう » ニコ生ゲーム関連の仕様 を参照してください。
"niconico"オブジェクト非推奨。後方互換性のために残されています。 "nicolive" を利用してください。
"external"オブジェクトプラグインなどの外部 API を利用する際の設定。通常、ゲーム開発者が編集する必要はありません。
akashic serve コマンドは、プラグインの動作確認のためにこの値を参照することがあります。詳細は リファレンス » sandbox.config.js の仕様 を参照してください。
json
  "environment": {
    "sandbox-runtime": "3"
  }

"sandbox-runtime" の値は、 akashic export html でエンジンをバンドルした HTML を出力する際にも参照されます。

maxPoints ​

akashic-engine@3.9.3 で導入。

ゲーム内での最大同時タップ数を指定します。 タッチデバイス等でのマルチタップに対して制限を加えられ、マルチタップに依る想定外の挙動を回避することができます。

moduleMainScripts ​

moduleMainScripts は、require() 解決用のために用意された値です。通常ゲーム開発者が編集する必要はありません。

現状、moduleMainPaths と同じ役割ですが、将来的には moduleMainScripts が deprecated となります。

moduleMainPaths ​

moduleMainPaths は、require() 解決用のために用意された値です。通常ゲーム開発者が編集する必要はありません。 node_modules/ 以下の package.json のパスをキーに、それの "main" フィールドの内容を値に持つオブジェクトです。

game.json の例 ​

妥当な game.json の一例を示します。

json
{
  "width": 320,
  "height": 320,
  "fps": 30,
  "main": "./script/main.js",
  "assets": {
    "main": {
      "type": "script",
      "path": "script/main.js",
      "global": true
    },
    "character": {
      "type": "image",
      "path": "image/character.png",
      "width": 32,
      "height": 32
    },
    "background": {
      "type": "image",
      "path": "image/background.jpg",
      "width": 320,
      "height": 320
    },
    "bgm": {
      "type": "audio",
      "path": "audio/bgm",
      "systemId": "sound",
      "duration": 1500,
      "hint": {
        "extensions": [".aac", ".ogg"]
      }
    }
  },
  "globalScripts": [
    "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",
    "node_modules/@akashic-extension/akashic-timeline/package.json"
  ],
  "environment": {
    "sandbox-runtime": "3"
  }
}