godot-theme-easter

概要

季節限定の「イースター風」ツールキットです。明るいパステルカラー、弾むような爽快感、卵やウサギのアイコンを取り入れ、カレンダーと設定によって有効化します。

最初に必ず読むこと： easter_seasonal_activation_gate.gd — 日付範囲、「Disable Seasonal Themes」のオプトアウト設定（user://settings.cfg）、開発者用オーバーライドを扱います。設定が変更されたら refresh_activation() を呼び出してください。_process でカレンダーをポーリングしてはいけません。

前提条件： ベースとなる Theme リソースが存在するまで、godot-ui-theming を読み込まないでください。季節限定のオーバーレイは StyleBox のオーバーライドを適用するものであり、基盤となる Theme の作成に代わるものではありません。

季節限定の初期化手順（順番どおり）

1. ゲート — easter_seasonal_activation_gate.gd をアタッチし、_ready 時と設定変更時に refresh_activation() を呼び出します。
2. テーマ — ゲートが有効な場合は、easter_pastel_color_palette.gd のトークンを使って、必ず easter_runtime_ui_themer.gd を使用します。
3. オーディオ — 標準 UI 効果音を季節限定のストリームに割り当てるため、必ず easter_seasonal_audio_swapper.gd を使用します。
4. 演出 — 手順 1〜3 が完了してから、紙吹雪、きらめき、カーソル、揺れのスクリプトを追加します（ゲートが無効な場合は、手順 2〜4 をすべてスキップします）。

判断ツリー — 代替ペインター（いずれか 1 つを選択）

コンテキスト	使用するもの	併用しないもの
surface_override を使った 3D メッシュの季節限定色調変更	easter_mesh_painter_override.gd	同じメッシュに対する easter_palette_override.gd
2D／modulate またはマテリアルスロットの切り替えがすでに設定済み	easter_palette_override.gd または seasonal_material_swapper.gd	同じ対象に対する mesh_painter

コアコンポーネント（イースター向け上級ツール）

easter_seasonal_activation_gate.gd

必須 — オプトアウトと開発者用オーバーライドに対応した、日付対応のマネージャーです。

easter_pastel_color_palette.gd

パステルカラーの Color トークンの唯一の信頼できる情報源です。SKILL 本文や無関係なスクリプトに 16 進数の色リストをハードコードしないでください。

easter_runtime_ui_themer.gd

UI ツリー全体にパステルスタイルを一括適用する、実行時テーマインジェクターです。

easter_squash_stretch_juice.gd

Tween を使い、卵のような有機的な動きを実現する上級者向けの「スクワッシュ＆ストレッチ」ロジックです。

easter_shimmer_vfx_emitter.gd

加算ブレンドとスケールカーブを使った、プロ品質の「隠しアイテム」きらめきエフェクトです。

easter_egg_collection_tracker.gd

シグナルベースの進行シグナルを使って隠しアイテムを追跡する、上級者向けのレジストリです。

easter_mesh_painter_override.gd

サーフェスオーバーライドを使ってベースアセットを保持する、季節限定の 3D マテリアル切り替え機能です。

easter_wobble_physics_body.gd

不安定さを取り入れた、「卵のように」揺れながら動く物理ボディです。

easter_camera_pop_juice.gd

アイテムの収集やポップの演出を強調する、没入感のある FOV の「キック」ロジックです。

easter_confetti_canon_vfx.gd

多色のパステルカラーの紙吹雪を使った、お祝い用の紙吹雪エフェクトです。

easter_custom_cursor_manager.gd

システムのマウスカーソルを、テーマに合わせたイースターアイコンに切り替える上級者向けのロジックです。

easter_seasonal_audio_swapper.gd

標準 UI サウンドを季節限定のバリエーションに置き換える、動的オーディオリソースローダーです。

easter_palette_override.gd / seasonal_material_swapper.gd

代替のペインターです — 上記の Decision Tree — Alternate Painters を参照し、対象ごとにいずれか一方の方法を選んでください。

ビジュアルガイドライン

• 色： easter_pastel_color_palette.gd からトークン（PINK、BLUE、YELLOW、MINT、PURPLE）をインポートしてください。機能に場当たり的な16進数カラーの羅列を直接貼り付けないでください。
• 形状： 角を丸くします（corner_radius > 8–12）。鋭いエッジやコントラストの強い黒は避けてください。
• VFX： 紙吹雪、きらめき、リボンには、紙吹雪／きらめきスクリプトを使用してください。

絶対に避けること（イースターに関する専門家向けルール）

美しさと演出

• 鋭いエッジやコントラストの強い黒は絶対に使わないでください — イースターの美しさには、丸みのある角（corner_radius > 12）と柔らかなパステルトーンが適しています。
• 弾む動きに標準の線形スケーリングを絶対に使わないでください — 線形スケーリングは「ロボット的」に感じられます。有機的な卵の動きには、必ず TRANS_ELASTIC または TRANS_QUART を使用してください。
• イースターのパーティクルにビルボードを絶対に使わないでください — UI の近接表示や VR では、ビルボードのきらめきが平面的に見えます。メッシュベースのパーティクルまたは軸回転を使用してください。

ロジックとパフォーマンス

• 元の .mesh または .tres リソースを絶対に変更しないでください — 共有 Resource のマテリアルを入れ替えると、ゲーム内のすべてのインスタンスに変更が反映されます。必ず surface_override または duplicate() を使用してください。
• _process で日付を絶対に確認しないでください — 毎フレーム、システムのカレンダーを確認するのは無駄です。Time.get_date_dict_from_system() は _ready で一度だけ実行するか、アクティベーションゲートを通じてイベント発生時に実行してください。
• 「No-Seasonal」トグルを絶対に無視しないでください — 季節ごとのオーバーライドを嫌うプレイヤーもいます。必ず設定に「季節テーマを無効にする」オプションを用意し、ゲートの ConfigFile キーを通じて接続してください。

上級者向けテーマ設定フック

• 動的な Z 順序： RenderingServer.canvas_item_set_draw_index() を使用すると、ノードを再親化せずに、取得した卵のパーティクルを UI の描画順の最前面へ動的に移動できます。
• 物理補間： 物理駆動の卵に TRANS_ELASTIC トゥイーンを使用する場合は、RenderingServer.canvas_item_reset_physics_interpolation() を呼び出し、ポップアニメーションの最初のフレームで視覚的な「ジッター」が発生するのを防いでください。
• StyleBox のオーバーライド： グローバルの Theme を変更するのではなく、Control.add_theme_stylebox_override("panel", my_stylebox) を使用し、季節ごとの変更を特定の UI モジュールに限定してください。

上級者向けイースター実装

1. カスタムマウスカーソル（演出）

必須： easter_custom_cursor_manager.gd — 必ず hotspot（うさぎの耳の先端／付け根）を設定してください。

2. テーマ別サウンドローダー

必須： easter_seasonal_audio_swapper.gd — 元の AudioStream と季節版の AudioStream のペアを格納したリソースマップです。

3. World-Environment-Override（春の輝き）

トランジション中に Environment のアンビエント／トーンマップ／フォグをトゥイーンしてください。フレームの途中で色を急に切り替えないでください。

func _apply_spring_env(env: Environment) -> void:
    var tween := create_tween()
    tween.tween_property(env, "ambient_light_color", EasterPastelColorPalette.YELLOW, 2.0)
    tween.tween_property(env, "tonemap_exposure", 1.2, 2.0)
    tween.tween_property(env, "fog_light_color", EasterPastelColorPalette.BLUE, 2.0)

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

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

トピック	リファレンス
カーソル／オーディオ／環境のレシピ	seasonal-implementation-recipes.md

リファレンス

段階的開示：特定の API を調査するときに限り、公式ドキュメントへのリンクを開いてください。 作業を関連分野の担当者へ振り分けるときは、関連スキルを読み込んでください。依存関係の全体を事前に読み込まないでください。

公式ドキュメント

• GUI スキニング — 季節ごとのテーマ切り替えと StyleBox の分離。
• テーマエディターの使用 — コードのみのスキンを使わずにイースターテーマのバリエーションを作成できます。
• テーマの型バリエーション — テーマ全体をフォークせずに卵やボタンのバリエーションを実現できます。
• パーティクルシステム (2D) — コレクションの爽快感を高める紙吹雪やきらめきの VFX。
• Tween — 弾むような卵のポップとカメラのパンチ。
• 環境とポストプロセス — 春の WorldEnvironment のグローやフォグのトゥイーン。
• Theme — 実行時の季節テーマの割り当て。
• Input — カスタムのうさぎカーソルのホットスポット。
• AudioStreamPlayer — 季節ごとの SFX バンクの再生。
• RenderingServer — 爽快感のある卵のための描画インデックスと物理補間の修正。
• GPUParticles2D — 紙吹雪の発射装置ときらめきのエミッター。
• Environment — アンビエント、トーンマップ、フォグの季節ごとのオーバーライド。

関連スキル

前提条件

• godot-ui-theming — 季節ごとのオーバーレイの前に必要なベーステーマのアーキテクチャ。
• godot-project-foundations — 季節パック用のアセットフォルダーと有効化ゲート。
• godot-resource-data-patterns — サウンドオーバーライドマップとパレットのリソース。
• godot-signal-architecture — コレクションのトラッカーと季節ごとの有効化イベント。

補完

• godot-tweening — 弾む TRANS のポップとカメラの爽快感。
• godot-particles — GPUParticles を再発明せずに紙吹雪やきらめきのエミッターを実現できます。
• godot-audio-systems — 季節ごとの SFX バンクとバスのルーティング。
• godot-2d-animation — コレクティブルに対するスクワッシュ・ストレッチの爽快感。
• godot-camera-systems — 卵を集めたときのカメラのパンチ。
• godot-3d-lighting — ゲームが 3D の場合の環境の春のグロー。

下流／利用者

• godot-genre-party — 季節限定のパーティーモードでは、このジューススタックをよく再利用します。
• godot-genre-puzzle — 軽めのパズルコンテンツとして、収集要素のあるエッグハントを取り入れます。
• godot-game-loop-collection — 季節限定のトラッカーを利用する収集ループです。
• godot-monte-carlo-balancer — 卵の報酬が進行条件になっている場合は、ドロップの経済バランスを検証します。

マスター

• godot-master — 季節テーマ向けのライブラリールーターおよびミラー化されたモジュールエントリーです。