State
Overview
State is an alternative way to preconfigure Loading and Screenshotting parameters, avoiding long calls with many optional arguments.
It defines how rooms are positioned, filtered by flags, transformed, and otherwise adjusted during Loading and Screenshotting. The intended workflow is as follows:
- Set State before calling any Loading or Screenshotting methods.
- Call any Loading or Screenshotting method.
- State resets automatically afterwards. If you want to apply the same configuration again, you must re-specify it before the next call.
This system uses a Builder pattern with a Fluent Interface, allowing you to chain methods in a natural, English-like flow to set up optional parameters in any order before Loading or Screenshotting a room.
// Loads rmExample's sprites and sequences centered in the room and randomly rotated
payload = RoomLoader
.Sprites().Sequences()
.MiddleCenter().Angle(random(360))
.Load(rmExample, room_width / 2, room_height / 2);
// Loads rmExample's instances scaled up by x2:
instances = RoomLoader.Scale(2).LoadInstances(rmExample, x, y);
// When working with perspective visuals, turns a visual walls tilemap into
// a collision tilemap
collisionTilemap = RoomLoader
.Tileset(tsWallsCollision)
.LoadTilemap(rmExample, 0, 0, "Walls", collisionLayer);The State system does not replace normal optional arguments - those are still available in all Loading and Screenshotting methods. Instead, it provides a more verbose and cleaner alternative, letting you cherry-pick only the arguments you care about without writing long calls.
The following sections break down the available State categories.
- Origin - Where the room is anchored.
- Flags - Which asset types to include.
- Transformation - Scaling, mirroring, flipping and rotating options.
- Miscellaneous - Extra parameters like custom tilesets when loading tilemaps, maybe more in the future.
Origin
.XOrigin()
RoomLoader.XOrigin(xOrigin)➜ Struct.RoomLoader
Sets the X Origin State to use in the next Loading or Screenshotting call.
| Parameter | Type | Description |
|---|---|---|
xOrigin | Real | The X Origin to use in the next Loading or Screenshotting call |
// Loads rmExample with a Top-Center origin
RoomLoader.XOrigin(0.5).Load(rmExample, x, y); .YOrigin()
RoomLoader.YOrigin(yOrigin)➜ Struct.RoomLoader
Sets the Y Origin State to use in the next Loading or Screenshotting call.
| Parameter | Type | Description |
|---|---|---|
yOrigin | Real | The Y Origin to use in the next Loading or Screenshotting call |
// Loads rmExample with a Middle-Left origin
RoomLoader.YOrigin(0.5).Load(rmExample, x, y); .Origin()
RoomLoader.Origin(xOrigin, [yOrigin])➜ Struct.RoomLoader
Sets the X and Y Origin states to use in the next Loading or Screenshotting call.
| Parameter | Type | Description |
|---|---|---|
xOrigin | Real | The X Origin to use in the next Loading or Screenshotting call |
[yOrigin] | Real | The Y Origin to use in the next Loading or Screenshotting call [Default: xOrigin] |
// Loads rmExample with a Middle-Center origin
RoomLoader.Origin(0.5, 0.5).Load(rmExample, x, y); Presets
For convenience, GMRoomLoader provides a set of built-in origin presets. These are shorthand methods with common values mimicking the GameMaker's sprite origin presets layout, so the pattern should feel immediately familiar.
The goal with these is readability: the methods create a natural English-like flow in code. Instead of raw numbers, you can write what you mean (almost) directly, e.g. "load the room at the top right" or "get a centered screenshot".
| Method | X Origin | Y Origin |
|---|---|---|
.TopLeft() | 0.0 | 0.0 |
.TopCenter() | 0.5 | 0.0 |
.TopRight() | 1.0 | 0.0 |
.MiddleLeft() | 0.0 | 0.5 |
.MiddleCenter() | 0.5 | 0.5 |
.MiddleRight() | 1.0 | 0.5 |
.BottomLeft() | 0.0 | 1.0 |
.BottomCenter() | 0.5 | 1.0 |
.BottomRight() | 1.0 | 1.0 |
// Load rmExample at the top-right corner of the room with Top-Right origin
payload = RoomLoader.TopRight().Load(rmExample, room_width, room_height);
// Take a centered screenshot of rmExample
screenshot = RoomLoader.MiddleCenter().ScreenshotSprite(rmExample); Flags
.Flags()
RoomLoader.Flags(flags)➜ Struct.RoomLoader
Sets the Flags to use in the next Loading or Screenshotting call. Check out filtering by Asset Type for more information.
| Parameter | Type | Description |
|---|---|---|
flags | Real | The flags (ROOMLOADER_FLAG_<NAME>) used to filter which asset types are loaded or screenshotted |
// Loads rmExample's Tilemaps and Sequences
var _flags = ROOMLOADER_FLAG_TILEMAPS | ROOMLOADER_FLAG_SEQUENCES;
RoomLoader.Flags(_flags).Load(rmExample, x, y); Builder
The Flags Builder lets you define what elements of the room should be included in the next Loading or Screenshotting call.
Each Builder method corresponds to a specific ROOMLOADER_FLAG_ macro and adds it to the Flags State.
- The first call to any of these methods before Loading or Screenshotting resets the State and sets it to that method's flag, so you always start clean with the one you choose.
- Subsequent calls add their flags on top, letting you combine multiple asset types.
Similar to Origin Presets above, this approach makes the code read in an English-like flow and provides an alternative interface if you don't like dealing with bitwise operators.
| Method | Flag |
|---|---|
.Instances() | ROOMLOADER_FLAG_INSTANCES |
.Tilemaps() | ROOMLOADER_FLAG_TILEMAPS |
.Sprites() | ROOMLOADER_FLAG_SPRITES |
.Sequences() | ROOMLOADER_FLAG_SEQUENCES |
.Particles() | ROOMLOADER_FLAG_PARTICLES |
.Texts() | ROOMLOADER_FLAG_TEXTS |
.Backgrounds() | ROOMLOADER_FLAG_BACKGROUNDS |
.Effects() | ROOMLOADER_FLAG_EFFECTS |
// Load rmExample's Instances
RoomLoader.Instances().Load(rmExample, x, y);
// Load rmExample's Instances, Tilemaps and Backgrounds
RoomLoader.Instances().Tilemaps().Backgrounds().Load(rmExample, x, y);
// Take a screenshot of rmExample with only Sprites and Tilemaps visible
RoomLoader.Sprites().Tilemaps().ScreenshotSprite(rmExample); RoomLoader
// First call, flags are reset to only Instances.
// Current flags representation: ROOMLOADER_FLAG_INSTANCES
.Instances()
// Second call, Tilemaps are added.
// Current flags representation: ROOMLOADER_FLAG_INSTANCES | ROOMLOADER_FLAG_TILEMAPS
.Tilemaps()
// Third call, Sprites are added.
// Current flags representation: ROOMLOADER_FLAG_INSTANCES | ROOMLOADER_FLAG_TILEMAPS | ROOMLOADER_FLAG_SPRITES
.Sprites()
// Load rmExample's Instances, Tilemaps and Sprites
.Load(rmExample, x, y);
// And in one line
RoomLoader.Instances().Tilemaps().Sprites().Load(rmExample, x, y); Transformation
.XScale()
RoomLoader.XScale(xScale)➜ Struct.RoomLoader
Horizontally scales the next Loading or Screenshotting call by setting the XScale State.
| Parameter | Type | Description |
|---|---|---|
xScale | Real | The horizontal scale to use in the next Loading or Screenshotting call |
// Loads rmExample horizontally scaled up by 2
RoomLoader.XScale(2).Load(rmExample, x, y); .YScale()
RoomLoader.YScale(yScale)➜ Struct.RoomLoader
Vertically scales the next Loading or Screenshotting call by setting the YScale State.
| Parameter | Type | Description |
|---|---|---|
yScale | Real | The vertical scale to use in the next Loading or Screenshotting call |
// Loads rmExample vertically scaled up by 2
RoomLoader.YScale(2).Load(rmExample, x, y); .Scale()
RoomLoader.Scale(xScale, [yScale])➜ Struct.RoomLoader
Sets horizontal and vertical scale states to be used in the next Loading or Screenshotting call.
| Parameter | Type | Description |
|---|---|---|
xScale | Real | The horizontal scale to use in the next Loading or Screenshotting call |
[yScale] | Real | The vertical scale to use in the next Loading or Screenshotting call [Default: xScale] |
// Loads rmExample scaled to half-size
RoomLoader.Scale(0.5).Load(rmExample, x, y); .Mirror()
RoomLoader.Mirror([mirror])➜ Struct.RoomLoader
When true, mirrors the next Loading or Screenshotting by setting the XScale State to -1.
| Parameter | Type | Description |
|---|---|---|
[mirror] | Bool | Mirror the next Loading or Screenshotting call? [Default: true] |
// Loads a mirrored tilemap from the "Tilemap" layer in rmExample
RoomLoader.Mirror().LoadTilemap(rmExample, x, y, "Tilemap"); .Flip()
RoomLoader.Flip([flip])➜ Struct.RoomLoader
When true, flips the next Loading or Screenshotting by setting the YScale State to -1.
| Parameter | Type | Description |
|---|---|---|
[flip] | Bool | Flip the next Loading or Screenshotting call? [Default: true] |
// Loads a flipped tilemap from the "Tilemap" layer in rmExample
RoomLoader.Flip().LoadTilemap(rmExample, x, y, "Tilemap"); .Angle()
RoomLoader.Angle(angle)➜ Struct.RoomLoader
Rotates the next Loading by setting the Angle State.
| Parameter | Type | Description |
|---|---|---|
angle | Real | The angle to use in the next Loading call |
// Loads rmExample's instances centered and randomly rotated
RoomLoader.Angle(random(360)).MiddleCenter().LoadInstances(rmExample, x, y); Miscellaneous
.Tileset()
RoomLoader.Tileset(tileset)➜ Struct.RoomLoader
Uses the given tileset in the next RoomLoader.LoadTilemap() call by setting the Tileset State.
| Parameter | Type | Description |
|---|---|---|
tileset | Asset.GMTileset | The tileset to use in the next RoomLoader.LoadTilemap() call |
// When working with perspective visuals, turns a visual walls tilemap into
// a collision tilemap
collisionTilemap = RoomLoader
.Tileset(tsWallsCollision)
.LoadTilemap(rmExample, 0, 0, "Walls", collisionLayer);.Part()
RoomLoader.Part(left, top, width, height)➜ Struct.RoomLoader
Defines a part of the room to capture in Screenshots. Coordinates and dimensions are expressed as percentages of the full room size (from 0 to 1), just like Origin.
This works similarly to part definition in draw_sprite_part(), with the only difference being that the values are normalized 0-1 percentages of the room size instead of raw pixel sizes.
| Parameter | Type | Description |
|---|---|---|
left | Real | The left x position of the room area to Screenshot |
top | Real | The top y position of the room area to Screenshot |
width | Real | The width of the room area to Screenshot |
height | Real | The height of the room area to Screenshot |
// Takes a sprite screenshot of the top-left quadrant of rmExample
screenshot = RoomLoader.Part(0, 0, 0.5, 0.5).ScreenshotSprite(rmExample);
// Takes a centered sprite screenshot of the bottom-right quadrant of rmExample,
// captures only instances and scales the sprite by a factor of 0.5
screenshot = RoomLoader
.Part(0.5, 0.5, 0.5, 0.5)
.Scale(0.5)
.Instances()
.MiddleCenter()
.ScreenshotSprite(rmExample);