# Bubble Rules for ZenTap Game

## Overview
This document defines the specific rules governing bubble behavior in the ZenTap game, ensuring consistent and predictable gameplay mechanics.

## Rule 1: Screen Capacity Calculation
### Description
Calculate the maximum number of full-size bubbles that can fit on the screen to optimize spawning and prevent overcrowding.

### Implementation
- **Bubble size**: 50px diameter at full size (25px radius)
- **Screen margins**: 120px from edges to account for UI elements
- **Minimum spacing**: 10px between bubbles to prevent visual overlap
- **Formula**: 
  ```
  Effective bubble area = (diameter + spacing)² = (50 + 10)² = 3600px²
  Available screen area = (screen_width - 2*margin) × (screen_height - 2*margin - 100)
  Max bubbles = floor(Available screen area / Effective bubble area)
  ```

### Code Location
- **File**: [`lib/game/components/bubble_spawner.dart`](lib/game/components/bubble_spawner.dart:1)
- **Method**: `calculateMaxBubblesForScreen()`

## Rule 2: Triple Collision Auto-Pop
### Description
If a bubble collides with other bubbles 3 times, it automatically pops to prevent clustering and maintain fluid gameplay.

### Implementation
- Each bubble tracks its collision count with other bubbles
- Collision counter increments only on actual contact (not proximity)
- After 3 collisions, bubble automatically pops with visual/audio feedback
- Counter resets if bubble doesn't collide for 2 seconds (grace period)

### Code Location
- **File**: [`lib/game/components/bubble.dart`](lib/game/components/bubble.dart:1)
- **Properties**: `collisionCount`, `lastCollisionTime`
- **Method**: `_handleBubbleCollision()`

## Rule 3: Single Bubble Per Shake
### Description
When the device is shaken, only one bubble is created per shake event to maintain controlled spawning.

### Implementation
- Shake detection cooldown period of 500ms between events
- Only one bubble spawned per valid shake
- Shake-spawned bubbles get special visual effect (different entrance animation)
- Existing bubbles still get shake effects (movement/animation)

### Code Location
- **File**: [`lib/game/zentap_game.dart`](lib/game/zentap_game.dart:1)
- **Method**: `handleShake()`
- **File**: [`lib/utils/tilt_detector.dart`](lib/utils/tilt_detector.dart:1)
- **Property**: `shakeDebounceTime`

## Rule 4: Collision Avoidance for Spawning
### Description
Prevent bubbles from spawning on top of or too close to existing bubbles to maintain visual clarity and prevent immediate collisions.

### Implementation
- All bubble spawning methods check for minimum distance (80px) from existing bubbles
- Uses attempt-based positioning with fallback to safe areas
- Smart positioning tries to find nearby safe spots when user taps
- Returns null if no safe position found (prevents spawning)

### Code Location
- **File**: [`lib/game/components/bubble_spawner.dart`](lib/game/components/bubble_spawner.dart:1)
- **Methods**: `_getValidSpawnPosition()`, `_findSafePositionNear()`, `_isPositionSafe()`

## Configuration Constants

```dart
// Bubble sizing and spacing
const double BUBBLE_MAX_DIAMETER = 50.0;
const double BUBBLE_MIN_SPACING = 10.0;
const double SCREEN_MARGIN = 120.0;
const double UI_TOP_MARGIN = 100.0;

// Collision rules
const int MAX_BUBBLE_COLLISIONS = 3;
const double COLLISION_GRACE_PERIOD = 2.0; // seconds

// Shake rules
const double SHAKE_DEBOUNCE_TIME = 500.0; // milliseconds
const int BUBBLES_PER_SHAKE = 1;

// Collision avoidance
const double MIN_SPAWN_DISTANCE = 80.0; // pixels
const int MAX_SPAWN_ATTEMPTS = 15;
const double SEARCH_RADIUS = 100.0; // pixels around user tap
```

## Performance Considerations

1. **Screen capacity calculation** runs only on screen resize events
2. **Collision counting** uses efficient collision detection without extra overhead
3. **Shake debouncing** prevents excessive bubble creation and maintains smooth performance

## Testing Scenarios

### Screen Capacity
- Test on various screen sizes (phones, tablets)
- Verify bubble spacing remains consistent
- Ensure no bubbles spawn outside safe area

### Triple Collision
- Spawn multiple bubbles in small area
- Verify collision counting accuracy
- Test grace period reset functionality

### Shake Control
- Rapid shake sequences should only create one bubble per valid shake
- Existing bubbles should still respond to shake effects
- Verify debounce timing prevents spam

### Collision Avoidance
- Bubbles should not spawn within 80px of existing bubbles
- User taps should find nearby safe positions when possible
- Automatic spawning should retry multiple times to find safe spots

## Future Enhancements

1. **Adaptive bubble size** based on screen density
2. **Predictive collision avoidance** using bubble movement vectors
3. **Shake intensity levels** affecting bubble spawn position/velocity
4. **Visual indicators** showing safe spawn areas