This is a "cheat sheet" for GMRoomPack extension by YellowAfterlife.
The extension can be acquired from GM:Marketplace or itch.io.
For questions/support, use forums, or send me an email.
An up-to-date version of this document can always be found online.

Click on sections to expand/collapse them.
Quick display controls: Categories · Sections · Everything · Toggle night mode

Setting up and general use

Setting up

- Add the extension to your project.
  For GMS1, right-click on Extensions in resource tree and pick "Import"; pick GMEZ;
  For GMS2, drag-and-drop the YYMP onto the workspace area of GMS2 window with your project open in it.
- Add the included files from the extension (prompted during installation).
  These are not needed at runtime and only serve to convert rooms for use with extension.
  That said, it is completely safe to unflag all platforms in their Properties or even move them to a non-project directory.
  On Mac, install Neko VM and omit importing .exe/.ndll files.
- Add a completely empty object, say, `obj_blank`
  and assign it to room_pack_blank_object,

      room_pack_blank_object = obj_blank

  before you call loading functions (usually, on Game Start)

Packing rooms

- On GMS1, double-click GMRoomPack.exe in Included Files
  On GMS2, right-click GMRoomPack.exe (Windows) or GMRoomPack.n (Mac) and pick "Open externally"
  If on Mac and you've not set Neko VM to open .n files, pick "Show in Finder" instead and run server from directory.
- At this point you are presented with a console window asking what you would like to do.
  If you have at least minor experience with CLI, you can check help for arguments, otherwise you can pick options and have it do the work for you.
  Extra note here - to export to a script/included file, you should add a blank script/file prior to the project for GMRoomPack to modify.

Loading rooms

- If you exported room(s) to JSON, you can load them via room_pack_load_file (for files containing single rooms) or room_pack_load_map (for cached data or a sub-map in a file with multiple rooms).
- If you exported room(s) to scripts, the script will return a new map for the room data upon calling it, which (or a sub-map of which) you can then pass to room_pack_load_map and free up later.

  Loading a single room:

      var json = scr_some(); // generated from rm_some
      room_pack_load_map(json);
      // and when you're done:
      ds_map_destroy(json);

  Loading from a pack of rooms:

      var json_rooms = scr_rts(); // generated from rooms starting with rt_
      // pick a random room name from the map:
      var name = ds_map_find_first(json_rooms);
      repeat (irandom_range(0, ds_map_size(json_rooms) - 1)) {
          name = ds_map_find_next(json_rooms, name);
      }
      // and load that:
      room_pack_load_map(json_rooms[?name]);
      // and when you're done:
      ds_map_destroy(json_rooms);

  Loading a room at callee's XY:

      // ...
      room_pack_load_map(json, x, y);

  Loading only instances and tiles from a room at XY:

      /// ...
      room_pack_load_map(json, x, y, room_pack_flag_instances | room_pack_flag_tiles);

Loading rooms

room_pack_flag

These are used in `room_pack_*` functions to indicate what you'd like loaded.

As they are bit flags, you can combine them via bitwise OR operator `|` or just `+`.

room_pack_flag_settings

Loads settings such as room size and physics setup.
You probably don't want this if loading a room to an offset in another room.

room_pack_flag_views

Applies view settings
You probably also don't want this if loading a sub-room.

room_pack_flag_instances

Loads instances (GMS1) / instance layers (GMS2)

room_pack_flag_backgrounds

Loads backgrounds
In GMS2, this means background layers, which "stack".
In GMS1, this means applying background settings, which will override the existing ones.

room_pack_flag_tiles

Loads tiles (GMS1) / tilemaps (GMS2)

room_pack_flag_sprites

Loads sprites for GMS2 asset layers

room_pack_flag_all

A combination of all above (use if you want to load everything)

Default flags are:

- GMS1: `room_pack_flag_instances | room_pack_flag_tiles`
- GMS2: `room_pack_flag_instances | room_pack_flag_tiles | room_pack_flag_backgrounds | room_pack_flag_sprites`

room_pack_load_file(path, x=0, y=0, ?flags)

Loads a room from the specified file.

Returns whether successful (fails if file doesn't exist or contains non-JSON data).

Creates-destroys a temporary map automatically - no cleanup needed.

Flags indicate what to load.

See configuring loader for additional settings.

See loading rooms for general instructions.

room_pack_load_string(path, x=0, y=0, ?flags)

Loads a room from a string.

Returns whether successful (fails if string contains non-JSON data).

Creates-destroys a temporary map automatically - no cleanup needed.

Flags indicate what to load.

See configuring loader for additional settings.

See loading rooms for general instructions.

room_pack_load_map(map, x=0, y=0, ?flags)

Loads a room from the specified `ds_map`.

Mind that this does not perform JSON validation (for the lack of any built-in functions for doing so) so try to not to pass random garbage instead of room data to it.

The input map remains unchanged and can be reused.

Flags indicate what to load.

See configuring loader for additional settings.

See loading rooms for general instructions.

room_pack_blank_object

Assign a blank object to this variable before calling any of `room_pack_load_` functions (see setting up).

This is used to get around the fact that you cannot set things like rotation/scale/color/custom variables for new instances prior to their Create event firing, so instead a blank instance is made, configured, and then `instance_change`-d to the actual thing (with Create event fired via `event_perform`).

Configuring loader

The following functions allow you to configure what and how will be loaded with the next call.

Affected settings are reset after a load.

room_pack_store_instances(list)

Adds all new instance IDs to the specified `ds_list`.

(note: does not clear the list prior)

room_pack_store_tilemaps(list)

For GMS1, adds new tile IDs to the specified `ds_list`.

For GMS2, adds new tilemap element IDs to the specified `ds_list`.

(note: does not clear the list prior)

room_pack_store_backgrounds(list)

GMS2 only - stores new background element IDs to the specified `ds_list`.

(note: does not clear the list prior)

room_pack_store_sprites(list)

GMS2 only - stores new sprite (asset layer) element IDs to the specified `ds_list`.

(note: does not clear the list prior)

room_pack_exclude_layer(name)

Skips loading the layer with specified name for the next load.

Excluding a parent layer will also exclude it's child layers.

room_pack_include_layer(name)

Once set, only "included" layers will be loaded.

Mind that parent layers also have to be "included".

Supporting variables / creation code

room_pack_const_script

Set this to a script taking constant name as `argument0` and value as `argument1`, and it will be called for each named instance/tile/layer element.

Intended for use if you want to access loaded room's elements by name.

room_pack_eval_script

If set, this will be called for each instance with it's creation code string / custom variable code as `argument0` and context string (for debug/errors) as `argument1`.

For instances, the instance in question will be `self` and the object that called `room_pack_load_` will be `other`.

Room creation code is executed for the object that called `room_pack_load_`.

If you are already using GMLive.gml, you can assign `live_execute_string` to this.

Otherwise, a free option is NSP (`NSP_execute_string`), or you may adapt any other interpreter - so long as it supports just enough GML to handle your use cases.

Technical

Room format

For both GMS1 and GMS2, GMRoomPack converts room data to JSON format resembling a simplified version of GMS2 room format.

This allows the data to be loaded quickly enough by the extension or by custom code (should you ever want to do something other than loading rooms).

Helper program

The helper program takes GMX/YY room files and outputs JSON data for the according version of the extension.

It has a command line interface and an interactive mode.

CLI doc is as following:

    GMRoomPack can be used as following:
    GMRoomPack [...pairs of input/output paths] <optional flags>
      Converts each input path to it's own output file (see below)
      e.g. GMRoomPack rooms/rm_test/rm_test.yy datafiles/rm_test.json
    GMRoomPack [...input paths] --combine [output path] <optional flags>
      Converts and combines all inputs into one output
      e.g. GMRoomPack rooms/rm_one/rm_one.yy rooms/rm_two/rm_two.yy --combine datafiles/rooms.json

    Input paths can be as following:
      rm_some.room.gmx, rm_some.yy: converts a single room
      .../project/rooms: converts and combines all rooms
      .../project/rooms/pfx_*: converts and combines all rooms that start with 'pfx_'

    Output paths can be as following:
      .../some.json: converts to JSON format
      .../some.gml: converts to a GML script that creates & returns a ds_map with JSON
      Any other extension is assumed to be JSON for now
    If multiple rooms are combined into one output file, the top-level structure will have room names as keys and room data as values.

    Supported flags:
      --watch: Keeps running and re-converts files on changes
      --prettyprint: Splits JSON into multiple lines to maintain readability

Limitations

GMS1 compatibility tile layers in GMS2

For the fact that these only appear in imported GMS1 projects and their associated functions are pretty slow, these are currently not supported. While this may change in the future, there's very little reason to use them in production code.