Communitygithub.com

UIプレビュー

ゲームプロジェクトにおいて、HUD要素、メニュー、プロンプト、トランジション、画面エフェクトをエンジンに実装する前に調整可能なHTMLプレビューを作成し、調整された値をビルド仕様に変換します。

UIプレビュー とは?

このスキルは、ゲームのUI要素やビジュアルエフェクトをエンジンに実装する前に、インタラクティブなHTMLプレビューでデザインと調整を行うためのものです。実際のゲームのスクリーンショットを背景に、スライダーやカラーピッカーなどのチューニングパネルを備えたプレビューページを作成し、調整結果を`values.json`として保存します。Godot、Unity、Unreal Engine向けのスクリプトが用意されており、保存された仕様からエンジン内のテーマやプロパティを自動的に適用できます。プレビューはゲームの実際のフォント、色、アートを使用し、ピクセル単位の正確さを保ちます。また、リデュースモーションやフラッシュ軽減設定にも対応しており、アクセシビリティを考慮したデザインが可能です。このワークフローにより、開発者は「マジックナンバー」をコードに埋め込むことなく、すべての調整値をエディタで公開可能なプロパティとして管理できます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomas-ratz/game-ui-proof/tree/HEAD/skills/ui-preview

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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)、Unity UnityTheme(.uss、ScriptableObject .asset)、Unreal UnrealTheme(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つのページに追加するのではなく、キットに追加します。

関連スキル