godot-ui-theming

UI のテーマ設定

テーマリソース、StyleBox のスタイリング、フォント管理、オーバーライドシステムによって、一貫した UI のビジュアルアイデンティティを定義します。

利用可能なスクリプト

global_theme_manager.gd

動的な切り替え、テーマバリアント、フォールバック処理に対応した高度なテーママネージャーです。

ui_scale_manager.gd

実行時のテーマ切り替えと、DPI／解像度のスケール管理を行います。

theme_swapper.gd

テーマルートをカスケード伝播させて、ダークモード／ライトモードを動的に実装します。

danger_button_assignment.gd

シーンを複製せずにセマンティックな UI スタイリングを行う、theme_type_variation の高度な活用例です。

dynamic_stylebox_color.gd

実行時に StyleBox を安全に変更します。個別のオーバーライドを行うための重要な duplicate() パターンを示します。

procedural_theme_safe.gd

NOTIFICATION_THEME_CHANGED を使用して、生成された UI 要素に確実にテーマを適用します。

custom_chart_drawing.gd

カスタムの _draw() ロジックでアクティブな Theme のプロパティ（色、フォント）を読み取るパターンです。

theme_isolation.gd

ノードを親テーマから分離し、プロジェクトのデフォルト設定を参照することで、HUD の一貫性を保ちます。

pulsating_ui_theme.gd

Tween を使って UI スタイルをアニメーションさせます。複製後に StyleBox のプロパティを直接操作します。

crisp_ui_scaler.gd

content_scale_factor を使用してフォントの鮮明さを保つ、高品質で解像度に依存しないスケーリングです。

memory_safe_custom_drawing.gd

RenderingServer 用にリソースをクラスレベルでキャッシュし、「消える StyleBox」バグを修正します。

rtl_theme_mirroring.gd

双方向（RTL／LTR）UI に対応します。レイアウト方向に応じてテーマバリアントを動的に切り替えます。

focus_prompt_icon_swapper.gd

コントローラー／キーボードのプロンプトアイコンバンク切り替えと、フォーカスハイライトパネルに対応します。アクセシビリティ用のプロンプト表示には必須です。

UI のテーマ設定で絶対にしてはいけないこと

• 多くのノードの _ready() で StyleBox を作成しないでください — StyleBoxFlat.new() を100回インスタンス化すると、固有のオブジェクトが100個作成されます。共通のスタイルには Theme リソースを使用してください。
• テーマの継承を忘れないでください — 子に独自のテーマがある場合、親のテーマは無視されます。ルートにテーマを適用し、個別の上書きには theme_type_variation を使用してください。
• StyleBox に色をハードコードしないでください — パレットの信頼できる情報源を一元化するため、theme.get_color() を使用してください。
• グローバルスタイルに add_theme_override を使用しないでください — この方法は壊れやすくなります。プロジェクト全体へ自動的に適用するには、Theme リソースでスタイルを定義してください。
• _draw() または _process() 中にテーマリソースを変更しないでください — 頻繁なレイアウト再計算によって、パフォーマンスが大幅に低下します。
• フォーカススタイルにフォールバックなしで StyleBoxEmpty を割り当てないでください — コントローラー／キーボード操作が気づかれないまま機能しなくなります [1]。必ず視認できる代替手段（例：スケールの変更）を用意してください。
• テーマプロパティに標準の set() を使用しないでください — node.set("font_color", red) は失敗します。専用の add_theme_color_override() API を必ず使用してください [3]。
• クリック可能領域を広げるために expand_margin_* を使用しないでください — これは視覚的な境界を広げるだけです。入力が機能するよう、StyleBox の content_margin_* を使用するか、Control のサイズを調整してください [5]。
• _draw() 内で StyleBox をローカル変数として定義しないでください — RenderingServer が描画を完了する前にガベージコレクションされる可能性があります [7]。クラスレベルに保存してください。
• 色を1つ変えるだけのためにシーンやテーマを複製しないでください — 同じ Theme 内で軽量な派生スタイル（例：「DangerButton」）を作成するには、theme_type_variation を使用してください [8]。
• StyleBoxFlat で corner_radius_all を省略しないでください — 角を均一に丸めるための省略記法です。すべての角が同じ場合は、4つの個別の半径フィールドよりこちらを優先してください。
• Theme アイテムと Control の上書きを混同しないでください — add_theme_*_override はそのノード上でのみ Theme リソースのアイテムより優先されます。独自の theme を持つ子 Control があると、親からのカスケードはブロックされます。ルートを切り替えるときは remove_theme_*_override でクリアし、新しい Theme と古い上書きが競合したままにならないようにしてください。

判断ツリー — テーマの所有者

目的	選択肢	備考／スクリプト
アプリ全体の外観	プロジェクト設定 → GUI → Theme	Theme エディターで作成します — ここではノードごとの StyleBox チュートリアルは扱いません
1つの Control だけを変える	そのノードで add_theme_*_override	ローカルのみです。グローバルスタイルには使用しないでください
ボタン／パネルのサブタイプ	theme_type_variation	danger_button_assignment.gd を参照してください
共有 Theme を変更せずに実行時の色を調整する	stylebox.duplicate() の後に上書き	dynamic_stylebox_color.gd を参照してください

フォントと StyleBox：Theme エディター／プロジェクト Theme から編集してください。実行時ヘルパー：global_theme_manager.gd、theme_swapper.gd、procedural_theme_safe.gd。

上級者向けテーマ設定パターン

1. 共有カラーパレット（静的パターン）

Theme エディターと GDScript の両方からアクセスできる、UI カラーの信頼できる情報源を一元化します。

• Theme の設定：.theme ファイルで Palette というカスタムタイプを作成し、Color アイテム（例：primary、danger、accent）を追加します。
• 静的アクセス：ThemeDB.get_project_theme() から値を取得する static func get_primary() -> Color を持つ SharedPalette クラスを使用します。これにより、UI スクリプトとビジュアルテーマが食い違わないようにできます。

2. テーマタイプのバリエーション

「Danger」や「Ghost」スタイルのようなバリエーションごとに、ボタンのシーンやスタイルボックスを複製するのは避けてください。

• 実装：テーマエディターで新しいタイプバリエーションを作成します。ベースタイプをButtonに設定します。
• 継承：バリエーションはベースタイプのすべてのプロパティを継承します。異なる部分のみを上書きします（例：DangerButtonのfont_colorを赤に設定します）。
• 使用方法：コードでnode.theme_type_variation = &"DangerButton"を設定するか、インスペクターのドロップダウンから割り当てます。

必須：danger_button_assignment.gdを読んでください。色のバリエーションごとにButtonのシーンをフォークしないでください。

3. 実行時のStyleBoxの色（最初に複製）

1つのControlの色合いを実行時に変更する場合は、変更を加える前にStyleBoxを複製してください。共有されるThemeのStyleBoxは変更せずに保つ必要があります。

必須：dynamic_stylebox_color.gdを読んでください。ThemeのStyleBoxをその場で変更しないでください。

4. 実行時のテーマ切り替え（アクセシビリティ）

ゲーム全体のビジュアルスタイルを、ライト、ダーク、ハイコントラストの各モードに効率よく切り替えます。

• カスケード更新：新しいThemeリソースをルートのControlノードに割り当てます。Godotがすべての子孫ノードに反映します。
• アクセシビリティ：自動テーマ設定に対応していない要素（カスタムの_draw()ロジックやRichTextエフェクトなど）を更新するには、NOTIFICATION_THEME_CHANGEDを使用します。
• ハイコントラスト：弱視のユーザーが利用しやすいよう、ハイコントラストテーマでは純粋な黒と白を使用し、フォーカスアウトラインを太くします。

必須：theme_swapper.gdを読んでください。テーマのルートで切り替え、すべてのControlにテーマを割り当てるために1つずつ処理しないでください。

5. RTL／LTRテーマのミラーリング

双方向レイアウトでは、方向が切り替わる際にStyleBoxやタイプバリエーションのセットをミラーリングする必要があります。アンカーだけを手動で反転する方法では不十分です。

必須：rtl_theme_mirroring.gdを読んでください。レイアウト方向に応じてテーマのバリエーションを切り替え、LTRの余白をハードコードしないでください。

6. テーマ付きアセットの読み込み（季節ごとのバリエーション）

Godotのテーマには、色やフォントだけでなく、テクスチャも保存できます。

• 設定：UIアイコンを、個別のThemeリソース（例：halloween.theme、christmas.theme）内のアイコン項目として定義します。
• 切り替え：ルートのテーマリソースを切り替えると、手動のロジックなしで新しいアイコンテクスチャがすべてのボタンやパネルに即座にカスケード反映されます。

7. UIフォーカスマネージャー（動的なコントローラーアイコン）

標準のフォーカススタイルは静的です。アクセシビリティを考慮したUXのため、デバイスに応じてプロンプトアイコンを切り替え、ハイライトパネルをget_global_rect()へトゥイーンします。

必須：focus_prompt_icon_swapper.gdを読んでください。ジョイパッドのアイコンパスをControlのスクリプトに貼り付けないでください。

上記の実行時のテーマ切り替え（アクセシビリティ）および、ハイコントラストのルートに使用するtheme_swapper.gdと組み合わせてください。

8. アセット依存関係の監査（ドローコールの削減）

UIテクスチャがレンダリング性能に最適化されていることを確認します。

• アトラスへのパッキング：AtlasTextureを使用して、大きな1枚のシートから小さなUI要素を切り出します。これによりVRAMの状態変更を減らし、ドローコールを最小限に抑えられます[14]。
• 圧縮ポリシー：
  • 2D／ピクセルアート：ぼやけたアーティファクトを防ぐため、ロスレス圧縮を使用します[15]。
  • UIの背景：VRAMの使用量を増やさずにディスク容量を節約するため、大きなイラストにはロッシー圧縮またはBasis Universalを使用します[15]。
• 監査：ResourceLoader.get_dependencies(scene_path)を使用して、圧縮されていない生アセット（例：.png）が最終エクスポートに紛れ込んでいないことを確認します[19]。

詳細レシピ（必要に応じて）

LLMが知らない前提のルール：一般的なエージェントが読む前に知らないような内容は、ここかscripts/に置きます。削除せず、移動してください。

トピック	リファレンス
StyleBox／フォントの設定	theme-authoring-recipes.md

リファレンス

段階的開示：特定の API を調査するときにのみ公式ドキュメントのリンクを開きます。 作業を関連領域の担当者に割り当てるときに関連スキルを読み込み、スキル全体を事前に読み込まないでください。

公式ドキュメント

• GUI のスキン設定 — Theme リソース、StyleBox、カスケード式のスキン所有権について説明します。
• テーマエディターの使用 — Control ごとのオーバーライドをすべて手動編集せずに Theme アセットを作成します。
• テーマタイプのバリエーション — テーマ全体を複製せずに、ボタンやパネルのサブタイプ向けのバリエーションを作成します。
• フォントの使用 — UI の読みやすさを高める DynamicFont／フォントサイズのテーマ設定について説明します。
• カスタム GUI コントロール — テーマを適用した _draw() でテーマ項目の参照が必要な場合について説明します。
• サイズとアンカー — テーマのスケールや DPI の変更に耐えるレイアウトについて説明します。
• Theme — 色、定数、アイコン、StyleBox の実行時の取得／設定について説明します。
• ThemeDB — プロジェクトのデフォルトテーマとフォールバックの解決について説明します。
• Control — テーマのオーバーライドと NOTIFICATION_THEME_CHANGED について説明します。
• StyleBox — ほとんどの Theme スキンで使用されるパネル／ボタンの装飾について説明します。
• AtlasTexture — UI アイコンをまとめて、描画呼び出しの頻繁な発生を抑えます。
• Input — カスタムカーソルと、ジョイパッド操作に応じたプロンプトアイコンの切り替えについて説明します。

関連スキル

前提条件

• godot-project-foundations — スキンシステムを構築する前に、プロジェクトのレイアウトと Control／Theme のデフォルト配置を整えます。
• godot-resource-data-patterns — パス文字列が散在しないよう、Theme／StyleBox／アイコンのバンクを Resource として管理します。
• godot-ui-containers — テーマの仕上げでレイアウトの問題が隠れる前に、コンテナを適切に設定します。
• godot-signal-architecture — テーマの切り替えやアクセシビリティモードの変更は、ポーリングせずシグナルで上位に伝えます。

補完スキル

• godot-ui-rich-text — Theme の書体と一貫性を保つ必要がある BBCode／フォントについて説明します。
• godot-tweening — フォーカスハイライトパネルと季節テーマの切り替えについて説明します。
• godot-input-handling — コントローラーに対応したプロンプトアイコンとフォーカス移動について説明します。
• godot-autoload-architecture — 所有権を明確にした Autoload としてのテーママネージャーについて説明します。
• godot-export-builds — 出荷する UI の VRAM に影響するアトラス／圧縮ポリシーについて説明します。
• godot-performance-optimization — 密度の高い HUD スキン向けの描画呼び出しとアトラスのパッキングについて説明します。

下流 / 利用先

• godot-theme-easter — このスキルに重ねて、テーマやアイコンのバンクを切り替える季節限定のオーバーレイです。
• godot-composition-apps — テーマの一貫性が成否を左右するアプリの UI です。
• godot-genre-visual-novel — ダイアログの装飾はテーマに大きく左右されます。
• godot-platform-mobile — タッチ操作向けの拡大表示と高コントラストのテーマバリエーションです。

マスター

• godot-master — UI テーマ設定用のライブラリルーター兼ミラー化されたモジュールエントリです。