145 lines
4.0 KiB
Markdown
145 lines
4.0 KiB
Markdown
# OpenSpec Change: enterprise-gaming-weather
|
||
|
||
- **Change ID**: enterprise-gaming-weather
|
||
- **Package**: `@suaveplan/weather`
|
||
- **Category**: gaming/world
|
||
- **Target path**: `gaming/world/weather`
|
||
- **Status**: PROPOSED
|
||
- **Date**: 2026-04-24
|
||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/weather.md`
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Deliver `@suaveplan/weather` on the genesis branch from scratch at enterprise quality. The package provides dynamic weather simulation with smooth transitions, regional zones, and gameplay effects. A `WeatherSystem` holds the current `WeatherState` (temperature, precipitation, wind, visibility, lightning) and advances it by transitioning toward a `WeatherPreset`; `WeatherZone` maps world regions to preset overrides; a `WeatherTransition` interpolates between two presets over a configurable duration. Genesis adds Zod preset schemas, structured errors, OTel weather-state gauge, injectable clock and RNG, and 100% coverage.
|
||
|
||
---
|
||
|
||
## Current-state audit (genesis)
|
||
|
||
Package does not exist on genesis yet — fresh build.
|
||
|
||
---
|
||
|
||
## Available workspace deps on genesis
|
||
|
||
| Package | Role |
|
||
|---|---|
|
||
| `@suaveplan/error` (`workspace:^`) | `WeatherError`; `WEATHER.*` codes |
|
||
| `@suaveplan/types` (`workspace:^`) | `Clock`, `Rng` |
|
||
| `@suaveplan/events` (`workspace:^`) | `weather:changed`, `weather:lightning`, `weather:zone_entered` events |
|
||
| `@suaveplan/day-night` (`workspace:^`) | `DayNightClock` for time-based weather probability |
|
||
| `zod` (`catalog:forms`) | `WeatherPreset`, `WeatherZone` schemas |
|
||
| `@opentelemetry/api` (`catalog:observability`) | Weather-state change counter |
|
||
|
||
---
|
||
|
||
## Public API surface
|
||
|
||
```ts
|
||
interface WeatherPreset {
|
||
name: string
|
||
temperature: number // celsius
|
||
precipitation: number // 0–1
|
||
windSpeed: number // m/s
|
||
windDirection: number // degrees
|
||
visibility: number // 0–1 (1=clear, 0=zero visibility)
|
||
fogDensity: number // 0–1
|
||
cloudCover: number // 0–1
|
||
lightningProbability?: number // per-minute probability 0–1
|
||
}
|
||
|
||
interface WeatherState extends WeatherPreset {
|
||
readonly isTransitioning: boolean
|
||
readonly transitionProgress: number // 0–1
|
||
}
|
||
|
||
function createWeatherSystem(options: WeatherSystemOptions): WeatherSystem
|
||
|
||
interface WeatherSystemOptions {
|
||
initialPreset: WeatherPreset
|
||
transitionDuration?: number // seconds, default 60
|
||
clock?: Clock
|
||
rng?: Rng
|
||
}
|
||
|
||
interface WeatherSystem {
|
||
transitionTo(preset: WeatherPreset, duration?: number): void
|
||
tick(dt: number): void
|
||
readonly state: WeatherState
|
||
readonly currentPreset: WeatherPreset
|
||
}
|
||
|
||
// Weather zones
|
||
function createWeatherZone(options: WeatherZoneOptions): WeatherZone
|
||
|
||
interface WeatherZoneOptions {
|
||
id: string
|
||
center: Vec3
|
||
radius: number
|
||
preset: WeatherPreset
|
||
blendRadius?: number // blend distance at zone edge
|
||
}
|
||
|
||
interface WeatherZone {
|
||
readonly id: string
|
||
getBlendFactor(position: Vec3): number // 0 = outside, 1 = fully inside
|
||
}
|
||
|
||
function blendWeather(base: WeatherPreset, override: WeatherPreset, factor: number): WeatherPreset
|
||
```
|
||
|
||
### Error codes
|
||
|
||
```ts
|
||
type WeatherErrorCode =
|
||
| 'WEATHER_INVALID_PRESET'
|
||
| 'WEATHER_ZONE_NOT_FOUND'
|
||
| 'WEATHER_TRANSITION_INVALID'
|
||
```
|
||
|
||
---
|
||
|
||
## File layout
|
||
|
||
```text
|
||
gaming/world/weather/
|
||
package.json
|
||
tsconfig.json
|
||
vitest.config.ts
|
||
src/
|
||
index.ts
|
||
error-codes.ts
|
||
constants/index.ts
|
||
types/common.ts
|
||
types/common.md
|
||
core/
|
||
weather-system/
|
||
weather-system.ts
|
||
weather-system.md
|
||
weather-system.types.ts
|
||
weather-system.test.ts
|
||
index.ts
|
||
weather-zone/
|
||
weather-zone.ts
|
||
weather-zone.md
|
||
weather-zone.types.ts
|
||
weather-zone.test.ts
|
||
index.ts
|
||
presets/
|
||
index.ts # CLEAR, RAIN, STORM, SNOW, FOG built-in presets
|
||
utils/
|
||
blend.ts
|
||
blend.md
|
||
blend.test.ts
|
||
tests/
|
||
integration.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## Impact
|
||
|
||
**Downstream**: `@suaveplan/r3f-weather` renders rain particles, fog, lightning effects driven by `WeatherState`. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/day-night`.
|