# 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.