Trinittu/dynamic-sky/SPEC.md

Stylized Dynamic Sky Specification (Godot 4.6)

Overview

This document specifies a stylized dynamic sky system for Godot 4.6. It defines the required features, behavior, data structures, and integration points without prescribing implementation code.

Goals

• Provide a visually stylized, dynamic sky suitable for stylized or semi-realistic games.
• Offer modular components that can be combined or replaced.
• Enable deterministic playback for cutscenes and synchronized multiplayer.
• Support art-direction via presets and editor-friendly controls.

Non-Goals

• Physically accurate atmospheric scattering.
• Real-world meteorology simulation.
• Automated terrain-aware shadow projections.

System Architecture

• DynamicSkyRoot: Top-level scene controlling time, weather, and global parameters.
• SkyboxPresetLibrary: Collection of preset skybox nodes (configured resources/scenes).
• DayNightController: Controls sun/moon movement, ambient light, and time-of-day curves.
• WeatherController: Drives weather states, transitions, and VFX spawning.
• CloudSystem2D: Handles layered 2D cloudscapes, flow, animation, and evolution.
• PostProcessController: Applies stylized gradients, fog shaping, and sun glow.
• VFXController: Shooting stars and meteor showers.
• ShadowProxySystem: Faked cloud shadows projected onto world.

Feature Specifications

Preset Skybox Nodes

Description: Pre-authored skybox configurations that can be swapped at runtime.

Requirements:

• At least 6 presets: Clear Day, Sunset, Night, Overcast, Storm, Dawn.
• Each preset includes:
  • Skybox texture/gradient resources.
  • Sun and moon color presets.
  • Ambient and fog color presets.
  • Default cloud layers and post-process settings.
• Presets can be overridden by runtime controllers without losing base values.
• Preset application is non-destructive and reversible.

Editor UX:

• Preset picker dropdown.
• “Apply Preset” button and “Revert to Preset” button.

Day/Night Cycle

Description: Stylized, configurable cycle controlling lighting and sky appearance.

Requirements:

• Time scale with configurable length (e.g., 10–240 minutes per day).
• Supports manual time-of-day override and pause.
• Sun and moon directional motion (arc across sky dome).
• Color and intensity curves:
  • Sun color and intensity.
  • Moon color and intensity.
  • Ambient color and intensity.
  • Fog color and density.
• Smooth transitions between time states.
• Optional star visibility curve.

Data:

• TimeOfDay (0.0–1.0 normalized)
• Curves for color/intensity across time.

Weather System

Description: State-based weather controller with transitions and parameters.

Weather States:

• Clear
• Cloudy
• Overcast
• Rain
• Storm
• Snow (optional, can be disabled)

Requirements:

• State machine with configurable transition durations.
• Each state defines:
  • Cloud density, opacity, and coverage.
  • Wind speed and direction (affects cloud flow).
  • VFX sets (rain, lightning, snow).
  • Ambient and fog adjustments.
• Randomized or scripted weather timeline support.
• Events/callbacks on state enter/exit.

2D Customizable Cloudscapes

Description: Layered 2D clouds rendered on the sky dome or as screen-space quads.

Requirements:

• Up to 4 independent layers: low, mid, high, wisps.
• Per-layer settings:
  • Texture/atlas selection.
  • Tiling and scale.
  • Opacity and color tint.
  • Parallax depth factor.
  • Flow direction and speed.
• Global cloud coverage control.

Cloud Flow, Animation, and Evolution

Description: Dynamic motion and shape changes over time.

Requirements:

• Continuous UV flow with wind influence.
• Optional noise-based distortion for stylized movement.
• Evolution parameter to morph coverage and shape (low-frequency drift).
• Time-based variation seed to keep deterministic playback when seeded.

Cloud Lighting Reacts with Sun and Moon

Description: Cloud shading changes based on celestial light direction and intensity.

Requirements:

• Light direction taken from sun/moon controller.
• Bright side and shadowed side color control.
• Night-time soft illumination from moon.
• Optional rim glow at dawn/dusk.

Weather Particle Kill Volumes

Description: Volumes that stop precipitation or weather particles in indoor or sheltered spaces.

Requirements:

• Axis-aligned and/or custom-shaped kill volumes.
• Particles inside kill volume are disabled or instantly culled.
• Priority/stacking rules when volumes overlap.
• Optional fade-out margin to avoid hard cutoffs.

Stylized Post Process for Fog and Sun Gradients

Description: Screen-space effects to enhance gradients and fog stylization.

Requirements:

• Adjustable sky gradient curve blending.
• Fog shaping controls (height fog, distance fog).
• Sun glow halo with stylized falloff.
• Dusk/dawn gradient emphasis.
• Option to toggle for performance profiles.

Shooting Star and Meteor Shower VFX

Description: Procedural or timed visual effects visible in the sky.

Requirements:

• Occasional shooting stars (randomized frequency).
• Meteor shower events with configurable duration and intensity.
• Trail length, brightness, and color control.
• Optional audio event hook for meteor shower start.

Faked Cloud Shadows

Description: Stylized cloud shadow overlay projected onto the world.

Requirements:

• Shadow texture projected in world space or onto a large quad.
• Movement matches cloud flow direction and speed.
• Darkness/opacity controls and color tint.
• Optional blur for softer look.

Data and Configuration

• SkyConfig Resource: Stores defaults for all controllers.
• Preset Resource: Encapsulates a SkyConfig plus skybox assets.
• WeatherProfile: Per-state settings and VFX parameters.
• CloudLayerConfig: Texture/flow/lighting settings per layer.
• PostProcessProfile: Gradient, fog, and sun glow parameters.

Performance Targets

• Target 60 FPS on mid-range hardware.
• Cloud layers should allow selective disabling.
• VFX update rates configurable.

Debug and Tooling

• On-screen debug panel showing time, weather state, cloud parameters.
• Seed display for deterministic playback.
• Editor gizmos for kill volumes.

Acceptance Criteria

• All required features are present and configurable in editor.
• Presets can be applied and reverted without data loss.
• Day/night transitions are smooth with no visible jumps.
• Weather transitions alter clouds, lighting, and VFX consistently.
• Cloud lighting visibly reacts to sun/moon changes.
• Kill volumes prevent precipitation in indoor spaces.
• Post process improves gradients and fog stylization.
• Shooting stars and meteor showers visible at night.
• Cloud shadows visibly move across the world.