General Information

Unlike in the editor, at runtime all interactions with MetSys are through code. The main code component is MetSys autoload singleton automatically added with the plugin. All interactions with the system go through the singleton, that includes methods and signals.

Note

Some of the features described in runtime guide are covered by system template, i.e. the template provides a reusable implementation that integrates the MetSys internals. When a feature has equivalent in the template, it will be noted in its section.

You can also check the included Sample Project for example implementation.

Code Documentation

Runtime MetSys code is fully documented using the GDScript documentation system. Anything that doesn't have description is not intended to be called/accessed by the user (but of course it's possible if you want to do some advanced hacks).

List of classes/scripts with documentation for this guide:

• MetroidvaniaSystem
• MapTheme
• "addons/MetroidvaniaSystem/Scripts/Settings.gd"
• "addons/MetroidvaniaSystem/Scripts/RoomInstance.gd"
• "addons/MetroidvaniaSystem/Scripts/MapData.gd".CellOverride
• "addons/MetroidvaniaSystem/Scripts/MapBuilder.gd"
• "addons/MetroidvaniaSystem/Scripts/CustomElementManager.gd"

To read them press F1 and search for the relevant script. If a script does not appear in help search, it might be an engine cache issue. You can fix it by going to the script and re-saving it.

Saving and Loading MetSys Runtime Data

Note

This feature is covered by Save Manager component of the project template.

MetSys comes with a simple save system that allows you to serialize its runtime data. Stored things include:

• discovered cells
• registered storable objects
• stored objects
• custom markers
• cell override data

This means that you don't need to worry about keeping the data of runtime MetSys operations, the system does it for you. To obtain the data, use MetSys.get_save_data(). It returns a Dictionary with the aforementioned contents. You need to save it yourself, e.g. using store_var(), var_to_str() or by adding it to your own save system. Note that using JSON is not recommended, because the data contains Godot's native types and integers.

To restore the data use MetSys.set_save_data(), passing the saved Dictionary. It will restore all discovered cells, stored objects etc. If you pass empty Dictionary (default), the data will be cleared.

When starting a new game session you should always call MetSys.reset_state() and MetSys.set_save_data(). The former will reset the singleton to make sure the player position and other variables are properly cleared. The latter will initialize the save data; you should always call it if you want to use save data, as otherwise the data is null.

Room Instance (runtime)

The currently active RoomInstance node can be accessed at runtime using MetSys.get_current_room_instance(). It grants access to a few useful methods:

• adjust_camera_limits(camera: Camera2D): Adjusts limit properties of the given camera to be within the room's boundaries.
• get_size() -> Vector2: Returns the size size of the room's bounding rectangle, in pixels.
• get_local_cells() -> Array[Vector2i]: Returns the cells occupied by the room, in local coordinates, i.e. (0, 0) is the top-left coordinate. This is useful to determine shape of irregular (not-rectangle) rooms to draw stuff outside the map etc.
• get_room_position_offset(other: RoomInstance) -> Vector2: Returns the position difference of 2 RoomInstance nodes, in pixels. When changing scenes, you can use this method to teleport player to the entrance of the new room by subtracting offset between new room and old room.
• get_neighbor_rooms() -> Array[String]: Returns names of the rooms from cells adjacent to the current room and connected via passages. This method can be used to preload these rooms (likely in a thread) for smoother transitions.

Note that since RoomInstance is basically a singleton within MetSys, only one can be active inside the scene tree. When RoomInstance enters tree, it will assign itself to MetSys and automatically remove itself when left. If you happen to have multiple room instances (which should be avoided), the newest one will have priority.