Build a data-driven world weather and atmosphere system

[zoeyrose]

Important

This issue is implemented in the fresh MIT-licensed Go server under the replacement program. Its gameplay and content-design decisions remain authoritative. C, CPython, classic packet, file-path, and enum details in the preserved specification are historical evidence only; do not copy, translate, or structurally port GPL implementation code.

Replacement implementation contract

Go owns coarse climate state, revisions, seeds, and gameplay tags; Game Protocol 1 delivers semantic state; Rust/WGSL rendering owns particles, lighting, and materials. Preserve all authored weather and atmosphere choices.

The server remains authoritative, consumes versioned compiled content, and exposes bounded generated Game Protocol 1 messages. Pure rules may use a specifically approved typed CEL environment. Starlark is not part of this issue unless the separate residual-scripting decision explicitly approves it.

Required verification

• Preserve every observable rule, balance decision, disclosure boundary, and anti-exploit invariant from the specification below.
• Add deterministic Go unit/property tests and wrapper-managed scenario coverage at the appropriate integration boundary.
• Add bounded malformed-input and persistence-failure cases where this feature accepts content, network, or stored data.
• Add Go/Rust protocol conformance fixtures for every new cross-process field; the client must not reconstruct authoritative rules from prose.
• Demonstrate that implementation and tests contain no copied GPL source/test material and execute no runtime Python.

Preserved product/design specification and historical implementation notes

Summary

Replace the single-map screen-overlay weather behavior with a data-driven world weather and atmosphere system that renders consistently across visible tiled maps, initializes without a top-of-screen restart, respects roofs/interiors, and can accumulate cosmetic wetness or snow.

This consolidates atrinik/atrinik#19, atrinik/atrinik#20, and the remaining weather portion of atrinik/atrinik#58. Roof/cutaway transport already exists on the current smooth-lighting path; this issue should consume that structure rather than revive the old proposal to author hundreds of weather-specific roof images.

The final client implementation depends on the SDL3 and GPU renderer work in atrinik/atrinik#128 and atrinik/client#23. Retained GPU map data (#130) and the data-driven shader/effect pipeline (#131) should be coordinated as implementation surfaces.

Current foundations

• Maps have an authored weather string in their header and mapstruct.
• server/src/socket/request.c sends only the effective weather for the player's current map through mapstats.
• client/src/gui/widgets/map.c passes that string to effect_start(), which starts a screen-space effect.
• Tiled neighboring maps can already be visible in one viewport.
• Roof/camera-surface flags and cutaway visibility are now transported per map cell.
• Game time-of-day and world darkness already provide an authored atmospheric clock.

Proposed design

Server-authored weather state

Define collected weather types and map/region climate profiles with stable IDs. A weather state should contain only authoritative coarse facts needed by clients and gameplay, for example:

• weather type and intensity;
• start/revision time and deterministic visual seed;
• wind vector or movement band;
• transition duration;
• optional temperature/wetness/snow gameplay tags;
• explicit indoor/underground/disabled overrides.

Start with static authored map weather expressed through the new schema, then add region transitions or schedules. Do not simulate or transmit individual particles.

For every map contributing visible cells, send its effective weather state and bounds/revision. Initial login, map scroll, linked-map changes, and stacked-map changes must produce a complete coherent snapshot followed by deltas.

World-space GPU atmosphere

After atrinik/atrinik#128/#129, render particles and atmosphere in world/map space rather than as a single full-screen effect. Clip emissions and surface effects by:

• the owning tiled map's bounds;
• roof/camera-surface and cutaway masks;
• indoor/underground map rules;
• visible stacked level;
• material/effect metadata where available.

Adjacent maps may have different weather without a seam-wide restart. Entering a map reconstructs a mature visual field from its start time/seed or prewarms the simulation, so rain/snow appears already in progress rather than falling from the top edge.

Use atrinik/client#22 for retained per-cell weather inputs and invalidation. Use atrinik/client#21 for particle, fog, wetness, snow, wind, and transition materials instead of adding hard-coded draw paths for each effect.

Accumulation

Treat accumulation as cosmetic in the first release:

• derive wetness/snow amount from weather type, intensity, elapsed exposure, material, roof cover, and decay;
• retain a bounded client-side value per visible/rendered cell;
• reconstruct a deterministic approximation when a cell becomes visible;
• blend/decay across transitions without authored snow variants for every roof sprite.

Only add persistent server-side accumulation if gameplay later consumes it. That requires explicit save scope, unloaded-map simulation, bounds, and protocol semantics and should not be implied by the visual MVP.

Atmospheric composition

Allow weather definitions to combine particles with fog/color grade, light response, wind, audio, and surface material parameters. The lighting and geometry renderers remain authoritative for occlusion; weather must not maintain a second roof/building model.

Delivery plan

1. Specify weather/climate definitions and a per-visible-map protocol snapshot.
2. Convert static map weather and validate dangling effect IDs.
3. Add GPU world-space precipitation with adjacent-map clipping and prewarmed entry.
4. Integrate roof/interior/stacked-level masks and transition blending.
5. Add bounded cosmetic wetness/snow accumulation through atrinik/client#22/#131.
6. Add scheduled/regional weather and gameplay tags only after the visual/state contract is proven.

Acceptance criteria

• Every visible tiled map can carry an independent coherent weather state.
• Entering or revealing a map shows weather already in progress without a top-edge restart.
• Neighbor weather renders only over cells owned by that neighbor.
• Roofed/indoor/cut-away/stacked cells use the same authoritative visibility and cover data as the renderer.
• Particle positions are client-simulated; the server sends bounded state, revisions, and seeds.
• Cosmetic accumulation uses materials and elapsed exposure without requiring duplicate weathered sprites.
• Weather definitions, map references, and protocol bounds are collected and validated.
• Disconnect/reconnect, map scroll, resize, and low/high frame rates converge to the same state.
• Software-renderer weather can be removed when the GPU path reaches parity rather than retained indefinitely.

Validation

Add protocol tests for initial snapshots, deltas, linked maps, stacked maps, and invalid IDs. Add renderer tests/screenshots for map seams, roofs, doors/windows, cutaways, indoor overrides, transitions, resize, reconnect, and deterministic seeds. Profile bounded particle/cell storage across the maximum viewport and validate representative snow, rain, and fog maps in runtime.

Supersedes atrinik/atrinik#19, atrinik/atrinik#20, and the weather-accumulation portion of atrinik/atrinik#58. Depends on atrinik/atrinik#128 and atrinik/client#23; coordinates with atrinik/client#22, atrinik/client#21, and atrinik/client#17.