Pixel Fish Tank 🐠

A cozy Android virtual pet game where players care for a cute pixel-art fish by feeding it, cleaning its tank, playing mini-games, and decorating its environment as the fish grows and levels up.

📱 About

Pixel Fish Tank is a Tamagotchi-style virtual pet game for Android. Take care of your fish by feeding it, keeping its tank clean, playing mini-games to earn coins, and decorating the tank to make your fish happy. Watch as your fish grows and levels up through your care!

🎬 Promo Video

Watch Pixel Fish Tank in action! See all the features, gameplay, and adorable pixel-art fish:

Google Play Games and Sidekick

Play Games Services v2 automatic platform authentication
Sidekick-visible achievements for care, progression, streaks, collecting, and mini-games
Global leaderboards for all six mini-games
Native achievement and leaderboard screens in Settings
Production safeguards that require complete Play Games resource configuration

See Play Games Sidekick release setup for the Play Console checklist.

📸 Screenshots

🎮 Gameplay Screens

Main Menu	Tank View
Mini-Games	Decoration Store
Store View	Home Screen Widgets

⚙️ Settings

✨ Features

Core Gameplay

Virtual Fish System: Manage your fish's hunger, cleanliness, happiness, level, and XP
Unlimited Leveling System: Progressive XP requirements with unlimited levels - each level requires more XP than the last
- Level 1 → 2: 100 XP
- Level 2 → 3: 300 XP total (200 more)
- Level 3 → 4: 600 XP total (300 more)
- Level 4 → 5: 1,000 XP total (400 more)
- And so on, with no level cap!
Tank Interaction: Feed your fish and clean its tank to keep it healthy
Six Mini-Games: Bubble Pop, Timing Bar, Cleanup Rush, Food Drop, Memory Shells, and Fish Follow, each with difficulty levels
Fish Color Skins: Unlock and equip new fish colors (Ocean Blue, Coral Pink, Mint Green, Royal Gold) with coins
Decoration System: Customize your tank with various decorations
Daily Tasks: Complete daily tasks to maintain streaks and earn rewards
Backup & Restore: Export and import your game progress with JSON validation
Offline-First: Fully playable without an internet connection

Home Screen Widgets

Small Fish Status Widget (2x1): Quick fish status with mood, hunger bar, level & coins
Medium Fish Status Widget (3x2): Detailed view with all three stat progress bars
Streak Counter Widget (2x2): Fire emoji with current streak and best streak record
Daily Tasks Widget (4x3): Task checklist with completion status and dynamic messages
Beautiful pastel gradient backgrounds with color-coded progress bars
Real-time updates when game state changes
All widgets clickable to open the app

Technical Features

Built with Jetpack Compose for modern UI
Uses DataStore for local data persistence
Firebase integration for crash reporting, analytics, and messaging
- Comprehensive analytics tracking for user interactions and gameplay patterns
- Event tracking for game actions, mini-games, progression, and app usage
Material Design 3 theming
Traditional RemoteViews for enhanced widget design
Smooth animations and pixel-art graphics
High score tracking for all mini-games

🎮 Getting Started

Prerequisites

Android Studio Hedgehog (2023.1.1) or later
Android SDK 24 (Android 7.0) or higher
JDK 17 or higher
Kotlin 1.9+

Installation

Clone the repository:

git clone http://10.0.0.129:3000/charles/Pixel-Fish-Tank.git
cd Pixel-Fish-Tank

Open the project in Android Studio
Add your google-services.json file:
- Get your Firebase configuration file from the Firebase Console
- Place it in app/google-services.json
- Note: This file is gitignored for security reasons
Sync Gradle files and build the project
Run on an emulator or physical device

Building

./gradlew assembleDebug    # Build debug APK
./gradlew assembleRelease   # Build release APK

📁 Project Structure

Virtual_Pet/
├── app/
│   ├── src/main/
│   │   ├── java/com/charles/virtualpet/fishtank/
│   │   │   ├── data/          # Data layer (repositories, stores)
│   │   │   ├── domain/         # Business logic (ViewModels, models)
│   │   │   ├── ui/             # UI components and screens
│   │   │   └── MainActivity.kt
│   │   ├── res/                # Resources (drawables, values)
│   │   └── AndroidManifest.xml
│   ├── build.gradle.kts
│   └── google-services.json    # Firebase config (not in repo)
├── assets/                     # Game assets (images, sprites)
├── build.gradle.kts
├── settings.gradle.kts
└── docs/                       # Documentation (see docs/ folder)

🛠️ Technology Stack

Language: Kotlin
UI Framework: Jetpack Compose
Architecture: MVVM (Model-View-ViewModel)
Dependency Injection: Manual (Factory pattern)
Data Persistence: DataStore Preferences
Navigation: Navigation Compose
Firebase: Crashlytics, Analytics, Messaging, Performance
Google Play Games cloud: automatic Saved Games sync and Recall account recovery
Build System: Gradle with Kotlin DSL

📊 Architecture

The app follows MVVM architecture:

Data Layer: GameStateRepository, DecorationStore - Handle data persistence
Domain Layer: GameViewModel, MoodCalculator, StatDecayCalculator - Business logic
UI Layer: Compose screens and components - Presentation

🎨 Design

Art Style: Pixel art with cozy, chibi-style fish
Theme: Material Design 3
Color Palette: Aquarium-inspired blues and greens
Animations: Smooth, gentle animations for a relaxing experience

📝 Development

Code Style

Follow Kotlin coding conventions
Use meaningful variable and function names
Add comments for complex logic
Keep functions focused and single-purpose

Testing

./gradlew test              # Run unit tests
./gradlew connectedAndroidTest  # Run instrumented tests

🤝 Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.

📄 License

See LICENSE for license information.

🔒 Privacy

See docs/PRIVACY_POLICY.md for our privacy policy.

📚 Documentation

Product Requirements Document - Detailed product specifications
Changelog - Version history and changes

🐛 Known Issues

Check the issue tracker for known bugs and planned features.

🗺️ Roadmap

v1.2 (Current)

✅ Fish Color Skins - unlock and equip new fish colors with coins

v1.1

✅ Beautiful home screen widgets (4 types)
✅ Three mini-games with difficulty levels
✅ Backup & restore functionality
✅ Enhanced widget system with RemoteViews
✅ High score tracking
✅ Unlimited levels with progressive XP requirements
✅ Firebase Analytics integration with comprehensive event tracking

v1.0

✅ Core fish care mechanics
✅ Decoration system
✅ Daily tasks and streaks
✅ Firebase integration

Future Features

Screenshot sharing
Additional fish species/shapes
More mini-games
Multiple tanks
iOS version

👤 Author

Charles

🙏 Acknowledgments

Inspired by classic Tamagotchi virtual pet games
Built with love for cozy, relaxing gameplay experiences

Made with ❤️ for virtual pet enthusiasts

Name		Name	Last commit message	Last commit date
.github		.github
app		app
assets		assets
cloudflare-worker		cloudflare-worker
distribution		distribution
docs		docs
gradle/wrapper		gradle/wrapper
promo		promo
public		public
screenshots		screenshots
scripts		scripts
worker		worker
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
build.gradle.kts		build.gradle.kts
env.template		env.template
firebase.json		firebase.json
firestore.indexes.json		firestore.indexes.json
gradle.properties		gradle.properties
gradle.properties.template		gradle.properties.template
gradlew		gradlew
gradlew.bat		gradlew.bat
keystore.properties.template		keystore.properties.template
package.json		package.json
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation