Getters

Overview

This section covers two ways to retrieve created element IDs from Payload.

1. Individual ID .Get<ElementType>() getters.
   • Instances, Sprites, Particle Systems, Sequences and Texts use their room IDs.
   • Tilemaps and Backgrounds use the name of the layer they're on.
2. Type-based .Get<ElementType>s() getters that return an array of element IDs, using layer names for lookup.

NOTE

All code examples on this page assume you have an existing instance of Payload retrieved from RoomLoader.Load() and stored in a payload variable.

Methods

.GetBbox()

payload.GetBbox() ➜ Struct

Returns the axis-aligned bounding box of the loaded room as a struct with the following variables:

Variable	Description
x1	The left x coordinate of the bounding box
y1	The top y coordinate of the bounding box
x2	The right x coordinate of the bounding box
y2	The bottom y coordinate of the bounding box

Example

// Gets the bounding box of the loaded room and draws a rectangle around it
var _bbox = payload.GetBbox(); 
draw_rectangle(_bbox.x1, _bbox.y1, _bbox.x2, _bbox.y2, true);

---

.GetPolygon()

payload.GetPolygon() ➜ Array

Returns the corners of the loaded room as a flat [x1, y1, x2, y2, x3, y3, x4, y4] coordinate array in clockwise order, accounting for any combination of position, origin, scale, and rotation.

Example

// Gets the polygon of the loaded room and draws its outline
var _polygon = payload.GetPolygon(); 
var _n = array_length(_polygon);
for (var _i1 = 0; _i1 < _n; _i1 += 2) {
    var _i2 = (_i1 + 2) mod _n;
    draw_line(_polygon[_i1], _polygon[_i1 + 1], _polygon[_i2], _polygon[_i2 + 1]);
}

---

.GetLayer()

payload.GetLayer(name) ➜ Id.Layer or Undefined

Returns the ID of the created Layer matching the given name if found, or Undefined if not found.

Parameter	Type	Description
name	String	The layer name to search for

Example

// Gets the created "Clouds" layer ID and randomizes its horizontal speed
var _cloudsLayer = payload.GetLayer("Clouds"); 
if (_cloudsLayer != undefined) {
    layer_hspeed(_cloudsLayer, random_range(5, 8));
}

---

.GetLayers()

payload.GetLayers() ➜ Array of Id.Layer

Returns an array of created Layers.

Example

// Gets an array of created Layers and randomly toggles their visibility
array_foreach(payload.GetLayers(), function(_layer) { 
    layer_set_visible(_layer, choose(true, false));
});

---

.GetInstance()

payload.GetInstance(roomId) ➜ Id.Instance or Noone

Returns the ID of the created Instance from the given room ID if found, or Noone if not found.

Parameter	Type	Description
roomId	Constant	The Instance room ID to search for

Example

// Grabs the created Instance ID from the InstWaypoint room ID and assigns it
// to objPlayer's waypointID
objPlayer.waypointID = payload.GetInstance(InstWaypoint); 

---

.GetInstances()

payload.GetInstances([object]) ➜ Array of Id.Instance

Returns an array of created Instances, optionally filtered by object.

Parameter	Type	Description
[object]	Asset.GMObject	The object to filter instances by. Only instances of this object will be returned [Default: undefined (no filter)]

Example

// Gets an array of created Instances and targets a random one
var _instances = payload.GetInstances(); 
var _randomInstance = script_execute_ext(choose, _instances);

// Gets an array of created objDoor instances
var _doors = payload.GetInstances(objDoor); 

---

.DetachInstances()

payload.DetachInstances() ➜ Array of Id.Instance

Detaches instances from the Payload and stops tracking them. Returns an array of the detached instance IDs, allowing their cleanup to be handled separately.

INFO

Useful when instances from a loaded room need to outlive the rest of the room's contents. For example, in chunk systems where an instance may move between chunks and should not be destroyed when its original chunk unloads.

WARNING

If detached instances remain on their original layers and those layers are destroyed during .Cleanup(), the instances will still be destroyed.

Example

// Detaches loaded instances from the payload and stores them for manual cleanup
var _instances = payload.DetachInstances(); 

// Later, destroy detached instances when needed
array_foreach(_instances, function(_inst) {
    instance_destroy(_inst);
});

---

.GetTilemap()

payload.GetTilemap(layerName) ➜ Id.Tilemap or Undefined

Returns the ID of the created Tilemap from the given layer name, or Undefined if not found.

Parameter	Type	Description
layerName	String	The Tile layer name to search for

Example

// Gets the created Tilemap ID from the "TilesCollision" layer
// to use for collision
var _collisionTilemap = payload.GetTilemap("TilesCollision"); 
if (_collisionTilemap != undefined) {
    array_push(global.collisionTilemaps, _collisionTilemap);
}

---

.GetTilemaps()

payload.GetTilemaps() ➜ Array of Id.Tilemap

Returns an array of created Tilemaps.

Example

// Gets an array of created Tilemaps and targets a random one
var _tilemaps = payload.GetTilemaps(); 
var _randomTilemap = script_execute_ext(choose, _tilemaps);

---

.GetSprite()

payload.GetSprite(roomId) ➜ Id.Sprite or Undefined

Returns the ID of the created Sprite matching the given room ID if found, or Undefined if not found.

Parameter	Type	Description
roomId	String	The Sprite room ID to search for

Example

// Gets the created Sprite ID using its "SpriteStar" room ID, and if found,
// rotates it randomly
var _sprite = payload.GetSprite("SpriteStar"); 
if (_sprite != undefined) {
    layer_sprite_angle(_sprite, irandom(360));
}

---

.GetSprites()

payload.GetSprites() ➜ Array of Id.Sprite

Returns an array of created Sprites.

Example

// Gets an array of created Sprites and blends them red
array_foreach(payload.GetSprites(), function(_sprite) { 
    layer_sprite_blend(_sprite, c_red);
});

---

.GetSequence()

payload.GetSequence(roomId) ➜ Id.Sequence or Undefined

Returns the created Sequence ID matching the given room ID if found, or Undefined if not found.

Parameter	Type	Description
roomId	String	The Sequence room ID to search for

Example

// Gets the created Sequence ID using its "SequenceWindow" room ID, and if found,
// randomizes its playhead position
var _sequence = payload.GetSequence("SequenceWindow"); 
if (_sequence != undefined) {
    var _length = layer_sequence_get_length(_sequence);
    layer_sequence_headpos(_sequence, random(_length));
}

---

.GetSequences()

payload.GetSequences() ➜ Array of Id.Sequence

Returns an array of created Sequences.

Example

// Gets an array of created Sequences and randomizes their speed scales
array_foreach(payload.GetSequences(), function(_sequence) { 
    layer_sequence_speedscale(_sequence, random_range(0.75, 1.25));
});

---

.GetParticleSystem()

payload.GetParticleSystem(roomId) ➜ Id.ParticleSystem or Undefined

Returns the ID of the created Particle System matching the given room ID if found, or Undefined if not found.

Parameter	Type	Description
roomId	String	The Particle System room ID to search for

Example

// Gets the "Sparkles" Particle System, and if found, randomizes its color
var _psSparkle = payload.GetParticleSystem("Sparkles"); 
if (_psSparkle != undefined) {
    var _randomColor = make_color_hsv(irandom(0, 255), 200, 200);
    part_system_color(_psSparkle, _randomColor, 1);
}

---

.GetParticleSystems()

payload.GetParticleSystems() ➜ Array of Id.ParticleSystem

Returns an array of created Particle Systems.

Example

// Gets all loaded Particle Systems and pre-updates them by 60 frames
var _systems = payload.GetParticleSystems(); 
if (array_length(_systems) > 0) {
    repeat (60) {
        array_foreach(_systems, function(_ps) {
            part_system_update(_ps);
        });
    }
}

---

.GetText()

payload.GetText(roomId) ➜ Id.Text or Undefined

Returns the ID of the created Text matching the given room ID if found, or Undefined if not found.

Parameter	Type	Description
roomId	String	The Text room ID to search for

Example

// Gets the created Text ID using its "TextTitle" room ID, and if found,
// randomizes its angle
var _text = payload.GetText("TextTitle"); 
if (_text != undefined) {
    layer_text_angle(_text, random(360));
}

---

.GetTexts()

payload.GetTexts() ➜ Array of Id.Text

Returns an array of created Texts.

Example

// Gets an array of created Texts and randomizes their colors
array_foreach(payload.GetTexts(), function(_text) { 
    layer_text_color(_text, make_color_hsv(irandom(255), 200, 200));
});

---

.GetBackground()

payload.GetBackground(layerName) ➜ Id.Background or Undefined

Returns the ID of the created Background matching the given layer name if found, or Undefined if not found.

Parameter	Type	Description
layerName	String	The Background layer name to search for

Example

// Gets the created Background ID from the "BackgroundClouds" layer and if found,
// blends it orange
var _bg = payload.GetBackground("BackgroundClouds"); 
if (_bg != undefined) {
    layer_background_blend(_bg, c_orange);
}

---

.GetBackgrounds()

payload.GetBackgrounds() ➜ Array of Id.Background

Returns an array of created Backgrounds.

Example

// Gets an array of created Backgrounds and randomizes their image indices
array_foreach(payload.GetBackgrounds(), function(_bg) { 
    var _frames = sprite_get_number(layer_background_get_sprite(_bg));
    layer_background_index(_bg, irandom(_frames - 1));
});