Description

An instance of the RoomLoaderReturnData constructor is returned by RoomLoader's .load() method. It stores all layers and elements created on load, and handles element fetching and cleanup.

[!Important] RoomLoaderReturnData is used in the context of storing and handling returned data exclusively and is not designed to make instances of.

RoomLoaderReturnData is located in the RoomLoaderReturnData script.

📋 Methods

• Getters
  • .get_layer(name)
  • .get_layers()
  • .get_instances()
  • .get_tilemap(layer_name)
  • .get_tilemaps()
  • .get_sprite(name)
  • .get_sprites()
  • .get_particle_system(name)
  • .get_particle_systems()
  • .get_sequence(name)
  • .get_sequences()
  • .get_background(layer_name)
  • .get_backgrounds()
• Cleanup
  • .cleanup()

---

ℹ️ Getters

This section covers two ways to retrieve created element IDs:

1. Individual ID .get_<element_type>(name) getters using string names for lookup.
   • Sprites, Particle Systems and Sequences use their unique in-room names.
   • Tilemaps and Backgrounds use the name of the layer they're on.
   • These are supported for all element types except Instances due to internal GameMaker limitations. Given instances are considered the most commonly used asset type and there could be up to thousands of them in a room, storing a unique string ID for each instance is considered inefficient and is not currently supported.
2. Type-based .get<element_type>s() getters that return an array of element IDs.

[!TIP] Use Instance Creation Code to target specific created instances using your own custom logic.

🔶 .get_layer(name) -> Id.Layer or undefined

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

Argument	Type	Description
name	String	The layer name to search for.

Example

// Gets the created "clouds" layer ID and changes its horizontal speed:
var _clouds_layer = data.get_layer("clouds");
if (_clouds_layer != undefined) {
    layer_hspeed(_clouds_layer, 7);
}

🔶 .get_layers() -> Array<Id.Layer>

Returns an array of created Layers.

Example

// Gets an array of created Layers and randomly toggles each one's visibility:
array_foreach(data.get_layers(), function(_layer) {
    layer_set_visible(_layer, choose(true, false));
});

---

🔶 .get_instances() -> Array<Id.Instance>

Returns an array of created Instances.

Example

// Gets an array of created Instances and targets a random one:
var _instances = data.get_instances();
var _target = script_execute_ext(choose, _instances);

---

🔶 .get_tilemap(layer_name) -> Id.Tilemap or undefined

Returns the created Tilemap ID matching the given layer name, or undefined if not found.

Argument	Type	Description
layer_name	String	The Tile layer name to search for.

Example

// Gets the created Tilemap ID on the "tiles_collision" layer and uses it for collision:
collision_tilemap = (data.get_tilemap("tiles_collision") ?? noone);

🔶 .get_tilemaps() -> Array<Id.Tilemap>

Returns an array of created Tilemaps.

Example

// Gets an array of created Tilemaps and targets a random one:
var _tilemaps = data.get_tilemaps();
var _target = script_execute_ext(choose, _tilemaps);

---

🔶 .get_sprite(name) -> Id.Sprite or undefined

Returns the created Sprite ID matching the given name, or undefined if not found.

Argument	Type	Description
name	String	The Sprite name to search for.

Example

// Gets the created Sprite ID named "sprite_star" and if found, rotates it randomly:
var _sprite = data.get_sprite("sprite_star");
if (_sprite != undefined) {
    layer_sprite_angle(_sprite, irandom(360));
}

🔶 .get_sprites() -> Array<Id.Sprite>

Returns an array of created Sprites.

Example

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

---

🔶 .get_particle_system(name) -> Id.ParticleSystem or undefined

Returns the created Particle System ID matching the given name, or undefined if not found.

Argument	Type	Description
name	String	The Particle System name to search for.

Example

// Gets the Particle System ID named "particles_smoke" and if found, progresses it by 3 seconds:
var _smoke_particles = data.get_particle_system("particles_smoke");
if (_smoke_particles != undefined) {
    repeat (game_get_speed(gamespeed_fps) * 3) {
        part_system_update(_smoke_particles);
    }
}

🔶 .get_particle_systems() -> Array<Id.ParticleSystem>

Returns an array of created Particle Systems.

Example

// Gets an array of created Particle Systems and positions them randomly around the player:
array_foreach(data.get_particle_systems(), function(_ps) {
    var _offset = irandom_range(32, 96);
    var _angle = irandom(360);
    var _x = obj_player.x + lengthdir_x(_offset, _angle);
    var _y = obj_player.y + lengthdir_y(_offset, _angle);
    part_system_position(_ps, _x, _y);
});

---

🔶 .get_sequence(name) -> Id.Sequence or undefined

Returns the created Sequence ID matching the given name, or undefined if not found.

Argument	Type	Description
name	String	The Sequence name to search for.

Example

// Gets the created Sequence ID named "seq_window" and if found, randomizes its playhead position:
var _seq_window = data.get_particle_system("seq_window");
if (_seq_window != undefined) {
    var _length = layer_sequence_get_length(_seq_window);
    layer_sequence_headpos(_seq_window, random(_length));
}

🔶 .get_sequences() -> Array<Id.Sequence>

Returns an array of created Sequences.

Example

// Gets an array of created Sequences and randomizes their speed scales:
array_foreach(data.get_sequences(), function(_sequence) {
    layer_sequence_speedscale(_sequence, random(0.75, 1.25));
});

---

🔶 .get_background(name) -> Id.Background or undefined

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

Argument	Type	Description
layer_name	String	The Background layer name to search for.

Example

// Gets the created Background ID on the "bg_clouds" layer and if found, blends it orange:
var _bg_clouds = data.get_background("bg_clouds");
if (_bg_clouds != undefined) {
    layer_background_blend(_bg_clouds, c_orange);
}

🔶 .get_backgrounds() -> Array<Id.Background>

Returns an array of created Backgrounds.

Example

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

---

ℹ️ Cleanup

🔶 .cleanup() -> undefined

Destroys created layers and their elements. After calling this method, the instance becomes practically useless and should be dereferenced to be picked up by the Garbage Collector.

Example

// Cleans up the RoomLoaderReturnData instance stored in the data variable:
data.cleanup();