> ## Documentation Index
> Fetch the complete documentation index at: https://docs.makkii.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# Design でモニターを組む

> Lua を書かずに描画モニターを作る。モニター・パーツ・アイテムと、生成される Lua の構造

Design は、描画モニターを GUI で組み立てる機能です。
Lua が書けなくてもモニターを作れます。拡張子は `.design` です。

生成された Lua はそのまま minify してゲームへ貼れるほか、
Storm Code 内から `require` して描画関数を呼ぶこともできます。

<Note>
  Design は、以前 Storm Sketch という単体のツールだったものを Storm Code に統合したものです。
  単体版は廃止されました。
</Note>

## 3つの概念

<CardGroup cols={3}>
  <Card title="モニター" icon="display">
    描画面そのもの。解像度、背景色、描画順を持ちます。
  </Card>

  <Card title="パーツ" icon="shapes">
    再利用できるアイテムの束。引数を取れます。
  </Card>

  <Card title="アイテム" icon="square">
    矩形・円・三角形・線・テキスト、そしてパーツの配置。
  </Card>
</CardGroup>

\*\*パーツは「定義」、その配置は「アイテム」\*\*です。
同じパーツを何箇所に置いても定義は1つで、座標・引数・表示条件は配置ごとに独立します。
パーツの中にパーツを置くこともできます (循環参照は配置時に拒否されます)。

## 最初はモニター1枚だけ

新しい Design を作ると、**モニター1枚のキャンバスだけ**が開きます。
パーツという概念はこの時点では出てきません。

複数のアイテムを選んで「パーツにまとめる」を実行したときに、初めてパーツが作られ、
選択していたアイテムがその配置に置き換わります。

逆向きの操作もあります。配置を選んで「アイテムに展開 (Detach)」すると、
パーツ定義は残したまま、その配置だけを素のアイテム群へ戻せます。

## 画面

| 場所       | 内容                                   |
| -------- | ------------------------------------ |
| 左サイドバー上段 | モニター一覧。追加・選択・解像度と背景色の設定              |
| 左サイドバー中段 | いま編集している面のアイテム一覧。重なり順の変更、表示/ロックの切り替え |
| 左サイドバー下段 | スニペット                                |
| 中央       | キャンバス。上部に選択・矩形・円・三角形・線・テキストのツール      |
| 中央下部     | パーツのホットバー。ドラッグ&ドロップまたはクリックで配置        |
| 右        | インスペクタ。選択したものに応じて内容が変わる              |

パーツを編集するときは、画面全体が切り替わるのではなく、
**モニター上の文脈を保ったままそのパーツの中に入ります**。
周りとの位置関係を見ながら中身を直せます。

パーツの配置を選んでいるとき、インスペクタは
「この配置 (座標・引数・表示条件)」と「参照先のパーツ (定義・使用箇所・全体への反映)」を分けて表示します。
どちらを触っているのかが分かるようにするためです。

## 動的な値

アイテムの各プロパティには、固定値のほかに Lua 式や Sim I/O の入力
(`in1`、`b1` など) を割り当てられます。インスペクタ上で切り替えます。

パーツの引数 (params) は `number` または `bool` で、それぞれプレビュー用の式を持ちます。
プレビュー実行のときはこの式が使われ、実行時は呼び出し側から渡された値が使われます。

## 生成される Lua

Design は3層の Lua を生成します。本物の `onTick` / `onDraw` は一番上の層にしかありません。

```
Orchestration (ui/pfd.lua)
  └─ Monitor 層 (ui/pfd/monitor/<key>.lua)
       └─ パーツ層 (ui/pfd/view/<key>.lua)
```

| 層               | 中身                                        |
| --------------- | ----------------------------------------- |
| パーツ層            | 純粋な描画処理。`return function(x, y, ...)` の形   |
| Monitor 層       | そのモニター上の配置を、順番と座標つきで呼び出す                  |
| Orchestration 層 | `onTick` で値を配線し、`onDraw` で描画順に応じて各モニターを呼ぶ |

**必要な層だけを `require` できます。**
モニター全体をそのまま使うなら一番上を、描画関数だけ自分のコードから呼びたいなら下の層を
`require` します。使わなかった上の層は結合時に取り除かれます。

生成された Lua は**読み取り専用**です。Design が正本で、生成物は派生物だからです。
Explorer では Design ノードの下に鍵アイコン付きの仮想ノードとして並び、開くと
ヘッダーに `require("<キー>")` のバッジが付いたタブが開きます。

<Warning>
  Design が生成する仮想モジュールのキー (`ui.pfd`、`ui.pfd.view.<key>` など) は、
  実ファイルと衝突できません。ファイルや Design の作成・名前変更、パーツのキー変更のいずれでも、
  衝突する操作は拒否されます。
</Warning>

## プレビュー

Design を編集すると、少し間を置いて自動で再コンパイルされ、プレビューが更新されます。
**コンパイルに成功したときだけ差し替わります。**
編集の途中で一時的に壊れた状態になっても、プレビューが真っ黒になることはありません。

プレビューは通常の実行とは独立した専用の実行単位で動くため、
メインの実行を止めずに確認できます。

## スニペット

よく使うパーツやアイテムの組み合わせはスニペットとして登録できます。
スニペットはワークスペース全体で共有され、`.scode/snippets.json` に保存されるので、
zip のエクスポート・インポートにも自動的に含まれます。

## 履歴

Design の履歴も[ファイル履歴](/storm-code/guides/history)に記録されます。
記録されるのは Design 全体の内容で、復元は1回の操作でまとめて行われます。

<Warning>
  旧バージョンの Design は新バージョンでは読めません。自動変換もしません。
  旧バージョンからの移行については[旧バージョンのデータを救出する](/storm-code/guides/legacy-rescue)を参照してください。
</Warning>