| name | render-loop |
| description | 絵を直すときの進め方。ヘッドレス生成で場面を生成して目視で批評し、一度に 1 つだけ直して前後を並べて見せるループを出す。絵・演出・手触りを直すとき、「見た目を直して」「ここが変」と言われたとき、make render SHOT= / make render-all / make diff を使うとき、どこから直すか候補を出すときに使う。 |
| allowed-tools | Read, Grep, Glob, Bash, Edit, Write |
絵の開発ループ（生成）
決定的な場面をヘッドレス生成で debug/ に生成し（スナップショットの外）、目視で批評 → 修正 → 再生成を回す。
見る前に数値（bench → img-digest → 目視の順）
生成した絵を毎回目視すると 1 枚数千トークン燃える。じょうごで絞る:
- まず
make -C templates/<name> reference-check（リファレンス画像とのハッシュ突き合わせ）。全一致ならここで終わり —
digest も目視も要らない
- 不一致の名前が出た時だけ、その名前を渡して数値で当たりを付ける:
bin/fge digest reference/ gallery/ battle.png # 名前を挙げた絵だけ要約
bin/fge digest old.png new.png # 2 枚だけ比べる
差分画素率・変化した領域・色数・明るさが数行で出る
- 画像を開くのは最終確認の 1 回だけ
- 機械的リファクタ（分割・Doc 化）は「前後の PNG バイト一致」で見た目不変を証明する
- リグレッション防護はリファレンス画像（
gallery/ vs reference/ のバイト比較）に任せる
描き出すのは触った 1 枚だけ
ゲーム側（テンプレ側）の描き出しは 3 つに分かれている。既定の手は「1 枚だけ」:
| やりたいこと | コマンド |
|---|
| 直した場面 1 枚だけ | make render SHOT=title |
| 何枚か | make render SHOT="title walk clear" |
| 全部（リファレンス画像と突き合わせる直前） | make render-all |
素の make render は使い方を出して失敗する。どの場面を見たいかは自分で決めてから打つ。
ループ中に全部描き直すと、直した 1 か所を見るのに他の場面のコンパイルと生成の時間を丸ごと払う。
make render-all を打つのは make reference-check でハッシュを突き合わせる直前と、
リリース前・engine を直した後の退行検知だけ。
描き出すのは触ったテンプレだけ
engine リポでテンプレを横断するときも同じで、ルートの make render-all は全テンプレを
描き直して実時間 150 秒かかる。ループを回している間は
make render-changed（git で変更のあったテンプレだけ。engine 側を直したときは全テンプレが対象）を使う。
ルート側も素の make render は使い方を出して失敗する（全部なら make render-all・並列なら
render-par・変更のあったテンプレだけなら render-changed）。
一度に 1 つだけ直す
直す所が複数見えても、一度に 1 つだけ直す。並びを揃えるため・リストを消化するために
手を広げない（絵に限らず、手触りやテンポも同じ）。
どれを直すかは人が決める
選ぶのは人の仕事。 遊ぶ人から見て目立つ順に候補を3 つまで並べる
（1 つ 1 行 + 生成した絵か再現手順）。人は番号で答えれば済む。
コードを見ても、遊ぶ人に何が見えているかは判らない。だから何を選ぶかをレビュー役に聴かない。
レビュー役に聴くのは「選んだ 1 つの直し方が 90 点か」だけ。
ただし壊れている物は聴かずに先に直す — 落ちる・黒い穴・スナップショットの退行は好みの問題ではない。
直したら前後を並べて見せる
make diff DIR=<game>。変わった絵だけ debug/diff/ に「左=前・右=後」で生成できる。
ファイル名を並べるだけにしない — 人が 2 枚を切り替えて差を探す羽目になる。
ループ GIF を生成したら継ぎ目を確かめる
完全ループを狙う GIF（コマ 0 に戻る演出）を生成したら、目視の前に
make lint-loop（または bin/fge loop <framesディレクトリ>）で
最終コマ→0 コマの継ぎ目が浮いていないか機械検査する。fade・wipe など
最初から戻らない演出は対象外。
描き出し / リファレンス画像の作り方（まだ無いゲームに足すとき）
配管一式（SceneRender entrypoint・flix.toml・フォント・HeadlessRender 呼び出し）の写経元は
docs/headless-render-recipe.md。リファレンス画像の更新は make -C templates/<name> reference-update（bin/reference-update.sh）、
比較は make -C templates/<name> reference-check（bin/reference-check.sh）。git に入るのは SHA256SUMS.txt と title.png だけ。
守ることは 2 つ: 調整中の画は debug/ 行きの別 entrypoint に分けてリファレンス画像を汚さない・
テストは検証だけ（描き出しは SceneRender.all の仕事）。
手順
- [ ] 1. 壊れている物（落ちる・黒い穴・スナップショット退行）が無いか見た。あれば聴かずに直す
- [ ] 2. 直す場面を 1 枚だけ描き出して目視した（make -C <game> render SHOT=<場面名>）
- [ ] 3. 候補を 3 つまでに絞って人に出した（1 つ 1 行 + 絵か再現手順）
- [ ] 4. 選ばれた 1 つだけを直した（他に手を広げていない）
- [ ] 5. make diff DIR=<game> で前後を並べて見せた
絵の部品選びは /visual-dict。絵の下限 5 性質は docs/drawing-floor.md が正（.claude/rules/drawing.md はその生成物）。
