MomijiUI リファレンス#

この説明書は MomijiUI 0.1.0（2026-10-21）のものです。

画面を JSON で書き、Unreal Engine（UE）とブラウザで同じ配置に描く UI フレームワーク MomijiUI の、画面 JSON の鍵・部品（17 種）とその鍵・列挙の値・動き・テーマ・診断のコードを全部引ける説明書です。表は、2 つの実装（UE とブラウザ）の診断の表から脚本が作っています。

• 見本を動かし、自分の画面を 1 つ書いて検査するまでの手順は導入ガイドにあります。初めての人はそちらから読んでください。
• English

目次#

1. このリファレンスの読み方
2. 画面 JSON
3. 部品
4. 配置
5. 値の差し込み
6. 焦点と当たり・選択
7. 動き
8. テーマ
9. 操作（あなたのプログラムの仕事）
10. 検査（診断）
11. 保証すること・しないこと
12. 同梱物の権利

1. このリファレンスの読み方#

1.1 単位と色#

• 画面は 1280×720 として書きます。 位置と大きさ（x y w h pad gap margin wrapW lineH）はこの上の論理 px です。実際の窓には縦横比のまま拡大して出し、余りは黒帯にします。
• fontSize はポイントです。 画面では fontSize × 4/3 px（17 → 23px）。書かなければ 16。
• 色は #rrggbb か #rrggbbaa です。それ以外の文字（red など）は無視されて既定の色になります（診断 bad-color）。
• 書体は同梱の BIZ UDP ゴシックで、OS の書体は使いません（§12）。

1.2 表の読み方#

• 型: 診断が見る値の型です。「（検査しない）」は、診断が知っている鍵として通すだけで形を見ない鍵です（形は「何を書くか」に書いています）。
• 既定: 書かなかったときの値です。「—」は既定が無い（書かなければ働かない）ことです。
• ブラウザ: 「描く」は UE とブラウザの両方が描きます。「UE だけ」は UE だけが描き、ブラウザは診断で知っている鍵として通しますが描きません（見た目の描き方・枠など。§11）。
• 部品の表は共通の鍵（§3.1）を繰り返しません。全部の部品に §3.1 の鍵も書けます。
• 鍵の名前は大文字と小文字を区別します。_ で始まる鍵は注記として扱い、診断も描画器も見ません。

1.3 2 つの実装#

同じ画面 JSON と同じ値からは、2 つの実装で同じ配置・同じ押せる場所・同じ焦点の動きになります（§11）。

2. 画面 JSON#

画面ファイルは root に部品の木を持つオブジェクトです。root が無いファイルは、ファイル全体を 1 つの部品として読みます。

{
 "root": {
  "type": "VerticalLayout", "anchor": "center", "w": 400, "h": 200, "pad": 20, "gap": 12,
  "children": [
   { "type": "Label", "text": "Hello {name}", "h": 32, "fontSize": 20, "align": "center" },
   { "type": "Button", "id": "ok", "text": "OK", "action": "ok", "h": 44 }
  ]
 }
}

最上位に書ける鍵:

画面 JSON に版の番号はありません。今の正しい JSON は、これからの版でも同じ寸法で動きます。

3. 部品#

部品は type で決まり、children で入れ子にします。並べる入れ物（VerticalLayout・HorizontalLayout・GridLayout・ScrollView・Modal）は子の位置を決めます。Panel は子を並べません。

3.1 共通の鍵#

全部の部品に書ける鍵（25）。

3.2 Panel#

板。子を並べない（子の x・y・w・h は画面の上の位置のまま使う。積むなら VerticalLayout）。押せる板にするなら action を書く。

例:

{ "root": { "type": "Panel", "x": 40, "y": 40, "w": 400, "h": 160, "variant": "dark",
  "children": [
   {"type": "Label", "x": 60, "y": 60, "w": 360, "h": 32, "text": "Score {score}"}
  ] } }

3.3 Image#

画像か色の四角。sprite も color も無ければテーマの panel の色。

例:

{ "root": {"type": "Image", "x": 40, "y": 40, "w": 320, "h": 180, "sprite": "Plugins/MomijiUI/Fixtures/images/landscape.png", "fit": "cover"} }

3.4 Label#

文字。1 行の文字は箱の縦の中心に置く。wrapW を書くと折り返し、高さは行数から決まる。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 480, "h": 160, "pad": 16, "gap": 8,
  "children": [
   {"type": "Label", "text": "Chapter {chapter}", "fontSize": 20, "align": "center", "h": 32},
   {"type": "Label", "text": "A long line of text that wraps inside the box.", "font": "main", "wrapW": 440, "textColor": "#9aa6b8"}
  ] } }

3.5 Button#

押せる板と文字。押すと action が host へ届く。

例:

{ "root": { "type": "HorizontalLayout", "anchor": "bottom", "h": 64, "pad": 8, "gap": 8,
  "children": [
   {"type": "Button", "id": "ok", "text": "OK", "action": "ok", "w": 160},
   {"type": "Button", "id": "cancel", "text": "Cancel", "action": "cancel", "variant": "ghost", "w": 160, "enabledIf": "canCancel"}
  ] } }

3.6 Slider#

溝と、値の分だけ塗った棒。押した位置の比（0〜1）が値として host へ届く（kind: slider）。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 400, "h": 80, "pad": 16, "gap": 8,
  "children": [
   {"type": "Label", "text": "Volume", "h": 24},
   {"type": "Slider", "id": "volume", "bindVar": "volume", "action": "set:volume", "h": 14}
  ] } }

3.7 Toggle#

四角の印と右の文字。押すと切り替えたあとの真偽が host へ届く（kind: toggle）。当たりは箱＋10＋文字の幅。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 400, "h": 60, "pad": 16,
  "children": [
   {"type": "Toggle", "id": "subtitles", "bindVar": "subtitles", "action": "toggle:subtitles", "text": "Subtitles"}
  ] } }

3.8 ToggleGroup#

タブのような排他の選択。子（各項目の text と action）を横に等分し、選んだ項目の上に accent の帯。押すと項目の番号が host へ届く（kind: toggle）。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 480, "h": 64, "pad": 8,
  "children": [
   { "type": "ToggleGroup", "id": "speed", "bindVar": "speed", "h": 40,
    "children": [
     {"id": "speed-0", "text": "Slow", "action": "speed:0"},
     {"id": "speed-1", "text": "Normal", "action": "speed:1"},
     {"id": "speed-2", "text": "Fast", "action": "speed:2"}
    ] }
  ] } }

3.9 ScrollView#

子を縦に積み、はみ出したら縦にスクロールする（flex は効かない）。中身が箱より高いと子の幅から 10 を引いてスクロール条を出す。見える範囲の外は描かず押せない。

例:

{ "root": { "type": "ScrollView", "id": "log", "x": 40, "y": 40, "w": 600, "h": 300, "pad": 8, "gap": 4, "selectable": true, "repeat": "lines", "children": [],
  "template": {"type": "Label", "text": "{item.text}", "font": "main", "wrapW": 560} } }

3.10 Modal#

画面全体の暗幕と中央の板。板は w×h（既定 480×320）で、x・y が 0 なら画面の中央。子は縦に積む。Modal の中は別の焦点の群で、開いている間は後ろの部品に焦点も入力も行かない。

例:

{ "root": { "type": "Panel", "variant": "spacer",
  "children": [
   { "type": "Modal", "id": "confirm", "text": "Quit?", "showIf": "askQuit", "pad": 16, "gap": 8,
    "children": [
     {"type": "Button", "id": "quit-yes", "text": "Yes", "action": "quit:yes", "h": 44},
     {"type": "Button", "id": "quit-no", "text": "No", "action": "quit:no", "variant": "ghost", "h": 44}
    ] }
  ] } }

3.11 VerticalLayout#

子を上から縦に積む。幅の無い子は親の幅いっぱい。高さの無い入れ物の子は測った高さを持つ。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 400, "h": 240, "pad": 16, "gap": 8, "variant": "dark",
  "children": [
   {"type": "Label", "text": "Title", "h": 32},
   {"type": "Panel", "variant": "light", "flex": 1},
   {"type": "Button", "id": "close", "text": "Close", "action": "close", "h": 44}
  ] } }

3.12 HorizontalLayout#

子を左から横に並べる。子の幅は w（無ければ 100）か flex。高さの無い子は親の高さいっぱい。

例:

{ "root": { "type": "HorizontalLayout", "anchor": "top", "h": 56, "pad": 8, "gap": 8,
  "children": [
   {"type": "Label", "text": "HP {hp}", "w": 160},
   {"type": "Panel", "variant": "spacer", "flex": 1},
   {"type": "Button", "id": "menu", "text": "Menu", "action": "menu", "w": 120}
  ] } }

3.13 GridLayout#

子を cols 列に左上から並べる。セル幅は等分、行はその行の最大の高さ＋gap だけ下げる。高さの無い子は 28。

例:

{ "root": { "type": "GridLayout", "anchor": "center", "w": 480, "h": 200, "cols": 3, "pad": 8, "gap": 8, "repeat": "items", "children": [],
  "template": {"type": "Button", "id": "item:{item.id}", "text": "{item.name}", "action": "use:{item.id}", "h": 44} } }

3.14 TextInput#

1 行の文字欄の枠。編集は MomijiUI が枠の位置に重ねる編集欄（UE は SEditableText、ブラウザは <input>）で、日本語入力が使える。Enter で action が届く（kind: submit・value は欄の文字）。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 480, "h": 80, "pad": 16,
  "children": [
   {"type": "TextInput", "id": "name", "bindVar": "name", "placeholder": "Your name", "maxLen": 12, "action": "name:submit", "h": 44}
  ] } }

3.15 Polyline#

折れ線。配置に参加しない（points は画面の上の位置）。2 点未満なら描かない。

例:

{ "root": { "type": "Panel", "variant": "spacer",
  "children": [
   {"type": "Polyline", "points": [[100, 400], [300, 300], [500, 360]], "thickness": 3, "color": "#5ab0ff"}
  ] } }

3.16 Ellipse#

楕円。x・y・w・h が外接する四角。配置に参加しない。

例:

{ "root": { "type": "Panel", "variant": "spacer",
  "children": [
   {"type": "Ellipse", "x": 600, "y": 300, "w": 80, "h": 80, "fill": false, "thickness": 2, "color": "#e0a04a"}
  ] } }

3.17 Polygon#

塗りの多角形。points は部品の左上からの位置で、並べる入れ物の中に置ける（w・h を持つ）。3 点未満なら描かない。UE だけ。

ブラウザはこの部品の形を描かず、箱をテーマの panel の色で塗る（診断は知っている部品として通す）。

例:

{ "root": { "type": "HorizontalLayout", "anchor": "top", "h": 48, "pad": 8,
  "children": [
   {"type": "Polygon", "w": 32, "h": 32, "points": [[0, 0], [32, 16], [0, 32]], "color": "#e0a04a"}
  ] } }

3.18 Divider#

区切り線。箱の縦の中央に線を引き、ornament で飾りを付ける。高さが無ければ 12。UE だけ。

ブラウザはこの部品の形を描かず、箱をテーマの panel の色で塗る（診断は知っている部品として通す）。

例:

{ "root": { "type": "VerticalLayout", "anchor": "center", "w": 400, "h": 80, "pad": 16,
  "children": [
   {"type": "Divider", "ornament": "diamond", "thickness": 1}
  ] } }

4. 配置#

4.1 列挙の値#

診断が値を確かめる鍵です。表の外の値は bad-value（error）になります。

4.2 高さの決め方#

h が 0 より大きければそれを使います。無ければ種類ごとに測ります。

4.3 並べる入れ物#

• VerticalLayout・HorizontalLayout: 主軸の残り＝内寸 − Σ(flex の無い子の大きさ ＋ 2·margin) − gap·子の数。flex の子は残りを flex の比で分け、minH・minW を下回りません。
• GridLayout: セル幅＝floor((w − 2·pad − (cols−1)·gap) / cols)。幅の無い子はセル幅 − 2·margin。
• ScrollView: 縦に積みます（flex は効きません）。スクロール量は id ごとに持ち、0〜(中身−箱) に収めます。スクロール条は幅 6・右端から 2 内側。
• Modal: 子は板の中で縦に積みます。同じ親に Modal が 2 つ同時に出たときは、後に描いた（手前の）Modal だけが入力を受けます。
• Panel: 子を並べません。Panel の中の子は自分の x y w h のまま描かれます（大きさが 0 なら見えません）。
• Polyline・Ellipse は配置に参加しません（画面の上の位置で描く）。Polygon は w h を持つので並べる入れ物の中に置けます。

4.4 anchor#

anchor は描く前に一度だけ解きます。値は §4.1 の表のとおりです。anchor の無い部品は x y w h を画面の上の位置として使います。

5. 値の差し込み#

あなたのプログラム（host）は、描くたびに 3 種類の値を渡します。画面 JSON の元の木は書き換えず、写しに入れます。

知らない {鍵} はそのまま残ります（診断もしません）。

5.1 repeat と template#

• repeat: "<一覧の名前>" の部品は、一覧の要素ごとに template を複製して子にします。
• templates: {"<種類>": 型} と templateKey: "<要素の鍵>" があれば、要素の item[templateKey] で型を選びます（無ければ template、それも無ければその要素は出しません）。
• 複製の text action id sprite enabledIf highlightIf showIf hideIf の {item.<鍵>} を要素の値で置き換えます。入れ子の repeat も同じです。
• 一覧の中の部品の id は "row:{item.id}" のように、データの安定した鍵で付けます。

5.2 条件式#

showIf hideIf enabledIf highlightIf と anim.pulse.whileIf に書く式です。

• 比較は 名前 演算子 数（== != >= <= > <）。数だけ（0 以外が真）・名前だけ（値が 0 以外で真）も書けます。
• &&（かつ）・||（または）・!（でない）・括弧が使えます。
• 名前は英字か _ で始まり、英数字・_・. が続きます（item.potion など）。知らない名前は 0 です。
• 名前は数（vars）で渡します。文字（strings）は条件に使えません。

例: count > 0・count >= 5 && ready・!(done) || n == 2。

5.3 描くまでの順#

1. 数の値を bindVar の部品へ入れる
2. repeat を展開する
3. {鍵} を置き換える
4. 条件を当てる（enabledIf が偽なら押せない・highlightIf が真なら強調・showIf が偽／hideIf が真の部品は子ごと消す）
5. 配置して描き、押せる場所を作る

1〜5 を 1 回でする入口が UE の KaedeUI::PresentScreen、ブラウザの MomijiUICanvas.present です（§9）。

6. 焦点と当たり・選択#

6.1 当たりと焦点#

• 当たり（押せる場所）は、action を持ち押せる部品の四角です。後に描いたものが勝ちます。押せない（enabled が偽）部品は当たりになりません。ScrollView の見える範囲の外は押せません。
• 部品の鍵: id があれば id:<id>、無ければ action:<action>。焦点・スクロール量・動き・文字欄の中身はこの鍵で追います。同じ action の部品が 2 つあってよいので、状態を持つ部品には id を付けます。
• 焦点の移動（方向キー・ゲームパッド）: 同じ群（Modal の外が 0、Modal はそれぞれ別の群）の中で、その方向にある当たりのうち、距離 ＋ 横（縦）のずれ × 2 が最小のものへ移ります。移った先が ScrollView の見える範囲の外なら、見えるところまでスクロールします。
• Modal を開くと焦点は Modal の中の先頭へ移り、閉じると前の部品へ戻ります。Modal が開いている間、後ろの部品にはキーも押下も届きません。
• 焦点の枠は方向キーを使っている間だけ、当たりの 3 外側に太さ 3 の橙色で出ます。ポインタを動かすと消えます。
• Enter・Space は、いちばん手前の群の焦点の部品を押します。

6.2 文字の選択とコピー#

• selectable: true を書いた Panel・VerticalLayout・ScrollView の中の Label の文字（runs の本文を含む）をマウスでなぞると選ばれ、離した瞬間にクリップボードへ入ります（「コピーしました」の札が出ます。Ctrl+C は要りません）。
• 選べるのは器 1 つの中だけです。ボタン・文字欄・ルビの文字は選べません。指（タッチ）では選べません（中身のスクロールになります）。
• 同じ Label の折り返しは続けて、Label が変わるところは改行して写します。
• 器の外・押せる部品・文字欄を押したとき、画面が変わったとき、選んでいた行の文字が変わったときに選択は消えます。

7. 動き#

anim に書きます。動く部品には id か action を付けます（動きはその鍵で追うので、無いと動きません）。入れ子の anim は外側が勝ちます。画面（host が渡す画面の名前）が変わったら、画面全体が 160ms で浮かび、前の画面の動きは捨てます。

• enter の type に書ける値は §4.1 の 3 つです。UE の描画器は "open"（縦に中心から伸びる）も描きますが、診断（UE・ブラウザとも）は "open" を bad-value（error）として出し、ブラウザの load はその画面を止めます。
• pulse で拡大縮小するのは箱だけで、文字の大きさと位置は変わりません。

8. テーマ#

テーマは画面全体の色と形の組です。UE は KaedeCore::BuiltinTheme("<名前>") か KaedeCore::LoadTheme(<テーマ JSON の文字列>)、ブラウザは R.setTheme("<名前>") か R.setTheme({…}) で選びます。テーマの JSON には変えたい鍵だけを書きます（UE の LoadTheme は atelier を元に、ブラウザの R.setTheme({…}) はいまのテーマを元に、書いた鍵だけを替えます）。

atelier	midnight	sakura

内蔵のテーマ 3 つ（atelier・midnight・sakura）。テーマの JSON の鍵は 29 で、ブラウザが読むのはそのうち色の 11。

9. 操作（あなたのプログラムの仕事）#

あなたのプログラムの仕事は 4 つです: 画面 JSON を読む → 状態から値を作って描く → 押された動作で状態を変える → 描き直す。 入力（ポインタ・ホイール・スクロール条のつまみ・指のスクロール・Slider のドラッグ・方向キーと Enter/Space・文字欄の編集・日本語入力）は MomijiUI が受け持ち、あなたのプログラムに届くのは事象だけです。座標や当たりを自分で解釈しないでください。

9.1 事象#

事象は {kind, action, nodeId, key, value, relX} です。

9.2 UE#

モジュールの *.Build.cs で MomijiUICore と MomijiUISlate に依存させます。見本は Plugins/MomijiUI/Source/MomijiUISlate/Private/Examples/SMomijiUICounterExample.cpp です。

9.3 ブラウザ#

ブラウザ版は依存の無い ES module 1 本（momiji-ui.mjs）と、<script> で読む従来形（window.MomijiUICanvas）です。静的な HTTP のサーバーで開きます（file:// では書体と fetch が働きません）。ブラウザの配布物は GitHub で準備中です。

10. 検査（診断）#

診断は描く前に、場所（JSON Pointer の path）つきで次を返します。描くときには呼びません（検査の道具です）。UE は KaedeCore::ValidateScreenJson、ブラウザは MomijiUICanvas.validate(doc)、手元のファイルは node Tools/momiji-ui/validate.mjs <画面 JSON …>（1 件 1 行・error があれば終了コード 1）。2 つの実装は同じコードを同じ path で出します。

• 重さ: error は描けないか意図どおりにならないもの、warn は無視されるが描けるもの。
• 未知の {鍵} は診断しません（補間の決まりどおり残ります）。

11. 保証すること・しないこと#

• 保証は照合の試料（Plugins/MomijiUI/Fixtures/ の 19 枚）で、UE と Windows の Chrome（ほかに Chromium・Firefox・WebKit）を突き合わせて確かめています。
• 「UE だけ」の鍵と部品（見た目の描き方・枠・Polygon・Divider・テーマの形の鍵・blink などの動き）は、ブラウザではその見た目で描かれません（Polygon・Divider は板の色の四角になります）。配置の保証は、それらを書かない画面のものです。
• 同梱の書体を読み終える前に描いた結果は保証の外です（ブラウザは loadFonts を待ってから描く）。製品版の Safari（macOS）・Edge・Mac／Linux は確かめていません。
• 対応する UE は 5.8・Windows です。

12. 同梱物の権利#

• 既定の書体は BIZ UDP ゴシックです。UE は SKaedeUiCanvas::SetFontFamily で明朝・手書き風・ドットに替えられます（Yomogi と DotGothic16 に太字はありません）。ブラウザはゴシックだけです。
• 書体を配るときは許諾文も一緒に配ります（UE は MomijiUISlate.Build.cs が配信物へ積みます）。