instance_select

Syntax:

instance_select(obj_or_instance_or_array_of_them, [array_to_prepend]);
Argument name Type Description
obj_or_instance_or_array_of_them array|instance|object The instances, objects, or combination of them
array_to_prepend array An array to prepend to the output array

Returns: (array) The array with the instances

Description:

Returns an array of all the INSTANCES (not objects, INSTANCES) passed.

The argument obj_or_instance_or_array_of_them can be:

  1. An object id (all instances of this object will be selected)
  2. An instance id
  3. An array of objects (all instances of those objects will be selected)
  4. An array of instances
  5. An array with a mix of instances and objects

If you pass an array in array_to_prepend, the array will be prepended to the normal output array. This is useful to concatenate a series of instance_select_* functions.

Example:

Suppose that you have in your room 6 boxes, 1 player and 3 trees, and 4 enemys. So you need to have an ARRAY that contains:

  • ALL the instances of the obj_box.
  • ONE specific tree. The instance which id is 100023.
  • ALL the instances of obj_player (only one will be selected since there is only one instance in the room)

So, you need to call:

var arr = instance_select( [obj_box, 100023, obj_player]);

And the output will be an array like this:

[100453, 100054, 100055, 100056, ... , 100455]

The first 6 will be ALL the instances of the boxes, the 7th item will be the tree and the last will be the id of the player.

If no instance match the specified query, then undefined is returned.