Ultimate Guide To Collision Functions

GameMaker has plenty of collision functions, each fulfilling a particular need.

Watch this video to understand how they all work:

The functions are divided into three categories (just for the sake of this explainer):

The rest of this page will briefly cover each function category. It is recommended to watch the video for full information.

Collision Event

The most basic way to do collisions is the Collision event. In an object, say obj_player, you can add a Collision event against another object, say obj_coin.

That event will run for an instance of obj_player when it collides with an instance of obj_coin.

Confused about objects and instances? See Objects vs. Instances.

In a Collision event, you can use the other keyword to refer to the instance you’ve collided with. In an instance of obj_player, following the example above, this would be the coin that it collided with.

You can then do anything with that other instance, like destroying it or changing a variable in it:

instance_destroy(other);
//or
other.image_index = 2;

place_meeting

place_meeting() checks if the current instance is colliding with an instance of an object. You can pass it a position that is different from the instance’s current position, so for the collision check it will check as if the instance were at that position.

If a collision is found, it returns true, otherwise it gets false.

For code examples, please watch the video above or read the linked manual entries.

position_meeting

position_meeting() checks if a single point/pixel in the room is colliding with an instance of an object. Just like place_meeting(), it returns true or false.

instance_place / instance_position

instance_place() and instance_position() are both the same as place_meeting() and position_meeting(). The only difference is that instead of returning true/false, they return the first instance that was found in collision, otherwise they return noone.

This is similar to how a Collision event gives you the other value. You can check if a collision was found by ensuring the return value is not noone (!= noone) and then performing any action on the returned instance.

collision_<shape>

There are functions for checking whether a shape is colliding with any instance of an object.

collision_circle() checks if a circle with the given position and radius would collide with an instance. If so, it returns the first instance found, similar to how instance_place() works.

These functions have two additional arguments: prec, for enabling collision checks with instances using precise masks, and notme, to skip returning the current instance if it matches the object you’re checking for.

Similarly there are the collision_ellipse(), collision_line(), collision_point() and collision_rectangle() functions which work the same and just use a different shape for the check.

<shape>_in_<shape>

The previous list of functions checked a shape against instances. This new category of functions only check a shape against another shape, so there are no instances involved.

point_in_rectangle() checks if a point is inside a given rectangle, and returns true/false. Similarly there are point_in_triangle() and point_in_circle().

rectangle_in_rectangle() checks if two rectangles overlap. This actually returns three values: 0 if there is no overlap, 1 if the first rectangle is completely inside the second rectangle, and 2 for any other case of overlap.

Then there are rectangle_in_triangle() and rectangle_in_circle() which work the same but check against different shapes.

_list() functions

Functions like instance_place() and collision_circle() will return the first instance found in collision. But what if you want to get all of the instances found to be, say, inside a circle?

For that you can use collision_circle_list(), and similarly there are list variants for the other instance-returning functions as well, such as instance_place_list(), instance_position_list(), etc.

To such functions, you must supply an already-created DS List. After the function call, that DS List will contain the instances that were found in collision, and the function call itself will have returned the number of instances added to the list.

The _list() functions do not remove any previous contents of the list and so you should clear the list before calling such a function. You should also destroy the list when you no longer need it.

Here is an example using instance_place_list():

// Create event
enemy_list = ds_list_create();

// Step event
ds_list_clear(enemy_list);

var _count = instance_place_list(x, y, obj_enemy, enemy_list, false);

for (var i = 0; i < _count; i++)
{
    instance_destroy(enemy_list[| i]);
}

// Destroy event
ds_list_destroy(enemy_list);

Happy GameMaking!