title	Otter River Rush README
type	reference
domain	core
status	ACTIVE
lastUpdated	2026-04-08
description	Root entrypoint and quick-start guide for the Otter River Rush Godot 4.6 project.
reads

Otter River Rush

Otter River Rush is a mobile-first endless river runner built in Godot 4.6 (Forward+).

This repository contains the 100% completed cleanroom port of the game, entirely abandoning the legacy React/Three.js web stack in favor of a robust, gdunit4-tested, and highly modular Godot scene-tree architecture.

Quick Start

# 1. Install required Godot addons (gdUnit4, LimboAI, etc.)
bash scripts/bootstrap-godot.sh

# 2. Compile .tres declarations from JSON manifests
bash scripts/generate-declarations.sh

# 3. Open the Godot 4.6 Editor
godot --editor --path .

# 4. Run the full unit & integration test suite (260/260 passing)
bash scripts/test-godot.sh

# 5. Capture the Visual Gallery (Headless screenshot generator)
bash scripts/capture-godot-gallery.sh

Canonical Architecture

The architecture enforces a strict "Ashford Manor" decomposition pattern:

• No file exceeds 200 Lines of Code (LOC).
• Declaration-driven Content: declarations/ is the strict source of truth for the roster, biomes, hazards, and modes.
• Node-based Directors: Systems like WaterDirector, CameraDirector, and RouteDirector act as single-responsibility Godot Nodes, hooking into _process() for reactive, physics-based updates.
• Phase Management: GameManager acts as a lightweight facade around PhaseManager, orchestrating high-level state (BOOTSTRAP, LANDING, RUN, RESULTS).

Key Game Features

• Procedural River Pathing: Bezier-curved procedural rivers where both the player and the spawned hazards automatically project their local lane coordinates into world-space curves.
• Split Routing (Reward vs. Pressure): The river dynamically forks into distinct branches. Reward corridors spawn dense, valuable pickups and warm lighting; Pressure corridors spawn tight obstacle blockers and harsh environments.
• Mastery-Aware Landing UI: The main.tscn landing screen actively reads the player's last run result and tension state to organically orbit the camera around the 3D Otter Carousel and tint the environmental mood.
• Seamless Scene Transitions: Polished card-wipe tweens govern handoffs between main.tscn and gameplay.tscn, supported by LimboAI state orchestrations.

Documentation

• docs/PORT_PLAN.md — Godot architecture, addon strategy, and the completed feature checklist.
• docs/DESIGN.md — Gameplay intent and mechanics.
• docs/BRAND_IDENTITY.md — Brand voice, palette, and character tone.
• CLAUDE.md / GEMINI.md — Agentic workflows and developer guidelines.