181 lines
6.7 KiB
Markdown
181 lines
6.7 KiB
Markdown
# 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.
|