Files
Bubberstation/code/modules/mapping
LemonInTheDark 5b4ba051a0 Builds logic that manages turfs contained inside an area (#70966)
## About The Pull Request

Area contents isn't a real list, instead it involves filtering
everything in world
This is slow, and something we should have better support for.

So instead, lets manage a list of turfs inside our area. This is simple,
since we already move turfs by area contents anyway

This should speed up the uses I've found, and opens us up to using this
pattern more often, which should make dev work easier.

By nature this is a tad fragile, so I've added a unit test to double
check my work

Rather then instantly removing turfs from the contained_turfs list, we
enter them into a list of turfs to pull out, later.
Then we just use a getter for contained_turfs rather then a var read

This means we don't need to generate a lot of usage off removing turf by
turf from space, and can instead do it only when we need to

I've added a subsystem to manage this process as well, to ensure we
don't get any out of memory errors. It goes entry by entry, ensuring we
get no overtime.
This allows me to keep things like space clean, while keeping high
amounts of usage on a sepearate subsystem when convienient

As a part of this goal of keeping space's churn as low as possible, I've
setup code to ensure we do not add turfs to areas during a z level
increment adjacent mapload. this saves a LOT of time, but is a tad
messy

I've expanded where we use contained_turfs, including into some cases
that filter for objects in areas. need to see if this is sane or not.

Builds sortedAreas on demand, caching until we mark the cache as
violated

It's faster, and it also has the same behavior

I'm not posting speed changes cause frankly they're gonna be a bit
scattered and I'm scared to.
@Mothblocks if you'd like I can look into it. I think it'll pay for
itself just off `reg_in_areas_in_z` (I looked into it. it's really hard
to tell, sometimes it's a bit slower (0.7), sometimes it's 2 seconds
(0.5 if you use the old master figure) faster. life is pain.)

## Why It's Good For The Game

Less stupid, more flexible, more speed

Co-authored-by: san7890 <the@san7890.com>
2022-11-04 20:13:54 -07:00
..

The code in this module originally evolved from dmm_suite and has since been
specialized for SS13 and otherwise tweaked to fit /tg/station's needs.

dmm_suite version 1.0
	Released January 30th, 2011.

NOTE: Map saving functionality removed

defines the object /dmm_suite
	- Provides the proc load_map()
		- Loads the specified map file onto the specified z-level.
	- provides the proc write_map()
		- Returns a text string of the map in dmm format
			ready for output to a file.
	- provides the proc save_map()
		- Returns a .dmm file if map is saved
		- Returns FALSE if map fails to save

The dmm_suite provides saving and loading of map files in BYOND's native DMM map
format. It approximates the map saving and loading processes of the Dream Maker
and Dream Seeker programs so as to allow editing, saving, and loading of maps at
runtime.

------------------------

To save a map at runtime, create an instance of /dmm_suite, and then call
write_map(), which accepts three arguments:
	- A turf representing one corner of a three dimensional grid (Required).
	- Another turf representing the other corner of the same grid (Required).
	- Any, or a combination, of several bit flags (Optional, see documentation).

The order in which the turfs are supplied does not matter, the /dmm_writer will
determine the grid containing both, in much the same way as DM's block() function.
write_map() will then return a string representing the saved map in dmm format;
this string can then be saved to a file, or used for any other purose.

------------------------

To load a map at runtime, create an instance of /dmm_suite, and then call load_map(),
which accepts two arguments:
	- A .dmm file to load (Required).
	- A number representing the z-level on which to start loading the map (Optional).

The /dmm_suite will load the map file starting on the specified z-level. If no
z-level	was specified, world.maxz will be increased so as to fit the map. Note
that if you wish to load a map onto a z-level that already has objects on it,
you will have to handle the removal of those objects. Otherwise the new map will
simply load the new objects on top of the old ones.

Also note that all type paths specified in the .dmm file must exist in the world's
code, and that the /dmm_reader trusts that files to be loaded are in fact valid
.dmm files. Errors in the .dmm format will cause runtime errors.