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

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 22 — Visual Briefing	Fog shader alpha tuning for semi-transparent layers per D-059	sprint	archived	22	visual

Sprint 22: Wire — Visual Tasks

Goal: Fix the fog regression, wire the authored Sova content into a production population and triangle set, and activate the contamination pacing layer that gives the vertical slice its 30-minute shape.

Branch: visual Agents: Araminta (art direction)

New Tickets

#	Title	Blocked by
#563	Fog shader too opaque — tune alpha for semi-transparent layers per D-059	#569 (client)

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

Key Decisions

• decisions/perception.md — D-059 (fog shader spec: light fog = desaturated 40-50%, brightness -30%; deep fog = near-monochrome with ~10% zone temperature tint; fog breathes with Perlin noise), D-011 (fog of perception is non-negotiable — world must be visible through fog, not hidden behind it), D-033 (entity color = relationship to player, must remain visible through fog overlay)
• decisions/architecture.md — D-066 (dual-scale grid, sim tiles vs visual tiles — fog gradient tuning is in visual-tile terms)
• decisions/perception.md — D-046 (three-reference lighting: warm amber = social/inhabited, cool white = institutional, mixed = transitional — zone temperature tint maps to this)

Open Questions to Resolve Early

None blocking #563. But coordinate with Stig (client team) — do not start #563 until #569 (fog architecture fix) is in client review. The shader file is the same artifact. Starting early will cause a merge conflict.

Notes

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

• Sequencing: This ticket is intentionally blocked by client #569. Stig fixes the broken gradient and explored-tile architecture. Once #569 is in review and the shader is structurally correct, Araminta takes the final tuning pass.
• The problem (from ticket): Current alphas are too high — light fog (layer 2) at 0.25-0.55 and deep fog (layer 3) at 0.78-0.90. These values make fog feel like a wall, not a perceptual filter. D-059 specifies the world should be visible through the fog — desaturated and dimmed, not hidden.
• Target behavior per D-059:
  • Clear (forward cone): Nearly transparent. Fog alpha ≈ 0.0 in the cone center. Soft gradient at the edge.
  • Explored (light fog): World content fully visible through desaturation and dimming. Fog alpha in the range 0.25-0.35 — enough to signal "not current attention" without obscuring art. The 8-10s Perlin noise breathe animates within this range (±0.04). Entity D-033 colors visible but slightly muted.
  • Previously explored (deep fog): World visible but near-monochrome. Fog alpha 0.55-0.70. Zone temperature tint applied as a color shift, NOT an additional opaque overlay. Bar zone: warm dark tint. Hub zone: cool dark tint. Corridor: neutral dark. The 15-20s Perlin breathe cycle is more pronounced here.
  • Unexplored: Solid #12141a. Alpha 1.0. Correct as-is.
• Files:
  • client/shaders/fog.gdshader — primary. Tune the fog_alpha constant and the DARK_OVERLAY color. The zone temperature tint is currently not implemented — add it as a sampled zone_tint_tex lookup (the uniform already exists in the shader; wire the zone palette into it from fog_state.gd).
  • client/scripts/autoloads/fog_state.gd — may need zone tint texture population if the uniform is not yet wired.
  • docs/architecture/fog-shader-spec.md — update if the approach changes from the current spec.
• Zone temperature palette (D-059 + D-046):
  • Terminal/hub: #1a1f2e (cool blue-dark)
  • Last Shift/bar: #2a1f15 (warm amber-dark)
  • Maintenance corridors: #1a1a1a (neutral dark)
• Artistic test — the "Hopper test" (D-046): After walking out of The Last Shift, the bar should still appear warm and inviting in deep fog — "the warm light is indifferent, not ironic." If the deep fog makes the bar's zone temperature tint readable as warm-dark against the surrounding cool-dark corridors, the tint is working. If everything looks the same dark, the tint needs more saturation.
• Do not: Apply D-033 relationship color tinting to the fog itself. Fog is a perceptual layer, not a relationship layer. Entity colors are unaffected by the fog shader — they render through it.
• Acceptance:
  • Light fog (explored): underlying art, sprites, furniture clearly visible at approximately 25-35% fog overlay.
  • Deep fog (previously explored): world visible but near-monochrome, zone temperature tint distinguishable between bar/hub/corridor.
  • Unexplored: solid near-black, unchanged.
  • Fog "breathes" — animated Perlin noise visible at both explored and previously-explored states.
  • No hard edges between fog states — all transitions are smooth.
  • Sign off from Stig (client team, who owns the underlying architecture) before merging.

Dependency Chain

#569 (client fog architecture fix) → #563 (visual fog alpha tuning)

Araminta should not begin shader work until Stig's #569 is in review on the client branch.

PR Workflow

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

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "fix(assets): Sprint 22 — fog shader alpha and zone temperature tint" --description "body" --base main --head visual