System Requirements Document for environmentworld-godot

1. Introduction

This document specifies environmentworld-godot, a ready-to-use 3D EnvironmentWorld setup (script + scene configuration) for Godot 4.7 that delivers the environment graphics for a scene: sky, clouds, lighting, and weather. The product intent is a beautiful, near-AAA urban environment look with a full day/night cycle — day, afternoon, night, and dawn (madrugada) — each with its own sky and cloud palette, no fog in the normal weather state, slightly boosted contrast and saturation, and a rain weather state in which the sky turns grey, raindrops fall from the sky, and rain reflections are visible.

The audience is a Godot environment artist (the project owner, Cristian Sanchez) who wants to drop the EnvironmentWorld into a 3D scene and immediately see the requested sky, cloud, and weather transitions without authoring the environment graphics from scratch.

2. System Overview

The product is a Godot 4.7 project asset: a 3D EnvironmentWorld composed of a WorldEnvironment configuration (sky material, environment settings, tonemapping, glow, reflections), a day/night cycle driver script, a cloud setup, and a rain weather state with particle raindrops and reflective wet surfaces. It is delivered as engine-side content — a script and scene setup — not as a web application, dashboard, or account-based service.

Actors

• Godot Environment Artist (active human persona): the person who installs, configures, and previews the EnvironmentWorld inside a Godot 4.7 3D scene.
• Godot Engine runtime (non-persona system actor): executes the EnvironmentWorld script, advances the day/night cycle, and renders sky, clouds, lighting, rain, and reflections.

Accepted behavior

• Daytime sky in light blue (celeste) tones with beautiful white clouds.
• Afternoon/late-day sky shifting to pink and light blue tones, with clouds matching those tones.
• Night sky in a beautiful blue.
• A full cycle covering day, afternoon, night, and dawn (madrugada).
• Normal (clear) weather as the default, with no fog.
• Slightly increased contrast and saturation for the EnvironmentWorld.
• Urban style graphics, close to AAA quality.
• A rain weather state: grey sky, raindrops falling from the sky, and visible rain reflections.
• Delivered as a 3D EnvironmentWorld.

Narrow exclusions

• No fog in the normal weather state (explicit constraint).
• No web UI, dashboard, account system, or network service is part of this product; delivery is engine-side Godot content.

2a. Product Interpretation and Delivery Boundary

The EnvironmentWorld is delivered as Godot 4.7 engine content that the artist adds to a 3D scene. All interaction happens inside the Godot editor and running game viewport: the artist attaches the EnvironmentWorld, sets the cycle speed and starting time of day, and toggles weather between normal and rain. The Godot runtime owns the continuous rendering and cycle advancement; the artist owns configuration and preview.

There is no application-owned identity, login, or remote service. The artist's "access" to the product is possession of the Godot project files and the editor. The current delivery horizon covers the day/night cycle, the four named time-of-day looks, the no-fog normal weather, the contrast/saturation boost, the urban near-AAA styling, and the rain state with grey sky, falling raindrops, and rain reflections. Nothing beyond these is in scope.

2b. Page Content and Component Coverage

The product has no web pages. Its user-facing surface is the Godot editor inspector and the running 3D viewport. Coverage below describes the EnvironmentWorld scene and its components as the product's working surface.

EnvironmentWorld Scene (Godot 4.7, 3D)

• Information/state
  • Current time of day within the cycle (day, afternoon, night, dawn).
  • Current weather state (normal/clear or rain).
  • Sky color and cloud color for the active time of day.
  • Environment settings: no fog in normal weather, boosted contrast and saturation, urban near-AAA look.
• Primary actions
  • Add the EnvironmentWorld to a 3D scene.
  • Set cycle speed and starting time of day.
  • Toggle weather between normal and rain.
  • Preview the scene in the Godot viewport.
• Supporting actions
  • Adjust contrast and saturation values.
  • Adjust rain intensity and reflection strength.
• Domain entities
  • EnvironmentWorld (scene root with WorldEnvironment).
  • DayNightCycle (driver script controlling time of day).
  • SkyProfile per time of day (day, afternoon, night, dawn) with sky and cloud colors.
  • WeatherState (normal, rain) with sky tint, raindrop emitter, and reflection settings.
• Component responsibilities
  • WorldEnvironment: applies sky material, ambient light, tonemap, glow, and reflection settings.
  • DayNightCycle script: advances time, interpolates sky/cloud colors between the four time-of-day profiles, and drives sun/moon lighting.
  • Cloud layer: renders white clouds in day, pink/celeste clouds in afternoon, and night-appropriate clouds.

• Rain controller: switches sky to grey, enables falling raindrop particles, and enables rain reflections on surfaces.
• States
  • Loading: scene initializes with the configured starting time of day and normal weather.
  • Empty: not applicable — the EnvironmentWorld always has a sky and a time of day.
  • Success: sky, clouds, lighting, and weather match the active time of day and weather state.
  • Error: if the Godot version is not 4.7 or required nodes are missing, the artist sees a clear editor/runtime error and can reattach the EnvironmentWorld.
  • Recovery: reset the scene to defaults (day, normal weather, no fog) and re-add the EnvironmentWorld.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Deliver a Godot 4.7 3D EnvironmentWorld setup (explicit) As a Godot Environment Artist, I should add a ready-made 3D EnvironmentWorld (script + scene configuration) to my Godot 4.7 scene so that the environment graphics — sky, clouds, lighting, and weather — are provided without authoring them from scratch.

• Trigger/input: artist adds the EnvironmentWorld to a 3D scene.
• Observable result: the scene renders a sky, clouds, lighting, and weather driven by the EnvironmentWorld.
• Access: engine-side content; no account or network.
• Failure/recovery: if the Godot version is not 4.7 or required nodes are missing, a clear error is shown and the artist can reattach the EnvironmentWorld.
• Continuation: artist configures cycle speed, starting time, and weather.

FR-2 — Daytime celeste sky with white clouds (explicit) As a Godot Environment Artist, I should see, during the day phase, a light blue (celeste) sky with beautiful white clouds so that the daytime look matches the requested palette.

• Trigger/input: cycle reaches the day phase.
• Observable result: sky renders in celeste tones; clouds render white.
• Failure/recovery: if colors are wrong, artist can reset to defaults and re-preview.
• Continuation: cycle continues toward afternoon.

FR-3 — Afternoon pink and celeste sky with matching clouds (explicit) As a Godot Environment Artist, I should see, in the afternoon/late-day phase, the sky shift to pink and light blue tones with the clouds matching those tones so that the late-day look is warm and cohesive.

• Trigger/input: cycle reaches the afternoon phase.
• Observable result: sky shows pink and celeste tones; clouds show matching pink/celeste tones.
• Continuation: cycle continues toward night.

FR-4 — Night sky in beautiful blue (explicit) As a Godot Environment Artist, I should see, at night, a beautiful blue sky so that the night phase has the requested look.

• Trigger/input: cycle reaches the night phase.
• Observable result: sky renders in a beautiful blue.
• Continuation: cycle continues toward dawn.

FR-5 — Full day/night cycle including dawn (madrugada) (explicit) As a Godot Environment Artist, I should have a full cycle covering day, afternoon, night, and dawn (madrugada) so that the environment transitions continuously through all four phases.

• Trigger/input: cycle runs at the configured speed.
• Observable result: the scene transitions through day → afternoon → night → dawn → day with corresponding sky, cloud, and lighting changes.
• Failure/recovery: if the cycle stalls, artist can reset the starting time and re-preview.
• Continuation: cycle loops indefinitely.

FR-6 — Normal weather default with no fog (explicit) As a Godot Environment Artist, I should have normal (clear) weather as the default with no fog so that the scene is clear and matches the requested constraint.

• Trigger/input: scene starts or weather is set to normal.
• Observable result: no fog is rendered; sky and clouds are clear.
• Continuation: artist can switch to rain weather.

FR-7 — Increased contrast and saturation (explicit) As a Godot Environment Artist, I should see slightly increased contrast and saturation in the EnvironmentWorld so that the graphics look richer and closer to AAA quality.

• Trigger/input: EnvironmentWorld is active.
• Observable result: contrast and saturation are boosted relative to defaults.
• Continuation: artist can fine-tune values.

FR-8 — Urban style, near-AAA graphics (explicit) As a Godot Environment Artist, I should get an urban-style environment look close to AAA quality so that the scene reads as a polished city environment.

• Trigger/input: EnvironmentWorld is active.
• Observable result: environment styling is urban and visually polished.
• Continuation: artist integrates the EnvironmentWorld into the target scene.

FR-9 — Rain weather state with grey sky, falling raindrops, and rain reflections (explicit) As a Godot Environment Artist, I should be able to switch to a rain weather state in which the sky turns grey, raindrops fall from the sky, and rain reflections are visible so that rainy scenes look convincing.

• Trigger/input: artist sets weather to rain.
• Observable result: sky turns grey; raindrop particles fall from the sky; reflective surfaces show rain reflections.
• Failure/recovery: if rain does not appear, artist can toggle weather back to normal and re-enable rain.
• Continuation: artist can return to normal weather.

FR-10 — 3D delivery (explicit) As a Godot Environment Artist, I should receive the EnvironmentWorld as a 3D setup so that it works in a 3D scene.

• Trigger/input: artist adds the EnvironmentWorld to a 3D scene.
• Observable result: the EnvironmentWorld renders in 3D with sky, clouds, lighting, and weather.
• Continuation: artist previews and integrates.

4. User Personas

Godot Environment Artist

• Product context: Works inside Godot 4.7 on a 3D scene and wants a ready-to-use EnvironmentWorld that produces a beautiful urban, near-AAA look with a full day/night cycle and a rain state.
• Primary goal: Drop the EnvironmentWorld into a 3D scene and immediately see the requested sky, cloud, and weather transitions.
• Distinct accepted responsibilities: Adds the EnvironmentWorld to a scene; sets cycle speed and starting time of day; toggles weather between normal and rain; previews and fine-tunes contrast, saturation, rain intensity, and reflection strength.
• Relevant inputs/decisions: Choice of starting time of day, cycle speed, weather state, and tuning values for contrast/saturation and rain.
• Interactions with other participants: Interacts with the Godot Engine runtime, which executes the cycle and renders the environment; no other human participants.
• Observable success: The scene shows celeste day skies with white clouds, pink/celeste afternoon skies with matching clouds, beautiful blue night skies, a dawn phase, no fog in normal weather, boosted contrast and saturation, an urban near-AAA look, and a rain state with grey sky, falling raindrops, and visible rain reflections.

5. Core User Flows

Flow A — Install and preview the EnvironmentWorld (day phase)

1. The Godot Environment Artist opens a Godot 4.7 3D scene.
2. The artist adds the EnvironmentWorld (script + scene configuration) to the scene.
3. The runtime initializes with the configured starting time of day (default: day) and normal weather.
4. The artist previews the scene and observes a celeste sky with white clouds, no fog, and boosted contrast and saturation.
5. The artist continues by configuring cycle speed or switching weather.

Flow B — Observe the full day/night cycle

1. The artist sets the cycle speed and starting time of day.
2. The runtime advances the cycle: day → afternoon → night → dawn → day.
3. During the day phase, the artist observes a celeste sky with white clouds.
4. During the afternoon phase, the artist observes the sky shift to pink and celeste tones with matching clouds.
5. During the night phase, the artist observes a beautiful blue sky.
6. During the dawn (madrugada) phase, the artist observes the transition back toward day.
7. The cycle loops; the artist can pause or reset the starting time.

Flow C — Switch to rain weather

1. The artist sets weather to rain.
2. The runtime turns the sky grey, enables falling raindrop particles, and enables rain reflections on surfaces.
3. The artist observes grey sky, raindrops falling from the sky, and visible rain reflections.
4. The artist returns to normal weather, restoring the clear sky with no fog.

Flow D — Recover from a configuration error

1. The artist notices the EnvironmentWorld is not rendering correctly (e.g., wrong Godot version or missing nodes).
2. The artist reads the editor/runtime error.
3. The artist resets the scene to defaults (day, normal weather, no fog) and re-adds the EnvironmentWorld.
4. The artist re-previews and confirms the environment renders correctly.

6. Visuals Colors and Theme

The user requested a specific palette and tone; these are the authoritative visual tokens.

• Day sky: light blue / celeste tones (e.g., #87CEEB to #AEE2F5).
• Day clouds: white (#FFFFFF).
• Afternoon sky: pink and celeste blend (e.g., #F7A8C4 pink with #AEE2F5 celeste).
• Afternoon clouds: matching pink/celeste tones.
• Night sky: beautiful blue (e.g., #0B1E4B to #1B3A8C).
• Dawn (madrugada): transitional tones between night blue and day celeste.
• Rain sky: grey (e.g., #7A7F87 to #9AA0A8).
• Rain: falling raindrops with visible reflections on surfaces.
• Tone: urban, near-AAA; slightly increased contrast and saturation.
• Fog: none in normal weather.

7. Signature Design Concept

The signature concept is a living urban sky: a 3D city scene whose sky and clouds continuously shift through celeste day, pink-and-celeste afternoon, deep blue night, and dawn, with a single weather switch that greys the sky and adds falling rain with reflective wet surfaces. The hero moment is the afternoon transition, where pink and celeste blend across the sky and clouds, demonstrating the full cycle in one view.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: dimensional_css

Landing Hero Motion Brief

• Focal subject: the urban sky and clouds transitioning through the day/night cycle.
• Input → transformation → outcome thesis: the cycle advances → sky and cloud colors interpolate through day, afternoon, night, and dawn → the artist sees a continuous, beautiful environment; switching weather → sky greys and rain falls with reflections.
• Motion vocabulary: slow color interpolation, gentle cloud drift, falling raindrops, subtle reflection shimmer.
• Composed first frame: celeste day sky with white clouds over an urban scene, no fog, boosted contrast and saturation.
• Reduced-motion state: static sky at the configured time of day with no cloud drift or raindrop animation.

9. Non-Functional Requirements

• Engine target: Godot 4.7 (explicit).
• Dimensionality: 3D EnvironmentWorld (explicit).
• No fog in normal weather (explicit).
• Rain state must grey the sky and show falling raindrops plus rain reflections (explicit).
• Visual style: urban, close to AAA quality (explicit).
• Performance: the cycle and rain effects should run smoothly in a 3D scene; raindrop particle counts and reflection settings should be tunable.
• Configurability: cycle speed, starting time of day, weather state, contrast/saturation, rain intensity, and reflection strength should be adjustable from the Godot inspector.

10. Tech Stack

• Engine: Godot 4.7 (explicit).
• Language: GDScript for the EnvironmentWorld and day/night cycle scripts.
• Rendering: Godot 3D WorldEnvironment, Sky material, GPUParticles3D for raindrops, and reflection probes / screen-space reflections for rain reflections.
• Delivery: Godot project files (scene + scripts) added to the artist's 3D scene.

11. Assumptions and Constraints

• Assumption: The artist has a Godot 4.7 project with a 3D scene to receive the EnvironmentWorld.
• Assumption: The urban scene geometry (buildings, streets) is provided by the artist's scene; the EnvironmentWorld supplies sky, clouds, lighting, and weather.
• Constraint: No fog in normal weather.
• Constraint: Rain state must grey the sky and show falling raindrops plus rain reflections.
• Constraint: Visual style is urban and close to AAA quality.
• Constraint: Delivered as a 3D EnvironmentWorld for Godot 4.7.

12. Glossary

• EnvironmentWorld: The Godot scene/script setup that provides sky, clouds, lighting, and weather for a 3D scene.
• Celeste: Light blue sky tone.
• Madrugada: Dawn / early-morning phase of the cycle.
• Normal weather: Clear weather state with no fog.
• Rain state: Weather state with grey sky, falling raindrops, and rain reflections.
• Day/night cycle: Continuous progression through day, afternoon, night, and dawn.