RoomLoader() static constructor ‐ main interface - glebtsereteli/GMRoomLoader GitHub Wiki

Description

RoomLoader is GMRoomLoader's main interface. It handles data initialization and removal, room loading, layer filtering and taking room screenshots.

Important

RoomLoader is a statically initialized, namespace-like constructor. It is not designed to make instances of. All methods are to be called as follows: RoomLoader.action(<arguments>) - notice the lack of () after the constructor name.

RoomLoader is located in the RoomLoaderMain script.


📋 Methods


ℹ️ Data Handling

📍 Initialization

The following methods initialize room data to be used for loading or taking screenshots later.

Important

Loading is only possible for rooms with initialized data. Make sure that data initialization is performed before utilizing the loading functions.

Note

While GMRoomLoader is designed to be as performant as possible, this part is the most performace-heavy, as it utilizes room_get_info() to fetch and process room data for future loading. It's best to call these methods at the very start of your game, or if you're working with large volumes and need to load/unload data throughout the game - between levels, hidden behind a transition/loading screen.

🔶 .data_init(room, ...) -> Struct.RoomLoader

Initializes data for all given rooms.

Argument Type Description
room Asset.GMRoom The room to initialize data for.
... Asset.GMRoom More rooms to initialize data for. Supports any amount of arguments.

Example

// Initializes data for rm_level_castle:
RoomLoader.data_init(rm_level_castle);

// Initializes data for rm_level_forest and rm_level_cliffs:
RoomLoader.data_init(rm_level_forest, rm_level_cliffs);

🔶 .data_init_array(rooms) -> Struct.RoomLoader

Initializes data for all rooms in the given array.

Argument Type Description
rooms Array<Asset.GMRoom> The array of rooms to initialize data for.

Example

// Initializes data for all rooms inside the rooms array:
rooms = [rm_level_cabin, rm_level_alley, rm_level_beach];
RoomLoader.data_init_array(rooms);

🔶 .data_init_prefix(prefix) -> Array<Asset.GMRoom>

Initializes data for all rooms starting with the given prefix. Returns an array of found rooms.

Argument Type Description
prefix String The prefix to filter rooms with.

Example

// Initializes data for all rooms starting with "rm_level_" and stores found rooms in a variable:
rooms = RoomLoader.data_init_prefix("rm_level_");

🔶 .data_init_tag(tag) -> Array<Asset.GMRoom>

Initializes data for all rooms with the given tag assigned. Returns an array of found rooms.

Argument Type Description
tag String The tag to extract rooms from.

Example

// Initializes data for all rooms with the "rooms_dungeon" tag assigned and stores found rooms in a variable:
rooms = RoomLoader.data_init_tag("rooms_dungeon");

📍 Removal

Even though the initialized room data doesn't take too much space, you still might want to unload it for rooms that are no longer needed. The following methods follow the Initialization structure and remove initialized room data from RoomLoader's internal data pool.

🔶 .data_remove(room, ...) -> Struct.RoomLoader

Removes data for all (initialized) given rooms.

Argument Type Description
room Asset.GMRoom The room to remove data for.
... Asset.GMRoom More rooms to remove data for. Supports any amount of arguments.

Example

// Removes data for rm_level_castle:
RoomLoader.data_remove(rm_level_castle);

// Removes data for rm_level_forest and rm_level_cliffs:
RoomLoader.data_remove(rm_level_forest, rm_level_cliffs);

🔶 .data_remove_array(rooms) -> Struct.RoomLoader

Removes data for all (initialized) rooms in the given array.

Argument Type Description
rooms Array<Asset.GMRoom> The array of rooms to remove data for.

Example

// Removes data for all rooms inside the rooms array:
rooms = [rm_level_cabin, rm_level_alley, rm_level_beach];
RoomLoader.data_remove_array(rooms);

🔶 .data_remove_prefix(prefix) -> Struct.RoomLoader

Removes data for all (initialized) rooms starting with the given prefix.

Argument Type Description
prefix String The prefix to filter rooms with.

Example

// Removes data for all rooms starting with "rm_level_":
RoomLoader.data_remove_prefix("rm_level_");

🔶 .data_remove_tag(tag) -> Struct.RoomLoader

Removes data for all rooms with the given tag assigned.

Argument Type Description
tag String TThe tag to extract rooms from.

Example

// Removes data for all rooms with the "rooms_forest" assigned:
RoomLoader.data_remove_prefix("rooms_forest");

🔶 .data_clear() -> Struct.RoomLoader

Removes all initialized room data.

Example

// Clears all previously initialized room data:
RoomLoader.data_clear();

📍 Status & Getters

🔶 .data_is_initialized(room) -> Boolean

Checks whether the data for the given room is initialized (returns true) or not (return false).

Argument Type Description
room Asset.GMRoom The room to check.

Example

if (RoomLoader.data_is_initialized(rm_level_tower)) {
    // Yay, the data for rm_level_tower is initialized!
}

🔶 .data_get_width(room) -> Real

Returns the width of the given room.

Argument Type Description
room Asset.GMRoom The room to get the width for.

Example

var _width = RoomLoader.data_get_width(rm_level_dungeon);

🔶 .data_get_height(room) -> Real

Returns the height of the given room.

Argument Type Description
room Asset.GMRoom The room to get the height for.

Example

var _height = RoomLoader.data_get_height(rm_level_dungeon);

ℹ️ Loading

The following methods handle room loading.

Important

Loading is only possible for rooms with initialized data. Make sure that data initialization is performed before utilizing the following functions.

🔶 .load(room, x, y, [xorigin], [yorigin], [flags]) -> Struct.RoomLoaderReturnData

Loads the given room at the given coordinates, [xorigin] and [yorigin], filtered by the given [flags]. Returns an instance of the RoomLoaderReturnData constructor.

Argument Type Description
room Asset.GMRoom The room to load.
x Real The X coordinate to load the room at.
y Real The Y coordinate to load the room at.
[xorigin=ROOMLOADER_DEFAULT_XORIGIN] Real The x origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_XORIGIN config macro.
[yorigin=ROOMLOADER_DEFAULT_YORIGIN] Real The y origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_YORIGIN config macro.
[flags=ROOMLOADER_DEFAULT_FLAGS] Enum.ROOMLOADER_FLAG The flags to filter the loaded data by.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_FLAGS config macro.

Example

// Loads rm_level_castle at arbitrary coordinates:
RoomLoader.load(rm_level_castle, some_x, some_y);

// Loads rm_level_forest centered in the room: 
var _x = (room_width / 2);
var _y = (room_height / 2);
RoomLoader.load(rm_level_forest, _x, _y, 0.5, 0.5);

// Loads rm_level_cliffs's Sprites and Tilemaps at the bottom-right corner of the room
// and stores the returned instance of RoomLoaderReturnData in a variable to be cleaned up later:
var _flags = (ROOMLOADER_FLAG.SPRITES | ROOMLOADER_FLAG.TILEMAPS);
data = RoomLoader.load(rm_level_cliffs, room_width, room_height, 1, 1, _flags);

Note

The table below outlines the currently supported room contents.

Contents Layer Type Implemented Planned
Instances Instance ✔️ ✔️
Tilemaps Tile ✔️ ✔️
Sprites Asset ✔️ ✔️
Particle Systems Asset ✔️ ✔️
Sequences Asset ✔️ ✔️
Backgrounds Background ✔️ ✔️
Filters/Effects Filter/Effect ✔️
In-layer Filters/Effects Any ✔️
Creation Code - ✔️ ✔️
Views -
Physics -
Display Buffer & Viewport Clearing -

🔶 .load_instances_layer(room, x, y, layer, [xorigin], [yorigin]) -> Array<Id.Instance>

Loads the given room's instances at the given coordinates, layer, [xorigin] and [yorigin]. Returns an array of created Instance IDs.

Argument Type Description
room Asset.GMRoom The room to load instances for.
x Real The X coordinate to load instances at.
y Real The Y coordinate to load instances at.
layer Id.Layer or String The Layer ID (or name) to assign intances to.
[xorigin=ROOMLOADER_DEFAULT_XORIGIN] Real The x origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_XORIGIN config macro.
[yorigin=ROOMLOADER_DEFAULT_YORIGIN] Real The y origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_YORIGIN config macro.

Example

// Loads rm_level_castle's instances at arbitrary coordinates on the "Instances" layer:
var _layer = layer_get_id("Instances");
RoomLoader.load_instances_layer(rm_level_castle, some_x, some_y, _layer);

// Loads rm_level_castle's instances at the bottom-left corner of the room on the "Instances" layer
// and stores the returned array of instance IDs in a variable:
instances = RoomLoader.load_instances_layer(rm_level_castle, 0, room_height, "Instances", 0, 1);

🔶 .load_instances_depth(room, x, y, depth, [xorigin], [yorigin]) -> Array<Id.Instance>

Loads the given room's instances at the given coordinates, depth, [xorigin] and [yorigin]. Returns an array of created Instance IDs.

Argument Type Description
room Asset.GMRoom The room to load instances for.
x Real The X coordinate to load instances at.
y Real The Y coordinate to load instances at.
depth Real The depth to create instances at.
[xorigin=ROOMLOADER_DEFAULT_XORIGIN] Real The x origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_XORIGIN config macro.
[yorigin=ROOMLOADER_DEFAULT_YORIGIN] Real The y origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_YORIGIN config macro.

Example

// Loads rm_level_castle's instances at arbitrary coordinates and -1000 depth:
RoomLoader.load_instances_depth(rm_level_castle, some_x, some_y, -1000);

// Loads rm_level_castle's instances at the top-right corner of the room at depth 250
// and stores the returned array of instance IDs in a variable:
instances = RoomLoader.load_instances_depth(rm_level_castle, room_width, 0, 250, 1, 0);

ℹ️ Whitelist/Blacklist Layer Filtering

In addition to bitwise flag filtering, GMRoomLoader supports layer-based filtering via whitelisting/blacklisting.

  • Whitelisting will only load the layers with specified names.
  • Blacklisting excludes the layers with specified names from loading.
  • Both filters have their own sets of methods and can be active either on their own or together. For example:
RoomLoader
.layer_whitelist_add("trees", "rocks", "grass") // Whitelists "trees", "rocks" and "grass" layer names. Only these layers will be loaded.
.layer_blacklist_add("rocks") // Blacklists the "rocks" layer name. Only "trees" and "grass" layers will be loaded.
.load(...); // Load...

Note

  • Filtering applies to .load() and .take_screenshot() methods.
  • Filters are managed entirely by the user and are not reset automatically after loading.
  • The following methods should be called prior to .load()/.take_screenshot() for them to take effect.

📍 Whitelist

🔶 .layer_whitelist_add(layer_name, ...) -> Struct.RoomLoader

Adds all given layer names to the Whitelist filter.

Argument Type Description
layer_name String The layer name to whitelist.
... String More layer names. Supports any amount of arguments.

Example

// Whitelists the "buildings" layer name:
RoomLoader.layer_whitelist_add("buildings");

// Whitelists the "trees" and "rocks" layer names:
RoomLoader.layer_whitelist_add("trees", "rocks");

🔶 .layer_whitelist_remove(layer_name, ...) -> Struct.RoomLoader

Removes all given layer names for the Whitelist filter.

Argument Type Description
layer_name String The layer name to whitelist.
... String More layer names. Supports any amount of arguments.

Example

// Removes the "buildings" layer name from Whitelist:
RoomLoader.layer_whitelist_remove("buildings");

// Removes "trees" and "rocks" layer names from Whitelist:
RoomLoader.layer_whitelist_remove("trees", "rocks");

🔶 .layer_whitelist_reset() -> Struct.RoomLoader

Resets the Whitelist by removing previously set layer names.

Example

// Resets the Whitelist:
RoomLoader.layer_whitelist_reset();

🔶 .layer_whitelist_get() -> Array<String>

Returns an array of whitelisted layer names.

Example

// Gets an array of whitelisted layer names, blacklists them and resets Whitelist:
array_foreach(RoomLoader.layer_whitelist_get(), function(_layer_name) {
    RoomLoader.layer_blacklist_add(_layer_name);
});
RoomLoader.layer_whitelist_reset();

📍 Blacklist

🔶 .layer_blacklist_add(layer_name, ...) -> Struct.RoomLoader

Adds all given layer names to the Blacklist filter.

Argument Type Description
layer_name String The layer name to blacklist.
... String More layer names. Supports any amount of arguments.

Example

// Blacklists the "buildings" layer name:
RoomLoader.layer_blacklist_add("buildings");

// Blacklists the "trees" and "rocks" layer names:
RoomLoader.layer_blacklist_add("trees", "rocks");

🔶 .layer_blacklist_remove(layer_name, ...) -> Struct.RoomLoader

Removes all given layer names for the Blacklist filter.

Argument Type Description
layer_name String The layer name to blacklist.
... String More layer names. Supports any amount of arguments.

Example

// Removes the "buildings" layer name from Blacklist:
RoomLoader.layer_blacklist_remove("buildings");

// Removes "trees" and "rocks" layer names from Blacklist:
RoomLoader.layer_blacklist_remove("trees", "rocks");

🔶 .layer_blacklist_reset() -> Struct.RoomLoader

Resets the Blacklist by removing all previously added layer names.

Example

// Resets the Blacklist:
RoomLoader.layer_blacklist_reset();

🔶 .layer_blacklist_get() -> Array<String>

Returns an array of blacklisted layer names.

Example

// Gets an array of blacklisted layer names, whitelists them and resets Blacklist:
array_foreach(RoomLoader.layer_blacklist_get(), function(_layer_name) {
    RoomLoader.layer_whitelist_add(_layer_name);
});
RoomLoader.layer_blacklist_reset();

ℹ️ Taking Screenshots

Important

The following methods return new sprite created by sprite_create_from_surface(). Make sure to keep track of them and delete them using sprite_delete() when they're no longer needed.

🔶 .take_screenshot(room, [xorigin], [yorigin], [flags]) -> Id.Sprite

Takes a screenshot of the given room. Assigns the given origin to the created sprite and filters the drawn elements by the given flags. Returns a Sprite ID.

Argument Type Description
room Asset.GMRoom The room to take a screenshot of.
[xorigin=ROOMLOADER_DEFAULT_XORIGIN] Real The x origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_XORIGIN config macro.
[yorigin=ROOMLOADER_DEFAULT_YORIGIN] Real The y origin to load the room at.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_YORIGIN config macro.
[flags=ROOMLOADER_FLAG.ALL] Enum.ROOMLOADER_FLAG The flags to filter the drawn elements by.
[Optional]. Defaults to the ROOMLOADER_FLAG.ALL flags.

Example

// Create event. Take a screenshot of the rm_chunk_easy_01 room with a Middle Center origin,
// only capture Tilemaps and Sprites:
var _flags = (ROOMLOADER_FLAG.TILEMAPS | ROOMLOADER_FLAG.SPRITES);
screenshot = RoomLoader.take_screenshot(rm_chunk_easy_01, 0.5, 0.5, _flags);

// Draw GUI event. Draw screenshot centered on the screen:
if (screenshot != undefined) {
    var _x = (display_get_gui_width() / 2);
    var _y = (display_get_gui_height() / 2);
    draw_sprite(screenshot, 0, _x, _y);
}

📚 Concepts

💢 Origin

All loading and screenshotting methods have [xorigin] and [yorigin] optional arguments that dictate the origin for the target room.

These values are relative and range from 0 (no offset) to 1 (full width/height). Each can be set to any floating point value between 0 and 1 (inclusive).

Examples

// Loads rm_chunk_easy_01 at the bottom right corner of the room:
RoomLoader.load(rm_chunk_easy_01, room_width, room_height, 1, 1);

// Takes a screenshot of rm_level_cliffs with a centered origin:
screenshot = RoomLoader.take_screenshot(rm_level_cliffs, 0.5, 0.5);
⚠️ **GitHub.com Fallback** ⚠️