このページのサンプルコードをダウンロード
画像や文字列などシーン上で描画されるオブジェクトを Akashic Engine ではエンティティと呼びます。 Akashic Engine には次のエンティティが標準で用意されています。
コンストラクタ名 | 機能 |
---|---|
FilledRect |
単色で塗りつぶした矩形を描画する |
Sprite |
画像を描画する |
FrameSprite |
画像を分割してそれらの一つを描画する。自動的にアニメーションさせることができる |
Label |
単一行テキストを描画する |
E |
複数のエンティティをまとめる |
Pane |
複数のエンティティをまとめ、領域でクリッピングする |
シーンにエンティティを配置するには、次の 2 つのステップが必要です。
new
演算子でエンティティオブジェクトを作る。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
のみです。また、他のエンティティと異なり width
と height
の指定が必須になっています。
それぞれのエンティティで指定可能な値や初期値は 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
) をシーンに追加します。
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.png
を image
ディレクトリに置いて
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");