Instances

Instances

In the game, the basic units are the instances of the different objects. During game play you can change a number of aspects of these instances. Also you can create new instances and destroy instances. Besides the movement related variables discussed above and the drawing related variables discussed below, each instance has the following variables:

object_index* Index of the object this is an instance of. This variable cannot be changed.
id* The unique identifier for the instance (>= 100000). (Note that when defining rooms the id of the instance under the mouse is always indicated.)
mask_index Index of the sprite used as mask for collisions. Give this a value of -1 to make it the same as the sprite_index.
solid Whether the instance is solid. This can be changed during the game.
persistent Whether the instance is persistent and will reappear when moving to another room. You often want to switch persistence off at certain moments. (For example if you go back to the first room.)

There is one problem when dealing with instances. It is not so easy to identify individual instances. They don't have a name. When there is only one instance of a particular object you can use the object name but otherwise you need to get the id of the instance. This is a unique identifier for the instance. you can use it in with statements and as object identifier. Fortunately there are a number of variables and routines that help you locate instance id's.

instance_count* Number of instances that currently exist in the room.
instance_id[0..n-1]* The id of the particular instance. Here n is the number of instance.

Note that the assignment of the instances to the instance id's changes every step so you cannot use values from previous steps. Also please note that instances that are deleted will remain in the list until the end of the step. So if you are also deleting instances you need to check whether the instance still exists. Let me give an example. Assume each unit in your game has a particular power and you want to locate the strongest one, you could use the following code:

{
  maxid = -1;
  maxpower = 0;
  for (i=0; i<instance_count; i+=1)
  {
    iii = instance_id[i];
    if (instance_exists(iii))
      if (iii.object_index == unit)
      {
        if (iii.power > maxpower)
          {maxid = iii; maxpower = iii.power;}
      }
  }
}

After the loop maxid will contain the id of the unit with largest power. Of course, for this particular situation the following code would be better:

{
  maxid = -1;
  maxpower = 0;
  with (unit) do
  {
    if (power > maxpower)
      {maxid = self; maxpower = power;}
  }
}

instance_find(obj,n) Returns the id of the (n+1)'th instance of type obj. obj can be an object or the keyword all. If it does not exist, the special object noone is returned. Note that the assignment of the instances to the instance id's changes every step so you cannot use values from previous steps.
instance_exists(obj) Returns whether an instance of type obj exists. obj can be an object, an instance id, or the keyword all.
instance_number(obj) Returns the number of instances of type obj. obj can be an object or the keyword all.
instance_position(x,y,obj) Returns the id of the instance of type obj at position (x,y). When multiple instances are at that position the first is returned. obj can be an object or the keyword all. If it does not exist, the special object noone is returned.
instance_nearest(x,y,obj) Returns the id of the instance of type obj nearest to (x,y). obj can be an object or the keyword all.
instance_furthest(x,y,obj) Returns the id of the instance of type obj furthest away from (x,y). obj can be an object or the keyword all.
instance_place(x,y,obj) Returns the id of the instance of type obj met when the current instance is placed at position (x,y). obj can be an object or the keyword all. If it does not exist, the special object noone is returned.

The following functions can be used for creating and destroying instances.

instance_create(x,y,obj) Creates an instance of obj at position (x,y). The function returns the id of the new instance.
instance_copy(performevent) Creates a copy of the current instance. The argument indicates whether the creation event must be executed for the copy. The function returns the id of the new copy.
instance_destroy() Destroys the current instance.
instance_change(obj,perf) Changes the instance into obj. perf indicates whether to perform the destroy and creation events.
position_destroy(x,y) Destroys all instances whose sprite contains position (x,y).
position_change(x,y,obj,perf) Changes all instances at (x,y) into obj. perf indicates whether to perform the destroy and creation events.