zentap/docs/BUBBLE_RULES.md

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
• 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
• 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
• Method: handleShake()
• File: lib/utils/tilt_detector.dart
• 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
• Methods: _getValidSpawnPosition(), _findSafePositionNear(), _isPositionSafe()

Configuration Constants

// 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