Maps

Maps are where the player and monsters roam. They contain objects, and some pre-computed information for each map square.

When making maps, please follow the Mapping Guide.

• Technical Information About Maps

All objects without the FLAG_REMOVED set are ultimately on a map, either directly or because their top-level container is on a map. The only exception are objects for archetypes and artifacts, which aren't anywhere.

Maps reset after some time, reverting to their default state. It is possible that the map is temporarily saved to disk to reclaim memory, in which case it will be reloaded when a player tried to enter it.

Type	Purpose	Exit	File Location
Regular		Path to map	$DATADIR/maps
Temporary	Maps that have not been recently visited are swapped out to a temporary file to save memory	Not used	$TMPDIR
Unique	Each player has their own instance of the map and all objects there are saved	Path to map, FLAG_UNIQUE must be set on the exit	Partmedia's version of /scorn/apartment/apartments is stored in $LOCALDIR/players/Partmedia/_scorn_apartment_apartments
Overlay	Store unique items from non-unique maps, loaded after the map as an "overlay"	Not used	Unique items in /scorn/shops/market are stored in $LOCALDIR/unique-items/scorn@shops@market.v00
Random	Procedurally-generated random maps	/!, generator arguments in exit object::msg	Generated by code in server/random_maps
Style	Used by the random map generator	Not used	$DATADIR/maps/styles

Map creation, load, save and reset

When a map resets, all objects on it are lost except when:

• the object has FLAG_UNIQUE set. It is then persisted to an overlay
• the FLOOR the object is on has the FLAG_UNIQUE set. Note that objects below the FLOOR will be lost. Persisted on an overlay
• the map has the mapstruct::unique flag set. The whole map is saved.

The usual function to call to obtain a valid mapstruct structure is ready_map_name(). It is responsible for loading a map from disk, adding unique items and overlays, reloading a map if it was swapped out. The flag parameter controls what should or not be done.

Other ways to get a map are:

• call get_linked_map(). This does not initialize the map's mapstruct::spaces field, though
• call get_empty_map(), which initializes this field.

In any case the map is linked to the map list.

Random maps use get_empty_map() to create the map, and plugins can access both functions if needed.

Maps are reset when they have been loaded more than map::reset_timeout seconds for fixed reset, or when the last player left it more than mapstruct::reset_timeout seconds.

The saving mechanism, as implemented by save_map(), uses two files to store the map: one for regular items, one for unique items. For unique maps or when swapping a map, the two files are equals to save everything in the same place.

Unless the flag parameter is 2, the objects on the map will be removed.

When a map is to be deleted totally, delete_map() should be called to clean the structure and associated fields, and remove the map from the linked list.

Main map-related functions:

• check_active_maps() is responsible for swapping out maps
• ready_map_name() is the main map loading function
• delete_map() totally frees a map structure
• free_map() removes the objects from a map, and clears the mapstruct::spaces field, but doesn't delete the map structure itself. Map is considered swapped.
• flush_old_maps() resets maps
• load_original_map(), load_temporary_map(), load_overlay_map() and load_unique_objects() load the various map types
• enter_exit() is the main function used when a player moves between maps. It uses the following subfunctions: enter_unique_map(), enter_random_template_map(), enter_fixed_template_map() and enter_random_map() depending on the exit parameters

Style maps

Random maps use style maps to gather random objects, and to insert random submaps into generated maps. These style maps are loaded through ready_map_name() with the MAP_STYLE flag so that the active objects are not put on the active object list, then removed from the linked map list and put on the random map style list (first item is styles). Thus those special maps are not really part of the active maps.

Todo:

• link plugin API, random map documentation, directory information
• check save_map() flags and meaning