doc-design

name	doc-design
description	ゲームの値を Doc（*.kind.json などの JSON）へ出すときの設計指針。新しい Doc やスキーマを作るとき、既存の Doc にフィールドを足すとき、エディタ（Studio）でフォームが出ない・タブが多すぎて使えないときに参照する
user-invocable	true

Doc 設計 — 何を外に出し、どう分け、どう見せるか

外形の規約（version / スキーマ / fail-open / note / project.json の登録 / 保存即反映）は docs/doc-conventions.md が担当範囲。ここは設計の判断を扱う。

1. 外に出すか、コードに置くか

外に出す	コードに置く
繰り返し調整する数値（テンポ・閾値・収支・確率）	描画アルゴリズム・演出の振り付け
個数が増減するデータ（配置・敵・アイテム）	導出できる値（明るい色は基準色から導く）
色テーマ・文言	一度決めたら触らない構造

判断軸は「保存即反映で調整できると嬉しいか（エディタや非プログラマ、未来の自分）」。

振る舞い（ルール・当たり判定・生成）はコードのまま。 ロジックを JSON に書き始めたら 設計の匂い — データとコードの境界を考え直す。

2. どう分けるか（1 Doc = 1 関心）

切る物差しは「いつ読み直したいか」。同時に読み直したい物だけを 1 つの Doc に入れる。

実例: harvest.kind.json は 29 個の設定を平らに持っていた。中身は「歩く速さ・暦」（手触り）と 「ふち光・接地影・粒・光の向き・落ち影・画素」（絵の仕上げ）の 2 つの関心で、後者は 絵を生成し直すときだけ読めばよい。harvest.kind.json（11）と harvest.paint.json（19）に 割ったら、エディタのタブは 29 枚から 5 + 6 枚になった。

割れの合図:

• 同じ接頭辞のキーが 5 個以上並ぶ（shade* shadow* *Grain*）
• note に「これは○○のとき 1 度だけ効く」と書きたくなる（＝別のライフサイクル）
• スカラーが 30 個を超える
• 一覧型（sprite.json / 配置 / 敵表）で項目が 16 個・20KB を超える。 割る線は「同じタイミングで描き直すか」 — 地面のタイルと建物と人は直す時が違う。 エディタは 1 筆の確定ごとにその Doc の項目を全部組み直すので、同居させた 無関係な項目の分だけ手触りが鈍る（JSON の読み書き自体は 50KB でも 0.6ms で誤差）

3. どう見せるか

大きさの目安と group の書き方は docs/doc-conventions.md の「大きさの目安」「タブの束ね方」を見る。 要点だけ:

• 単一値が 5 個以上なら group で束ねる（タブが値の数だけ増えるのを防ぐ）
• 後から名前が増えるデータは catalog（フィールドを 1 つずつ宣言しない）
• group は Doc を割らない言い訳にしない。まず 1 Doc = 1 関心で割れないか考える

4. スキーマ方言の早見表

Studio がフォームにできるのはこの 5 種類。それ以外の kind は生 JSON 編集に落ちる。

kind	形	使いどころ
value / field	セクション自体が 1 個の値	スカラー。group で束ねる
record	文書直下のキーの下に入れ子の値	まとまった 1 かたまり（start: {x, y}）
catalog / map	名前 → 中身の辞書	後から名前が増える物（色票・敵の種類）
list	並び順に意味がある列	行・配置・波

書き間違えやすい所（どれも黙ってフォームが出なくなる）:

• fields を item と書く（list だけは両方の方言がある）
• 型名は float / int / text / bool / color / vec2 / grid / enum / ref （number / string / boolean ではない）
• order は整数だけ。42.5 と書くと黙って無視されて並びが崩れる
• project.json の登録キーは schema（schemaPath ではない）

5. 作ったあとの確認

• エディタで開いてフォームが出るか（出なければ方言の書き間違い）
• タブが 8 枚以下・1 タブ 15 個以下か
• 「スキーマが "x" を宣言していません」が出ていないか（宣言し忘れ）
• 壊れた JSON で起動するか（fail-open）
• 値を変えずに形だけ変えたなら、生成した絵がバイト一致するか