Skip to content

About

An otter drifting game built with Dart + Flutter + Flame

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

51 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿฆฆ Otter Drift

An arcade-style Flutter + Flame game where you guide an otter down river rapids while collecting items and dodging hazards.

Flutter Dart Flame Platform CI

๐Ÿ“ธ Screenshots

Gameplay Screenshot Menu Screenshot Gameplay 1 Gameplay 2 Gameplay 3 Gameplay 4

โœจ Features

  • ๐ŸŽฎ Smooth Gameplay - Fast-paced river navigation with responsive tap controls
  • ๐ŸŽฏ Score System - Collect lilies and avoid logs to build your high score
  • โค๏ธ Health Management - Start with 3 hearts, collect power-ups to restore health
  • ๐Ÿ“ˆ Progressive Difficulty - River speed increases over time for added challenge
  • ๐Ÿ† Leaderboards - Compete globally with authenticated players
  • ๐Ÿ‘ค Player Profiles - Track achievements, game history, and statistics
  • ๐Ÿ” Secure Authentication - JWT-based auth with certificate pinning support
  • ๐ŸŽต Immersive Audio - Background music and sound effects
  • ๐ŸŽจ Beautiful Graphics - Animated sprites and smooth visuals
  • ๐Ÿ”„ Guest Mode - Play without an account (scores won't sync)

๐ŸŽฎ How to Play

Objective

Stay alive as long as possible while racking up the highest score!

Controls

  • Tap anywhere on the screen to move the otter horizontally toward the tap position

Game Elements

  • ๐Ÿชต Logs (60% spawn rate)

    • Avoid these! Colliding with a log costs one heart
    • Repeated collisions end your run
  • ๐ŸŒธ Lilies (25% spawn rate)

    • Collect these for 10 points each
    • Focus on gathering as many as possible for a high score
  • โค๏ธ Hearts (15% spawn rate)

    • Restore one heart when collected (max 3 hearts)
    • Essential for survival on longer runs

Difficulty Progression

  • Starting Speed: 120 px/s
  • Speed Increase: ~10% every 20 seconds
  • Maximum Speed: 240 px/s (capped)

Game Over

When you run out of hearts, you'll see:

  • Final score
  • Statistics (lilies collected, hearts collected)
  • Option to submit score (if authenticated)
  • Play Again or return to Main Menu

Getting Started

Prerequisites

  • Flutter 3.38+ (check with flutter --version)
  • Dart SDK 3.10+ (bundled with Flutter)
  • Backend API - Rails API server running (see Backend Repository)

Installation

  1. Clone the repository

    git clone <repository-url>
    cd otter_drift
  2. Install dependencies

    flutter pub get
  3. Configure API credentials

    Run the app with required environment variables:

    flutter run \
      --dart-define=API_KEY=your_64_char_hex_key \
      --dart-define=CLIENT_ID=game_client_1 \
      --dart-define=API_BASE=http://localhost:3000

    Note: Android emulators automatically use http://10.0.2.2:3000 instead of localhost

  4. Build for release

    flutter build apk --dart-define=API_KEY=prod_key_here
    # or for iOS
    flutter build ios --dart-define=API_KEY=prod_key_here

Project Structure

otter_drift/
โ”œโ”€โ”€ lib/
โ”‚   โ”œโ”€โ”€ game/                    # Flame game engine code
โ”‚   โ”‚   โ”œโ”€โ”€ components/          # Game entities (Otter, Logs, Lilies, Hearts)
โ”‚   โ”‚   โ”œโ”€โ”€ hud/                 # Heads-up display components
โ”‚   โ”‚   โ””โ”€โ”€ otter_game.dart      # Main game class
โ”‚   โ”œโ”€โ”€ screens/                 # Flutter UI screens
โ”‚   โ”‚   โ”œโ”€โ”€ auth/                # Login/Signup screens
โ”‚   โ”‚   โ”œโ”€โ”€ game/                # Game screen wrapper
โ”‚   โ”‚   โ”œโ”€โ”€ menu/                # Main menu screen
โ”‚   โ”‚   โ””โ”€โ”€ profile/             # Profile management screens
โ”‚   โ”œโ”€โ”€ services/                # Business logic & API integration
โ”‚   โ”‚   โ”œโ”€โ”€ api_service.dart     # HTTP client wrapper
โ”‚   โ”‚   โ”œโ”€โ”€ auth_service.dart    # Authentication handling
โ”‚   โ”‚   โ”œโ”€โ”€ backend.dart         # API endpoint definitions
โ”‚   โ”‚   โ””โ”€โ”€ security_config.dart # Certificate pinning config
โ”‚   โ”œโ”€โ”€ models/                  # Data models
โ”‚   โ”œโ”€โ”€ widgets/                 # Reusable UI widgets
โ”‚   โ””โ”€โ”€ util/                    # Utilities (RNG, etc.)
โ”œโ”€โ”€ assets/                      # Game assets
โ”‚   โ”œโ”€โ”€ images/                  # Sprites and UI graphics
โ”‚   โ””โ”€โ”€ audio/                   # Sound effects and music
โ”œโ”€โ”€ test/                        # Test suite
โ”‚   โ”œโ”€โ”€ game/                    # Game logic tests
โ”‚   โ”œโ”€โ”€ screens/                 # Widget tests
โ”‚   โ””โ”€โ”€ util/                    # Utility tests
โ””โ”€โ”€ pubspec.yaml                 # Dependencies and asset configuration

Testing

Run the test suite:

# Run all tests
flutter test

# Run specific test file
flutter test test/util/rng_test.dart

# Run with coverage
flutter test --coverage

Currently passing: 11 tests (RNG utility tests)

Configuration

Required Environment Variables

Variable Description Default
API_KEY 64-character hex API key for backend authentication Required
CLIENT_ID Client identifier for the API game_client_1
API_BASE Base URL for the backend API http://localhost:3000

Security

  • JWT Tokens: Stored securely via flutter_secure_storage
  • Certificate Pinning: Configurable in lib/services/security_config.dart
  • Sensitive Logging: SecureLogger automatically masks sensitive fields

Backend Integration

This project requires a Rails API backend. See the backend repository for setup instructions.

The backend must provide:

  • Authentication endpoints (login, signup, refresh)
  • User profile management
  • Leaderboard API
  • Game session submission endpoint

Default API routes:

  • /api/v1/auth/* - Authentication
  • /api/v1/players/* - Player data
  • /api/v1/leaderboard - Global leaderboard
  • /api/v1/game_sessions - Score submission

Troubleshooting

Common Issues

Missing API Key Error

Error: API_KEY is required

Solution: Run with --dart-define=API_KEY=your_key_here

401 Authentication Errors

  • Verify backend is running
  • Check API key matches backend configuration
  • Ensure device/emulator can reach the API URL
  • Android emulator should use http://10.0.2.2:3000 instead of localhost

Assets Not Loading

  • Run flutter pub get after modifying pubspec.yaml
  • Verify asset paths in pubspec.yaml match file structure
  • For web builds, check asset bundling configuration

Audio Issues

  • Ensure audio files are in assets/audio/ directory
  • Check file formats are supported (WAV recommended)

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Dependencies

Core

  • Flutter - UI framework
  • Flame 1.33 - Game engine
  • Flame Audio - Audio system

Networking

  • Dio - HTTP client
  • Connectivity Plus - Network status

Storage & Security

  • Flutter Secure Storage - Secure credential storage
  • Shared Preferences - App preferences
  • JWT Decoder - Token parsing

Monetization

  • Google Mobile Ads - AdMob integration for banner, interstitial, and rewarded ads

See pubspec.yaml for complete dependency list.

Documentation

API Documentation

Generate API documentation using dartdoc:

dart doc

Documentation will be generated in docs/api/.

Deployment Guide

For instructions on deploying to Google Play Store and configuring advertisements, see the Deployment Guide.

Code Documentation

All code is documented with dartdoc comments. Key areas:

  • Game Engine (lib/game/) - Core game logic and components
  • Services (lib/services/) - Business logic, API integration, and ad management
  • UI Components (lib/screens/, lib/widgets/) - User interface screens and widgets
  • Models (lib/models/) - Data models and structures

See Documentation README for more information.


Made with โค๏ธ and ๐Ÿฆฆ

Happy Drifting! ๐Ÿž๏ธ

About

An otter drifting game built with Dart + Flutter + Flame

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages