/ 
Game-Collisions-0.5
River stage zero No dependents
/ Game::Collisions

NAME

Game::Collisions - Fast, pure Perl collision 2D detection

SYNOPSIS

my $collide = Game::Collisions->new;

my $box1 = $collide->make_aabb({
    x => 0,
    y => 0,
    length => 1,
    height => 1,
});
my $box2 = $collide->make_aabb({
    x => 2,
    y => 0,
    length => 1,
    height => 1,
});

if( $box1->does_collide( $box2 ) ) {
    say "Collides";
}

my @collisions = $collide->get_collisions;

DESCRIPTION

Checks for collisions between objects. Can check for a collision between two specific objects, or generate the collisions between all objects in the system.

What's an Axis-Aligned Bounding Box (AABB)?

A rectangle that's aligned with the x/y axis (in other words, not rotated). It's common to have the box surround (bound) the entire area of a more complex object. Since it's cheap to check for AABB collisions, it's useful to start there, and only then use more expensive algorthims to check more accurately.

Understanding the Tree

This module uses a binary tree to quickly search AABB collisions. Each branch of the tree must be big enough to contain all its children. When you move a leaf (any actual object you want to check will be a leaf), its parents must be resized to accommodate.

If many leaves get moved rather far, you'll want to rebalance the tree. This is expensive (which is why we normally resize rather than rebalance), so you wouldn't want to do it all the time.

If you would like more details, see:

https://www.azurefromthetrenches.com/introductory-guide-to-aabb-tree-collision-detection/

Circular References

This module does use circular references to keep track of parent/child relationships. This would normally be a problem, but if you're using <Game::Collisions::AABB->remove> to take nodes out of the tree, then references are cleaned up, anyway.

METHODS

new

Constructor.

make_aabb

my $box1 = $collide->make_aabb({
    x => 0,
    y => 0,
    length => 1,
    height => 1,
});

Creates an AABB at the specified x/y coords, in the specified dimentions, and adds it to the tree.

get_collisions

Returns a list of all collisions in the system's current state. Each element is an array ref containing the two objects that intersect.

get_collisions_for_aabb

get_collisions_for_aabb( $aabb )

Returns a list of all collisions against the specific AABB. Each element is an array ref containing the two objects that intersect.

get_collisions_for_aabb_bruteforce

get_colisions_for_aabb_bruteforce( $aabb );

Returns a list of all collisions against the specific AABB. Each element is an AABB object that collides against the passed object.

This is mainly for benchmarking purposes. It's possible that this method is faster than the tree algorithm if the list of AABBs is small. Probably not, but you can try.

rebalance_tree

Build a new tree out of the current leaves. You'll want to do this if the objects are moving around a lot.

SEE ALSO

LICENSE

Copyright (c) 2018 Timm Murray All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, 
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright 
  notice, this list of conditions and the following disclaimer in the 
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.