flutter_hitbox #

A powerful Flutter package for generating hitboxes from any shape (circles, rectangles, polygons, custom paths) and detecting collisions between them.

Example #

Features #

• 🎯 Multiple Shape Support: Create hitboxes from circles, rectangles, squares, polygons, and custom paths
• 🔄 Collision Detection: Efficient collision detection between any combination of shapes
• 🎨 Complex Shapes: Support for complex shapes like arrows, curves, and custom paths
• ⚡ Performance: Optimized algorithms for fast collision detection
• 📱 Cross-Platform: Works on iOS, Android, Web, Windows, macOS, Linux, and WASM
• ✅ Well Tested: Comprehensive test suite with >90% coverage

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_hitbox: ^0.0.1

Then run:

flutter pub get

Usage #

Basic Example #

import 'package:flutter_hitbox/flutter_hitbox.dart';

// Create a circle hitbox
final circle = CircleHitbox(Offset(100, 100), 30);

// Create a rectangle hitbox
final rectangle = RectangleHitbox(Offset(150, 150), Size(50, 50));

// Check for collision
if (circle.intersects(rectangle)) {
  print('Collision detected!');
}

Creating Hitboxes #

Circle

final circle = CircleHitbox(Offset(100, 100), 30);
// or using ShapeParser
final circle = ShapeParser.fromCircle(Offset(100, 100), 30);

Rectangle

final rectangle = RectangleHitbox(Offset(0, 0), Size(100, 50));
// or using ShapeParser
final rectangle = ShapeParser.fromRectangle(Offset(0, 0), 100, 50);

Square

final square = ShapeParser.fromSquare(Offset(0, 0), 50);

Polygon

final vertices = [
  Offset(0, 0),
  Offset(50, 0),
  Offset(50, 50),
  Offset(0, 50),
];
final polygon = PolygonHitbox(Offset(100, 100), vertices);
// or using ShapeParser
final polygon = ShapeParser.fromPolygon(Offset(100, 100), vertices);

Custom Path

final path = Path()
  ..moveTo(0, 0)
  ..lineTo(50, 0)
  ..lineTo(25, 50)
  ..close();
final pathHitbox = PathHitbox(Offset(100, 100), path);
// or using ShapeParser
final pathHitbox = ShapeParser.fromPath(Offset(100, 100), path);

Arrow Shape

final arrow = ShapeParser.fromArrow(
  position: Offset(100, 100),
  length: 80,
  width: 10,
  headLength: 20,
  headWidth: 30,
  direction: 0.785, // 45 degrees in radians
);

Collision Detection #

The package provides efficient collision detection between any combination of shapes:

// Circle vs Circle
final circle1 = CircleHitbox(Offset(0, 0), 10);
final circle2 = CircleHitbox(Offset(15, 0), 10);
if (circle1.intersects(circle2)) {
  // Collision detected
}

// Circle vs Rectangle
final circle = CircleHitbox(Offset(50, 50), 20);
final rectangle = RectangleHitbox(Offset(0, 0), Size(100, 100));
if (circle.intersects(rectangle)) {
  // Collision detected
}

// Polygon vs Polygon
final poly1 = PolygonHitbox(Offset(0, 0), vertices1);
final poly2 = PolygonHitbox(Offset(50, 50), vertices2);
if (poly1.intersects(poly2)) {
  // Collision detected
}

// Using CollisionDetector directly
if (CollisionDetector.checkCollision(hitbox1, hitbox2)) {
  // Collision detected
}

Point Containment #

Check if a point is inside a hitbox:

final circle = CircleHitbox(Offset(100, 100), 30);
if (circle.containsPoint(Offset(110, 110))) {
  print('Point is inside the circle');
}

Getting Bounding Box #

Get the axis-aligned bounding box of any hitbox:

final hitbox = CircleHitbox(Offset(100, 100), 30);
final bounds = hitbox.boundingBox;
print('Bounds: ${bounds.left}, ${bounds.top}, ${bounds.right}, ${bounds.bottom}');

API Reference #

Hitbox Classes #

• CircleHitbox: Represents a circular hitbox
• RectangleHitbox: Represents a rectangular hitbox
• PolygonHitbox: Represents a polygonal hitbox
• PathHitbox: Represents a custom path hitbox

Utility Classes #

• ShapeParser: Utility class for creating hitboxes from various shape definitions
• CollisionDetector: Static utility class for collision detection

Methods #

All hitbox classes implement the following methods:

• containsPoint(Offset point): Check if a point is inside the hitbox
• intersects(Hitbox other): Check if this hitbox intersects with another
• get boundingBox: Get the axis-aligned bounding box
• get area: Get the area of the hitbox
• copyWith({Offset? position, ...}): Create a copy with modified properties

Examples #

See the example directory for a complete example app demonstrating collision detection with draggable shapes.

Platform Support #

• ✅ iOS
• ✅ Android
• ✅ Web
• ✅ Windows
• ✅ macOS
• ✅ Linux
• ✅ WASM

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.

Author #

Dhia Bechattaoui

• GitHub: @Dhia-Bechattaoui
• Sponsors: GitHub Sponsors

Support #

If you find this package useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🤝 Contributing code

Changelog #

See CHANGELOG.md for a list of changes.