Hexic Ultimate

An Android puzzle game inspired by the classic Hexic HD, featuring a minimalistic flat design and modern Material 3 UI.

🎮 A modern take on the beloved puzzle classic, built with cutting-edge Android technologies

📱 Screenshots

Screenshots will be added here

📋 Table of Contents

• Features
• Technical Architecture
• Installation
• Game Rules
• Technical Implementation
• Future Enhancements
• Contributing
• License
• Acknowledgments

🎮 Game Features

Core Gameplay

• Hexagonal Grid: Rotate hexagonal pieces to form clusters and flowers
• Multiple Game Modes:
  • Marathon: Endless puzzle challenge
  • Timed: Race against the clock (2 minutes)
  • Survival: Clear the entire board
• Complete UI: Settings, About, and High Scores screens
• Special Pieces:
  • Silver Stars: Created by forming flowers around normal pieces
  • Gold Stars: Created by forming flowers around silver stars
  • Black Pearls: The ultimate goal - formed from gold star flowers
  • Bombs: Must be defused by clustering or face game over

Game Mechanics

• Intuitive Controls: Tap to select, tap adjacent piece to swap, or drag between pieces
• Clusters: Match 3 or more adjacent pieces of the same color
• Flowers: Surround a center piece with 6 pieces of the same color
• Chain Reactions: Clearing pieces causes gravity effects and potential cascades
• Progressive Difficulty: Increasing challenge with level progression

🏗️ Technical Architecture

Technologies Used

• Language: Kotlin
• UI Framework: Jetpack Compose with Material 3
• Architecture: MVVM (Model-View-ViewModel)
• State Management: StateFlow and Compose State
• Minimum SDK: Android 12 (API 31)
• Target SDK: Android 15 (API 35)

Project Structure

app/src/main/java/com/hexicultimate/game/
├── model/              # Data models and game logic entities
├── engine/             # Core game engine and logic
├── viewmodel/          # ViewModels for state management
├── ui/
│   ├── screens/        # Main game screens
│   ├── components/     # Reusable UI components
│   └── theme/          # Material 3 theming
├── MainActivity.kt     # Main menu activity
└── GameActivity.kt     # Game activity

Key Components

Game Engine (GameEngine.kt)

• Hexagonal grid management
• Cluster detection algorithms
• Flower formation logic
• Gravity and piece movement
• Scoring system

Hexagonal Board (HexagonalBoard.kt)

• Custom Canvas drawing for hexagonal pieces
• Touch interaction handling
• Visual effects (selection, hints, animations)
• Coordinate system conversion (hex ↔ pixel)

Game Models (GameModels.kt)

• Immutable data classes for game state
• Hexagonal coordinate system implementation
• Type-safe game piece definitions

🎨 Design Philosophy

Visual Design

• Minimalistic Flat Design: Clean, modern aesthetic
• Material 3: Following Google's latest design language
• Dark Theme: Focused gaming experience
• Vibrant Colors: Clear piece differentiation with accessibility in mind

Color Palette

• Background: Dark gradients (navy to deep blue)
• Game Pieces: Bright, contrasting colors for each type
• UI Elements: Material 3 color tokens
• Special Effects: Subtle glows and highlights

🚀 Getting Started

Prerequisites

• Android Studio Hedgehog (2023.1.1) or later
• Kotlin 1.9.10+
• Gradle 8.2+
• Android SDK 35

Installation

1. Clone the repository
2. Open in Android Studio
3. Sync Gradle files
4. Run on device or emulator (API 31+)

Note: The project has been tested and builds successfully with:

• Android Gradle Plugin 8.5.2
• Kotlin 1.9.20
• Compose BOM 2023.10.01
• compileSdk 34 / targetSdk 34

Building

# Debug build
./gradlew assembleDebug

# Release build
./gradlew assembleRelease

🎯 Game Rules

Basic Gameplay

1. Tap a piece to select it (white border appears)
2. Tap a green-highlighted adjacent piece to swap them, or drag between adjacent pieces
3. Form clusters of 3+ connected same-colored pieces to clear them
4. Create flowers by surrounding a piece with 6 same-colored pieces
5. Advance pieces through the special piece hierarchy:
   • Normal → Silver Star → Gold Star → Black Pearl

Winning Conditions

• Marathon: Achieve the highest score possible
• Timed: Score as many points as possible in 2 minutes
• Survival: Clear the entire board

Game Over Conditions

• Bomb Explosion: Bomb timer reaches zero
• No Valid Moves: No adjacent swaps can create clusters or flowers

🔧 Technical Implementation

Hexagonal Grid System

The game uses axial coordinates (q, r) for the hexagonal grid:

• Efficient neighbor calculation
• Accurate distance measurement
• Proper coordinate conversion for rendering

Performance Optimizations

• Immutable state management
• Efficient cluster detection algorithms
• Minimal recomposition in Compose UI
• Optimized Canvas drawing

State Management

• Unidirectional data flow
• Separation of game logic and UI state
• Reactive state updates with StateFlow

🎵 Future Enhancements

Planned Features

• Sound effects and background music
• Particle effects and enhanced animations
• Local high score storage
• Achievement system
• Difficulty settings
• Tutorial mode
• Theme customization

Technical Improvements

• Game state persistence
• Performance profiling
• Accessibility improvements
• Tablet optimization
• Testing coverage

📱 System Requirements

• Minimum: Android 12 (API 31)
• Target: Android 14 (API 34)
• Recommended: Android 13+ with 4GB+ RAM
• Storage: ~50MB
• Permissions: Vibration (optional)

APK Information

• Debug APK Size: ~50MB
• Architecture: Universal APK (supports all architectures)

🤝 Contributing

We welcome contributions! This project demonstrates modern Android development practices and offers opportunities to learn:

• Clean Architecture principles
• Jetpack Compose best practices
• Material Design implementation
• Custom Canvas drawing techniques
• Game development patterns in Android

Please read our Contributing Guidelines for details on:

• Setting up the development environment
• Code style and architecture requirements
• Submitting bug reports and feature requests
• Pull request process

Quick Start for Contributors

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/hexic-ultimate.git
3. Open in Android Studio and wait for Gradle sync
4. Create a feature branch: git checkout -b feature/amazing-feature
5. Make your changes and test thoroughly
6. Commit your changes: git commit -m 'feat: add amazing feature'
7. Push to your branch: git push origin feature/amazing-feature
8. Open a Pull Request

Areas for Contribution

• 🎵 Audio System: Sound effects and background music
• ✨ Animations: Enhanced visual effects and transitions
• 🏆 Features: Achievement system, daily challenges
• 🎨 Themes: Additional color schemes and visual styles
• 🐛 Bug Fixes: Performance optimizations and bug fixes
• 📱 Accessibility: Improved accessibility features
• 🧪 Testing: Unit tests and integration tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: This project is inspired by the original Hexic game concept by Alexey Pajitnov. This is an independent implementation and is not affiliated with or endorsed by Microsoft or the original creators of Hexic.

🙏 Acknowledgments

• Alexey Pajitnov: Creator of the original Hexic game concept
• Microsoft: Original Hexic HD implementation and inspiration
• Material Design Team: Design system and guidelines
• Jetpack Compose Team: Modern UI toolkit that made this possible
• Android Community: For the amazing tools and libraries

🌟 Star History

If you find this project helpful, please consider giving it a star! ⭐

📞 Support

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Open an issue
• 💬 Questions: Start a discussion

---

Built with ❤️ for the Android community

⬆ Back to top