EMG 0.5 リファレンス

概要

v0.5.0 の全体像を、まず 1 画面で。

1 つの .emg は パーツの集まりです。 パーツは static（レイヤーを重ねて描く。体、背景、部屋の壁）か switch（フレームを 1 つだけ描く。目、口、看板の表示内容、エフェクトのコマ）の どちらかで、この区別が全実装の分岐点になっています。

// data.json の骨格
{
  "version": "0.5.4",
  "requiredExtensions": [],          // 0.4.0
  "baseCanvasWidth": 2894,
  "baseCanvasHeight": 4093,
  "textures": [ { … } ],              // アトラス PNG の宣言
  "parts":    [ { … } ],              // パーツとレイヤー
  "sprites":  [ { … } ],              // フレーム切り替え・変換
  "presets":  [ { … } ]               // 0.5.0
}

v0.5.0 で増えたもの

コンテナ

.emg は拡張子を変えた ZIP です。

アトラスの分割

全素材を 1 枚のテクスチャに詰めます。1 辺 8192px に収まらない場合に限り複数枚へ分割し、 レイヤーはそれぞれ textureFile で参照先を指します。

フレーム識別子 0.5.0

v0.5.0 の中心概念。ここを理解すると残りが繋がります。

switch パーツが「今どれを表示するか」を指す値をフレーム識別子と呼びます。

フレーム識別子 = layer.frameName ?? layer.textureID

parts[].default、sequence.frames[]、 sequence.keys[].frame、presets[].parts、 mapping.json の参照 — すべてがこの値で解決されます。

frameName を持たないファイルでは textureID と同一になるため、 v0.3.0 / v0.4.0 のファイルの意味は一切変わりません。これが、既存ファイルを壊さずに 「複数レイヤーで 1 つの差分」を表現できる理由です。

{ "textureID": "上着",     "frameName": "制服" }   // ┐ 同時に表示される
{ "textureID": "スカート", "frameName": "制服" }   // ┘
{ "textureID": "シャツ",   "frameName": "私服" }
{ "textureID": "ズボン",   "frameName": "私服" }

root

data.json の最上位オブジェクト。

textures[]

アトラス PNG の宣言。1 枚に収まらない場合のみ複数。

{ "textures": [
  { "textureFile": "texture.png", "width": 4096, "height": 8192 }
] }

8 bit / sRGB。1 辺の上限は 8192px です 0.4.0。

parts[]

描画の単位。type が全実装の分岐点です。

type の意味

// static — 体は 3 枚が重なって 1 つの体になる
{ "partID": "Body", "type": "static",
  "layers": [ { "textureID": "胴", … },
              { "textureID": "腕", … },
              { "textureID": "脚", … } ] }

// switch — 目は 6 枚のうち 1 枚だけが出る
{ "partID": "Eyes", "type": "switch",
  "default": "01",               // 初期表示のフレーム識別子
  "control": "animated",
  "layers": [ { "textureID": "01", … },
              { "textureID": "02", … }, … ] }

表示フレームの決定順序

優先順に、次で決めます。

• 外部制御（ホストの指定、再生中の sprites[]、mapping.json の解決結果）
• default と一致するフレーム識別子を持つレイヤー
• いずれも解決できなければ layers の先頭

defaultVisible 0.5.0 switch は 0.5.1

型によって意味が変わります。

switch の場合も default は必須のままで、意味が変わります — 「表示状態にされたときに選ばれるフレーム」です。

control 0.5.0

制約ではなくヒントです。 control: "user" のパーツを sprites[] が切り替えても、animated のパーツを 利用者が固定してもかまいません。制約にすると「演出で衣装を切り替える」といった 正当な用途を禁じることになるためです。

実装は無視してよく、描画には影響しません。用途は UI で、 「衣装」を表情の切り替え欄ではなく設定欄に出す、といった提示の分岐に使います。

parts[].layers[]

アトラスの矩形 1 つと、それをキャンバスのどこへ描くか。

サンプル

目パーツの layers[]。開き目と閉じ目が 1 枚ずつ入っています。

"layers": [
  {
    "textureID": "01",                 // パーツ内で一意
    "textureFile": "texture.png",
    "x": 194, "y": 497,                // ← アトラスのどこを切るか
    "width": 238, "height": 82,
    "basePosition_x": 244,           // ← キャンバスのどこへ置くか
    "basePosition_y": 342,
    "textureZIndex": 24,             // 大きいほど手前
    "opacity": 1,
    "blendMode": "normal"
  },
  {
    "textureID": "04",
    "textureFile": "texture.png",
    "x": 194, "y": 579,
    "width": 238, "height": 82,
    "basePosition_x": 244,           // 同じ位置に重なるので値は同じ
    "basePosition_y": 342,
    "textureZIndex": 24
  }
]

frameName を使う場合 0.5.0

同じ frameName を持つレイヤーは同時に表示されます。 textureID は引き続きパーツ内で一意である必要があります。

"layers": [
  { "textureID": "上着",     "frameName": "制服", "textureZIndex": 30, … },
  { "textureID": "スカート", "frameName": "制服", "textureZIndex": 28, … },
  { "textureID": "シャツ",   "frameName": "私服", "textureZIndex": 30, … },
  { "textureID": "ズボン",   "frameName": "私服", "textureZIndex": 28, … }
]
// この場合 parts[].default は "制服" / "私服"（textureID ではない）

textureZIndex

ファイル全体で 1 本の順序です。パーツ単位ではありません。 値が大きいほど手前で、描画は昇順（奥から手前）に行います。 同じ値が複数ある場合は宣言順（parts[] の順、 その中の layers[] の順）で描きます 0.5.2。

blendMode 0.4.0

許容値は CSS の mix-blend-mode と同じ集合です — normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, hue, saturation, color, luminosity。 未知の値は normal として描画します。

0.5.4 で plus-lighter（加算）が加わり、許容値は 17 語になりました。 上の 16 語は CSS Blending Level 1 の集合で、加算に当たる値を含んでいなかったためです。 色は min(1, Cb + Cs)、アルファは通常どおり source-over です （Photoshop の「覆い焼き（リニア）— 加算」に一致）。 Porter-Duff の PLUS（canvas の lighter）ではありません — あちらはアルファまで足すため、半透明の部分が重ねるたびに不透明へ寄ってしまいます。

normal 以外の実装は任意です（0.4.0 §5.3）。未対応の実装は normal として描いて構いません。

anchor_x / anchor_y 0.4.0

回転と拡縮の基準点（キャンバス座標）。tracks[] でのみ使います。 不在時は basePosition_* と同値です。

sprites[]

フレームの切り替え（sequence）と座標変換（tracks）。

loop 0.5.0

tracks の再生の仕方。duration を 1 周期として扱います。

phaseOffset は再生開始位置のずれ（秒）です。 同じ動きを複数パーツに付けるとき、値をずらすと揃って動く不自然さを避けられます。

targetPartID の制約

sequence

フレームの並びと再生順。frames と keys は排他です。

keys[] 0.5.0

t は再生開始からの累積秒数（各コマの長さではありません）。 昇順に並んでいる必要があります。時刻 t の表示フレームは key.t <= t を満たす最後のキーです。

{ "spriteID": "blink", "targetPartID": "Eyes",
  "sequence": { "type": "ordered", "keys": [
    { "t": 0.00, "frame": "01" },
    { "t": 0.06, "frame": "03" },
    { "t": 0.10, "frame": "04" },
    { "t": 0.18, "frame": "03" },
    { "t": 0.24, "frame": "01" }
  ] } }

keys を使う場合、fps は不要です。書くと解釈が二重になります。

trigger

いつ発火するか。不在なら自律再生しません。

sprites[].tracks[] 0.5.0

移動・回転・拡縮・不透明度のアニメーション。

path — 対象プロパティ

この 6 種のみです。 メッシュ変形・色調補正・textureZIndex の変更は範囲外です。

この集合に限ることで、CSS transform・OS コンポジタ・GPU・CPU 合成の どの経路でも実現できます。これを超えると、いずれの経路でも自前描画が必要になります。

適用順序

対象となる各レイヤーへ、この順で適用します。1 と 4 で使うのは、そのレイヤー自身のアンカーです。

1. アンカー点（anchor_x, anchor_y）を原点へ移動
2. scale_x / scale_y
3. rotation
4. アンカー点を元の位置へ戻す
5. translate_x / translate_y
6. opacity を layer.opacity に乗じる

targetLayer — パーツの一部だけを動かす 0.5.3

トランスフォームの対象を、targetPartID のパーツ内の 特定のフレーム識別子に絞ります。不在ならこれまでどおりパーツ全体が対象です。

{
  "spriteID": "hair_sway",
  "targetPartID": "Body",
  "targetLayer": "Back_hair",   // 0.5.3
  "duration": 3.0,
  "loop": "pingpong",
  "tracks": [ { "path": "rotation", "keys": [ … ] } ]
}

同じことは動かしたい部分を独立した parts[] に切り出しても表現できます。 それでもこの機能があるのは、パーツが描画の単位であると同時に状態と意味づけの単位でもあるためです。 presets[] の parts / toggles、 mapping.json の blinkPartKey などはすべて partID で働くので、 動きの都合で房を独立させると、衣装の着せ替えプリセットが体を指しても房には及ばなくなります。

interpolation — キーとキーの間をどう埋めるか

cubic を Catmull-Rom に固定しているのは、 制御点を持たないため追加データが不要で、実装間で結果が一意に定まるからです。 端点は最初／最後のキーを複製して計算します。

キーは t の昇順である必要があります。 範囲外の時刻では端のキーの値を保持します。

{ "spriteID": "hair_sway", "targetPartID": "hair_back",
  "duration": 3.0, "loop": "pingpong",
  "tracks": [
    { "path": "rotation",
      "keys": [ { "t": 0.0, "v": 0 },
                 { "t": 1.5, "v": 2.5 },
                 { "t": 3.0, "v": 0 } ],
      "interpolation": "linear" }
  ] }

presets[] 0.5.0

複数パーツの状態をまとめて名前で呼ぶ。

{ "presetID": "happy_look",
  "label": "にこやか",
  "parts":   { "Eyebrows": "01", "Blushs": "01" },
  "toggles": { "arms": true } }

状態の使い分け

差し替え・on/off・まとめ指定を、どの機構で表現するか。

v0.5 には状態を表す機構が 4 つあります。似て見えますが排他性の扱いが違い、 選び間違えると後から破綻します。

着せ替えは frameName が本命

「上着とスカートが同時に切り替わる」は presets[].toggles でも書けますが、 排他性を自分で管理することになります — 制服を選んだら私服の全パーツを false にする、という列挙が要り、衣装を 1 つ足すたびに 既存プリセット全部の書き換えが必要になります。

switch + frameName なら排他は自動です。 z が非連続な組（上着 z=20 / 体 z=10 / スカート z=5）も 1 フレームにできるのが この機構の存在理由なので、「1 枚の画像に焼き込む」で代替できない組み合わせもここで扱えます。

presets[] が要るのは、衣装の切り替えに小物の on/off が伴う場合です （制服のときだけ帽子を出す、など）。switch パーツと static のトグルにまたがるため、まとめる側が要ります。

表情はどこに置くか

avatarId は識別用のラベルで、解決には使いません。 mapping.json は独自のバージョンを持たず、同梱される data.json の version に従います 0.5.2。

したがって想定される分担は、プリセットが「どのフレーム・どのトグル」という構造を持ち、 表情がそれを presetID で参照しつつ、目・口だけを overrides で足す形です。

現状の制約

0.5 系列では次を扱いません。回避策とあわせて把握しておいてください。

いずれも conflicts / requires のような依存グラフを 導入すれば解けますが、組み合わせ検証の実装を全消費側に要求するため、 必要性が実データで確認されるまで見送られています（0.5.0 §4.4）。

mapping.json

任意のコンパニオンファイル。まばたき・口パク・表情の意味づけ。

data.json が構造を定めるのに対し、 mapping.json は意味を与えます — 「どのパーツが目か」「どのフレームが閉じ目か」。 存在しなくても .emg は有効で、対応しない実装は無視してかまいません。

{
  "avatarId": "avatar",
  "baseMapping": {
    "blinkPartKey": "Eyes",
    "blink": { "open": "01", "half": "03", "closed": "04" },
    "lipSyncPartKey": "Mouth",
    "lipSync": { "a": "02", "i": "03", "u": "04",
                 "e": "05", "o": "06", "n": "01" }
  },
  "expressions": {
    "default": {},
    "angry": { "parts": { "Eyebrows": ["04"] },
               "overrides": { "blink": { "open": "05", "half": "06", "closed": "04" } } }
  }
}

avatarId は識別用のラベルで、解決には使いません。 mapping.json は独自のバージョンを持たず、同梱される data.json の version に従います 0.5.2。

描画モデル

1 フレーム分の描画手順（規範）。

• 対象を集める。 static は全レイヤー、 switch は解決した 1 フレーム分のみ
• textureZIndex の昇順に並べ替える。 パーツ単位でまとめて描いてはいけません（パーツをまたぐ重なりが壊れます）
• 順に描く。 アトラスの矩形をキャンバスの位置へ、opacity を乗じて合成

draw = []
for part in data.parts:
    if part.defaultVisible == False: continue      # 0.5.0
    if part.type == "static":
        draw += part.layers
    else:
        fid = resolve_switch(part)
        draw += [l for l in part.layers if frame_id(l) == fid]

for layer in sorted(draw, key=lambda l: l.textureZIndex):
    blit(src=(layer.x, layer.y, layer.width, layer.height),
         dst=(layer.basePosition_x, layer.basePosition_y, layer.width, layer.height),
         alpha=layer.opacity)

キャンバスの背景は透明です。.emg は背景色を持ちません。

結果を一致させる規定 0.5.2

「複数の実装が同じ絵を出す」ために必要な前提。0.5.1 まで未定義だったもの。

座標系

キャンバスもアトラスも 左上が原点、X は右、Y は下。単位は px。 rotation の時計回りが正は、この向きでの右回りです。

色空間とアルファ

sequence と tracks

1 つの sprite が両方を持てます。それぞれ独立に評価します。

loop は sequence に効きません。 sequence が末尾に達したとき、auto_loop なら先頭から再開し、 それ以外（random_interval / external / 不在）は 末尾のフレームを保持します。

keys があれば fps は無視します。 両方を書いてはいけませんが、遭遇した場合の解釈はこれで一意に定まります。

同じパーツを複数の sprite が対象にしたとき

違反したファイルに遭遇した場合、および外部制御で複数が同時に有効になった場合は、 sprites[] の宣言順で後にあるものが勝ちます。

tracks も同じで、同一パーツの同一 path に 複数のトラックが効く場合は宣言順で後のものが上書きします。 加算してはいけません — 加算にすると評価順の違いがそのまま値の違いになります。

再生中の sprite に同じ spriteID の再生要求が来たら、 先頭から再生し直します（無視もキューイングもしない）。

参照の欠落と異常系

数値

• 座標・寸法・textureZIndex は整数
• opacity が 0.0〜1.0 の範囲外ならクランプする
• 内部精度は実装に委ねる。ピクセル完全一致は要求しない — 求めるのは「同じ絵に見えること」

アトラスの滲み（参考）

アトラスは矩形を密に詰めておりパディングを持ちません。等倍では問題ありませんが、 scale_* で拡大したりバイリニアでサンプリングすると、 隣接領域の色が滲むことがあります。0.5 系列ではパディングを要求しません。 拡大を前提とする素材では、生成側が 1〜2px の余白を入れると回避できます。

互換性の規則 0.4.0

v0.3.0 にはこれに相当する規定がありませんでした。

前方互換 — 古い実装が新しいファイルを読む

後方互換 — 新しい実装が古いファイルを読む

requiredExtensions[] 0.4.0

理解できない実装に読ませてはならない機能の宣言。

宣言が不要なもの

control、presets[]、 sequence.keys[]、tracks[]、 anchor_*、static での defaultVisible — いずれも無視されても絵は成立します。

実装対応表

2026-08-25 時点。

「一部」は presets 未実装を指します。 「評価器」は値の解決まで実装済みで、描画への適用はホスト側に委ねている状態です。

落とし穴

実データで実際に踏んだもの。

textureID は一意ではない

パーツ内でのみ一意です。実ファイルでは "1"〜"5" が 眉・口・目に、"6"〜"14" が口・目に存在します。 参照は (partID, フレーム識別子) の組で持ってください。

名前から意味を推測しない

textureID は単なる番号のことが多く （"14", "24", "15_1"）、 名前から母音や閉じ目を当てることはできません。推測が働かない場合は 無効に倒すべきで、誤った推測をしてはいけません。

z 順が反転しているファイルがある

ある時期より前に書き出されたファイルは textureZIndex が 前後逆です（体が最前面になっています）。原因は生成側が ag-psd のレイヤー順を逆に仮定していたことで、既に修正されています。 古いファイルは再書き出しするか、z' = maxZ - z で正規化してください。

ファイル全体が 1 つのパーツになっているファイルがある

生成側の不具合で、入れ子のグループが 1 つのパーツに潰れたファイルが存在します （36 レイヤーで 1 パーツ）。これは再書き出しで直すべきもので、 消費側で対処しようとすると static パーツ内のレイヤー単位フィルタが必要になり、 どの実装もそれを持っていません。

version は嘘をつくことがある

"0.2.2" と書かれているのに v0.2 以前の平坦な構造を持つファイルが実在します。 構造の判定はフィールドの有無で行ってください（規則 B1）。

完全なサンプル

最小構成の data.json。

{
  "version": "0.5.2",
  "requiredExtensions": ["EMG_switch_none"],
  "baseCanvasWidth": 1024,
  "baseCanvasHeight": 1024,

  "textures": [
    { "textureFile": "texture.png", "width": 1024, "height": 1024 }
  ],

  "parts": [
    { "partID": "Body", "type": "static",
      "layers": [
        { "textureID": "body", "textureFile": "texture.png",
          "x": 0, "y": 0, "width": 400, "height": 600,
          "basePosition_x": 312, "basePosition_y": 300,
          "textureZIndex": 0, "opacity": 1, "blendMode": "normal" }
      ] },

    { "partID": "Eyes", "type": "switch", "default": "open",
      "control": "animated",
      "layers": [
        { "textureID": "open",   "textureFile": "texture.png",
          "x": 400, "y": 0, "width": 120, "height": 40,
          "basePosition_x": 452, "basePosition_y": 380,
          "textureZIndex": 10 },
        { "textureID": "closed", "textureFile": "texture.png",
          "x": 400, "y": 40, "width": 120, "height": 40,
          "basePosition_x": 452, "basePosition_y": 380,
          "textureZIndex": 10 }
      ] },

    // 差分を持ちながら「どれも出さない」のが常態のパーツ
    { "partID": "Blush", "type": "switch",
      "default": "cheek", "defaultVisible": false,
      "layers": [
        { "textureID": "cheek", "textureFile": "texture.png",
          "x": 400, "y": 80, "width": 160, "height": 30,
          "basePosition_x": 432, "basePosition_y": 400,
          "textureZIndex": 20 },
        { "textureID": "pale",  "textureFile": "texture.png",
          "x": 400, "y": 110, "width": 160, "height": 30,
          "basePosition_x": 432, "basePosition_y": 400,
          "textureZIndex": 20 }
      ] }
  ],

  "sprites": [
    { "spriteID": "blink", "targetPartID": "Eyes",
      "sequence": { "type": "ordered", "keys": [
        { "t": 0.00, "frame": "open" },
        { "t": 0.06, "frame": "closed" },
        { "t": 0.14, "frame": "open" }
      ] },
      "trigger": { "type": "random_interval",
                   "intervalMin": 3.0, "intervalMax": 8.0 } }
  ],

  "presets": [
    { "presetID": "shy", "label": "照れ",
      "parts": { "Blush": "cheek" },
      "toggles": { "Blush": true } }
  ]
}