Start dynamic sky

dynamic-sky/SPEC.md

@@ -0,0 +1,180 @@
+# 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.