Basic Map Features
In-game map is an important feature of most metroidvania games. MetSys comes with various methods for drawing and manipulating the map.
Note
This feature is covered by Minimap component of the project template.
Usually the in-game map is drawn in forms of minimap and a full map on a separate screen. MetSys provides a special class that manages drawing a portion of the map. It's optimized using RenderingServer methods. The aformementioned Minimap is higher level and easier to use; usually it should be sufficient.
MetSys.make_map_view() creates an instance of MapView class, which does the drawing. The method takes few arguments:
-
parent_item: The CanvasItem node that will be parent of the map. -
begin: Top-left corner of the displayed map area. -
size: Size of the displayed map area. -
layer: Layer that the map will show initially.
begin, layer and size can be changed afterwards, these are only initial values necessary to display something.
MapView is a RefCounted object, so it will be gone if you lose all references. It does not update by itself, you have to update it using the provided update_ and move_ methods. The former (update_cell(), update_rect() and update_all()) will redraw the specified cells, in case the map has changed (by discovering or adding overrides etc.), while the latter (move() and move_to()) will change coordinates of the displayed cells. The easiest way to use it is connecting MetSys.map_updated to update_all() and MetSys.cell_changed to move_to().
To move the drawn map, you need to move the parent canvas item, as there is no built-in offset. The MapView has visible property though, which can be useful for managing multiple layers. Note that MapView may use higher z-indexes for drawing some elements. If you want to add custom overlay over the map, it needs to have z-index of 4 or more (relative to base CanvasItem), to make sure it's on top.
If you used older versions of MetSys, you might remember draw_cell() method. It's gone. The new MapView object automatically takes care of drawing shared borders and custom elements and is much faster, at a cost of a bit of flexibility (you can't easily draw cells arbitrarily anywhere, but it's not useful anyway).
Note
This feature is covered by MetSys Game component of the project template.
Tracking player position allows for automatically discovering cells and changing scenes when player goes out of bounds. Tracking position is performed by using MetSys.set_player_position(). The method takes a position relative to the current scene's origin (i.e. top-left corner of the room). Unless your map's root node is offsetted, you can just use player's global_position. The method has to be called each frame, after the player has done moving. Example:
... some input
move_and_slide()
MetSys.set_player_position(global_position)MetSys will automatically detect if the current map cell is different and emit cell_changed signal, which you can use to update your minimap. When the position is in a different room, MetSys will emit room_changed signal that also contains the name of the new scene that you should load. The scene name is not a full path; you can get the full path by using MetSys.get_full_room_path() on its name.
You can display player's location on your map by using MetSys.add_player_location(). This method should be called once per map CanvasItem. It will add your player location scene defined in the map theme as child of that node and automatically move it when visible, based on your supplied player position. The method also optionally takes an offset, in case your map CanvasItem has some margins.
A cell may have assigned any number of markers, out of the markers defined in map theme (each marker can be assigned only once). Markers assigned at runtime will override the symbol assigned in the Map Editor. They are stored as a bitmask, which means you can define and assign only up to 63 markers. If multiple markers are assigned, the one being the furthest on the theme list will be used. Gameplay-wise, markers are usually assigned based on events, manually by players on map screen, or automatically via storable objects. Assign a marker using MetSys.add_custom_marker(), remove it using MetSys.remove_custom_marker().
Cells on the map can be in 3 states: undiscovered, mapped and explored. Undiscovered rooms don't draw at all, explored rooms draw with the default style. Mapped rooms draw with an alternate style and rules that can be specified in the map theme. You can manually discover cells using MetSys.discover_cell() or you can discover a group of cells (e.g. when picking up a map item) by using MetSys.discover_cell_group(). Cell groups can be defined in the editor. Discovering a cell emits MetSys.map_updated signal.
You can use is_cell_discovered() to check if a cell is discovered and get_explored_ratio() to get ratio of explored cells vs all cells.
