settled-reach/docs/sprints/sprint-21/visual.md

Sprint 21: Instantiate — Visual Tasks

Goal: The template system becomes executable — templates spawn NPCs, assign triangles, and place them in world space; cross-template triangles link social sites; the client gains save/load game flow; and the generator pipeline gets its architectural design.

Branch: visual Agents: Araminta (art direction)

New Tickets

#	Title	Blocked by
#564	Fog shader too opaque — tune alpha for semi-transparent layers per D-059	—

Use tooling/db/ticket show <id> for full details.

Key Decisions

• decisions/perception.md — D-059 (fog: shader-based, five layers, knowledge-graph-driven), D-011 (fog of perception non-negotiable, same system for NPCs and player)
• decisions/architecture.md — D-066 (dual-scale grid: 0.5m sim tiles, 1m visual tiles; fog gradient edge = 6-8 sim tiles = 3-4 visual tiles), D-043 (visual style: "functional warmth", Godot Light2D pipeline, sprites are shape templates the lighting completes)

Notes

#564 — Fog shader too opaque — tune alpha for semi-transparent layers per D-059

The fog shader is implemented and structurally correct. The issue is that the alpha values for Layer 2 (peripheral) and Layer 3 (deep fog) are heavier than D-059 specifies, making the fog feel like a dark wall rather than limited visibility.

File to edit: client/shaders/fog.gdshader

Current alpha values (reference fog_shader.gd for context):

• Layer 2 (peripheral, vis between PERIPHERAL_LOW=0.55 and CLEAR_THRESHOLD=0.85): alpha mix(0.55, 0.25, coverage) + noise * 0.1 — peaks at 0.55–0.65 at the peripheral edge
• Layer 3 (deep fog, explored > 0.3): alpha mix(0.78, 0.90, noise_val) — near-fully opaque

D-059 intent:

• Layer 2 (light fog / peripheral): "desaturated 40–50%, brightness -30%". This implies entities and world geometry are still partially visible — something in the 30–45% alpha range at the peripheral boundary, fading smoothly toward clear.
• Layer 3 (deep fog / previously explored): "near-monochrome with ~10% zone temperature tint". The zone tint (zone_tint_tex) must be readable through the fog. The current 0.78–0.90 alpha buries it. Targeting 0.60–0.75 range should let tint breathe without revealing too much detail.
• Layer 1 (clear, vision cone): the soft gradient edge should span 6-8 sim tiles = 3-4 visual tiles (D-066). Verify the smoothstep(CLEAR_THRESHOLD, 1.0, vis) range still produces this after alpha changes. CLEAR_THRESHOLD = 0.85 and PERIPHERAL_LOW = 0.55 are the knobs — do not change these unless the gradient edge width breaks.

What to tune:

1. Layer 2: reduce the heavy-end alpha from 0.55 → ~0.38, keep the light-end at 0.25. Adjust noise contribution proportionally. Entities behind peripheral fog should be dimmed and desaturated, but recognisable in silhouette.
2. Layer 3: reduce the alpha range from mix(0.78, 0.90, noise_val) → mix(0.62, 0.76, noise_val). Zone tint (10% contribution via mix(vec3(0.04), zone_tint, 0.1)) should now be faintly visible as a colour cast. The "fog breathes" effect is preserved — keep the noise animation as-is.
3. Verify that Layer 5 (unexplored, no maps, #12141a, alpha 1.0) remains fully opaque — information zero, no change.

How to test:

• The Fog Theater gauntlet room (accessible via the Gauntlet hub in the running game) exercises all five fog layers in a single space.
• Observable pass criteria:
  1. An NPC standing in the peripheral zone (Layer 2) is visibly dimmed and slightly desaturated — their D-033 relationship colour is still readable.
  2. A previously-explored room (Layer 3) shows a faint zone temperature tint (bar zone = warm, hub zone = cool, corridor = neutral) rather than uniform near-black.
  3. The vision cone edge is soft — no visible hard line between clear and peripheral.
  4. Unexplored tiles remain fully black.
• Also run make ci-client to confirm no shader compilation regressions.

Note: client/scripts/rendering/fog_shader.gd (the GDScript controller) does not need changes — it sets uniforms, not alpha values. client/scripts/autoloads/fog_state.gd generates the textures fed to the shader — verify the zone tint texture is being populated correctly if Layer 3 tint still doesn't show after alpha reduction.

Dependency Chain

#564 (fog alpha tuning) — standalone

PR Workflow

When ready to submit, create a PR with tea CLI:

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "fix(visual): tune fog shader alpha per D-059" --description "body" --base main --head visual