• 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)

• 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.

• 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);
  

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 +.

• 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

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.

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.

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.

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

Adds all new instance IDs to the specified ds_list.

(note: does not clear the list prior)

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)

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

(note: does not clear the list prior)

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

(note: does not clear the list prior)

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

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

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

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

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.

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_.

Some options:

• GMLive.gml:

  If you are already using GMLive and/or need to call arbitrarily complex code, you can use it's live_execute_string function:

  room_pack_eval_script = live_execute_string;
  

• TXR:

  TXR is an interpreter for general GML-like code, originally as per my guide and then further expanded.

  room_pack_eval_script = txr_exec;
  

  (but don't forget to run txr_init on game start!)

• NSP:

  Historically regarded as the close second as far as GML coverage goes.

  Unfortunately, generally requires your creation code to be at least somewhat correct, else it may crash.

  room_pack_eval_script = NSP_execute_string;
  

• "execute_string" extension by mintypython:
  A more recent candidate, this extension aims to more or less accurately replace the deprecated execute_string function.

  room_pack_eval_script = execute_string;
  

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

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

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.