instance_create_depth


Description

With this function you can create a new instance of the specified object at any given point within the room and at the depth specified. The depth can be any value, where the lower the depth the "nearer" to the camera things will be drawn and the higher the depth the further away, so an instance at depth -200 will be drawn over an instance at depth +300 (for example). Note that this function will actually create a room layer for the instance, since all instances must be on a layer in the room, but since this is a managed layer (ie: not one that you have created through code or in the room, but one that GameMaker Studio 2 has created automatically) you cannot access it, and the layer instance variable will return -1.

IMPORTANT! There is a minimum and maximum layer depth of -16000 to 16000. Anything placed on a layer outside that range will not be drawn although all events will still run as normal.

This function returns the id of the new instance which can then be stored in a variable or used to access that instance. Note that this function will also call the Create Event of the instance being created before continuing with the code or actions for the event that called the function.


Syntax:

instance_create_depth(x, y, depth, obj);


Arguments:

Argument Description
x The x position the object will be created at
y The y position the object will be created at
depth The depth to assign the created instance to
obj The object index of the object to create an instance of


Returns:

Real (instance ID value)


Example:

var inst;
inst = instance_create_depth(x, y, -10000, obj_Bullet);
with (inst)
   {
   speed = other.shoot_speed;
   direction = other.image_angle;
   }

The above code creates a new instance of the object "obj_Bullet" and stores the instance id in a variable. This variable is then used to assign speed and direction to the new instance.