コンテンツ作成の基本

このページのサンプルコードをダウンロード

# エンティティ

画像や文字列などシーン上で描画されるオブジェクトを Akashic Engine ではエンティティと呼びます。 Akashic Engine には次のエンティティが標準で用意されています。

コンストラクタ名 機能
FilledRect 単色で塗りつぶした矩形を描画する
Sprite 画像を描画する
FrameSprite 画像を分割してそれらの一つを描画する。自動的にアニメーションさせることができる
Label 単一行テキストを描画する
E 複数のエンティティをまとめる
Pane 複数のエンティティをまとめ、領域でクリッピングする

シーンにエンティティを配置するには、次の 2 つのステップが必要です。

  1. new 演算子でエンティティオブジェクトを作る。
  2. シーンの append() メソッドでエンティティオブジェクトをシーンに追加する。

例えば矩形を scene という名前のシーンに追加するには、次のようなコードを書きます。

const rect = new g.FilledRect({
  scene: scene,
  cssColor: "red",
  width: 50,
  height: 50
});
scene.append(rect);

Akashic Engine の機能はグローバル変数 g を通して利用できます。 FilledRect コンストラクタは、コード上では g.FilledRect となります。

エンティティのコンストラクタはオブジェクトを引数にとります。このように引数として渡すオブジェクトを Akashic Engine ではパラメータオブジェクトとよびます。パラメータオブジェクトのプロパティや指定できる値は関数ごとに異なっています。例えば new g.FilledRect() に渡すパラメータオブジェクトには次のプロパティを指定できます。

プロパティ名 指定可能な値 意味 必須かどうか
scene シーンオブジェクト エンティティを表示するシーン 必須
width 数値 横幅 必須
height 数値 高さ 必須
cssColor CSS 色を表す文字列 塗りつぶす色 必須
x 数値 X座標 任意(初期値:0)
y 数値 Y座標 任意(初期値:0)
opacity 0.0以上1.0以下の数値 不透明度 任意(初期値:1)
scaleX 数値 横方向の拡大率 任意(初期値:1)
scaleY 数値 縦方向の拡大率 任意(初期値:1)
angle 数値 回転角度(度)。回転の軸は矩形はアンカーポイント位置(指定されている場合) 任意(初期値:0)
anchorX 数値またはnull アンカーポイントの水平成分。0.0でエンティティの左端、1.0で右端。(詳細) 任意(初期値:0)
anchorY 数値またはundefined アンカーポイントの垂直成分。0.0でエンティティの上端、1.0で下端。(詳細) 任意(初期値:0)
compositeOperation g.CompositeOperationの定数 描画時の既存部分との合成方法 任意(初期値:SourceOver)
children エンティティの配列 子エンティティ 任意(初期値:[])
hidden 真理値 非表示にするかどうか 任意(初期値:false)
touchable 真理値 ポイントイベントに反応するかどうか 任意(初期値:false)

表中のほとんどのプロパティは FilledRect 以外のオブジェクトでも共通です。 FilledRect 特有のプロパティは矩形の色を指定する cssColor のみです。また、他のエンティティと異なり widthheight の指定が必須になっています。

それぞれのエンティティで指定可能な値や初期値は API リファレンスに書かれています。例えば FilledRect であればこちらのドキュメントに書かれています。

エンティティをシーンに追加する操作は、シーンの読み込み後に行う必要があります。シーンの読み込み完了のようなタイミングを通知するのに、 Akashic Engine はトリガー(g.Trigger)とよばれる仕組みを利用します。トリガーには add() メソッドで関数を登録することができます。トリガーに対応するイベントが発生すると、登録されたメソッドが呼び出されます。

シーンの読み込み完了のタイミングを知るには scene.onLoad トリガーを利用します。次の例では handleSceneLoad() 関数を scene.onLoad トリガーに登録しています。

const scene = new g.Scene({ game: g.game });
scene.onLoad.add(handleSceneLoad);

function handleSceneLoad() {
  // シーンが読み込まれたときに行う処理
}

無名関数を利用すると、次のような書き方もできます。

const scene = new g.Scene({ game: g.game });

scene.onLoad.add(() => {
  // シーンが読み込まれたときに行う処理
});

以下は、これまで説明した内容を利用して、座標 (50, 50) に幅 100、高さ 100 の赤色の矩形を表示するプログラムです。座標は初期状態ではシーンの左上が原点で、右に行くほど X の値が大きくなり、下に行くほど Y の値が大きくなります。

function main() {
  const scene = new g.Scene({ game: g.game });
  scene.onLoad.add(() => {
    const rect = createRect(scene);
    scene.append(rect);
  });
  g.game.pushScene(scene);
}

function createRect(scene) {
  return new g.FilledRect({
    scene: scene,
    x: 50,
    y: 50,
    width: 100,
    height: 100,
    cssColor: "red"
  });
}

module.exports = main;

プログラムを akashic-sandbox で実行すると以下のように表示されます。

実行中にゲーム自身の情報を参照する際は g.game オブジェクトを利用します。 g.game オブジェクトはこれまでもシーンを作成する際の引数に登場していました。 Akashic Engine のいくつかのオブジェクトは明示的に g.game オブジェクトを渡す必要があります。

const scene = new g.Scene({ game: g.game });

g.game オブジェクトの width プロパティと height プロパティには、 game.json に指定したゲームの幅と高さが格納されています。この値を利用すると、例えば以下のようにゲーム全体を青色で塗りつぶすように矩形を配置できます。

const backgroundRect = new g.FilledRect({
  scene: scene,
  width: g.game.width,
  height: g.game.height,
  cssColor: "blue"
});

複数の矩形を配置するには、new g.FilledRect()scene.append() をそれぞれ複数回呼び出します。以下はループを使って矩形を格子状に並べるプログラムです。

const rectHeight = 40,
  rectWidth = 60,
  rectMargin = 10;

function main() {
  const scene = new g.Scene({ game: g.game });
  scene.onLoad.add(() => {
    let x, y, rect;
    for (y = 0; y < g.game.height; y += rectHeight + rectMargin) {
      for (x = 0; x < g.game.width; x += rectWidth + rectMargin) {
        rect = createRect(scene, x, y);
        scene.append(rect);
      }
    }
  });
  g.game.pushScene(scene);
}

function createRect(scene, x, y) {
  return new g.FilledRect({
    scene: scene,
    x: x,
    y: y,
    width: rectWidth,
    height: rectHeight,
    cssColor: "#7F3F3F"
  });
}

module.exports = main;

# 画像を扱う

Akashic Engine では PNG 形式と JPEG 形式の画像を扱えます。ここでは以下の PNG 画像 (player.png) をシーンに追加します。

player

Akashic Engine のゲームには推奨されるディレクトリ構造があります。このディレクトリ構造に従うことで、面倒な作業を自動化できます。例えば画像は、アセットとして game.json に登録する必要があります。追加したい画像が image ディレクトリに置かれている場合、次のコマンドで game.json にアセットの情報が追加されます。

akashic scan asset

akashic scan asset がアセットを探すディレクトリは以下の 5 つで、それぞれ配置するアセットの種類が決まっています。

名前 役割
script JavaScriptのコードを配置する
image PNG形式またはJPEG形式の画像を配置する
audio M4A(またはAAC)形式とOGG形式のオーディオファイルを配置する
text その他のデータ(テキスト形式)を配置する
assets 上記 4 種類全てのアセットを配置できる
(v3 以降で利用可能。柔軟ですが他と扱いが違うため、詳細は 後述 します)

akashic init の JavaScript テンプレートを利用している場合、これらのディレクトリはすでに用意されています。 akashic scan asset を実行すると、これらのディレクトリ内に新しいファイルが見つかった場合は game.json に登録し、ディレクトリからファイルが削除されたら game.json から登録を解除します。

player.pngimage ディレクトリに置いて akashic scan asset を実行すると、画面に以下のように表示されます。

INFO: Added (or updated) the declaration for player (image/player.png)
INFO: Done!

game.json を開くと以下の項目が assets プロパティに追加されていることが確認できます。

"player": {
  "type": "image",
  "width": 63,
  "height": 53,
  "path": "image/player.png"
}

以下はシーンに画像を表示するプログラムです。

function main() {
  const scene = new g.Scene({
    game: g.game,
    assetIds: ["player"] // シーン内で利用するアセットID
  });

  scene.onLoad.add(() => {
    const sprite = new g.Sprite({
      scene: scene,
      src: scene.asset.getImageById("player")
    });
    scene.append(sprite);
  });
  g.game.pushScene(scene);
}

module.exports = main;

画像やオーディオなどのアセットは、シーンの生成時に、assetIds プロパティで利用するアセットの ID を指定します。 スクリプトアセットは例外で、指定しなくても自動的に読み込まれます (akashic scan コマンドで登録した場合)。

アセットの ID は game.json に登録されている名前です。 これはアセットを akashic scan で登録した場合は、ファイル名から拡張子をのぞいた文字列になっています。 例えば player.png の場合、アセット ID は player になります。

const scene = new g.Scene({ game: g.game, assetIds: ["player"] });

画像を表示するには Sprite エンティティを使います。 Sprite エンティティのパラメータオブジェクトには src プロパティがあります。ここに画像アセットオブジェクトを指定すると、対応する画像を表示するエンティティが作成されます。

シーンに読み込んだアセットオブジェクトは、 scene.asset から取り出すことができます。アセット ID が player であれば次のコードで参照できます。

scene.asset.getImageById("player");

アセット ID ではなく、アセットのファイルパスを Scene に渡すことでも、アセットを読み込むことができます。

const scene = new g.Scene({ game: g.game, assetPaths: ["/image/player.png"] });

アセットパスを用いてアセットを参照する場合、 game.json のあるディレクトリからの絶対パス表記を用いる必要があることに注意してください。 アセットは次のコードで参照できます。

scene.asset.getImage("/image/player.png");