Manage

Unlike the other 2 tabs, Manage has no map view. Instead it's a simple list of options.

General Settings

Selecting "General Settings" option will open the MetSys settings file in the inspector. By default the file is located in res://MetSysSettings.tres, but you can move it by modifying addons/metroidvania_system/settings_file project setting.

General Settings are a configuration file for MetSys plugin in your project.

• Theme: The map theme of your project. It determines how map cells are drawn. See Map Theme section for more details.
• Map Root Folder: The location of your world's scenes (see scene assign). All scenes you want to assign to your rooms need to be inside this directory or its subdirectories. MapData.txt, which stores the map information, is also located in this folder.
• Map Extents: Size of the map drawn in the editor, in both directions (e.g. extents of 100 is a 200x200 map). Cells beyond this value will not be drawn. Adjust this to your needs, but keep in mind that big values will cause editor slowdowns or instability. This is planned to be improved in the future.
• Scene Template: Scene created when using Create New Scene button in Scene Assign Mode. If empty, a default scene with Room Instance node will be created. You can use it to customize new map scenes for your project needs.
• In Game Cell Size: The size of one cell of a room as it appears in game (not on map). It affects how exact player position is displayed on map and also affects camera bounds (if adjusted).
• Discover Whole Rooms: If enabled, when entering a new room, all its cells will be discovered. It's a feature of some metroidvania games, and it's used by default in Modern Map extension. In the future this might be moved to Map Theme.
• Cache Group Reverse Lookup: Enables caching of overlapping groups for each cell. The cache is kept in auxiliary Dictionary, and can take quite a bit of memory if you have many cells with groups, but it makes group lookup much faster. You can disable it if you don't plan to use get_cell_groups().
• Custom Element Script: script defining available custom elements. See Custom Element Script section for more details.

Validation

There are two kinds of validation: map data validation and map theme validation. Validation checks if the validated data is correct, to prevent errors and crashes. If it results in errors, you need to fix them, otherwise your map/theme won't work correctly. Warnings can be ignored.

Map data validation checks the integrity of your world. It most importantly checks for invalid data (symbols and borders) that would make your project work incorrectly, but also gives some potential warnings.

The checks are as follows (italic are warnings):

• Invalid symbol: Cell's symbol index does not exist on the symbol list. It will result in an error when drawing.
• Invalid border: Cell's border style does not exist on the border list. It will result in an error when drawing.
• No assigned map: Room has no assigned map. Has no adverse effects, other than not emitting a signal when entering the room area.
• Passage to nowhere: Room has a passage border with no adjacent room. Since all custom border styles are considered passage, this is prone to false-positives.
• Potentially unused symbol: A symbol is not placed anywhere nor used as default for collectibles. This does not detect symbols assigned from code.

Theme data validation ensures that the map theme you are using is correctly defined. This part is much more prone to errors that will break your map display, so it's important to fix all found errors. Other than validation, this option will also display some inferred info about the theme, i.e. cell size and shape (square/rectangle).

The checks are as follows (italic are warnings):

• Missing center texture: The theme has no center texture assigned. It's the most important piece, so the validation stops if this error is found.
• Size mismatch between empty texture and center texture: Empty texture and center texture must match in size, otherwise they wouldn't display correctly. Only checked if empty texture is defined.
• Number of horizontal and vertical borders do not match: In a rectangle shape theme you need to provide separate borders for horizontal and vertical edges. All vertical borders need a horizontal equivalent.
• Border has invalid height: All border sprites must be oriented vertically, including horizontal borders. It makes the rotation code simpler.
• Border is empty: Border array has a null value inside or an invalid texture.
• Player location scene is not a Node2D: The player location needs to be Node2D to be displayed on map. Only checked if player location scene is defined.
• (Un)collected item symbol index is greater than number of available symbols: The default collectible symbols need to be within the defined symbols range (i.e. less than number of symbols, because it starts from 0).
• Symbol is bigger than center texture: Not critical, but it makes the symbol stick outside the cell.
• Texture is wider than half of the center texture: This applies to borders. They should be thin horizontally, otherwise they won't display properly.
• Missing player location scene: If player location scene is missing, the system for drawing player location on map can't be used.

Database Theme

The theme used for MetSys database. This defines colors used in various areas. You can modify them if they happen to be unreadable when used with your map theme.

Here are the colors available for customization:

• Active Custom Element: In Custom Elements editor mode, this color is used for elements on the map that match the currently selected element type on the sidebar.
• Assigned Scene: Room highlight in Scene Assign editor mode when a scene was assigned.
• Border Highlight: Border hover highlight in border editing modes.
• Current Scene Room: Highlight color for the Map Viewer room matched with the currently opened editor scene.
• Cursor Color: Color of the editor cell cursor (square/rectangle).
• Cursor Color Erase: Same as above, but used when erasing cells in Room Layout editor mode.
• Custom Element Marker: Color of the marker denoting origin point of an element in Custom Elements editor mode.
• Foreign Marked Collectible Room: Highlight color for the cell when hovering over a collectible in Collectible Finder list, when the collectible is on a different layer than currently selected.
• Group Color: Highlight color for cells in Cell Group editor mode when group is assigned.
• Highlighted Room: Highlight color for the hovered room in Scene Assign editor mode and other modes that support full room operations.
• Hovered Room Preview Name: Color of room name label when hovering RoomInstance preview.
• Hovered Room Preview Outline: Color of the outline when hovering RoomInstance preview.
• Inactive Custom Element: Opposite of the active element, i.e. elements with different type than selected.
• Invalid Room Drop Position: Highlight color for invalid cells when moving a room via drag and drop.
• Marked Collectible Room: Same as marked collectible above, but used for the same layer.
• Room Assigned: Font color when hovering a room with scene assigned in Map Viewer.
• Room Not Assigned: Same as above, but room has no scene.
• Scene Cell Border: Used for marking room edges when a scene with room assigned is opened in the 2D editor.
• Scene Room Exit: Same as above, but for passages.

Using the Reset Database Theme button you can restore the original colors. Note that this action is irreversible.

Custom Element Script

Custom Element script is responsible for registering and drawing custom map elements, like elevators, area labels, etc. It must be a @tool script that extends MetroidvaniaSystem.CustomElementManager. The elements are registered in the constructor (_init()) using register_element(element_name: String, callback: Callable) (e.g. register_element("label", draw_label)). Once you define the list of elements and add the script in General Settings (make sure to use the "Refresh Custom Elements" option after adding script or elements), you can place the elements in Custom Elements mode in the map editor.

When using Minimap or MapView, the custom elements will be drawn automatically by using their specified callbacks. The callback is as follows: func function_name(canvas_item: CanvasItem, coords: Vector3i, pos: Vector2, size: Vector2, data: String).

• function_name: You need to provide this name to the register_callback().
• canvas_item: The RID of CanvasItem that will draw the element; provide it to the draw methods.
• coords: Cell coordinates on the world map.
• pos: Position of the top-left corner of the element, in pixels.
• size: Size of the element's rectangle, in pixels.
• data: The data string provided when creating the element.

Using these arguments, you need to draw your element using custom drawing methods from RenderingServer. For example:

var texture := preload("res://icon.svg")
RenderingServer.canvas_item_add_texture_rect(canvas_item, Rect2(pos, texture.get_rid()), texture.get_rid(), false)

Some classes, like Texture2D or Font, provide their own draw methods that will call RenderingServer methods under the hood, thus this code can be simplified to:

var texture := preload("res://icon.svg")
texture.draw_rect(canvas_item, Rect2(pos, texture.get_rid()), false)

Note that all elements that overlap the visible area are drawn regardless if they are discovered or not. You need to manually check if the cell occupied by element (or any related cell you want to consider) was discovered, using MetSys.is_cell_discovered(coords).

Other options

Two remaining options in the Manage tab are:

• "Reload and Cleanup Map Data": As the name says, this will force reloading map data from file and also cleanup invalid data like scenes assigned to non-existent cells etc. This option is useful when working with VCS and sharing map data, as the editor won't reload it automatically. Note that invalid data can be created only as a result of a bug or manual tampering with the map data file.
• "Export Map as JSON": Exports the contents of MapData.txt as JSON, in case you want to use it in external tools or just not rely on custom format. MetSys itself does not support JSON.