Skip to content

RoomLoader() static constructor ‐ main interface

Jump to bottom
Gleb Tsereteli edited this page Mar 11, 2024 · 79 revisions

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) -> Struct.RoomLoader

Fetches all room IDs in the project and initializes data for all rooms starting with the given prefix. Room IDs are fetched once and stored in a static variable inside the method.

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

Example

// Initializes data for all rooms starting with "rm_level_":
RoomLoader.data_init_prefix("rm_level_");

📍 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_clear() -> Struct.RoomLoader

Removes all initialized room data.

Example

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

📍 Miscellaneous

🔶 .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!
}

ℹ️ 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, [origin=ROOMLOADER_DEFAULT_ORIGIN], [flags=ROOMLOADER_DEFAULT_FLAGS]) -> Struct.RoomLoaderReturnData or undefined

Loads the given room at the given coordinates and [origin] filtered by the given [flags]. Returns an instance of the RoomLoaderReturnData constructor used for further processing or undefined if the data for the given room hasn't been initialized.

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.
[origin=ROOMLOADER_DEFAULT_ORIGIN] Enum.ROOMLOADER_ORIGIN The origin to load the room at. Follows GameMaker's sprite origin layout.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_ORIGIN 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, ROOMLOADER_ORIGIN.MIDDLE_CENTER);

// 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, ROOMLOADER_ORIGIN.BOTTOM_RIGHT, _flags);

Note

The table below outlines the currenly 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, [origin=ROOMLOADER_DEFAULT_ORIGIN]) -> Array<Id.Instance> or undefined

Loads the given room's instances at the given coordinates, layer and [origin]. Returns an array of created Instance IDs or undefined if the data for the given room hasn't been initialized.

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.
[origin=ROOMLOADER_DEFAULT_ORIGIN] Enum.ROOMLOADER_ORIGIN The origin to load instances at. Follows GameMaker's sprite origin layout.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_ORIGIN 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", ROOMLOADER_ORIGIN.BOTTOM_LEFT);

🔶 .load_instances_depth(room, x, y, depth, [origin=ROOMLOADER_DEFAULT_ORIGIN]) -> Array<Id.Instance> or undefined

Loads the given room's instances at the given coordinates, depth and [origin]. Returns an array of created Instance IDs or undefined if the data for the given room hasn't been initialized.

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.
[origin=ROOMLOADER_DEFAULT_ORIGIN] Enum.ROOMLOADER_ORIGIN The origin to load instances at. Follows GameMaker's sprite origin layout.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_ORIGIN 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, ROOMLOADER_ORIGIN.TOP_RIGHT);

ℹ️ 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 only applies to the main .load() method.
  • Filters are managed entirely by the user and are not reset automatically after loading.
  • The following methods should be called prior to .load() 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();

ℹ️ Miscellaneous

🔶 .take_screenshot(room, [origin], [flags]) -> Id.Sprite or undefined

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 if the data for the given room has previously been initialized, or undefined if it hasn't.

Warning

This method returns a new sprite created by sprite_create_from_surface(). Make sure to keep track of it and delete it using sprite_delete() when it's no longer needed.

Argument Type Description
room Asset.GMRoom The room to take a screenshot of.
[origin=ROOMLOADER_DEFAULT_ORIGIN] Enum.ROOMLOADER_ORIGIN The origin to assign to the created Sprite.
[Optional]. Defaults to the ROOMLOADER_DEFAULT_ORIGIN 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 Middle Center origin,
// only capture Tilemaps and Sprites:
var _flags = (ROOMLOADER_FLAG.TILEMAPS | ROOMLOADER_FLAG.SPRITES);
screenshot = RoomLoader.take_screenshot(rm_chunk_easy_01, ROOMLOADER_ORIGIN.MIDDLE_CENTER, _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);
}
Clone this wiki locally