SVG ファイルを画像アセットとして利用する

この機能は現段階では実験的な立ち位置です。本文書にある注意事項を把握した上で利用するようにしてください。また、将来的に仕様が変更/廃止される可能性があることをご留意ください。

akashic-engine@3.2.0 以降では SVG ファイルを画像アセットとして利用することができます。 SVG ファイルを利用することで今まで Akashic Engine で表現することが難しかった円や曲線などの描画を手軽に実現することが可能になります。

利用できる SVG ファイルの仕様

Akashic Engine では SVG ファイルを単一の画像データとしてのみ利用することができます。したがって以下の機能は利用することができません。

アニメーション (animation, transition など) を伴う機能
外部リンクへの遷移やスクリプト実行を伴う機能

加えて実装の都合上、以下の条件を満たす必要があります。

ルートの <svg> 要素に width, height 属性が存在し、単位として px が使われている (% や mm などではない)

SVG ファイル

以下は 100x100 のベージュ色の円を表す Akashic Engine として妥当な SVG ファイルの記述例です。

<svg width="100" height="100" viewbox="0 0 100 100" version="1.1" xmlns="http://www.w3.org/2000/svg">
  <circle fill="#D2B48C" cx="50" cy="50" r="50" />
</svg>

SVG ファイルのスキャン

akashic-cli v2.11.0 以降であれば akashic scan 時に .svg ファイルを "vector-image" アセットとしてスキャンできます。ただし前述した制限に該当する SVG ファイルはスキャン時にリジェクトされます。

上記の SVG ファイルを circle.svg として保存し、 image ディレクトリや assets ディレクトリに格納しておくと、 akashic scan asset でスキャンできるようになります。

"circle": {
  "type": "vector-image",
  "width": 100,
  "height": 100,
  "path": "image/circle.svg"
}

ゲームコンテンツからの利用

ゲームコンテンツから利用する場合、SVG の画像データを g.Surface に変換 (ラスタライズ) します。ゲーム開発者自身が生成した g.Surface はエンジンによるリソース開放処理が行われません。描画用メモリの枯渇を防ぐためにも、適切なタイミングで g.Surface を開放してください。

var asset = scene.asset.getVectorImageById("sample");
var surface = asset.createSurface(200, 200); // 当該の SVG 画像を 200x200 のサーフェスにラスタライズ

if (!surface) {
  // ! SVG が利用できない場合のフォールバック対応
}

var sprite = new g.Surface({
  scene: scene,
  src: surface // g.Sprite のソース画像として利用
});

// ...

surface.destroy(); // ! 参照されなくなったタイミングで開放
// or
sprite.destroy(true); // ! g.Sprite の場合は destroy() に引数 true を渡すことで g.Surface を開放可能

注意事項

SVG ファイルのサポートは現時点では実験段階です。特にマルチプレイモード (参考リンク) でゲームを作成する場合、サーバサイドで実行されるインスタンス上では createSurface() の戻り値が null となることがあります。 null を返すことを想定せず直接 g.Sprite の src に渡すなどしてしまうと思わぬエラーが発生する可能性があります。そのため、以下のように 必ず開発者自身でフォールバック対策を行う ようにしてください。

空の g.Surface を利用する
SVG 画像データをソースとする g.Sprite などのエンティティを生成しない
代替の PNG 画像を読み込む

Akashic Engine 逆引きリファレンス