What is an Instance?

An instance is a copy of a Game Maker object that is created during runtime.

Objects vs Instances

Instances are not the objects themselves. In comparison, an object is a prototype from which instances are created.

Objects are like cookie-cutters, instances are like cookies.

Local Variables

All instances of all objects have all the built-in local variables : x, y, direction, etc. For a complete list of local variables in instances, see list of variables.

Creating Instances

Ways to Create an Instance

There are several different ways to create an instance. An instance can be created by a function, an action, or by a room when it creates the instances inside it.

• Add an Instance to a Room before runtime.

Actions that Create Instances

• Create Instance - create an instance
• Create Moving - create an instance that is moving
• Create Random

Functions that Create Instances

• instance_create()

When an Instance Is Created

These things happen :

• object_index is given the name the object the instance is created from.
• It is assigned an instance id. This is a unique id that is different for every instance, no matter what object it was created from.
• It's xstart and ystart variables are set to the x and y position where the instance was created.
• It receives a Create event

Create a Random Number of Instances

The GML code below creates a random number of instances between 1 and 50 of obj at random locations in the current room :

no_of_instances = floor(random(50)) + 1 ;
for (i = 1; i <= no_of_instances; i += 1)
{
    rand_x = floor(random(room_width)) + 1;
    rand_y = floor(random(room_height)) + 1;
    instance_create (rand_x, rand_y, obj) ;
}

Destroying Instances

Actions that Destroy Instances

• Destroy Instance
• Destroy at Position

Functions that Destroy Instances

• instance_destroy()

Destroy the Current Instance

To destroy the current instance (the one performing the action or running the code)

You can :

Use Destroy Instance.
Use instance_destroy().

Destroy an Instance Colliding with the Current Instance

To destroy the other instance involved in a collision with the current instance, you can :

Use Destroy Instance with other checked.
Use the following GML code :

with(other) instance_destroy();

Destroy all Instances of an Object in a Room

To destroy all the instances of a specific object in a room, use :

with(object_name) instance_destroy();

Advanced stuff

Get the instance's name

object_get_name(ID.object_index)

• For example

I created an object called "Jorge" and then an instance of it.
The instance's id is 100005 and i put it into a variable called "dueno"

So:

object_get_name(dueno.object_index) = "Jorge"

Instance Management

Activate and Deactivate Instances

• instance_deactivate_all() - deactivate all instances

Other

• instance_count - count the number of instances

Related Pages

• Local Variable
• Object

Actions

• Change Instance
• Create Instance - create an instance
• Create Moving - create an instance that is moving
• Create Random
• Destroy Instance - destroy an instance
• Destroy at Position

Errors

• Asking to change into non-existing object

Events

• Create Event
• Destroy Event

GML

Functions

• instance_change()
• instance_copy()
• instance_create()
• instance_activate_all()
• instance_activate_object()
• instance_activate_region()
• instance_deactivate_all()
• instance_deactivate_object()
• instance_activate_region()
• instance_destroy()
• instance_exists()
• instance_find()
• instance_furthest()
• instance_nearest()
• instance_number()
• instance_place()
• instance_position()
• position_change()
• position_destroy()

Variables

• id
• instance_count
• instance_id[] (actually an array}
• mask_index
• object_index
• persistent
• solid

Tutorials

• Add an Instance to a Room

To Do

• Instance description needs to be expanded.
• Related pages is missing functions and variables related to instances.
• Moving an instance.
  • Create a moving instance, traveling in a specific direction.
• Change instance depth.
• Get instance id
• Selecting Instances
  • Topmost instance
  • Find nearest instance
• Destroying instances
  • Destroy instance at position or location
  • Destroy instances within a range (for bombs)
  • Destroy instance chosen by mouse