plan-cityDrainageSystemSimulation

Prompt file imported from suhail-asarat/city-drainage-system-simulation (.github/prompts/plan-cityDrainageSystemSimulation.prompt.md). Copyright stays with the author.

Plan: MVP City Drainage Simulation

Recommended path: deliver the simulation-first milestone you selected (MVP Simulation), defer UI, and target stable behavior at 30 FPS minimum.

Steps

1. Phase 1 - Baseline architecture.
2. Refactor loop boundaries in main.cpp into explicit simulation-update and render-pass stages. This blocks downstream work.
3. Add lightweight frame-time instrumentation and tunable simulation-load constants in main.cpp. Parallel with Step 4.
4. Phase 2 - Hydrology core.
5. Add tile water-depth model (W_depth) aligned to grid dimensions in include/CityGrid.hpp and orchestrated from main.cpp. Depends on Step 2.
6. Implement drain/sink flow depletion with per-drain capacity rules. Depends on Step 5.
7. Couple rainfall input from include/ParticleSystem.hpp into hydrology deposition (with deterministic fallback mode). Depends on Step 5.
8. Stabilize simulation stepping with fixed/semi-fixed timestep logic in main.cpp. Depends on Step 5.
9. Phase 3 - Flood visualization.
10. Add off-screen FBO render path in main.cpp as post-process backbone. Depends on Step 2.
11. Implement flood hazard overlay shader using green/yellow/red thresholds from W_depth. Depends on Steps 5 and 10.
12. Add depth-based fog pass for heavy-rain readability. Depends on Step 10.
13. Add wet-surface modulation in base shading using local saturation. Depends on Steps 5 and 10.
14. Phase 4 - World context and controls.
15. Add basic drainage landmarks/markers in include/CityGrid.hpp to visualize sink locations. Depends on Step 6.
16. Add camera mode toggles (free-fly, orthographic top-down, subterranean slice) in main.cpp and include/Camera.hpp. Depends on Step 2.
17. Keep Dear ImGui out of this milestone (explicitly deferred).
18. Phase 5 - Performance and robustness.
19. Tune grid resolution, particle count, and update cadence to keep average FPS >= 30. Depends on Steps 7, 11, 12, 13.
20. Add explicit shader/FBO/simulation parameter validation logs in include/Shader.hpp and main.cpp. Parallel with Step 19.

Relevant files

• main.cpp - simulation/render orchestration, input/toggles, frame pacing.
• include/CityGrid.hpp - grid-to-hydrology mapping and drain visual markers.
• include/ParticleSystem.hpp - rainfall source data and update cadence.
• include/Shader.hpp - uniforms and shader diagnostics.
• shaders/basic.vert and shaders/basic.frag - base scene shading plus wetness hook.
• shaders/particle.vert and shaders/particle.frag - rain rendering stage.

Verification

1. Build succeeds: cmake -B build -S . && cmake --build build.
2. Runtime: W_depth rises under rain and drains reduce local depth.
3. Overlay: color thresholds map correctly to W_depth state.
4. Fog: depth attenuation visibly increases under severe rain.
5. Camera: all three modes switch correctly without control breakage.
6. Performance: average FPS stays at or above 30 with MVP defaults.
7. Failure handling: shader/FBO errors surface clearly in logs.

Decisions Captured

• Included now: hydrology + drains + flood overlay + FBO backbone + fog/wetness + camera toggles.
• Deferred: Dear ImGui until simulation stability is proven.
• Optimization target: minimum 30 FPS before adding optional complexity.

Further Considerations

1. Rainfall coupling model recommendation: start with rate-per-cell deposition for stability, then optionally blend particle impact contributions.
2. Underground view recommendation: begin with a clip-plane/slice visualization before building full sewer mesh geometry.
3. If schedule tightens, prioritize Steps 5, 6, 10, and 11 as the strict MVP core.