add-template

name	add-template
description	templates/ にスターターを足す・更新する手順。reference/title.png・lint-palette・Doc 外形規約・画風の宣言・Studio への登録と swap-jar まで、どれか 1 つ欠けると Studio で「出ない / 絵がない / 作れない」になる 7 手順を出す。新しいジャンルのテンプレを作るとき、templates/ 配下を直すとき、make new-game が動かないとき、Studio のジャンルカードに絵が出ないときに使う。
allowed-tools	Read, Grep, Glob, Bash, Edit, Write

テンプレートを足す・更新する

templates/ の各スターターは make new-game の複製元であり、Studio の「ジャンル」の顔でもある。

2 系統ある

• 具体値式（rpg / novel / race / tetris / platformer-starter）: 値をそのまま書く。in-repo で make -C templates/<name> check / test / render-all が通りリファレンス画像を持つ作り込み例。 凝った演出もテストも載せられる。Studio の「はじめる」は複製で始まる。
• トークン式（game-starter）: __NAME__ __W__ などを埋めた最小の骨組み。 in-repo ではビルドしない（make new-game が置換して初めて動く）。W/H を引数で決める素体。

空の抜け殻を置かない

src/ の無いディレクトリを templates/ に残すと、Studio のジャンルカードからは選べるのに複製しても動かない。 中身を作れないうちは Studio 側の starter を空にしておき、ディレクトリごと作らない （存在しないパスを starter に書くのも同じ事故になる）。

手順

このチェックリストを回答にコピーし、埋めながら進める。 どれか欠けると Studio で「出ない / 絵がない / 作れない」になる。

- [ ] 1. templates/<genre>-starter/ を作った（rpg-starter を写経元に。具体値式ならリファレンス画像も生成する）
- [ ] 1b. Makefile は共有 mk を include するだけにした（共通ターゲットを書かない）
- [ ] 2. reference/title.png を用意した
- [ ] 3. make lint-palette が通った
- [ ] 4. Doc の外形規約を守った（全 Doc に version・schema は sections 方言）
- [ ] 5. 画風を宣言した（AGENTS.local.md + View.flix 冒頭の層の並び）
- [ ] 6. Studio に登録した（Genesis.flix の families の starter）
- [ ] 7. make swap-jar して Studio を Cmd+Q → 開き直した

1b. Makefile に共通ターゲットを書かない

run / test / check / render / status などの共通の口は engine の mk/game.mk が持つ。 テンプレの Makefile はそれを include し、SHOTS・PALETTE・PALETTE_DEPS・RENDER_NOTE と そのテンプレ固有のターゲットだけを持つ（写経元は templates/rpg-starter/Makefile。 -include local.mk → ENGINE ?= ../.. → ENGINE 不在の $(error) ガード → 空白を退避した include の順で、この 4 つはそのまま写す）。

写すと engine を直しても既に産まれたゲームへ届かない（upgrade-game が運ぶのは flix.toml の バージョンと lib/ と agents-pack だけで、Makefile は取り残される）。

2. reference/title.png を必ず用意する

Studio のジャンルカードのサムネイルは GET /genesis/title がこれを読む（無いと空絵になる）。 生成に title シーンを 1 枚足してリファレンス画像を更新する。

更新は make -C templates/<name> reference-update。これが gallery/*.png を reference/ へ写し、 reference/SHA256SUMS.txt まで作り直す。git に入るのはこの一覧と title.png だけで、 他のリファレンス画像 PNG は管理外（make reference-check は一覧と突き合わせて退行を見る）。 SHA256SUMS.txt を作り忘れると、clone した人の make reference-check が「リファレンス画像がまだ作られていません」で止まる。

トークン式（game-starter）だけは SHA256SUMS.txt を持てない。 __W__ を埋める前は 型検査が通らず描き出せないので、退行検知そのものが成り立たない（TEMPLATE_DIRS から 除外されているのも同じ理由）。title.png は Studio のサムネイル用に手で置く。 この 1 本を「期待値の更新し忘れ」として直そうとしない。

3. make lint-palette を通す

ドット絵（*.sprite.json）の legend に書いた意味色キーは、*.theme.json のトップレベル・ paletteFile の指す色票・直下の palette のどれかに実体が無いと Studio が仮色で塗り、 編集画面と実機で配色が食い違う。

派生色をコードで導いているなら、色票 JSON を生成する make ターゲットを作り、 paletteFile でそれを指す（kaidan の Palette モジュール + palette ターゲット + テストが手本。テストで生成物と実機の色を pin する）。

4. Doc の外形規約を守る

docs/doc-conventions.md に従う。全 Doc ファイルに version を入れる （無いと Studio の健康診断が「version がありません」を出す）。

*.schema.json は Studio の sections 方言で書く（語彙リファレンス形式で書くと Studio のフォームが「Expecting an OBJECT with a field named sections」で読めない。 語彙の解説は docs/ 側に置く）。詳しくは /doc-design。

5. 画風を宣言する

AGENTS.local.md に「## この画面の画風」を書き（色 3 つ・やらないこと 1 つ）、 src/View.flix の頭に層の並びと、各層が「絵の下限」の 5 性質のどれを受け持つかを書く。

テンプレどうしで画風をそろえない — 揃えると「この画風が正解」という手本になってしまう （テンプレごとに別画風にしてある。現物は各 AGENTS.local.md の「## この画面の画風」宣言が正）。

音と粒（パーティクル）も絵と同じ強さで意識する。詳しくは docs/audio.md と /visual-dict。粒を出すときはまず docs/module-index.md の逆引きを引く。

6. Studio に登録する

flix_ge_studio の server/src/Genesis.flix の families で、該当ジャンルの starter = "templates/<genre>-starter" にする（starter が空だとゼロ生成フローのまま）。

7. Studio に反映する

flix_ge_studio で make swap-jar（動いている .app の同梱 jar を差し替え + 再署名） → Studio を Cmd+Q して開き直し。make jar だけでは動いている .app に効かない。

複製する

make new-game GAME=/abs NAME=x TITLE=題名 TEMPLATE=<genre>-starter

TITLE は自由文でよい（アポストロフィ・空白・記号も通る）。具体値式テンプレは自身の W/H・題名を 使う（引数の W/H・TITLE は反映されない — 作成後に project.json の「ゲームの題・画面」Doc で変える）。