godot-theme-easter

Overview

Seasonal "Easter-fy" toolkit: bright pastels, bouncy juice, egg/bunny iconography — gated by calendar + settings.

MANDATORY first read: [easterseasonalactivationgate.gd](scripts/easterseasonalactivationgate.gd) — date window, Disable Seasonal Themes opt-out (user://settings.cfg), and Dev Override. Call refreshactivation() when settings change; never poll the calendar in process.

Prerequisite: Do NOT Load godot-ui-theming until a base Theme resource exists — seasonal overlays inject StyleBox overrides; they do not replace foundational Theme authoring.

Seasonal Bootstrap (ordered)

1. Gate — Attach [easterseasonalactivationgate.gd](scripts/easterseasonalactivationgate.gd); call refreshactivation() on ready and when settings change.
2. Theme — If gate active: MANDATORY [easterruntimeuithemer.gd](scripts/easterruntimeuithemer.gd) using tokens from [easterpastelcolorpalette.gd](scripts/easterpastelcolorpalette.gd).
3. Audio — MANDATORY [easterseasonalaudioswapper.gd](scripts/easterseasonalaudioswapper.gd) to map standard UI SFX → seasonal streams.
4. Juice — Layer confetti/shimmer/cursor/wobble scripts only after steps 1–3 pass (gate off = skip 2–4 entirely).

Decision Tree — Alternate Painters (pick one)

Core Components (Expert Easter Tools)

[easterseasonalactivationgate.gd](scripts/easterseasonalactivationgate.gd)

MANDATORY — Date-aware manager with opt-out + Dev Override.

[easterpastelcolorpalette.gd](scripts/easterpastelcolorpalette.gd)

Single source of truth for pastel Color tokens — do not hardcode hex lists in SKILL bodies or random scripts.

[easterruntimeuithemer.gd](scripts/easterruntimeuithemer.gd)

Runtime theme injector for applying mass pastel styles across the UI tree.

[eastersquashstretchjuice.gd](scripts/eastersquashstretchjuice.gd)

Expert 'Squash and Stretch' logic for organic egg-like interactions using Tweens.

[eastershimmervfxemitter.gd](scripts/eastershimmervfxemitter.gd)

Professional 'Hidden Item' shimmer effect with additive blending and scale curves.

[eastereggcollectiontracker.gd](scripts/eastereggcollectiontracker.gd)

Expert registry for tracking hidden items with signal-based progression signals.

[eastermeshpainteroverride.gd](scripts/eastermeshpainteroverride.gd)

Seasonal 3D material swapper using surface overrides to preserve base assets.

[easterwobblephysicsbody.gd](scripts/easterwobblephysicsbody.gd)

Instability-driven physics body for 'Egg-like' wobbly movement.

[eastercamerapopjuice.gd](scripts/eastercamerapopjuice.gd)

Immersive FOV 'kick' logic to emphasize collection or pop events.

[easterconfetticanonvfx.gd](scripts/easterconfetticanonvfx.gd)

Celebratory confetti explosion with multi-colored pastel flakes.

[eastercustomcursormanager.gd](scripts/eastercustomcursormanager.gd)

Expert logic for swapping system mouse cursors with themed Easter icons.

[easterseasonalaudioswapper.gd](scripts/easterseasonalaudioswapper.gd)

Dynamic audio resource loader that replaces standard UI sounds with seasonal variants.

[easterpaletteoverride.gd](scripts/easterpaletteoverride.gd) / [seasonalmaterialswapper.gd](scripts/seasonalmaterialswapper.gd)

Alternate painters — see Decision Tree — Alternate Painters above; pick one path per target.

Visual Guidelines

• Colors: Import tokens from [easterpastelcolorpalette.gd](scripts/easterpastelcolorpalette.gd) (PINK, BLUE, YELLOW, MINT, PURPLE) — never paste ad-hoc hex laundry lists into features.
• Shapes: Rounded corners (corner_radius > 8–12). Avoid sharp edges / high-contrast blacks.
• VFX: Confetti, sparkles, ribbons via confetti/shimmer scripts.

NEVER Do (Expert Easter Rules)

Aesthetics & Juice

• NEVER use sharp edges or high-contrast blacks — Easter aesthetics favor rounded corners (corner_radius > 12) and soft pastel tones.
• NEVER use standard linear scaling for pops — Linear scaling feels 'robotic.' Always use TRANSELASTIC or TRANSQUART for organic eggs.
• NEVER use billboarding for Easter particles — In close-up UI or VR, billboard sparkles look flat. Use mesh-based particles or axial rotation.

Logic & Performance

• NEVER modify the original .mesh or .tres resource — Swapping materials on a shared Resource changes it for EVERY instance in the game. Always use surface_override or duplicate().
• NEVER run date-checks in process — Checking the system calendar every frame is wasteful. Run Time.getdatedictfromsystem() once on ready or event trigger via the activation gate.
• NEVER ignore the 'No-Seasonal' toggle — Some players hate seasonal overrides. Always provide a 'Disable Seasonal Themes' option in settings (wired through the gate's ConfigFile keys).

Elite Theming Hooks

• Dynamic Z-Ordering: Use RenderingServer.canvasitemsetdrawindex() to dynamically move collected egg particles to the front of the UI stack without reparenting nodes.
• Physics Interpolation: When using TRANSELASTIC tweens on physics-driven eggs, invoke RenderingServer.canvasitemresetphysics_interpolation() to prevent visual "jitter" on the first frame of the pop animation.
• StyleBox Overrides: Use Control.addthemestyleboxoverride("panel", mystylebox) instead of modifying the global Theme to isolate seasonal changes to specific UI modules.

Expert Easter Implementation

1. Custom-Mouse-Cursor (Juice)

MANDATORY: [eastercustomcursormanager.gd](scripts/eastercustomcursormanager.gd) — always set a hotspot (bunny-ear tip / base).

2. Themed-Sound-Loaders

MANDATORY: [easterseasonalaudioswapper.gd](scripts/easterseasonalaudioswapper.gd) — Resource map of original → seasonal AudioStream pairs.

3. World-Environment-Override (Spring Glow)

Tween Environment ambient/tonemap/fog during a transition — never hard-cut colors mid-frame.

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)

Deep recipes (on demand)

LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API;
load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• GUI skinning — Seasonal Theme swaps and StyleBox isolation.
• Using the theme editor — Author Easter Theme variants without code-only skins.
• Theme type variations — Egg/button variants without forking the whole theme.
• Particle systems (2D) — Confetti / shimmer VFX for collectible juice.
• Tween — Elastic egg pops and camera punch.
• Environment and post-processing — Spring WorldEnvironment glow/fog tweens.
• Theme — Runtime seasonal Theme assignment.
• Input — Custom bunny cursor hotspots.
• AudioStreamPlayer — Seasonal SFX bank playback.
• RenderingServer — Draw-index and physics-interpolation fixes for juiced eggs.
• GPUParticles2D — Confetti canons and shimmer emitters.
• Environment — Ambient/tonemap/fog seasonal overrides.

Related Skills

Prerequisites

• godot-ui-theming — Base Theme architecture before seasonal overlays.
• godot-project-foundations — Asset folders and activation gates for seasonal packs.
• godot-resource-data-patterns — Sound override maps and palette Resources.
• godot-signal-architecture — Collection trackers and seasonal activation events.

Complements

• godot-tweening — Elastic TRANS pops and camera juice.
• godot-particles — Confetti/shimmer emitters without reinventing GPUParticles.
• godot-audio-systems — Seasonal SFX banks and bus routing.
• godot-2d-animation — Squash/stretch juice on collectibles.
• godot-camera-systems — Camera pop punches on egg collect.
• godot-3d-lighting — Environment spring glow when the game is 3D.

Downstream / consumers

• godot-genre-party — Seasonal party modes often reuse this juice stack.
• godot-genre-puzzle — Collectible egg hunts as light puzzle content.
• godot-game-loop-collection — Collection loops that consume seasonal trackers.
• godot-monte-carlo-balancer — If egg rewards gate progression, validate drop economies.

Master

• godot-master — Library router and mirrored module entry for seasonal themes.