Watershed

Imported from ford442/Watershed (AGENTS.md). Install upstream with npx skills add ford442/Watershed. Copyright stays with the author.

AGENTS.md — Watershed Project Guide

Watershed is a high-fidelity 3D downhill action game that blends kinetic speed with survival simulation. The player navigates a river canyon from alpine source to valley delta across authored maps and biomes.

Package name: watershed (v0.1.0 in package.json).

Core Philosophy: "Shedding"

1. Geographical: Traversing an interconnected water system from source to delta
2. Kinetic: Moving with such velocity that the player "sheds" water as they pass it

Architecture truth (read first)

Canonical entry / scene graph (as of main):

App.tsx
  └─ Experience.tsx          # LODProvider → BiomeProvider → SunPositionProvider
       └─ InnerExperience.tsx
            ├─ EnhancedSky (useBiome())
            ├─ WaterReflectionLayer / WaterPhysicsEffects  # experience/WaterStack.tsx
            │    ├─ WaterForceSystem
            │    └─ SplashSystem
            ├─ VehicleMount → RunnerVehicle | RaftVehicle
            ├─ TrackManager | ReachManager | LevelLoader
            └─ PostProcessingPipeline.jsx

Player movement lives in src/vehicles/, not a top-level Player component. Post-processing live path is PostProcessingPipeline.jsx. Water forces live in physics/WaterForces.ts + WaterForceSystem / WaterFlowForces.tsx.

CI path check: node scripts/validate-markdown-paths.js (living markdown only; bans renamed/deleted dual stems — see the script).

Technology Stack

Key dependencies

{
  "@react-three/fiber": "^9.4.0",
  "@react-three/drei": "^10.7.7",
  "@react-three/rapier": "^2.2.0",
  "@react-three/postprocessing": "^3.0.4",
  "three": "^0.168.0",
  "@dimforge/rapier3d-compat": "0.19.2",
  "zustand": "^5.0.13",
  "ajv": "^8.18.0",
  "postprocessing": "^6.38.3"
}

Configuration

Directory map

Matches git ls-files src (star = primary touch points). Full listing: git ls-files src.

src/
├── App.tsx                      # Canvas, renderer toggle, error boundaries
├── Experience.tsx               # ★ Provider shell (LOD → Biome → SunPosition)
├── index.tsx                    # Rapier pre-init, global handlers
├── style.css
│
├── experience/                  # Scene composition
│   ├── InnerExperience.tsx      # ★ Track, vehicle, post-processing
│   ├── WaterStack.tsx           # ★ Reflection + Splash + WaterForceSystem
│   ├── VehicleMount.tsx
│   ├── SceneLighting.tsx
│   ├── ExperienceUI.tsx
│   └── hooks/
│
├── components/
│   ├── TrackManager.tsx         # ★ Chunk treadmill (MapSystem-driven)
│   ├── TrackSegment/            # ★ Canyon geometry + decorations
│   ├── FlowingWater.jsx         # ★ Water surface GLSL
│   ├── PostProcessingPipeline.jsx
│   ├── EnhancedSky.jsx          # useBiome() sky / fog
│   ├── WaterReflection.jsx
│   ├── WaterFlowForces.tsx      # Segment flow samples → raft impulses
│   ├── Environment/             # 25+ biome decorations
│   ├── Obstacles/ / VFX/ / LevelEditor/
│   └── GameHUD.tsx / UI.tsx / Loader.tsx / …
│
├── vehicles/
│   ├── RunnerVehicle/           # ★ Default first-person runner
│   └── RaftVehicle/             # ★ Raft buoyancy / paddle
│
├── systems/                     # See SYSTEMS.md
│   ├── MapSystem.ts             # ★ JSON maps, chunk config
│   ├── ChunkManager.ts
│   ├── ReachManager.tsx / ReachStreamer.ts / ReachNormalizer.ts
│   ├── BiomeSystem.tsx / LODManager.tsx / GameState.ts
│   ├── SplashSystem.tsx / WaterForceSystem.tsx / AudioSystem.ts
│   └── …
│
├── physics/                     # WaterForces.ts, Rapier worker proxy
├── maps/                        # Authored JSON + registry.ts
├── configs/ / constants/ / hooks/ / materials/ / rendering/
├── utils/                       # RiverShader, validators
└── formats/                     # level / reach schemas

Repo also has public/ (textures, WASM, levels), emscripten/ (optional native WASM), docs/, and build scripts. There is no AssemblyScript assembly/ tree.

Build and development

pnpm install
pnpm dev          # Vite on :3000 (alias: pnpm start)
pnpm test         # vitest run (one-shot)
pnpm typecheck    # tsc -p tsconfig.typecheck.json --noEmit
pnpm build        # optional emscripten WASM + vite → build/

Use pnpm only — the pinned version lives in package.json's packageManager field; do not commit package-lock.json (it is gitignored).

pnpm build runs emscripten/build.sh first; if Emscripten is missing it prints a skip message and exits 0, then Vite proceeds.

Key architecture notes

Track treadmill (TrackManager.tsx)

• Map-driven via MapSystem / maps/registry.ts (?map= or ACTIVE_MAP_ID)
• Pool: ~7 active segments, recycle behind player
• Segments: CatmullRom control points; decorations via TrackSegment/

Vehicles

Orchestration: VehicleMount + VehicleSystem / input via usePlayerControls.

Coordinates

Y (up) — canyon rim ~+15, water ~0.5
Z — downstream (gameplay forward is −Z)
X — left / right

Spawn defaults are map-driven; see MapSystem / active map registry.

Audio

AudioSystem.ts uses Three.js AudioLoader / AudioBuffer. Do not add Howler.

Renderer

Default WebGL2 (?renderer=webgl). WebGPU preference exists but forces WebGL2 backend while legacy GLSL materials remain. See docs/reference/RENDERER.md.

gpu-chores (#369)

HUD/minimap helpers (grid-reduce, luma-histogram, downsample-2d, blur) live in src/rendering/gpuChores/. Backend order: WebGPU → WASM → JS. The kit adopts the renderer session GPUDevice when Three's backend is native WebGPU; it never requestDevice()s. ?no_gpu_compute closes that WebGPU lane only — WASM water and WASM/TS chores still run. SWE / heightmap_flow.wgsl / TSL water materials stay domain. See docs/reference/GPU_CHORES.md.

Reach API

ReachStreamer hits /api/reaches/.... There is no backend in this repo — 404s fall back to procedural / map mode. Expected in cloud/dev.

Key files

Testing

pnpm test
pnpm typecheck          # tsc + untyped-surface allowlist guard
pnpm build
pnpm test:visual-smoke   # headless WebGL gate (preview serving build/)
node scripts/validate-markdown-paths.js
# chore goldens: src/rendering/gpuChores/reduceParity.test.ts (not pixelmatch)

Typecheck surface (honest foundation)

tsconfig.typecheck.json type-checks all src/**/*.ts and src/**/*.tsx (tests excluded). Residual untyped .js / .jsx modules, if any appear, are tracked in scripts/untyped-allowlist.json; pnpm typecheck runs scripts/check-typecheck-surface.mjs to fail CI if the allowlist drifts.

Shared decoration prop shapes live in src/components/Environment/types.ts (BiomeDecorationProps, built on PlacementTransform / TreePlacement / FlowerPlacement / MistPlacement from TrackSegment/types.ts). KNOWN_LEVEL_SCHEMA_DEBT is empty.

Manual smoke: spawn, WASD + pointer lock, track generates (−Z), textures visible, no console errors, no debug wireframes in polished mode.

Cursor Cloud notes

Single-service frontend — only the Vite dev server. Dependencies come from pnpm install.

Do not stand up a Reach API backend for local play. Do not reintroduce deleted dual Player/post-processing stems, legacy RiverTrack/CreekCanyon components, Howler, or @xenova/transformers.