instance_place_list


Description

With this function you can check a position for a collision with all instances of an object using the collision mask of the instance that runs the code for the check. When you use this you are effectively asking GameMaker Studio 2 to move the instance to the new position, check for a collision, then move back and tell you if a collision was found or not. This will work for precise collisions, but only if both the instance and the instances of the object being checked for have precise collision masks selected otherwise only bounding box collisions are applied. The function will populate a (previously created) DS list with the unique id values of all instances of the object that are considered to be in collision with the calling instance, and you have the option to order the list based on the distance from the origin of the instance doing the checking to the origin of the instances found to be in collision. Note that the function also accepts the special keyword all, in which case all instances found to be in collision will be listed. The function returns the number of instances found, or 0 if none are found.

Note that the given x/y coordinates will be rounded to the nearest integer before the check is performed, so if this is not what you require (or you have been using a legacy GameMaker product), you should floor the coordinates in the check: instance_place_list(floor(x), floor(y), obj_Enemy, list, true).


Syntax:

instance_place_list(x, y, obj, list, ordered);

Argument Description
x The x position to check for instances.
y The y position to check for instances.
obj The object to check for instances of.
list The DS list to use to store the IDs of colliding instances.
ordered Whether the calling instance, if relevant, should be excluded (true) or not (false).


Returns:

Int (The number of instances found to be in collision)


Example:

var _list = ds_list_create();
var _num = instance_place_list(x, y, obj_Enemy, _list, false);
if _num > 0
    {
    for (var i = 0; i < _num; ++i;)
        {
        instance_destroy(_list[| i]);
        }
    }
ds_list_destroy(_list);

The above code will check for a collision with all instances found at the calling instances position. These will be added to a DS list, which is then looped through to destroy each of the instances in collision.