UIプレビュー は何をしますか?
ゲームのUIの見た目を変えるものは、担当者がHTMLプレビューを調整して保存ボタンを押すまで、一切ビルドしてはいけません。保存された values.json が仕様書です。その中のすべての数値は、エディタで公開可能なプロパティまたはテーマエントリとなり、コード内のマジックナンバーにはなりません。誰にも見えない変更にはプレビューは不要です。
作業順序: プレビューするもの → 該当箇所のスクリーンショット → プレビューページ → レビューシート → 担当者が調整して保存 → values.json からビルド → ビルド vs プレビュー比較シート。
1. セットアップ(プロジェクトごとに1回)
assets/kit/をdocs/mockups/kit/にコピーします(別のフォルダでも可。その場合はスクリプトに--mockupsを渡します)。使用しないエンジン固有のファイルは省略できます。godot_theme.js+apply_godot.py(Godot)、unity_theme.js+apply_uss.py(Unity)、unreal_theme.js+apply_unreal.py(Unreal)。Godotの場合は、assets/godot/project.jsもkit/にコピーして記入します(フォント、キーグリフ)。Godotページはそこから読み込みます。project.cssは唯一編集が必要なキットファイルです。ゲームのフォント(@font-face)とパネルのパレット(--displayを含む)を定義します。kit.jsは描画前に宣言されたすべてのフォントを読み込みます。- プレビューはエンジンのインポート対象から除外します(Godot:
docs/mockups/に空の.gdignoreを配置)。さらにdocs/mockups/*/values.draft.jsonとdocs/mockups/*/shots/を.gitignoreに追加します。 - プロジェクトルートをサーブします:
python docs/mockups/kit/serve.py(stdlibのみ)。その後、http://127.0.0.1:8765/docs/mockups/<feature>/を開きます。ページは相対パスでゲームのアートを読み込み、調整内容をディスクに保存します(§5)。 - プロジェクト自身のスタイルをパネルに読み込む方法:Godot
GodotTheme(テーマ.tres)、UnityUnityTheme(.uss、ScriptableObject.asset)、UnrealUnrealTheme(C++クラスのデフォルト値(ヘッダーとDefault*.iniから)、JSON/CSVにエクスポートしたDataTable)。詳細はreferences/engines.mdを参照。各エンジンにはassets/<engine>/に動作例のページがあります。
2. 確認して、実際の背景を取得する
- どの画面、要素、またはエフェクトか、どのような状況かを尋ねます(すでに明確でない場合)。
- ゲームのビューポートサイズ(プロジェクトの解像度設定、マニフェストの
stageでもある)で、UIを非表示にした状態の該当箇所のスクリーンショット、および今日のUIを表示した状態のベースライン用スクリーンショットを撮ります。エンジンで実行する小さなスクリプト(Godotテンプレート:assets/godot/game_shots.gd、その他:references/engines.md)を使用し、ビルドチェックのためにプレビューの隣に配置します。 - スクリプトで該当箇所を取得できない場合のみ、担当者にスクリーンショットを依頼します。まだ撮影するものが何もない新規要素の場合、またはここでエンジンを実行できない場合は、プレーンな背景またはモックの背景を使用し、その旨を状態のキャプションに明記します。
3. ページを作成する
assets/template/(または assets/<engine>/)を docs/mockups/<feature>/ にコピーします。ページ形式、パネル仕様、Kit.spec、URLパラメータについては references/kit.md を参照してください。
manifest.json: タイトル、stage([幅, 高さ])、states(プレイヤーが見ることができる状況ごとに1つ:空、満杯、フォーカス、無効、最長テキスト、アニメーション途中。それぞれにキャプションとshotTimeを設定)、variants(実際に選択肢がある場合は2〜4。それぞれに名前と注釈)、recommend(バリアントとその理由を1〜2行で)。index.html:Kit.start({ feature, images, groups, variants, draw })。約6つ以上の値を持つグループにはsectionを指定して、パネルが折りたためるようにします。各グループはエンジン内で値が配置される場所(スクリプトクラス、テーマタイプ、シェーダー)を表し、各キーはビルドが使用するプロパティ名(エンジンの単位で指定)です。draw(ctx, values, s)はs.tの純粋関数でなければなりません(ループアニメーションはt % lengthを使用)。- 近似ではなく、ゲーム独自の外観を使用する: ゲームのフォントとサイズ、テーマカラー(新しい色は提案です。どのパレットに加わるかを明記)、相対パスによる実際のアート、実際のテキストと数値、実際にバインドされているキーを示すプロンプト。
- ピクセルアート:ピクセル全体、スムージングなし(キットのデフォルト)。
- モーションは実際の継続時間とイージングで実行します。揺れ、ドリフト、フラッシュ、点滅があるものは、
preview: trueグループに「動作減らす / フラッシュ減らす」トグルを追加し、それらの設定がどのように見えるかを表示します。 - 既存のものを調整する場合、バリアント
aは現在の状態を正確に再描画します。ベースラインのスクリーンショットと一致するまで確認し、一致しない場合は他のすべてのバリアントが間違ったベースラインと比較されます。 - 複数のプレビューで描画されるものは、キット内の共有ファイルに配置し、ページごとにコピーしないでください。
4. レビューシート
python docs/mockups/kit/shots.py <feature>(Chrome、Edge、またはChromiumと、Pillow ≥ 10.1が必要)を実行すると、shots/<variant>_<state>.pngが作成され、sheet.pngが連結されます。保存されたvalues.jsonを使用してバリアントを描画します(--defaultsはページのデフォルトを使用)。ページが失敗した場合は非零で終了し、エラーが該当ショットに描画されます。- シートを確認してから担当者に見せます。決定する部分を2倍で切り抜きます:テキストのクリッピングやオーバーラップ、間違ったフォント、ステージからはみ出したもの、退屈な瞬間で停止しているアニメーション(
shotTimeを移動)。 - シート、ライブURL、決定事項をあなたの推奨とともに送信します。
5. 調整内容の読み取り
- 調整中、すべての変更は
<feature>/values.draft.jsonに書き込まれます。担当者が意見を求めてきたらいつでも読み取ってください。ただし、このドラフトからビルドしてはいけません。 - 保存(またはCtrl/Cmd+S)を押すと、
<feature>/values.json(承認済み仕様)が書き込まれ、ページはその内容で開きます。異なる行はマークされ、↺ は1つの値を戻し、リセットはすべての値を戻します。プレビューのみの値はマークも保存もされません。 serve.pyがない場合、調整内容はブラウザ内にのみ保存されます。保存を押すとJSONがコピーされ(そのブラウザのデフォルトとして保持されます)、担当者はそれをチャットに貼り付け、あなたがvalues.jsonとして保存します。- 形式:
{"feature", "variant", "values": {Group: {Key: value}}}。プレビューのみのグループは省略されます。
6. 仕様からビルドする
- Godot:
python docs/mockups/kit/apply_godot.py <feature>を実行すると、仕様がテーマ.tres、各グループが指定するスクリプトの[Export]/@exportデフォルト、<name>.gdshaderグループのユニフォームデフォルト、まだエクスポートがないキー、およびこれらのプロパティをオーバーライドするシーンに何を変更するかが一覧表示されます。--writeで適用します。 - Unity:
python docs/mockups/kit/apply_uss.py <feature>を実行すると、USSカスタムプロパティ(uss:グループ)に対して同様の処理を行います。ScriptableObjectの値は手動で適用します。 - Unreal:
python docs/mockups/kit/apply_unreal.py <feature>を実行すると、各グループのC++クラスに何を変更するかが一覧表示されます。Configクラスの場合はConfig/Default<Config>.iniのオーバーライド(--target headerは宣言のデフォルトを直接書き換えます)、まだUPROPERTYがないキー(貼り付け用の宣言付き)、手動で設定するデフォルト。--writeで適用します。DataTableの値は、編集したエクスポートを再インポートして適用します。 - まだ存在しないものをビルドします:エンジンのテーマまたはスタイルシステム内の色、フォント、パネル。JSONと同様にグループ化されたエディタ公開可能なプロパティとしてサイズ、オフセット、継続時間、強度を追加し、承認された値をデフォルトとして設定します。
- 実行中のゲームで検証します:プレビューの各状態のスクリーンショットを撮り、
<feature>/build_vs_preview.pngを作成します(ゲームショットとプレビューショットを並べます)。異なる部分を修正します。チェックできなかったことを明記します。ブラウザとエンジンのテキストアンチエイリアスは異なるため、エッジピクセルではなく、位置とサイズを判断します。 - 承認された外観への後続の変更は、新しいラウンド(プレビュー、シート、保存、ビルド)として扱います。
ルール
- プレビューはリポジトリに残します。UIがそのように見える理由を記録します。
sheet.pngとvalues.jsonはコミットします。shots/とドラフトは再生成されます。 values.jsonが存在するまでビルドしてはいけません。ドラフトからビルドしてはいけません。- キットにプレビューに必要なものが不足している場合は、1つのページに追加するのではなく、キットに追加します。