Dynamic Map Features

MetSys provides 2 ways of altering the map data at runtime. You can modify existing cells or add new ones.

Cell overrides

Cell overrides allow for runtime modifications of the map. You can change any room's property, i.e. color, borders or default symbol and even the assigned scene. Typical use-cases are opening passages after breaking walls, marking hazardous rooms based on current upgrades or changing a room to a "destroyed" version (e.g. when SA-X visits it).

To override a cell you can call MetSys.get_cell_override(). The method takes Vector3i coords of the cell. If an override already exists, it will return existing one. If it doesn't, it will be automatically created (unless you use false as the second argument). The method returns an object of type CellOverride that can be used to customize the cell. The customization is done using a set of methods. Note that the value argument in each method is optional; using default value makes the override reset it to the default.

• set_border(idx, value): Sets the border type. 0 is passage, 1 is wall, 2+ are custom styles defined in theme. You can also use -1 for no border, but it's not recommended. idx is the direction of the border. Use MetSys.R/D/L/U enum constants to select border direction.
• set_border_color(idx, value): Sets the border color.
• set_color(value): Sets the cell's center color.
• set_symbol(value): Sets the cell's symbol. Note that this is separate from custom markers.
• set_assigned_scene(value): Sets the cell's assigned scene. The scene should be full path (with extension) to the scene, without the root folder prefix. E.g. if your map_root_folder is res://Maps and your map is in res://Maps/DarkWorld/Desert1.tscn, you should assign DarkWorld/Desert1.tscn. You can also assign an absolute path to the scene, even from user://, but then you'll need to add special handling in your code. Note that unlike other functions, assigning scene has effect on all cells in a room, to keep consistency.

Override can be deleted with MetSys.remove_cell_override(), which takes override's coords. The override does not need to exist, so the method is safe to call (unless the cell itself does not exist). Modifying and removing overrides will emit MetSys.map_updated signal.

Map Builder

Map Builder is a tool to create custom rooms at runtime. It's intended for procedurally generated maps. You can obtain a MapBuilder object using MetSys.get_map_builder(). The Map Builder is a very simple class. It has 2 methods: create_cell() and update_map(). create_cell() takes coordinates of the new cell and will return CellOverride object, the same as when overriding rooms. You can customize the cell by customizing the received override object. update_map() will cause MetSys to emit the map_updated signal (overrides from custom cells don't do it automatically). Call it when you have finished generating the desired layout.

The overrides from map builder allow calling destroy(), which will remove the custom cell completely. You can obtain references to custom cells you have created by accessing cells property of the Map Builder. Note that, since custom cells are overrides themselves, using MetSys.get_cell_override() on a custom cell will not create a new override.

When using Map Builder with MetSys save system, remember to store the coordinates of your created cells. The save system will only save the overrides, but it doesn't keep the information whether they override existing cell or not.