suaveplan/openspec/changes/enterprise-gaming-r3f-weather/proposal.md

OpenSpec Change: enterprise-gaming-r3f-weather

• Change ID: enterprise-gaming-r3f-weather
• Package: @suaveplan/r3f-weather
• Category: gaming/scene
• Target path: gaming/scene/r3f-weather
• Status: PROPOSED
• Date: 2026-04-24
• Reference spec: /mnt/s/web/suaveplan/enterprise/r3f-weather.md

---

Summary

Deliver @suaveplan/r3f-weather on the genesis branch from scratch at enterprise quality. The package provides R3F weather rendering: GPU-instanced rain/snow particles driven by WeatherState from @suaveplan/weather; dynamic <fog> density from weatherState.fogDensity; lightning flash via PointLight pulse on weather:lightning event; surface wetness PBR normal-map overlay applied via material compositing. A WeatherRenderer component subscribes to WeatherSystem and drives all sub-systems. Genesis adds structured errors, OTel particle-count gauge, and 100% coverage.

---

Available workspace deps

@suaveplan/error, @suaveplan/weather, @suaveplan/events, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function WeatherRenderer(props: WeatherRendererProps): JSX.Element
// weatherSystem, particleCount, lightningIntensity

function RainParticles(props: RainParticlesProps): JSX.Element
function SnowParticles(props: SnowParticlesProps): JSX.Element
function LightningFlash(props: LightningFlashProps): JSX.Element
function FogLayer(props: FogLayerProps): JSX.Element
function useWeatherRenderer(): WeatherRenderState

---

File layout

gaming/scene/r3f-weather/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts / constants/index.ts
    types/common.ts + md
    components/
      WeatherRenderer/ (tsx + md + test + stories + index)
      RainParticles/ (tsx + md + test + stories + index)
      SnowParticles/ (tsx + md + test + stories + index)
      LightningFlash/ (tsx + md + test + stories + index)
      FogLayer/ (tsx + md + test + stories + index)
    hooks/use-weather-renderer.ts + md + test
  tests/integration.test.ts