Sovereign 8s.is mirror of standardgalactic/rivermarsh
- TypeScript 57.7%
- HTML 42%
- Dockerfile 0.2%
- Java 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
Some checks failed
CI / Build (Web) (push) Has been cancelled
CI / Test (push) Has been cancelled
CI / Build (Android) (push) Has been cancelled
CI / Release (push) Has been cancelled
Deploy Documentation to Pages / build (push) Has been cancelled
Deploy Documentation to Pages / deploy (push) Has been cancelled
* chore: remove nightly-improve.yml (handled by control-center) * chore: remove project-sync.yml (handled by control-center) * chore: remove auto-assign.yml (handled by control-center) * chore: remove auto-merge.yml (handled by control-center) * chore: remove ollama-pr-review.yml (handled by control-center) * chore: remove pr-review.yml (handled by control-center) * chore: remove claude-code.yml (handled by control-center) |
||
| .crewai | ||
| .cursor | ||
| .github | ||
| .husky | ||
| .kiro | ||
| android | ||
| dist | ||
| docs | ||
| e2e | ||
| examples | ||
| memory-bank | ||
| node_modules | ||
| playwright-report | ||
| public | ||
| src | ||
| test-results | ||
| .gitignore | ||
| AGENTS.md | ||
| biome.json | ||
| capacitor.config.ts | ||
| CLAUDE.md | ||
| DESIGN.md | ||
| index.html | ||
| package.json | ||
| playwright.config.ts | ||
| pnpm-lock.yaml | ||
| README.md | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| vite.config.ts | ||
| vitest.config.ts | ||
Otterfall
A mobile-first 3D exploration game built with React Three Fiber and Capacitor. Control an otter navigating diverse biomes in a living ecosystem with dynamic weather, time-of-day cycles, and AI-driven NPCs.
Showcase
Check out the demo and examples:
- Playable Demo: Run
pnpm run buildandpnpm run previewto see the latest web build. - Screenshots: High-quality gameplay captures are available in
docs/screenshots/. - Code Examples: Practical implementations of ECS components and systems can be found in
examples/.
Features
- 7 Unique Biomes: Marsh, Forest, Desert, Tundra, Savanna, Mountain, Scrubland
- Dynamic Weather System: Rain, fog, snow, storms with real-time effects
- Day/Night Cycle: 24-hour time progression with lighting changes
- AI Ecosystem: Predator/prey behaviors using steering algorithms
- Mobile-First Controls: Touch-optimized virtual joystick and gestures
- Performance Optimized: LOD system, adaptive quality, 60 FPS target
Tech Stack
- React Three Fiber - 3D rendering
- Zustand - State management
- Miniplex ECS - Entity Component System
- Tone.js - Procedural audio synthesis
- Capacitor - Native mobile deployment
Development
Prerequisites
- Node.js 18+
- pnpm 8+
Install Dependencies
pnpm install
Run Development Server
pnpm run dev
Open http://localhost:5173 in your browser.
Build for Production
pnpm run build
Run Tests
# Unit tests
pnpm test
# Watch mode
pnpm test:watch
# E2E tests
pnpm test:e2e
# E2E with UI
pnpm test:e2e:ui
Linting and Formatting
This project uses Biome for fast linting and formatting.
# Check for linting and formatting issues
pnpm run lint
# Automatically fix issues
pnpm run lint:fix
# Format files
pnpm run format
Mobile Deployment
Android
Prerequisites
- Android Studio
- JDK 21
- Android SDK (API 33+)
Build APK
# Full build pipeline
pnpm run build:android
# Or step by step:
pnpm run build # Build web assets
pnpm run cap:sync:android # Sync to Android platform
cd android && ./gradlew assembleRelease
The APK will be generated at:
android/app/build/outputs/apk/release/app-release-unsigned.apk
Development
# Sync changes to Android
pnpm run cap:sync:android
# Open in Android Studio
pnpm run cap:open:android
# Run on device/emulator
pnpm run cap:run:android
iOS
iOS deployment requires macOS with Xcode. See Capacitor iOS documentation for setup.
Project Structure
packages/otterfall/
├── src/
│ ├── components/ # R3F rendering components
│ │ ├── Player.tsx # Player character
│ │ ├── NPCs.tsx # AI-driven entities
│ │ ├── World.tsx # Terrain and environment
│ │ └── ui/ # HUD and UI components
│ ├── ecs/ # Entity Component System
│ │ ├── components.ts # ECS component definitions
│ │ ├── systems/ # Game logic systems
│ │ └── data/ # Static game data
│ ├── stores/ # Zustand state management
│ ├── shaders/ # GLSL shaders
│ ├── systems/ # Game systems (audio, input)
│ └── utils/ # Utility functions
├── public/ # Static assets
│ ├── models/ # 3D models (GLB)
│ ├── textures/ # PBR textures
│ └── audio/ # Sound effects
├── e2e/ # Playwright E2E tests
├── android/ # Android platform (generated)
└── capacitor.config.ts # Capacitor configuration
Game Systems
Time System
- 24-hour day/night cycle
- 4 phases: Dawn, Day, Dusk, Night
- Dynamic lighting and fog
Weather System
- 6 weather types: Clear, Rain, Fog, Snow, Storm, Sandstorm
- Smooth transitions (30 seconds)
- Affects visibility and movement
Biome System
- 7 distinct biomes with unique terrain
- Smooth biome transitions
- Biome-specific resources and NPCs
AI System
- Steering behaviors (seek, flee, wander, avoid)
- State machines (idle, walk, run, chase, flee, attack)
- Predator/prey dynamics
Resource System
- 3 resource types: Fish, Berries, Water
- Restores health and stamina
- Respawn mechanics
Audio System
- Procedural audio synthesis (Tone.js)
- Biome-specific ambient soundscapes
- Weather sound effects
- Footstep sounds (terrain-based)
- Spatial audio for NPCs
Performance Optimization
- LOD system (4 levels: Full, Medium, Low, Culled)
- Adaptive quality (dynamic particle/shadow reduction)
- Instanced rendering (grass, rocks, trees)
- Memory monitoring and GC hints
Controls
Desktop
- Arrow Keys - Move
- Space - Jump
- ESC - Pause
Mobile
- Tap - Move (virtual joystick appears)
- Swipe Up - Jump
- Pinch - Zoom camera
- Tap Resource - Collect
Performance Targets
- 60 FPS on iPhone 13 equivalent
- < 500MB memory usage
- < 100 draw calls per frame
- < 500k vertices per frame
Testing
The project includes comprehensive test coverage:
- 177 unit tests - Components, systems, utilities
- 52 property-based tests - Invariant validation
- 8 E2E test suites - Complete gameplay workflows (biome exploration, NPC behaviors, resource collection, player movement, game systems, time/weather, initialization, gameplay)
Contributing
See CONTRIBUTING.md for development guidelines.
License
MIT © jbcom