|What exactly is an away site?
It's a kind of map template which:
Er, what's a map template?
- is placed in its own zlevel (or collection of zlevels),
- should only get placed once per round,
- can be randomly picked to be placed automatically during round setup,
- normally has an overmap presence and shuttle landmarks so ships can fly to it.
It's a datum you can define in the code (
How do I make away sites?
/datum/map_template) which points at one or more .dmm map files, and allows the game (or admins) to spawn those map files when and where they please, whether that's into an existing zlevel (like decorating exoplanets with ruins), or on a totally fresh one (like an away site!).
tl;dr you make your .dmm files, then you write a new map template datum (
/datum/map_template/ruin/away_site/insert_your_away_site_name_here), then you include whatever file you defined that datum in into
away_sites_testing.dm, and you're all set.
BUT HEED MY RUMINATIONS
While mappingDon't use Torch-specific types
Away maps are expected to work whether you're on Torch, the example map, or anything else you might want to load as the server's main map. That means your map mustn't use areas, turfs, objects, mobs or datums that are specific to any main map.
e.g. you can use
/turf/simulated/wall, because neither are specific to Torch. They live out in the main codebase, are always compiled in, and are available to all maps. But you can't use
/obj/random_multi/single_item/punitelly, because Punitelli only exists when Torch is compiled.
To make life easier, you can uncheck maps/torch/torch.dm (or your regional equivalent), then recompile, to make sure these types aren't available while you're mapping.
Don't re-use area types from other maps
Except for, like,
/area/space. That one's probably fine.
(Now that's just areas! Other stuff might be ok. Except very map-specific stuff as noted!)
Re-using areas is a shortcut, but it's bad for testability, and you can't guarantee that the area you re-use isn't loaded up and in active use on the server - in which case it'll hideously merge together with its brother in terms of stuff like air alarms, APCs, etc. Suddenly your derelict starship is randomly receiving power from another zlevel. Not good. Avoid. Make your own area types!
If in doubt, ask #codershuttle on IRC/#coding on Discord.
If you're doing multi-z, make a different .dmm file for each zlevel
Not exactly a technical requirement, but it makes things easier in terms of collaboration. See how it's done with
Afterwards (or during, I'm not a cop)Make sure you've got a .dm file for all your stuff
Make a map template datum there
maps/away/derelict/derelict.dm. It's a pretty good place to put all your new types! #include other files here too. This file's going to be the hub of your map's wheel, to cack-hand a metaphor.
The game will read this to learn about your new shiny away sites, including what .dmm files it needs to load, how much it 'costs' to spawn (usually 1, increase for more performance-heavy away sites). Ask devs or read code if unsure.
Include your .dm file in any main map file, and away sites testing
Don't include it, or the .dmms, in the .dme
maps/away_sites_testing/away_sites_testing.dm, and probably
maps/torch/torch.dm. It goes in the testing one to make sure it is checked during unit testing, and it goes in the Torch one to make it available while we play Torch. If we have since changed map, yell at someone to update this doc.
That means don't have any of your away map stuff checked in Dream Maker. It'll get included, as if by magic, via the work you did in the previous step!
That's it! You're probably done! Unless the unit tests explode on you.
Some of the stuff I put in my map isn't behaving properly!
The map loader works best when everything it's spawning does all its initialisation work in
Initialize, instead of in
New. Most likely your misbehaving thing is doing more initialisation than is healthy in
New. It's fixable! Often not even that hard. Go talk to a dev.