zentap/docs/COLLISION_AND_TILT_FEATURES.md

ZenTap - New Features

Recently Added Features

🎯 Bubble Collision Detection

• Physics-based Movement: Bubbles now move with realistic physics including velocity, friction, and collision response
• Collision Detection: When bubbles collide with each other, they bounce off and change direction naturally
• Visual Feedback: Smooth collision animations that make bubble interactions feel more dynamic and satisfying

📱 Device Tilt Detection

• Accelerometer Integration: Uses the device's built-in sensors to detect when the phone is tilted
• Responsive Movement: When you tilt your device left or right, bubbles will gently drift in the opposite direction
• Smooth Experience: Tilt detection is filtered to prevent jittery movement and provide a calm, relaxing experience

How It Works

Collision System

1. Each bubble has a circular collision hitbox that matches its visual size
2. When two bubbles overlap, the collision system calculates the collision direction
3. Bubbles push away from each other with realistic physics
4. Collision damping prevents bubbles from bouncing indefinitely

Tilt Detection

1. The accelerometer monitors device orientation changes
2. Tilt angles are filtered and normalized to provide smooth input
3. Only significant tilts (> 5 degrees) trigger bubble movement
4. Bubbles receive gentle forces opposite to the tilt direction for intuitive feel

Technical Implementation

Dependencies Added

• sensors_plus: ^6.1.1 - For accelerometer/gyroscope access

Key Components

• TiltDetector - Service class that manages accelerometer data and provides clean tilt callbacks
• Bubble class enhanced with:
  • CollisionCallbacks mixin for collision detection
  • Physics properties (velocity, friction, collision damping)
  • applyTiltForce() method for responding to device tilt

Performance Optimizations

• Low-pass filtering on accelerometer data to reduce noise
• Efficient collision detection using Flame's built-in collision system
• Velocity clamping to prevent excessive speeds
• Periodic cleanup of physics calculations

User Experience

Play Mode & Zen Mode

Both game modes now feature:

• More dynamic bubble movement due to physics system
• Responsive bubble interactions when they collide
• Subtle tilt-based movement for enhanced relaxation

Accessibility

• Tilt sensitivity is tuned for comfortable use
• Works in both portrait and landscape orientations
• Tilt detection automatically pauses when game is paused

Future Enhancements

Potential additions could include:

• Adjustable tilt sensitivity in settings
• Different collision sound effects
• Particle effects on bubble collisions
• Multi-touch gesture support for enhanced bubble spawning