mintris/README.md

# pixelmintdrop

A modern block-stacking puzzle game for Android, featuring smooth animations, responsive controls, and a beautiful minimalist design.

## Features

### Core Gameplay
- Classic block-stacking mechanics
- 7-bag randomizer for piece distribution
- Ghost piece preview
- Hard drop and soft drop
- T-Spin detection and scoring
- High score system with top 5 scores

### Modern Android Features
- Optimized for Android 11+ (API 30+)
- Hardware-accelerated rendering
- High refresh rate support
- Haptic feedback for piece movement and line clears
- Dark theme support
- Responsive touch controls
- Edge-to-edge display support

### Scoring System

The game features a comprehensive scoring system:

#### Base Scores
- Single line: 40 points
- Double: 100 points
- Triple: 300 points
- Quad (4 lines): 1200 points

#### Multipliers

1. **Level Multiplier**
   - Score is multiplied by current level
   - Level increases every 10 lines cleared
   - Maximum level is 20

2. **Combo System**
   - Combo counter increases with each line clear
   - Resets if no lines are cleared
   - Multipliers:
     - 1 combo: 1.0x
     - 2 combos: 1.5x
     - 3 combos: 2.0x
     - 4 combos: 2.5x
     - 5+ combos: 3.0x

3. **Back-to-Back Quad**
   - 50% bonus (1.5x) for consecutive quad clears
   - Resets if a non-quad clear is performed

4. **Perfect Clear**
   - 2x for single line
   - 3x for double
   - 4x for triple
   - 5x for quad
   - Awarded when clearing lines without leaving blocks

5. **All Clear**
   - 2x multiplier when clearing all blocks
   - Requires no blocks in grid and no pieces in play

6. **T-Spin Bonuses**
   - Single: 2x
   - Double: 4x
   - Triple: 6x

### Controls
- Swipe left/right to move piece
- Swipe down quickly for hard drop
- Swipe down slowly for soft drop
- Single tap to rotate

### Visual Effects
- Smooth piece movement animations
- Pulsing border glow during line clears
- Ghost piece preview
- Block glow effects
- Subtle grid lines
- Animated title screen with falling pieces

## Technical Details

### Requirements
- Android 11 (API 30) or higher
- Hardware acceleration support
- 2GB RAM minimum

### Performance Optimizations
- Hardware-accelerated rendering
- Efficient collision detection
- Optimized grid operations
- Smooth animations at 60fps
- Background thread for score calculations

### Architecture
- Written in Kotlin
- Uses Android Canvas for rendering
- Follows Material Design guidelines
- Implements high score persistence using SharedPreferences

## Project Improvements and Best Practices

### Performance Optimizations

The codebase includes several performance optimizations:

1. **Release Build Configuration**
   - Minification enabled to reduce APK size
   - Resource shrinking to remove unused resources
   - ProGuard rules to optimize while preserving critical classes

2. **Memory Management**
   - Proper lifecycle handling to prevent memory leaks
   - Resource cleanup through `releaseResources()` methods
   - Efficient bitmap handling with reuse when possible

3. **Rendering Efficiency**
   - Custom view invalidation limited to areas that need updating
   - Hardware acceleration for canvas operations
   - Bitmap caching for frequently used graphics

### Code Organization

The codebase follows good architecture practices:

1. **Package Structure**
   - `model`: Data classes and game logic
   - `game`: Core gameplay implementation
   - `ui`: User interface components
   - `audio`: Sound and music management
   - `accessibility`: Accessibility helpers

2. **Responsibility Separation**
   - `GameLifecycleManager`: Handles lifecycle events
   - `GameUIManager`: Manages UI state and updates
   - `GameAccessibilityHelper`: Improves accessibility features
   - `GamepadController`: Manages gamepad input

### Google Play Compliance

The app meets Google Play standards:

1. **Manifest Configuration**
   - Proper permissions declaration
   - Screen orientation handling
   - Full backup rules for user data

2. **Accessibility Support**
   - Content descriptions for UI elements
   - Color contrast considerations
   - Screen reader compatibility

3. **Shortcuts and Deep Links**
   - App shortcuts for quick actions
   - Proper intent handling

### Usage Examples

#### Lifecycle Management

```kotlin
// In your activity
private lateinit var lifecycleManager: GameLifecycleManager

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleManager = GameLifecycleManager(this)
}

override fun onPause() {
    super.onPause()
    lifecycleManager.onPause(gameView, gameMusic, statsManager, highScoreManager)
}

override fun onResume() {
    super.onResume()
    lifecycleManager.onResume(gameView, gameMusic, isMusicEnabled)
}

override fun onDestroy() {
    lifecycleManager.onDestroy(gameView, gameMusic, statsManager, highScoreManager)
    super.onDestroy()
}
```

#### Accessibility Implementation

```kotlin
// In your activity
private lateinit var accessibilityHelper: GameAccessibilityHelper

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    accessibilityHelper = GameAccessibilityHelper(this)
    
    // Setup accessibility descriptions for controls
    accessibilityHelper.setupAccessibilityDescriptions(
        leftButton, rightButton, rotateButton, dropButton, 
        holdButton, pauseButton, gameView, holdPieceView, nextPieceView
    )
}

// When level changes
private fun onLevelUp(newLevel: Int) {
    accessibilityHelper.announceLevelUp(gameView, newLevel)
}

// When game ends
private fun onGameOver(score: Long) {
    accessibilityHelper.announceGameOver(gameView, score)
}
```

## Building from Source

1. Clone the repository:
```bash
git clone https://github.com/cmclark00/pixelmintdrop.git
```

2. Open the project in Android Studio

3. Build and run on your device or emulator

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

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