RoomLoader() static constructor ‐ main interface - glebtsereteli/GMRoomLoader GitHub Wiki
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 theRoomLoaderMain
script.
- Data Handling
- Loading
- Whitelist/Blacklist Layer Filtering
- Taking Screenshots
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. |
// 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. |
// 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. |
// 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. |
// 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");
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. |
// 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. |
// 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. |
// 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. |
// 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.
// Clears all previously initialized room data:
RoomLoader.data_clear();
🔶 .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. |
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. |
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. |
var _height = RoomLoader.data_get_height(rm_level_dungeon);
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. |
// 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. |
// 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. |
// 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);
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.
🔶 .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. |
// 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. |
// 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.
// Resets the Whitelist:
RoomLoader.layer_whitelist_reset();
Returns an array of whitelisted layer names.
// 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();
🔶 .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. |
// 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. |
// 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.
// Resets the Blacklist:
RoomLoader.layer_blacklist_reset();
Returns an array of blacklisted layer names.
// 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();
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. |
// 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);
}
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).
-
xorigin
: 0 is left, 0.5 is center, 1 is right. Defaults to the ROOMLOADER_DEFAULT_XORIGIN config macro. -
yorigin
: 0 is top, 0.5 is center, 1 is bottom. Defaults to the ROOMLOADER_DEFAULT_YORIGIN config macro.
// 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);