(Cleaned up old comments, new escape pod dock subtypes, more JSON research.)
(не показаны 24 промежуточные версии 2 участников)
Строка 1:
Строка 1:
{{Under construction
{{Under construction
|reason = This is a sandbox to make incremental edits to incorporate [[User:San7890|san7890's]] improved guide to mapping. Absolutely everything is subject to change, and I encourage you to overwrite literally anything.
|reason = This is a sandbox to make incremental edits to incorporate [[User:San7890|san7890's]] improved guide to mapping. Absolutely everything is subject to change, and I encourage you to overwrite literally anything. Editors note: standardize linking all headers to the respective HackMD headers so that readers absolutely can not miss it.
}}
}}
Other related guides: [[Understanding SS13 code]], [[SS13 for experienced programmers]], [[Guide to door access]] and [[Map Merger]]
Other related guides: [[Understanding SS13 code]], [[SS13 for experienced programmers]], [[Guide to door access]] and [[Map Merger]]
= '''<big>SMITHERS I DON'T KNOW HOW MEDIAWIKI WORKS SO HOPEFULLY YOU SEE THIS - I STRUCK THROUGH STUFF THAT I REWROTE AND ALL THE INFORMATION SHOULD BE IN COMMENTS AT THE HEADER OF THE DENOTED SECTION THANKS</big>''' =
{{Important
{{Important
|Title=Read this!
|Title=Read this!
|Note=Lots of information was taken from <big>'''[https://hackmd.io/@tgstation/SyVma0dS5 san7890's A-Z Guide to Mapping]'''</big>, a hackmd document that details mapping essentials. It is recommended that you read that document as it is well organized, updated, and contains very useful visuals that this page may lack.
|Note=This page is mostly port of <big>'''[https://hackmd.io/@tgstation/SyVma0dS5 san7890's A-Z Guide to Mapping]'''</big>, a HackMD document that details the mapping essentials. It is recommended that you read that document '''first''' as it is well organized, updated, and contains very useful visuals that this page may lack. If you are an experienced mapper, <big>'''[https://hackmd.io/@tgstation/ry4-gbKH5 san7890's Mapping Reference Collection]'''</big> may be more useful to you.
|Image=Notice.png
|Image=Notice.png
|Color=Blue
|Color=Blue
}}
}}
{{Speech|image=[[File:Bigchungus.png|64px|right]]|name=Big Chungus|text=Nyehehehehe I'm Big Chungus (big chungus voice). I just went through some stuff and left some comments. If you want something nice to write about the Guide to Mapping (and the Mapping Reference Collection) in those above chat bubbles, I like Goonstation ZeWaka's Prompt (inspired probably by san7890's own words), which can be found here: https://hackmd.io/@goonstation/maps#Goonstation-Mapping-Guide .}}
== <big>KS</big> ==
=[https://hackmd.io/@tgstation/SyVma0dS5#Ingredients Getting Set Up]=
=Getting Set Up=
Setting up before doing anything is crucial to having a smooth and painless mapping experience.
Setting up before doing anything is crucial to having a smooth and painless mapping experience.
== '''<big>(NEW)</big>''' Mapper's Checklist ==
== Mapper's Checklist ==
{{Speech
|name=SpaceSmithers
|text=TODO: hyperlink all of these with their corresponding external links.</code>
It is ''imperative'' that you use the [[Map Merger]] tools before committing any changes to a map. See [[Map_Merger|here]] for how. Some modern programs do similar functions to what Map Merger does, but running this and getting your Git Hooks set up save you a lot of headache.
It is ''imperative'' that you use the [[Map Merger]] tools before committing any changes to a map. See [[Map_Merger|here]] for how. Some modern programs do similar functions to what Map Merger does, but running this and getting your Git Hooks set up save you a lot of headache.
==Forking the Repository==
==[https://hackmd.io/@tgstation/SyVma0dS5#Gitting-Set-Up Forking the Repository]==
Firstly, you need a fork. A fork will be your very own copy of our repository, free do with as you
Firstly, you need a fork. A fork will be your very own copy of our repository, free do with as you wish! Just hit the "Fork" button on https://github.com/tgstation/tgstation. Feel free to be creative with the name of your fork. {{Tooltip2|[https://tgstation13.org/wiki/images/7/7f/Mappingguide_branch.png Displayed should be "(GitHub username)/(name of fork), forked from tgstation/tgstation",]|It should look something like this: [[file:Mappingguide_branch.png]]}}.
wish! Just hit the "Fork" button on https://github.com/tgstation/tgstation. Feel free to be creative with the name of your fork. <br>
<span style="background-color:yellow">Displayed should be [GitHub username]/[name of fork], forked from tgstation/tgstation</span>
Within your fork, you'll want to click {{Tooltip2|[https://tgstation13.org/wiki/images/d/d6/Mappingguide_opengitdesktop.png the "Code" button, then click "Open with GitHub Desktop"]|[[File:Mappingguide_opengitdesktop.png]]}} (assuming you've downloaded it) under the dropdown. A prompt from the application will open; find a clean folder to locally copy your repository and click Clone. This may take a few minutes. Another prompt will appear asking: "How are you planning to use this fork?" You will want to select "To contribute to the parent project". This will make creating [[#Pull Requests|Pull Requests]] easier.
{{Speech
===[https://hackmd.io/@tgstation/SyVma0dS5#GitHub-Desktop-or-associated-client Branching the Fork]===
|name=SpaceSmithers
[[File:Gitdesktop1.png|right|thumb|GitHub Desktop should look something like this]]
|text=An image embed would be good here. <code><nowiki>[[File:bruhstation.png|thumb|flavor text]]</nowiki></code>
|image=[[File:Spell.png|64px|right]]
}}
Within your fork you'll see a green button labelled "code" <span style="display: inline; border: 2px double; background-color:lime; padding:4px;">Code▼</span>. In the dropdown menu, click Open with GitHub Desktop (assuming you've downloaded it). A prompt from the application will open; find a clean folder to locally copy your repository and click Clone. This may take a few minutes. Another prompt will appear asking: "How are you planning to use this fork?" You will want to select "To contribute to the parent project". This will make creating [[#Pull Requests|Pull Requests]] easier.
===Branching the Fork===
The final part to setting up GitHub is to make a new branch. '''This part is super-duper important''', because you want to keep your “master” branch on your fork as clean as possible, since it’s a pain to clean out and send pull requests to.<br>
The final part to setting up GitHub is to make a new branch. '''This part is super-duper important''', because you want to keep your “master” branch on your fork as clean as possible, since it’s a pain to clean out and send pull requests to.<br>
To do this, click on the Current branch (which defaults to "master") and click on the "New branch" button next to the filter bar. For every individual project you work on and submit a Pull Request for, you want to be on a brand new branch. Feel free to name it whatever you want, can be as goofy or as organizational as you want. It’s your fork, after all.<br>
To do this, {{Tooltip2|[https://tgstation13.org/wiki/images/5/5b/Mappingguide_newbranch.png click on the Current branch (which defaults to "master") and click on the "New branch" button next to the filter bar]|[[File:Mappingguide_newbranch.png]]}}. For every individual project you work on and submit a Pull Request for, you want to be on a brand new branch. Feel free to name it whatever you want, can be as goofy or as organizational as you want. It’s your fork, after all.<br>
:You may also get a screen that says “base it off the current branch” or “base it off the upstream/master”. That depends on what you want, but if you want to start fresh on a new project, always hit “base it off the upstream/master”.
:You may also get a screen that says “base it off the current branch” or “base it off the upstream/master”. That depends on what you want, but if you want to start fresh on a new project, always hit “base it off the upstream/master”.
{{Speech
=Mapping: [https://hackmd.io/@tgstation/SyVma0dS5#StrongDMM-and-You-The-Basics San7890's Guide to StrongDMM]=
|name=SpaceSmithers
|text=The last introductory GitHub image would be good here. <code><nowiki>[[File:git_guide_branch.png|thumb|This is what GitHub Desktop should look like]]</nowiki></code>
|image=[[File:Spell.png|64px|right]]
}}
=Mapping=
==San7890's Guide to StrongDMM==
===Preamble===
===Preamble===
In the time of Metacide, the creator of MetaStation and the last person to make a "guide to mapping", all that you had was Dream Maker's program. Dream Maker sucks though, and we have better tools. While all of the content you see on the rest of this page and elsewhere may be lifted straight from DreamMaker, this will serve as a small "pointer" to where you can find that same functionality in StrongDMM. Everything you can do in Dream Maker, you can do about 100 times better in StrongDMM. If you've managed to grasp the bare essentials of even playing Space Station 13, then I have no doubt that getting acclimated to StrongDMM will probably be a walk-in-the-park. However, BYOND hasn't changed in how it parses maps, so that will all hold steadfast and true.
In the time of Metacide, the creator of MetaStation and the last person to make a [https://tgstation13.org/wiki/index.php?title=Guide_to_mapping&oldid=37972 "Guide to Mapping"], all that you had was Dream Maker's program. Dream Maker sucks though, and we have better tools. While all of the content you see on the rest of this page and elsewhere may be lifted straight from DreamMaker, this will serve as a small "pointer" to where you can find that same functionality in StrongDMM. Everything you can do in Dream Maker, you can do about 100 times better in StrongDMM. If you've managed to grasp the bare essentials of even playing Space Station 13, then I have no doubt that getting acclimated to StrongDMM will probably be a walk-in-the-park. However, BYOND hasn't changed in how it parses maps, so that will all hold steadfast and true.
At the time of me writing this guide, it is currently in an “alpha state” (Versions 2.0.0 and up). I will be using the alpha version since it’s the path the program is going to take in the future, but if you’re hesitant about an alpha version, feel free to downgrade to Version 1.9.1 (it has a few features 2.0.0 is missing). You can actually run both concurrently, too! Irregardless, let’s start mapping!
At the time of me writing this guide, StrongDMM is currently in an “alpha state” (Versions 2.0.0 and up). I will be using the alpha version since it’s the path the program is going to take in the future, but if you’re hesitant about an alpha version, feel free to downgrade to Version 1.9.1 (it has a few features 2.0.0 is missing). You can actually run both concurrently, too! Regardless, let’s start mapping!
===Mapping===
===Starting StrongDMM===
Go into "File" in the top-right of your screen and hit “Open Environment”. The “environment” is how StrongDMM is able to find, collect, and parse the atoms that make up every part of every map. This is an important step, and make sure you always use the .DME (Dream Maker Environment) file on your repository, to keep things as straightforward as possible. Just get tgstation.dme.
Go into "File" in the top-right of your screen and hit “Open Environment”. The “environment” is how StrongDMM is able to find, collect, and parse the atoms that make up every part of every map. This is an important step, and make sure you always use the .DME (Dream Maker Environment) file on your repository to keep things as straightforward as possible. Just get tgstation.dme.
{|
{|
Строка 69:
Строка 51:
|Then, go back into "File" and hit "Open Map". You'll want to go into the ``_maps`` directory of your repository, and then find any map you like. I'll be using MetaStation.dmm for the purposes of this guide. Once StrongDMM loads the map of your choosing, you can use Middle-Click and the Scroll Wheel to find your way around. Soon, you should get something that looks like this:
|Then, go back into "File" and hit "Open Map". You'll want to go into the ``_maps`` directory of your repository, and then find any map you like. I'll be using MetaStation.dmm for the purposes of this guide. Once StrongDMM loads the map of your choosing, you can use Middle-Click and the Scroll Wheel to find your way around. Soon, you should get something that looks like this:
|}
|}
<big>'''End of san7890 guide and StrongDMM'''</big>
{{Speech
|name=SpaceSmithers
|text=Need to find a good way to transition from StrongDMM to Meta's Dream Maker sections.
|image=[[File:Spell.png|64px|right]]
}}
----
So now you have your folder with the latest code in, and a zip backup to go back to if you break everything. In the master folder, you'll see "tgstation.dme". You want to open this with Dream Maker a program that'll be in your BYOND folder. Set Dream Maker as the default program for opening .dme files, if it isn't already. When you open it, you'll see a two tabs on the left: file, and object. In the file tab, open '''maps''', and then open 'tgstation.2.1.2.dmm', or whatever the current map version is called. You'll then get something looking a bit like this:
{{Speech
|name=SpaceSmithers
|text=san removed this image for some reason <pre>[[File:Dreammakermap.png|center|600px]]</pre>
Switch from the '''files''' tab to the '''objects''' tab, and you'll see '''area''', '''mob''', '''objects''', and '''turf'''. These are the four primary 'layers' that you can see in the editor. You can toggle their visibility and interactivity on and off using the '''layers '''dropdown. I'd advise copying this map, and renaming it to, say, teststation.dmm. Perhaps delete most or all of the default station, and build on the now-empty z-level, wherever you like. To build stuff, use the object tree on the left of the UI to select things, then click to place them. A simple click lets you place one item per tile from each category, while Ctrl-click '''stacks''' it on '''top''' of all previous ones and Shift-click deletes the '''topmost''' item. You can have multiple maps open at once - I usually have the default /tg/station map and mine open, and can then shamelessly copy-paste things far more easily. Also, finding stuff in the object tree can be tedious as hell - right click something you see and you can see its path in the tree - obj/structure/closet/etc. This will help you find things. From this point on, really, you can begin mapping proper.
[[File:strongdmm_hide.png|frame|right|Layers and their keybinds to toggle them]]
Beautiful! Let’s talk about those colors. Those are [https://www.byond.com/docs/ref/#/area areas] which are important for the game to understand what discrete location is what, and we use it for several things code-side. For example, the [[bridge]] is a different area than the [[bar]], so you want to make sure everything is defined appropriately. They tend to be a bit distracting through, so you can hit {{Key|Ctrl}}+{{Key|1}} to get rid of those. Do make sure you define them properly when you’re done, though.
You can select areas to copy/paste/delete, or enter add or fill mode when placing objects. Basically just click around all the menus and you'll work out how they work, more or less. '''Options>Zoom''' allows you to zoom out to 50% to see more stuff. Use layers to select which of area, objects and turf you want to edit. If you actually want to be able to see anything, I'd deselect area, and tick 'only show selectable layers'.
The first step, then, is to be able to create your first few rooms. Select a turf (floor) from the generic simulated floors. These will start with the right make-up and pressure of air on them, which is how you'll want it. Surround these floors with walls, and hey presto you have a room. Try sticking some tables in there, perhaps a vending machine or two.
If you want to add some chips to your new den but are unhappy of how they neatly stack on top of eachother, you can change their "pixel_x" and "pixel_y" values in the "edit" rmb-menu to arrange them as you want! (Remember to start and end the value with doublequotes! Also, all custom values are '''bold''' so it's easier to identify them.) In fact, most wall-mounted machines on stations are shifted like this, and while they APPEAR to be on a wall, they are actually on the tile in front of it. Just don't go overboard with this, as every new instance of an object is added as its own entry in the menu, and when there are dozens of them it can get hard to remember which one you wanted. Once you've made your room you'll want to put lights in.
Areas are one of four different, distinct “layers” we use in BYOND. The other three are [https://www.byond.com/docs/ref/#/turf turfs], [https://www.byond.com/docs/ref/#/obj objs] (for Objects), and [https://www.byond.com/docs/ref/#/mob mob] (for creatures/animals/what-have-you). Their progenitor species is the [https://www.byond.com/docs/ref/#/atom atom]. You can go into the options tab or hit the respective keybind to quickly filter for those.
|[[File:Mystery pipe.png|left|frame|There is one uninvited guest here!]]
|[[File:Sdmm_tools.png|left|frame]]
|'''Important:''' While building your station you might find yourself in need of an object with a specific alignment (windows, pipes, cables etc) that does not appear in your menu. This is because BYOND does not simulate instances of an object other than its base state unless they are present on the map. You can generate them by right clicking an object and selecting "generate instance from state/direction". This function has an '''unwanted feature''' in which a generated object sometimes has a tag added automatically. These tags can cause error with certain features of the game during a round, and need to be removed. To check for it, right click an item on the map or in the menu, select "edit" and scroll to the "tag" line, which should be empty save for two doublequotes (""). If it's not (which is easy to tell since the tag is massive and bold, impossible to miss even scrolling at lightspeed), change it. Well maintained maps don't usually contain these, so you should be safe to copy-paste to your heart's content. As a tip, remember that all non-standard objects have their own entry in the menu, and having a tag is not standard at all for most object!
|These are your tools to edit with. From left to right, they are:
* Add ({{Key|1}})
* Fill ({{Key|2}})
* Grab ({{Key|3}})
* Pick (Hold {{Key|S}})
* Delete (Hold {{Key|D}})
* Replace (Hold {{Key|R}})
They each do their own thing, and you can hover over them in the program to see what you might want to use. Feel free to get a feel with the tools by toying around with stuff, and eventually getting to work on your own maps as you desire.
|}
|}
{|
===[https://hackmd.io/@tgstation/SyVma0dS5#Testing-Your-Map Testing Your Map]===
|[[File:Editinstance.png|left|200px]]
[[File:Githubdesktop_externaleditor.png|right|400px|thumb|The “Open in Visual Studio Code” button. Click the image to expand.]]
| So now we get to the basics of making a functioning room. First of all, you'll need to re-enable the area layer. Pick some area from the object tree, and cover your room in it. You can rename this area if you want, we'll do that later. Make sure the area isn't used anywhere else on the map. Each area should have one APC or Area Power Controller in it. Copy one in from the default map or spawn one yourself, then rename its "name" variable through "edit" to something appropriate. If you copied your APC from another map, chances are that cell type and dir are both in bold. Cell type defines how much power the APC can hold, and for your first map you'll want to set this nice and high as you don't have any sort of generator yet - 10,000 ought to do. Dir defines the direction the APC is in with regards to the cell it occupies. Basically, 1 means it is above the cell you place it in, 2 is below, 4 is to the right and 8 to the left.
You should always test your code, test your maps, test your sprites, test everything whenever it’s a non-trivial amount of work. There’s an incredibly simple way to do this, which I’ll reveal to you now:
Note that with APCs, '''dir ''' is the only variable controlling their position. Other objects have their positions defined by '''pixel_x '''and '''pixel_y''' - this changes where APCs appear in the editor, but once ingame they snap to whatever the '''dir''' variable says. Other things, like signs on walls, will only take notice of the pixel variables and not necessarily dir. In a normal power system, you'd connect the APC up to all the others and the station's generator via SMES cells, but we'll do that later. For now you have a basic room that is powered and starts with enough air to breathe happily. You can put an air canister in if you think you'll consume all the oxygen, or somesuch.
The easiest/fastest way to do this is to go into Github Desktop and find the button that reads “Open in Visual Studio Code”. If it doesn’t, [https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor set your default editor] to Visual Studio Code.
|[[File:Directions.png|right|200px]]
|}
Once inside Visual Studio Code, you'll want to hit {{Key|Ctrl}}+{{Key|F5}}, or just {{Key|F5}}. This will start [https://github.com/tgstation/tgstation/blob/master/tools/build/README.md compiling your code], which shouldn’t take more than a few minutes. Once done, it’ll boot up BYOND’s Dream Seeker, connect you to the [https://github.com/tgstation/tgstation/blob/master/.github/guides/RUNNING_A_SERVER.md#installation local server], and automatically give you the highest permissions. This is because you’re doing everything in the debugging mode, which is quite nifty. This is arguably the simplest way to do it.
Once Space Station 13 has started, the Server tab located in the Stat-Panel will be a big help. From there, you can change maps and also skip the post-initialization wait time by clicking Start Now (or just type <code>Start-Now</code> in the command bar). Observe as a ghost and view your changes. Compiling is a good way to view the more subtle nuances that you weren’t able to pick up on through the editor. This includes (but is certainly not limited to): lighting, door accesses, mob interactions, and just figuring out if it looks good.
----
Simply follow these steps and you should be able to catch most errors mapping brings. The [https://hackmd.io/@tgstation/ry4-gbKH5#Pre-Commit-Checklist Pre-Commit Checklist], also provided in a dropdown below, best applies to outright Station Mapping and may not be applicable to ruins/away missions/shuttles/etc., but it’s still quite good to check as much as you can rather than assume that it works.
'''<u>Important Note:</u>''' There are '''nudge_x '''and '''nudge_y''' variables in the editor, as well as various z-axis variables. Don't ever change these, they're not used in SS13 and break things.
*Are floors with or without air, as they should be? (regular or airless)
**You can test this one out by looking for Active Turfs.
*Does the area have an APC?
*Does the area have an Air Alarm?
*Does the area have a Request Console?
**Not every area needs this, look at other stations.
*Does the area have lights?
**When you compile your map for testing, make sure the lighting is adequate. You don’t want any unwarranted “dark” spots in your rooms. If you’re going for “warm” or “cold” lighting, make sure it all matches.
*Does the area have a light switch?
**Only smaller rooms that get minimal traffic should recieve lightswitches. Areas like primary hallways should definitely not have them.
*Does the area have enough security cameras? (Use the '''[https://hackmd.io/@tgstation/SyVma0dS5#Things-To-Look-Out-For Debug Verbs]''' for help)
*Does the area have enough security cameras? (Use the verbs under Mapping for help)
*Does the area have enough intercoms? (The verb <code>Intercom Range Display</code> in the [https://hackmd.io/@tgstation/SyVma0dS5#Things-To-Look-Out-For Mapping Debug Verbs] helps with this.)
*Is the area connected to the vent air loop (distro)?
*Is the area connected to the scrubber air loop (waste)?
*Is everything wired properly?
*Does the area have a fire alarm and firelocks?
**Typically, doors leading into maintenance do not need firelocks. Do not place firelocks on doors facing the exterior of the station (like space or the planet).
*Do all airlocks work properly?
*Are accesses set properly on doors, buttons, etc.?
**For typical airlocks, you can use the [https://github.com/tgstation/tgstation/pull/65580 Airlock Mapping Helpers]. Otherwise, consult the [[Guide_to_door_access|reference for Door Accesses]].
{{Speech
|name=SpaceSmithers
|text=I'm working on an Access Helper table which might help for this part. Also, I copied the checklist into a nifty dropdown seen above in the hackmd port.
|image=[[File:spell.png|64px|right]]
}}
{{Speech
|image=[[File:Bigchungus.png|64px|right]]
|name=Big Chungus|
text=san7890 went through and documented all of the access helper define macros here: https://github.com/tgstation/tgstation/blob/master/code/__DEFINES/access.dm
don't know how much that helps.}}
{{Speech
|name=SpaceSmithers
|text=Looks good. A much needed update, I think. Side note: Keycard Auth grants auto-connect ability on Holopads. Smithers' Niche Funfact #113.
|image=[[File:spell.png|64px|right]]
}}
To be able to actually spawn into a room, you'll want to place spawners. You'll see these as the big red X symbols on the default map, for each role. There are also blue Xs for xeno spawn locations and the spawns for all latecomers on the arrival shuttle. Stick in a spawn_late somewhere in your room for now.
*Are all items placed properly?
**In summary, are your objects all on tables as needed? Are tables or other objects obscuring your vents/scrubbers?
*Does the disposal system work properly from all the disposal units in this room as well as the pipes of which pass through this room?
**Just throw yourself through a few disposals systems that seem to pass through the area you touched. Easy to forget.
*Check for any misplaced or stacked piece of pipe.
**/tg/station also [https://hackmd.io/@tgstation/ry4-gbKH5#Linters lints] for this to catch you if you forget.
*Check for any misplaced or stacked piece of wire.
**/tg/station also [https://hackmd.io/@tgstation/ry4-gbKH5#Linters lints] for this to catch you if you forget.
*Identify how hard it is to break into the area and where the weak points are and balance the area accordingly.
**For example, the [[Vault]] should be made of reinforced structures and electrified windows, the [[Kitchen]] should not. Be reasonable, not everything has to be an overly-secure structure to prevent the “tide” or other events. You will be vetted on this, just make your best choice.
*Check if the area has too much empty space.
**You don’t want vast, bald spots in your rooms that serve little purpose. Fill it up with stuff if you can, or just trim the fat entirely. Whatever works best for the station and your design.
*Are there any [[guide_to_mapping#Room Structure|indestructible turfs]] where they shouldn't be? |dropdown|collapsed=true|closename=Click to retract Map Testing Checklist|openname=Click to expand Map Testing Checklist}}</div>
<!-- I struck through this following portion because you don't actually need it any more, see: https://hackmd.io/@tgstation/SyVma0dS5#Testing-Your-Map -->
*In the Stat-Panel (mentioned previously), go into the <code>Debug</code> Tab. Now, select the <code>Mapping Verbs - Enable</code> verb.
<s>To actually play your map and be able to screw around in it as an admin, you'll have to compile it. First, make sure the file tree (on the left like the object tree, click the file tab) is open, and go to maps. Make sure the only one ticked is your own. Then click Build>Compile from the top, and wait for it to finish. This will give you a something like "tgstation.dmb" in the folder containing bot, code, config, maps, etc. Whilst here, quickly go into config, and open 'admins.txt'. Replace everything in there with:</s>
*You should now have the <code>Mapping</code> Tab.
*Check for errors for cameras, power cables, and atmos pipes.
*Powersink the station and ghost around to check for unconnected powernets (APCs that aren’t discharging/charging).
*Ride disposals from start to finish to check for broken disposals.
*Make yourself an AI and check for blindspots in camera networks. You can also use the Camera Range Display Verb.
*Spawn yourself in (check [https://hackmd.io/@tgstation/SyVma0dS5#Debugging-Hottips Debugging Hottips])
<s>"<yourbyondname> = Game Master", filling in your BYOND name.</s>
Fix your errors, and run through this list again to double check, because chances are you missed something or you broke something else. That’s just how it is.
Doing so will save everyone a lot of headaches down the line. Specifically, yours, because you will have to fix your own shit.
----
In mapping, there are a lot of errors that may come up during [http://www.byond.com/forum/post/2012623 Initialization of the world]. However, we do check for a lot of these errors. Here’s how you can check these out and get them ironed out before we have to catch it for you.
<s>This will make you an admin, which is very helpful for tinkering ingame. Now to actually boot up a server so you can run your map! Find 'Dream Daemon' (has a big green icon) in your BYOND folder, and click the 'File' dropdown at the bottom. Select your "tgstation.dmb". Select a port if you want, put security on safe, and visibility to invisible, for now. Click start to start the server, which will take a little while. You can then connect to it through BYOND by putting in either your external IP, shown in Dream Daemon, if that port is correctly forwarded. Otherwise use your internal IP, 192.168.x.x, where x is whatever. If you don't know this, ask and I can help. Once in, go to the admin tab and click 'start game'. By joining after the start, you'll spawn at the late spawn you made, and, being an admin, will be able to make stuff, delete stuff, and other handy admin things (like causing massive explosions).</s>
Assuming your world is already compiled, wait for Initialization to finish, and then type in this verb into your chat box <code>Get-Current-Logs</code>. You should see a pop-up with a whole list of logs. You just want to go down this list and select the option that says <code>map_errors.log</code>. Go ahead and either “View” or “Download” this log file (“Open” doesn’t typically work for me).
<!-- The following is a personal note, which is nice, but I touch upon that throughout both the guide and the reference collection. -->
We also now do this check for you on every pull request for ''station'' maps through our GitHub [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] process. I would advise checking this for non-station maps, though.
From there on, you can make whatever you like, really. Copying the default map and working out how everything works isn't too hard and is fairly rewarding. You could just tweak the default one for a bit if you like. The first thing I made was a small shuttle - you can see this at the bottom. Just tweak it and add stuff and you'll work out how almost everything works fairly easily. For explanations of wiring, piping, and atmos, ask away on here. I'll add an atmos guide later on, as well as a power generation and wiring guide. If you're a good engineer in-game, it'll help a lot as a mapper.
If you've managed to get all the way to the end of this before I've added more, fine effort on your part. Have fun screwing around with stuff, and feel free to ask anything you like. I'll add more stuff here soon.
===[https://hackmd.io/@tgstation/SyVma0dS5#Committing-Your-Changes--Requesting-A-Pull Committing and Pulling]===
Return to GitHub and you'll see your modifications to the [https://hackmd.io/@tgstation/ry4-gbKH5#Map-Keys-no-holds-barred Map Keys] in the line changes. In the bottom-left corner, you'll see the commit menu. [https://github.com/tgstation/tgstation/blob/master/.github/CONTRIBUTING.md#pull-request-process Maintainers at /tg/ really do appreciate if you write out a thoughtful commit title and description, because you will need to justify your changes in one way or another when you submit it for review through the Pull Request Process!]
====Committing your changes====
[[File:Mappingguide_commitbox.png|thumb|An example of a good commit title and message.]]
Once you've written the constructive title and brief description, hit "'''[https://git-scm.com/docs/git-commit Commit] to (your branch name here)'''”. If it says “Commit to Master/Main”, don’t hit that button because you’ll dirty the master branch of your forked repository. Make a new branch, and base it off what you’re currently on. If it doesn’t say that, everything’s just fine. Congratulations, you’ve “committed” your changes!<br>
== <!-- About 90% of the stuff from this point onwards is outdated. I rewrote everything from this point in another HackMD (https://hackmd.io/@tgstation/ry4-gbKH5#Pre-Commit-Checklist) onwards. I need someone to explain how shuttles work to me (again) before I'm 100% done with that though, but I've struck through everything ported over (or that I don't really see why it should be ported over). --> ==
What if you didn’t like that, realize you made a typo, or just wanna go back? You can always just go back into StrongDMM to edit your map and make a new commit, but you can also go to the History tab, right-click on your commit, and click "'''[https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things Undo commit...]'''", which will just undo your commit, and then you can make as many changes as you please, then recommit. This is one of the greatest advantages of Git, [https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control it has a powerful versioning system] that you can easily use to hop from one day’s work to another.<br>
== <s>Pre-commit checks</s> ==
If you’re happy, then seek out a '''"Publish branch"''' button. This will [https://git-scm.com/docs/git-remote upload your branch] to the remote ([https://github.com/ github.com]).<br>
====Creating a Pull Request====
Once all the "[https://git-scm.com/docs/pack-heuristics deltas are resolved]" and what-not, a '''"Create Pull Request"''' button should appear on GitHub Desktop. Click that, and your web browser will open to GitHub. Ta-da, just fill in the [https://github.com/tgstation/tgstation/blob/master/.github/PULL_REQUEST_TEMPLATE.md?plain=1 template just like the descriptions in the contributing template say] (including an image or two of your changes is always well appreciated), hit '''“Create Pull Request”''', and wait for the feedback to roll through. I would advise viewing some example PRs, open up a few of them (if you haven’t already been tracking how people write Pull Requests) and try to learn well.
*<s>Are floors with or without air, as they should be? (regular or airless)</s>
The /tg/ guidelines for Pull Requests can be found [https://github.com/tgstation/tgstation/blob/master/.github/CONTRIBUTING.md#pull-request-process here]. Another document with friendly advice from a coder can be found [https://hackmd.io/@tgstation/ry4-gbKH5#The-Pull-Request-Process-on-the-Technical-and-Emotional-Levels here].
*<s>Does the area have an APC?</s>
*<s>Does the area have an Air Alarm?</s>
*<s>Does the area have a Request Console?</s>
*<s>Does the area have lights?</s>
*<s>Does the area have a light switch?</s>
*<s>Does the area have enough intercoms?</s>
*<s>Does the area have enough security cameras? (Use the verbs under Mapping for help)</s>
*<s>Is the area connected to the scrubbers air loop?</s>
*<s>Is the area connected to the vent air loop? (vent pumps)</s>
*<s>Is everything wired properly?</s>
*<s>Does the area have a fire alarm and firedoors?</s>
*<s>Do all pod doors work properly?</s>
*<s>Are accesses set properly on doors, pod buttons, etc.</s>
*<s>Are all items placed properly? (not below vents, scrubbers, tables)</s>
*<s>Does the disposal system work properly from all the disposal units in this room and all the units, the pipes of which pass through this room?</s>
*<s>Check for any misplaced or stacked piece of pipe (air and disposal)</s>
*<s>Check for any misplaced or stacked piece of wire</s>
*<s>Identify how hard it is to break into the area and where the weak points are, and balance the area accordingly (eg. the Vault should be made of reinforced structures and electrified windows, the Kitchen should not)</s>
*<s>Check if the area has too much empty space. If so, make it smaller and replace the rest with maintenance tunnels</s>
*<s>Are there any [[guide_to_mapping#Room Structure|indestructible turfs]] where they shouldn't be?</s>
You’ve done it! You’ve done mapping! I hope that wasn’t too painful, and the rest of this page (or the links below) will introduce you to some deeper contents that I briefly touched on in regards to mapping.
* <s>Don't run pipes/cables/disposals through walls if you can avoid it. Otherwise it's a pain to repair or sabotage them, especially under r-walls.</s>
While this guide is meant to contain the bare-bones of information to get people started on mapping, the [https://hackmd.io/@tgstation/ry4-gbKH5 Mapping Reference Collection] will contain a wealth of information for mappers. I heavily recommend reading this.
* <s>Try to connect departments to maintenance through a back or side door. This lets players escape and allows antags to break in. Metastation is a good example for this.</s>
=== <s>Atmospherics</s> ===
Stumped? Feel free to ask some more experienced mappers any questions on the [https://tgstation13.org/phpBB/viewforum.php?f=11 /tg/ forums] or the [https://discord.com/invite/VW9ZEwc Discord]
* <s>Each area should have EXACTLY one air alarm (Exceptions are only possible if a room has scrubbers or vent pumps on different frequencies).</s>
* <s>Each ROOM (Walled off space) should have at least one vent pump and scrubber, which is properly connected to its respective loop.<br> Keep in mind that scrubbers don't detect gases/pressure; only air alarms do.</s>
* <s>The air supply loop's pipes should be colored blue.</s>
* <s>The scrubbers loop's pipes should be colored red.</s>
* <s>Some areas require special air alarm subtypes: /engine for the SME and /server for tcomms or the RnD server room.</s>
=== <s>Power</s> ===
* <s>Each area (which requires power) should have exactly one APC. For areas with a high roundstart power draw (engineering/cargo), one of the highcap subtypes can be used.</s>
== <s>Atmospherics</s> ==
----
=== <s>Pipes and manifolds</s> ===
<s>Atmospherics releases it's cocktail of gases into the air supply loop (blue pipes). The station is also equipped with a scrubber loop, which filters unwanted gases and sends them back to atmospherics via the scrubber loop (red pipes).</s>
=SpaceSmithers' Guide to Mapping Supplementals=
{{Speech
|name=SpaceSmithers
|text=Since almost all of Metacide's guide will be overwritten, I'll be sure to include a hyperlink at the top of the page that will take the user to an older version of the page with Dream Maker instructions. It could be useful to ''someone'', I guess. You can always check out [https://tgstation13.org/wiki/index.php?title=User:SpaceSmithers/guide_sandbox&action=history an earlier revision of this page] to review older info from this draft.
|image=[[File:Spell.png|64px|right]]
}}
----
{{Speech
|name=SpaceSmithers
|text=Double-check for missing or needed hyperlinks, and if more supporting images could be added.
|image=[[File:Spell.png|64px|right]]
}}
The first step, then, is to be able to create your first few rooms. Select an open turf from the generic simulated floors, preferably <code>/turf/open/iron</code>. Each floor has a preset make-up of air on them, unless you use one titled "airless". Surround these floors with walls, and hey presto you have a room. Try sticking some tables in there, perhaps a vending machine or two.
<s>If you're expanding the air supply loop (blue pipes) use the objects in /obj/machinery/atmospherics/pipe/simple/supply/visible or ../hidden depending on if you want it to show above floors or below them. For manifolds use the objects in /obj/machinery/atmospherics/pipe/manifold/supply/visible and ../hidden.</s>
<s>If you are expanding the scrubber loop (red pipes) use the objects in /obj/machinery/atmospherics/pipe/simple/scrubbers/visible or ../hidden depending on if you want it to show above floors or below them. For manifolds use the objects in /obj/machinery/atmospherics/pipe/manifold/scrubbers/visible and ../hidden.</s>
If you want to add some chips to your new den but are unhappy with how they neatly stack on top of each other, [https://tgstation13.org/wiki/images/a/a5/SDMM_nudge.gif you can adjust their "pixel_x" and "pixel_y" values with the Nudge and Dir menu]. You can click & drag the values, use the mouse wheel on them, or double-click on them to enter exact values.
<s>If you are however building a pipe network which has nothing to do with the air supply or scrubbers loop, you should use the objects in /obj/machinery/atmospherics/pipe/simple/general/visible or ../hidden. For manifolds use the objects in /obj/machinery/atmospherics/pipe/manifold/general/visible and ../hidden.</s>
{|
|[[File:SDMM_prefab_and_instance.png|thumb|right|The Prefab and Instance menus.]]
| Changes by Nudging or in Direction (dir) are reflected in the Prefab and Instance menus. All modified values are <span style="color:green>green</span> so it's easier to identify them. Un-modified variables may be hidden, in which you'll need to uncheck "Show modified only" by clicking on the gear icon. Most wall-mounted machines on stations are shifted like this, and while they APPEAR to be on a wall, they are actually on the tile in front of it. Luckily, most wall mounts come with convenient directional subtypes in the object selector so you don't have to manually nudge them. Just don't go overboard with this, as every new instance of an object is added as its own entry in the menu, and when there are dozens of them it can get hard to remember which one you wanted<span style=background-color:yellow;">(still relevant? I guess it clogs the prefab menu.)</span>. Once you've made your room you'll want to put lights in.
|}
{|
|[[File:SDMM_prefab.png|left|frame|There is one uninvited guest here!]]
|<s>'''Important:''' While building your station you might find yourself in need of an object with a specific alignment (windows, pipes, cables etc) that does not appear in your menu. This is because BYOND does not simulate instances of an object other than its base state unless they are present on the map. You can generate them by right clicking an object and selecting "generate instance from state/direction". This function has an '''unwanted feature''' in which a generated object sometimes has a tag added automatically. These tags can cause error with certain features of the game during a round, and need to be removed. To check for it, right click an item on the map or in the menu, select "edit" and scroll to the "tag" line, which should be empty save for two doublequotes (""). If it's not (which is easy to tell since the tag is massive and bold, impossible to miss even scrolling at lightspeed), change it. Well maintained maps don't usually contain these, so you should be safe to copy-paste to your heart's content. As a tip, remember that all non-standard objects have their own entry in the menu, and having a tag is not standard at all for most object!</s>
<s>To add new colors of pipes, you will need add a new subtypes in the appropriate .dm files located in tgstation\code\modules\atmospherics\machinery\pipes</s>
{{Speech
|name=SpaceSmithers
|text= At San's request, the Prefab section will be re-written to better suit modern expectations and definitions, and to account for SDMM.
|image=[[File:Spell.png|64px|right]]
}}
|}
{|
So now we get to the basics of making a functioning room. First of all, you'll need to re-enable the area layer. Pick some area from the object tree, and cover your room in it. You can rename this area if you want <span style=background-color:yellow;">(Really? We can manually edit the names of areas?)</span>, we'll do that later. Make sure the area isn't used anywhere else on the map. Each area should have one APC (Area Power Controller) in it. When creating an APC, the "auto_name" subtype will automatically name the APC to the area that it is in. Or, you can use the generic parent type and manually set its <code>name</code> variable. Other subtypes of APCs may include "unlocked" and "highcap". For testing, you might want to use a "highcap" variant that stores more energy, since we don't have a power source yet. Alternatively, you can change the "cell_type" variable to <code>/obj/item/stock_parts/cell/infinite</code> for infinite power <span style=background-color:yellow;">(Source: It came to me in a dream. Untested.)</span>. If there are no directional types for the APC you're using, you can use the Nudge and Dir menu from earlier to adjust it. In a normal power system, you'd connect the APC up to all the others and the station's generator via SMES cells, but we'll do that later. For now you have a basic room that is powered and starts with enough air to breathe happily. You can put an air canister in if you think you'll consume all the oxygen, or somesuch.
|[[File:Directions.png|right|200px]]
|}
<s>Please refrain from var-editing pipes, as it typically introduces graphical glitches and other issues.</s>
=== <s>Air Alarm</s> ===
<s>Every single area (with scrubbers and/or vent pumps) should have exactly one air alarm. More than one should be placed if vent pumps or scrubbers use different radio frequencies than the default one (1439).</s>
'''<u>Important Note:</u>''' There are '''nudge_x '''and '''nudge_y''' variables in the editor, as well as various z-axis variables. Don't ever change these, they're not used in SS13 and break things.<span style=background-color:yellow;">(Needs to be re-written for SDMM's nudge menu.)</span>
=== <s>Scrubbers (Station air supply)</s> ===
To be able to actually spawn into a room, you'll want to place spawners. You'll see these as the big red X symbols on the default map, for each role. There are also blue Xs for xeno spawn locations <span style=background-color:yellow;">(pretty sure spawners now use fancy sprites for their respective spawns)</span> and the spawns for all latecomers on the arrival shuttle.<span style=background-color:yellow;">(old/irrelevant, shuttles are not placed onto station maps anymore.)</span> Stick in a spawn_late somewhere in your room for now.
<s>Every room (ie. walled off space) except for maintenance hallways should have at least one scrubber.</s>
<span style=background-color:yellow;">(may change for redundancy reasons)</span>
To actually test your map and be able to screw around in it as an admin, you'll have to compile it. The easiest way to do this is through Github Desktop, where you will open the repository in your external editor by clicking the "Open in Visual Studio Code" button. If this is not present, change your default editor in the options to Visual Studio Code. In Visual Studio Code, press <code>F5</code> to both compile and launch the game. Full permissions are automatically granted as "localhost".
<s>The path for scrubbers that start on is '''/obj/machinery/atmospherics/components/unary/vent_scrubber/on'''</s>
The best possible training is through experience. From here on out, you can make whatever you like, really. Copying the default map and working out how everything works isn't too hard and is fairly rewarding. You could just tweak the default one if you like. The first thing I made was a small shuttle - you can see this at the bottom. Just tweak and add stuff and you'll work out how almost everything works fairly easily. Poke around with both Github Desktop and StrongDMM. For explanations of wiring, piping, and atmos, ask away on [https://discord.tgstation13.org/ the mapping channel of our discord] or [https://tgstation13.org/phpBB/viewforum.php?f=11 on the forums].
<s>And make sure the '''id_tag''' is the default one (null)</s>
=== Gas tanks and filters ===
{{Speech
<s>Also ensure the scrubber is connected to the scrubber loop!!</s>
|name=SpaceSmithers
|text=This section will be overhauled. It may not be exhaustive, however. It will probably just describe key points such as monitored meters, mixing, common errors, etc. Similar to how it is currently.
=== <s>Vent Pumps (Station air supply)</s> ===
|image=[[File:spell.png|64px|right]]
}}
<s>Every room (ie. walled off space) except for maintenance hallways should have at least one vent pump.</s>
<s>The path for vents that start on is '''/obj/machinery/atmospherics/components/unary/vent_pump/on'''</s>
<s>Please make sure the '''id_tag''' is the default one (null)</s>
<s>Also ensure the vent pump is connected to the air supply loop!!</s>
=== <s>Gas tanks and filters</s> ===
<s>Each station should have a full set of these - or at the bare minimum, one for N2, one for O2 and a third tank to filter dangerous gases into.</s>
<s>Each station should have a full set of these - or at the bare minimum, one for N2, one for O2 and a third tank to filter dangerous gases into.</s>
|text='''IMPORTANT:''' I don't want a repeat of the old guide; this is not the place to dump random shuttle code documentation. <u>This is a mapping guide</u>. Keep things simple and clear for mappers. If you want to document shuttle code, comment in the code itself or make a separate, dedicated wiki page.
|image=[[File:spell.png|64px|right]]
}}
There are two types of shuttle docks:
*[[File:port_stationary.png]] stationary == places where the shuttle can dock
*[[File:port_mobile.png]] mobile == placed on shuttles
Mobile ports will dock directly on top of stationary ports.
=== <s>APC</s> ===
Sometimes listed as its own type of port, transit ports <code>/obj/docking_port/stationary/transit</code> are automatically generated in a dedicated transit z-level, so you don't have to worry about that.
<s>Each new room needs at least one, this will provide all the power for the room (magically). Each piece of machinery inside the APC's area will draw power from either the lighting, equipment or environmental channel.</s>
For places like [[arrivals]] and [[departures]], we will have to add a <code>/obj/docking_port/stationary</code> for each, and manually edit in some variables for them to work. It's a good idea to have an updated, pre-existing map open in your workspace to reference or copy.
<s>Any room that is very equipment heavy (for example cargo bay) may need a beefed up APC (apc/highcap) to prevent early blackouts. These start with higher capacity power cells.</s>
Before we do anything, lets identify some of the variables we will likely be seeing.
*<code>dir</code>: The direction of the port.
**If a shuttle's mobile docking port direction is different than the stationary docking port's direction, the shuttle and all items on it will be rotated accordingly.
**This rotates the entire plane. Other variables, like <code>width</code> and <code>height</code>, are relative to this direction. This means that on a docking port facing west or east (dir = 4 or 8 respectively), <code>height</code> will be horizontal on the mapping workspace, and <code>width</code> will be vertical.
*<code>height</code>: The size of covered area, parallel to dir.
*<code>width</code>: The size of covered area, perpendicular to dir.
*<code>dheight</code>: Distance in height from the (0,0) origin point to the dock. [[#Dwidth_and_Dheight|More details can be found here]].
*<code>dwidth</code>: Distance in width from the (0,0) origin point to the dock. [[#Dwidth_and_Dheight|More details can be found here]].
*<code>name</code>: A name string for the port. This name will be visible on shuttle consoles, Shuttle-Manipulator admin verb, and during debugging.
*<code>roundstart_template</code>: The template that will spawn on this port when the map initializes. Used on docks for arrivals, escape pods, and more.
*<code>shuttle_id</code> (formerly <code>id</code>): Identification variable. Mandatory for certain ports.
**'''IMPORTANT:''' For standard stations, you MUST use these '''exact''' strings for the listed areas, or else they will not function. <span style=background-color:yellow;">Stub? double-check all instances of shuttle_id in case i missed some.</span>
***Auxiliary Base Construction: <code>"aux_base_zone"</code>
=== <s>Wiring</s> ===
A stationary port is strict with its width and height variables when deciding if a shuttle can dock there. They should generally be greater than or equal to the dimensions of the shuttle that wants to dock. If a shuttle is larger than the stationary port's dimensions, it will outright refuse to dock. When testing your map, debug/admin tools such as the <code>Shuttle-Manipulator</code> verb will be a tremendous asset.
<s>Make sure the wires lead from the main power grid, and to the APC(s) of your area. If any equipment in your new area requires a wire under it, line it up, connected to the main power grid, and under the machinery.</s>
<s>Wires are also helpful when making electrical grilles (just dot wire under a grille), make sure the wires touch the main power grid (or they won't shock people).</s>
The stationary ports for the labor shuttle, mining shuttle, public mining shuttle, and the auxiliary base zone each have their own, unique subtypes. These are presets and should not be edited, except for their direction.
== <s>Equipment</s> ==
'''Escape pods''' utilize two unique stationary port types for each pod; one is the <code>escape_pod</code> subtype to spawn the pod itself (which should go unedited except for its direction), and also the <code>random</code> subtype. When the map initializes, the random ports are automatically teleported to a random spot in lavaland (or the icemoon if using the respective icemoon subtype). These spots are reserved for emergency launches when the station is on red or delta alert levels. Random ports need a <code>shuttle_id</code> for pods to dock, and generally use the following naming scheme: "pod_lavaland", "pod_2_lavaland", "pod_3_lavaland", and so on.
=== <s>Lights</s> ===
Most stationary ports generally face the shuttle or face away from the thing the shuttle docks with, but not always, as it depends on the position of the mobile port on the shuttle. If you're unsure where to place the docks, its always a good idea to use another pre-existing map as a reference. Also remember that mobile ports park '''directly on top of''' stationary ports, and will also rotate to adopt their dir.
<s>Lights take up a lot of power, don't use too many! Make sure to put in just enough so the room is fully lit, but not so many that the equipment will go out in ten minutes of the round starting.</s>
=== <s>Light switch</s> ===
===Mobile Ports [[File:port_mobile.png|18px]]===
<s>For mood lighting, or to show the room is currently not in use by the primary occupant. These disable the lighting equipment (and power drain associated) in the area, but not desk lamps. Place these on walls, usually by a door.</s>
The mobile port variables are quite different from their stationary counterpart. Lets go through them:
*The <code>width</code>, <code>height</code>, <code>dwidth</code>, and <code>dheight</code> are all generated '''automatically'''.
**Many existing shuttles in the codebase do have these variables edited in despite not being required.
*<code>name</code>: Name your spacecraft! Will be printed in consoles and also station-wide announcements if its an escape shuttle.
*<code>preferred_direction</code>: The direction the shuttle appears to travel in. Changes the parallax animation.
*<code>port_direction</code>: Relative direction of the docking port from the front of the shuttle. If you rotate the ship so that it points north, what direction will the mobile port be facing?
=== <s>Request Console</s> ===
You should cover your entire shuttle with one or more proper subtypes of <code>/area/shuttle</code>, especially if its an escape shuttle with a brig on it. This ensures that everything works and moves properly. Otherwise, your shuttle may encounter unwanted errors or claim turfs within the bounding box that shouldn't be moving with your shuttle.
<s>If a certain room has no need for materials, or produces no materials, do not give it a Request Console. If it does (for either case or both) make sure it has at least one, that is in a place where some one will see it.</s>
=== <s>Intercoms</s> ===
Some shuttles should be using specialized subtypes of the mobile docking port, like arrivals and emergency shuttles. Be sure to check these subtypes before settling with the generic one, or else they may not work as expected.
<s>At least every room should have one of these. They should be set to 145.9, and be speaker ON Microphone OFF. This is so radio signals can reach people even without head sets on. Larger room will require more than one at a time.</s>
=== <s>Security Cameras</s> ===
===Dwidth and Dheight===
<s>Most areas should have these, enough to see the general area from a Human point of view, but, not bunched together for the AI's sake. Larger rooms may require more than one.</s>
This section can get a bit confusing at first, but it will get better as it goes along. The area of the docking port is not centered at the dock itself; at first, the dock will be at the (0,0) coordinate of the area, which we will label as the '''origin point'''. Its important to note that the entire grid, along with the origin point, will rotate with the docking port's direction (dir), just like other variables.
! scope="col" class="unsortable" |Origin point (0,0) location
|-
|1 (North)
|Bottom-left
|-
|2 (South)
|Top-right
|-
|4 (East)
|Top-left
|-
|8 (West)
|Bottom-right
|}
{{Speech
|name=SpaceSmithers
|text=This table (that I, myself, made) might be misplaced or outright unnecessary. I'll come back to decide its fate at another time.
|image=[[File:spell.png|64px|right]]
}}
<code>dwidth</code> and <code>dheight</code> define the relative position of the docking port in its own covered area by measuring from the origin point (0,0). Since we're calculating the distance from the origin point, a (0,0) coordinate, the tile with origin point itself <u>does not count</u> for these measurements.
== <s>Room Structure</s> ==
To the average mapper, all of this technical jargon is incomprehensible. We'll use some visual diagrams to help explain what it all means.
=== <s>Access</s> ===
{|
''' <s><span style="color:#FF5238"> Refer to ..\code\__DEFINES\access.dm for door access values.</span></s>'''
|[[File:Mapping_dockhelper.png|thumb|right|Docking port reference guide. Click to expand.]]
|Displayed is an example port facing in four different directions. We can see how everything rotates as the port's dir changes, such as width and height, its delta counterparts, and the tile marking the (0,0) origin point. Lets look at <code>dwidth</code> and <code>dheight</code> and note how it measures from the origin point '''(0,0)''' to the [[File:port_stationary.png]] '''docking port''', and how the tile with the origin point is '''not counted'''. Measuring these tiles for this example port, we see that <code>dwidth</code> is 3 and <code>dheight</code> is 4. '''If there's anything you should pick up from this section, reference this image to determine where and how you should be measuring.'''
| Lets apply this knowledge. Here in this image we have Metastation's arrivals dock. You can see the area it covers with its width and height variables. Since the port is rotated to the west, <code>width</code>, <code>height</code>, and the origin point (0,0) are all rotated as well. In the image, you can see how <code>dwidth</code> is measured from the (0,0) tile. The <code>dheight</code> variable goes unedited in this case, because the dock is '''0''' tiles away height-wise from the (0,0) point, and the default value is already 0.
|}
<s>Access to doors is handled by req_access values. There are four when editing a door - req_access, req_access_txt, req_one_access, and req_one_access_txt. The one's we're concerned with are '''req_access_txt''' and '''req_one_access_txt'''.</s>
Setting the offset for where the docking port is relative to the covered area is important for making sure shuttles can fit within the respective bounds. Without <code>dwidth</code> and <code>dheight</code>, the dock would always be stuck in the corner at the origin point, and certain shuttles would fail to dock properly. This is especially true for docks that support interchangeable shuttles that differ in size, like departures.
[[File:DoorAccessImage1.png|thumb|left|300px]] <s>This image shows a door on the Arrivals shuttle - since it's a public door, the access is set to "0", as everyone should be able to open it. If we look at the Brig front door, we would set the access to 63, because that's the value for Security front doors - accessible by Security positions, but no one else.</s>
|text=Work in-progress. Documented from [https://github.com/tgstation/tgstation/blob/master/code/__DEFINES/maps.dm maps.dm], [https://github.com/tgstation/tgstation/blob/master/code/datums/map_config.dm map_config.dm], and more. Certain entries could use examples or more depth.
|image=[[File:spell.png|64px|right]]
}}
Your map should come with a JSON configuration file placed in the "_maps" folder, especially if its utilizes Multi-Z. This config file points the game to where your map is located, the map's name, what shuttles will be used, and more. '''All listings will be case-sensitive.''' Lets go through some of the more common configuration types.
*<code>version</code>: Version tracking was introduced in [https://github.com/tgstation/tgstation/pull/53663 pull #53663], but goes unused in the /tg/ codebase. Set this to "1" like every other map.
*<code>map_name</code>: The official name for your map. Will be referenced in the stat-panel or external hooks like the Discord bots.
*<code>map_path</code>: The folder where the map .dmm file is located. The "_maps" folder will be the root, so this string should look something like <code>"map_files/YourStation",</code>.
*<code>map_file</code>: The filename for your map that is found in the above folder. Example: <code>YourStation.dmm</code>.
*<code>shuttles</code>: This entry will be a list. These are the shuttles available for changing:
**<code>cargo</code>: The cargo shuttle.
**<code>ferry</code>: The ferry generally used by admins that travels between Central Command and the main station during the round.
**<code>whiteship</code>: The [[White Ship|whiteship]] that will spawn in space somewhere for those [[curator|explorers]].
**<code>emergency</code>: The [[Escape Shuttle]]. Remember that this is interchangeable during the round via communications consoles, unless <code>allow_custom_shuttles</code> is set to false.
*<code>planetary</code>: If the map is planetary, set this to "1".
*<code>space_ruin_levels</code>: Planetary maps should include this and have it set to "0"
*<code>space_empty_levels</code>: Planetary maps should include this and have it set to "0"
*<code>job_changes</code>: This will expand into a list consisting of job titles, which will list again into changes for that job. Some jobs like [[Captain]] and [[Cook]] have unique modifiers exclusive only to them.
**<code>Captain</code>
***<code>special_charter</code>: Adding this variable will replace the charter with a banner representing the claim to a celestial body. IceboxStation has this set to "moon", while Kilostation and Tramstation have this set to "asteroid".
**<code>Cook</code>
***<code>additional_cqc_areas</code>: Extra areas for the Cook's close quarters combat abilities. An example entry would be <code>["/area/station/service/bar", "/area/station/commons/lounge"]</code>, extending the range to both the Bar and the general Lounge areas.
**The following modifiers can be used for any job, such as <code>Station Engineer</code> or <code>Prisoner</code>.
***<code>spawn_positions</code>: Sets the amount of positions that can be filled at roundstart.
***<code>total_positions</code>: Sets the total amount of positions available after roundstart. '''Roundstart positions will still be filled to the number defined in <code>spawn_positions</code>, even if this variable is set to a lower number'''. If '''both''' of these variables are set to zero, the respective job will not be listed in either preferences or the late-join menus.
***<code>additional_access</code>: Grants extra access to the respective job. Grant the Clown <code>armory</code> access. See [https://github.com/tgstation/tgstation/blob/master/code/datums/id_trim/jobs.dm jobs.dm] for help with access.
***<code>additional_minimal_access</code>: Grants extra access to the respective job when the station is under-staffed. '''IMPORTANT:''' These are two separate lists and do not stack. This means that <u>during a skeleton crew, only the accesses listed here will be granted, and those under the regular <code>additional_access</code> will not carry over.</u>
<s>Multiple accesses to doors are handled by adding a semicolon (with no spaces) between access values (eg. "28;31" is for Kitchen and Cargo access). This might seem worthless, but it's useful for small maps, where jobs might need to share access due to cramped spaces.</s>
<span style=background-color:yellow;">TEST: Setting traits in .json will not retain default Z-level linkage? See [https://github.com/tgstation/tgstation/pull/65183 '''this PR fixing Kilostation's space exploration by manually re-adding z linkage''']</span>.
Defines listed under <code>trait</code> are for configuring the map's Z levels. For example, designating where levels of a Multi-Z map are relative to the others, enabling weather, mining, ruins, and more.<br>
'''Important:''' If you are adding/modifying any z-trait to a config file, you must include <code>Linkage</code> because the default is not retained, resulting in an 'invisible wall' effect to the map's edges.
*<code>trait:</code>
**<code>"Linkage"</code>: Defines how z-levels are traversed at a map's edge. Stations in space use "Cross", while planetary stations are set to "null". When nulled, hitting a map's edge does nothing.
**<code>"Secret"</code>: Boolean. Does this z-level prevent ghosts from observing it?
**<code>"No Phase"</code>: Boolean. Forbids teleporting and such. True for the CentCom level.
**<code>"Bombcap Multiplier"</code>: Number. Multiplier for the bombcap. [[KiloStation]], a lower-pop map, has this set to 0.7.
**<code>"allow_custom_shuttles"</code>: Boolean. If set to false, the Purchase Shuttle button on communications consoles will be removed.
<s>There's an important difference between the two that you need to pay attention to - req_access_txt requires '''ALL LISTED ACCESSES''' to open the door, while req_one_access_txt lets anyone with '''ONE OF THE LISTED ACCESSES''' open the door. For example - say you want your Brig to be openable by the Detective and Security Officers, we would put "63;4" in '''req_one_access_txt''', because we want the Detective '''AND''' Security to have access. If we used req_access_txt, you would need '''BOTH''' accesses to open the door, meaning neither the Detective or Security could open it.</s>
----
'''Multi-Z''': turf definitions and z-level and traits are required for Multi-Z maps.
<s>You can view all of the access values in the code/game/jobs/access.dm file. (Most should be self explanatory or have a label, but if you really aren't sure, you can take a look at Boxstation's map file and check the value on the door you're looking for).</s>
[https://github.com/tgstation/tgstation/blob/master/code/__DEFINES/maps.dm#L108 good reference for up & down vars in multi-z config]
=== <s>Airless Floors</s> ===
{{Speech
|name=SpaceSmithers
|text=I'll add a section showcasing one or more full config JSON files to demonstrate proper formatting, with comments explaining their functions.
|image=[[File:spell.png|64px|right]]
}}
<s>Ideal for rooms or chambers that mix gas, and for tiles exposed to space. Not ideal for areas that humans will cross in frequency.</s>
<s>Use these on external tiles (to prevent lag when the game starts) and chambers that will require gas mixing (toxins mix chamber/ furnace). Double check these to make sure you don't suffocate mobs in the new rooms.</s>
|name=SpaceSmithers
|text=Untouched section. It may become overwritten or obsolete.
=== <s>Fire Alarms and Fire Doors</s> ===
|image=[[File:spell.png|64px|right]]
<s>Make sure to put these INSIDE of the boundary of the area, so there is a lock down. Any spot that gets hot as a normal function should not have a fire Alarm right next to the heat source (toxin mix chamber). Make sure there is a fully sealed area (with the exception of maintenance doors for people to escape fires) that can't be open by normal civilians.</s>
}}
Multi-Z is a feature which allows a station map to have multiple Z-levels layered on top of each other, behaving as a single station with multiple floors. This feature is currently in use on the [[Tramstation]] and [[IceboxStation]] maps. A station's multiple levels can be bundled into one map file, or in several seperate files. The traits section of the map configuration json tells SS13 how to link the maps together.
=== <s>Weak Points</s> ===
<s>Judge how high security the room will be, if it is high security, reinforced walls and electrified grill windows may be in order. Areas that do not need a lot of security can use basic walls, and windows to your liking (though normal glass windows break very very easy). Each room should have one place that's weaker than the rest (like a back door, side entrance, or a window), just because the main entrance might be out of commission (and realistically, for traitors to break into).</s>
=== <s>Item and Machinery Distribution</s> ===
<s>Be smart about what will go in an area, keep a fine balance between the size of the room and amount of equipment. Large rooms may require multiple APCs to prevent power outages early in game. Second, make sure to place equipment that make sense for the area (security computer in a security area/ Medical vendor in a medical area).</s>
=== <s>Indestructible Turfs</s> ===
<s>Before you finalize a map, check for any indestructible turfs. These turfs ignore things like external damage and are typically meant for things like special ruins/rooms where you want to avoid people trying to circumvent a path. Due to these characteristics, they have no real place on regular station maps and would probably lead to confusion for players more than anything.</s>
== <s>Balance</s> ==
=== <s>Item contents</s> ===
<s>The harder the room is to enter, the more goodies or sensitive equipment there is inside. Make sure to keep this in mind (and don't make an empty room that's covered in blast doors, electrified grills, reinforced walls, and captain level doors).</s>
=== <s>Room security</s> ===
<s>A room is only as secure as its necessity. Public rooms should not have many security functions (other than a fire alarm), but private work space must be more secure (based on job). The bartenders do not need reinforced walls around their storage, but engineers do.</s>
<s>The highest security rooms should utilize the highest security measures. The lowest security rooms should utilize the cheapest security measures.</s>
== <s>Step_x, step_y and the broken movement syndrome</s> ==
<s>So you compiled the map and suddenly whenever you move you no longer get the animation of moving but just 'appear' on the next tile?</s>
<s>So a while back step_x and step_y were introduced to allow pixel based movement. SS13 does not utilize this. Step_x and step_y are variables that each atom has. The way they work is that as soon as you set any object on the map to use one of these variables, the game interprets that you overrode all default movement code and wrote your own - but you didn't (The code that makes the animation from tile to tile).</s>
<s>To fix this problem you need to close dream maker (save the project first, obviously). Open your map (.dmm) file in a text editor, such as notepad or notepad++. Search (ctrl+f) through the file for step_x and step_y and remove any reference to it. Once no more step_x or step_y -es are found in the file, save it and open it in dream maker once again. Compile the code and movement should work fine once more. Go to [[Community|the development IRC]] if you need more help.</s>
== <!-- This entire section regarding shuttles is just garbage that doesn't actually make sense by the way... I'm going to chase down someone to baby me through it so I can get a suitable rewrite done for modern shuttles. --> ==
==<s>Shuttles</s> ==
<s>Basically there's 3 types of shuttle dock stationary, transit and mobile</s>
*<s>stationary == places where the shuttle can dock</s>
*<s>transit == shuttle as it moves</s>
*<s>mobile == the place with the actual shuttle</s>
<s>so you'd have a transit dock in the transit area and 2 stationary docks, one in centcomm and the other one in the station and 1 mobile dock, in centcomm for most shuttles (apart from mining)</s>
<s>The shuttle docks are grouped by id eg id = "cargo_away" id = "cargo_transit"</s>
<s>You need to add the dock types to the map and edit the bounding boxes via varediting the dock, you need to varedit height, width, dheight and dwidth at minimum. These are offset by the dir so do keep that in mind, eg if dir == 2 then width goes from EAST to WEST, if dir == 4 then width goes from NORTH to SOUTH and dwidth/dheight are offsets from the lower-left corner of the plane switched to the dock's dir</s>
<s>You should also ensure the directions face the shuttle or face away from the thing the shuttle docks with.</s>
<s>If a shuttle's mobile docking port direction is different then the stationary docking port's direction, the shuttle and all items on it will be rotated accordingly. (Try it, it works properly for just about everything)</s>
<s>'''Warning the bounding box for the mobile dock must fit inside of the stationary dock (after any rotation)''' Or the shuttle will refuse to move.</s>
<s>If the shuttle's mobile docking port is in an area that is a subtype of /area/shuttle, Only turfs in the bounding box in that same area are moved. Otherwise it moves all turfs in the bounding box. This can be used for odd shaped shuttles. (the area will be transfer over as well)</s>
<s>Also note that the emergency shuttle and cargo shuttle need special subtypes of the dock type eg so /obj/docking_port/mobile/emergency</s>
<s>The other variables of note is traveldir, which defines if the shuttle rotates on transit, it's an angle in degrees (just imagine the shuttle is inside a circle . For example, if you want the shuttle going right to left set it to 270 degrees.</s>
===<s>Dwidth and Dheight in more depth</s>===
<s>dwidth/dheight is the offset of the docking_port obj from the (0,0) bounding box corner. In dir == 1 (north) 0,0 is the bottom left corner? This changes for each direction, For example when dir is 2 it's the upper right corner. so dwidth and dheight identify where the bounding box starts relative to the docking port obj whereaswidth and height determine the actual width and height of the bounding box</s>
'''<s>Note: We count step 0 as a tile, so a height and width of 9 is actually 10 tiles (tile 0 to tile 9)</s>'''
<s>Here is an example for the north facing shuttle dock direction - you can rotate this image to determine where the offset is for each other cardinal direction
[[File:ShuttleBox.png]]</s>
==<s>Other files</s>==
<s>If you are adding a map to the game, you need to ensure it has a JSON file under _maps, and is included in the maps config file.</s>
= <!-- I'm going to keep it 100% with you, I don't even know why we have this section. I didn't bother adding it to the modern guides because I don't even know the usecase of it... feel free to leave it here if you want, but I don't know of a usecase. --> =
==<s>Helpful regular expressions</s>==
<s>Everything in the code blocks is a regular expression, most decent text editors are able to use regex in their searches.</s>
<s>Replace the regex proceding <tt>=></tt> with what follows.</s>
=== <s>Pesky var edits for the `something` var are all over my map</s> ===
<s>Replace <tt>something</tt> with the var that needs to be removed. You need to run both replacements to catch all cases.</s>
<s>Multi-Z is a feature which allows a station map to have multiple Z-levels layered on top of each other, behaving as a single station with multiple floors. This feature is currently in use on the [[Tramstation]] and [[IceboxStation]] maps. A station's multiple levels can be bundled into one map file, or in several seperate files. The traits section of the map configuration json tells SS13 how to link the maps together.</s>
* <s>If you are building station rooms on a lower Z level, ensure that a floor of some type is mapped on the Z level above the room. You can check the coordinates in the mapping editor to ensure you floor over the correct dimensions of the room. When running the server in Dream Daemon to test the map, you can go to the Debug tab and hit show debug verbs, go to Mapping tab and hit Show ATs, if the list is empty, you are good.</s>
* <s>Earlier versions of multi-z did not require a baseturf to be defined under each z-level's traits in the config json. Each level must now have a baseturf set.</s>
* <s>The maploader '''will not''' load and link a map file without areas or turfs defined. An empty space (nothing but baseturf) map will runtime. If you are adding a Z-level to an existing map, be aware of this.</s>
* <s>SS13 will cache a map's configuration json file in data\next_map.json. If you alter a map's configuration json locally, you must also clear this file by using the change-map verb in game, deleting the file, or replacing it with your updated json file.</s>
*If you are building station rooms on a lower Z level, ensure that a turf of some type is mapped on the Z-Level above the room to function as a “ceiling”. You can check the coordinates in the Mapping Editor to ensure you map over the correct dimensions of the room. When running the server to test the map, you can go to the Debug tab and hit “Mapping Verbs - Enable”, go to Mapping tab and hit Show ATs. If the list is empty, you are good.
*Earlier versions of Multi-Z did not require a baseturf to be defined under each Z-Level’s traits in the config JSON. Each level must now have a baseturf set.
*The maploader '''will not''' load and link a map file without areas or turfs defined. An empty space (nothing but baseturf) map will runtime. If you are adding a Z-level to an existing map, be aware of this.
*SS13 will cache a map’s configuration JSON file in <code>data\next_map.json</code>. If you alter a map’s configuration JSON locally, you must also clear this file by using the change-map verb in game, deleting the file, or replacing it with your updated JSON file
Текущая версия от 09:46, 21 февраля 2023
This page is currently under construction!
The following page is currently in the process of being created, is undergoing a major structural rework and/or is being moved. The reason for this is: "This is a sandbox to make incremental edits to incorporate san7890's improved guide to mapping. Absolutely everything is subject to change, and I encourage you to overwrite literally anything. Editors note: standardize linking all headers to the respective HackMD headers so that readers absolutely can not miss it."
This page is mostly port of san7890's A-Z Guide to Mapping, a HackMD document that details the mapping essentials. It is recommended that you read that document first as it is well organized, updated, and contains very useful visuals that this page may lack. If you are an experienced mapper, san7890's Mapping Reference Collection may be more useful to you.
Big Chungus говорит: "Nyehehehehe I'm Big Chungus (big chungus voice). I just went through some stuff and left some comments. If you want something nice to write about the Guide to Mapping (and the Mapping Reference Collection) in those above chat bubbles, I like Goonstation ZeWaka's Prompt (inspired probably by san7890's own words), which can be found here: https://hackmd.io/@goonstation/maps#Goonstation-Mapping-Guide ."
You may substitute this for any Git client that you know how to use already (Bash or GitKraken). If you do not know how to use any Git client, Github Desktop remains a perfectly acceptable client for mapping changes, and I will be using it throughout this guide.
This is recommended because you will need to test your mapping changes! In the words of MMMiracles (creator of Cere, Donut, and Tram): “Knowing how to code greatly expands your mapping horizons.” You will not need to know how to code in order to map but having this set up at the very start will greatly assist your future endeavors!
We use the Goonstation Extension Pack for easy interaction with BYOND’s Dream Maker code, it is a must-have. Don’t fret the name (because /tg/ coders made most of the stuff anyways haha).
This is needed for Git Hooks, which are important in your mapping endeavors.
Love
It is imperative that you use the Map Merger tools before committing any changes to a map. See here for how. Some modern programs do similar functions to what Map Merger does, but running this and getting your Git Hooks set up save you a lot of headache.
Within your fork, you'll want to click the "Code" button, then click "Open with GitHub Desktop" (assuming you've downloaded it) under the dropdown. A prompt from the application will open; find a clean folder to locally copy your repository and click Clone. This may take a few minutes. Another prompt will appear asking: "How are you planning to use this fork?" You will want to select "To contribute to the parent project". This will make creating Pull Requests easier.
The final part to setting up GitHub is to make a new branch. This part is super-duper important, because you want to keep your “master” branch on your fork as clean as possible, since it’s a pain to clean out and send pull requests to.
To do this, click on the Current branch (which defaults to "master") and click on the "New branch" button next to the filter bar. For every individual project you work on and submit a Pull Request for, you want to be on a brand new branch. Feel free to name it whatever you want, can be as goofy or as organizational as you want. It’s your fork, after all.
You may also get a screen that says “base it off the current branch” or “base it off the upstream/master”. That depends on what you want, but if you want to start fresh on a new project, always hit “base it off the upstream/master”.
In the time of Metacide, the creator of MetaStation and the last person to make a "Guide to Mapping", all that you had was Dream Maker's program. Dream Maker sucks though, and we have better tools. While all of the content you see on the rest of this page and elsewhere may be lifted straight from DreamMaker, this will serve as a small "pointer" to where you can find that same functionality in StrongDMM. Everything you can do in Dream Maker, you can do about 100 times better in StrongDMM. If you've managed to grasp the bare essentials of even playing Space Station 13, then I have no doubt that getting acclimated to StrongDMM will probably be a walk-in-the-park. However, BYOND hasn't changed in how it parses maps, so that will all hold steadfast and true.
At the time of me writing this guide, StrongDMM is currently in an “alpha state” (Versions 2.0.0 and up). I will be using the alpha version since it’s the path the program is going to take in the future, but if you’re hesitant about an alpha version, feel free to downgrade to Version 1.9.1 (it has a few features 2.0.0 is missing). You can actually run both concurrently, too! Regardless, let’s start mapping!
Go into "File" in the top-right of your screen and hit “Open Environment”. The “environment” is how StrongDMM is able to find, collect, and parse the atoms that make up every part of every map. This is an important step, and make sure you always use the .DME (Dream Maker Environment) file on your repository to keep things as straightforward as possible. Just get tgstation.dme.
Your map in StrongDMM
Then, go back into "File" and hit "Open Map". You'll want to go into the ``_maps`` directory of your repository, and then find any map you like. I'll be using MetaStation.dmm for the purposes of this guide. Once StrongDMM loads the map of your choosing, you can use Middle-Click and the Scroll Wheel to find your way around. Soon, you should get something that looks like this:
Layers and their keybinds to toggle them
Beautiful! Let’s talk about those colors. Those are areas which are important for the game to understand what discrete location is what, and we use it for several things code-side. For example, the bridge is a different area than the bar, so you want to make sure everything is defined appropriately. They tend to be a bit distracting through, so you can hit Ctrl+1 to get rid of those. Do make sure you define them properly when you’re done, though.
Areas are one of four different, distinct “layers” we use in BYOND. The other three are turfs, objs (for Objects), and mob (for creatures/animals/what-have-you). Their progenitor species is the atom. You can go into the options tab or hit the respective keybind to quickly filter for those.
These are your tools to edit with. From left to right, they are:
Add (1)
Fill (2)
Grab (3)
Pick (Hold S)
Delete (Hold D)
Replace (Hold R)
They each do their own thing, and you can hover over them in the program to see what you might want to use. Feel free to get a feel with the tools by toying around with stuff, and eventually getting to work on your own maps as you desire.
The “Open in Visual Studio Code” button. Click the image to expand.
You should always test your code, test your maps, test your sprites, test everything whenever it’s a non-trivial amount of work. There’s an incredibly simple way to do this, which I’ll reveal to you now:
The easiest/fastest way to do this is to go into Github Desktop and find the button that reads “Open in Visual Studio Code”. If it doesn’t, set your default editor to Visual Studio Code.
Once inside Visual Studio Code, you'll want to hit Ctrl+F5, or just F5. This will start compiling your code, which shouldn’t take more than a few minutes. Once done, it’ll boot up BYOND’s Dream Seeker, connect you to the local server, and automatically give you the highest permissions. This is because you’re doing everything in the debugging mode, which is quite nifty. This is arguably the simplest way to do it.
Once Space Station 13 has started, the Server tab located in the Stat-Panel will be a big help. From there, you can change maps and also skip the post-initialization wait time by clicking Start Now (or just type Start-Now in the command bar). Observe as a ghost and view your changes. Compiling is a good way to view the more subtle nuances that you weren’t able to pick up on through the editor. This includes (but is certainly not limited to): lighting, door accesses, mob interactions, and just figuring out if it looks good.
Simply follow these steps and you should be able to catch most errors mapping brings. The Pre-Commit Checklist, also provided in a dropdown below, best applies to outright Station Mapping and may not be applicable to ruins/away missions/shuttles/etc., but it’s still quite good to check as much as you can rather than assume that it works.
Are floors with or without air, as they should be? (regular or airless)
You can test this one out by looking for Active Turfs.
Does the area have an APC?
Does the area have an Air Alarm?
Does the area have a Request Console?
Not every area needs this, look at other stations.
Does the area have lights?
When you compile your map for testing, make sure the lighting is adequate. You don’t want any unwarranted “dark” spots in your rooms. If you’re going for “warm” or “cold” lighting, make sure it all matches.
Does the area have a light switch?
Only smaller rooms that get minimal traffic should recieve lightswitches. Areas like primary hallways should definitely not have them.
Does the area have enough security cameras? (Use the Debug Verbs for help)
Does the area have enough security cameras? (Use the verbs under Mapping for help)
Does the area have enough intercoms? (The verb Intercom Range Display in the Mapping Debug Verbs helps with this.)
Is the area connected to the vent air loop (distro)?
Is the area connected to the scrubber air loop (waste)?
Is everything wired properly?
Does the area have a fire alarm and firelocks?
Typically, doors leading into maintenance do not need firelocks. Do not place firelocks on doors facing the exterior of the station (like space or the planet).
Do all airlocks work properly?
Are accesses set properly on doors, buttons, etc.?
SpaceSmithers говорит: "I'm working on an Access Helper table which might help for this part. Also, I copied the checklist into a nifty dropdown seen above in the hackmd port."
SpaceSmithers говорит: "Looks good. A much needed update, I think. Side note: Keycard Auth grants auto-connect ability on Holopads. Smithers' Niche Funfact #113."
Are all items placed properly?
In summary, are your objects all on tables as needed? Are tables or other objects obscuring your vents/scrubbers?
Does the disposal system work properly from all the disposal units in this room as well as the pipes of which pass through this room?
Just throw yourself through a few disposals systems that seem to pass through the area you touched. Easy to forget.
Check for any misplaced or stacked piece of pipe.
/tg/station also lints for this to catch you if you forget.
Check for any misplaced or stacked piece of wire.
/tg/station also lints for this to catch you if you forget.
Identify how hard it is to break into the area and where the weak points are and balance the area accordingly.
For example, the Vault should be made of reinforced structures and electrified windows, the Kitchen should not. Be reasonable, not everything has to be an overly-secure structure to prevent the “tide” or other events. You will be vetted on this, just make your best choice.
Check if the area has too much empty space.
You don’t want vast, bald spots in your rooms that serve little purpose. Fill it up with stuff if you can, or just trim the fat entirely. Whatever works best for the station and your design.
Fix your errors, and run through this list again to double check, because chances are you missed something or you broke something else. That’s just how it is.
Doing so will save everyone a lot of headaches down the line. Specifically, yours, because you will have to fix your own shit.
In mapping, there are a lot of errors that may come up during Initialization of the world. However, we do check for a lot of these errors. Here’s how you can check these out and get them ironed out before we have to catch it for you.
Assuming your world is already compiled, wait for Initialization to finish, and then type in this verb into your chat box Get-Current-Logs. You should see a pop-up with a whole list of logs. You just want to go down this list and select the option that says map_errors.log. Go ahead and either “View” or “Download” this log file (“Open” doesn’t typically work for me).
We also now do this check for you on every pull request for station maps through our GitHub Continuous Integration process. I would advise checking this for non-station maps, though.
Once you've written the constructive title and brief description, hit "Commit to (your branch name here)”. If it says “Commit to Master/Main”, don’t hit that button because you’ll dirty the master branch of your forked repository. Make a new branch, and base it off what you’re currently on. If it doesn’t say that, everything’s just fine. Congratulations, you’ve “committed” your changes!
What if you didn’t like that, realize you made a typo, or just wanna go back? You can always just go back into StrongDMM to edit your map and make a new commit, but you can also go to the History tab, right-click on your commit, and click "Undo commit...", which will just undo your commit, and then you can make as many changes as you please, then recommit. This is one of the greatest advantages of Git, it has a powerful versioning system that you can easily use to hop from one day’s work to another.
If you’re happy, then seek out a "Publish branch" button. This will upload your branch to the remote (github.com).
Once all the "deltas are resolved" and what-not, a "Create Pull Request" button should appear on GitHub Desktop. Click that, and your web browser will open to GitHub. Ta-da, just fill in the template just like the descriptions in the contributing template say (including an image or two of your changes is always well appreciated), hit “Create Pull Request”, and wait for the feedback to roll through. I would advise viewing some example PRs, open up a few of them (if you haven’t already been tracking how people write Pull Requests) and try to learn well.
The /tg/ guidelines for Pull Requests can be found here. Another document with friendly advice from a coder can be found here.
You’ve done it! You’ve done mapping! I hope that wasn’t too painful, and the rest of this page (or the links below) will introduce you to some deeper contents that I briefly touched on in regards to mapping.
While this guide is meant to contain the bare-bones of information to get people started on mapping, the Mapping Reference Collection will contain a wealth of information for mappers. I heavily recommend reading this.
Stumped? Feel free to ask some more experienced mappers any questions on the /tg/ forums or the Discord
SpaceSmithers говорит: "Since almost all of Metacide's guide will be overwritten, I'll be sure to include a hyperlink at the top of the page that will take the user to an older version of the page with Dream Maker instructions. It could be useful to someone, I guess. You can always check out an earlier revision of this page to review older info from this draft."
SpaceSmithers говорит: "Double-check for missing or needed hyperlinks, and if more supporting images could be added."
The first step, then, is to be able to create your first few rooms. Select an open turf from the generic simulated floors, preferably /turf/open/iron. Each floor has a preset make-up of air on them, unless you use one titled "airless". Surround these floors with walls, and hey presto you have a room. Try sticking some tables in there, perhaps a vending machine or two.
Changes by Nudging or in Direction (dir) are reflected in the Prefab and Instance menus. All modified values are green so it's easier to identify them. Un-modified variables may be hidden, in which you'll need to uncheck "Show modified only" by clicking on the gear icon. Most wall-mounted machines on stations are shifted like this, and while they APPEAR to be on a wall, they are actually on the tile in front of it. Luckily, most wall mounts come with convenient directional subtypes in the object selector so you don't have to manually nudge them. Just don't go overboard with this, as every new instance of an object is added as its own entry in the menu, and when there are dozens of them it can get hard to remember which one you wanted(still relevant? I guess it clogs the prefab menu.). Once you've made your room you'll want to put lights in.
There is one uninvited guest here!
Important: While building your station you might find yourself in need of an object with a specific alignment (windows, pipes, cables etc) that does not appear in your menu. This is because BYOND does not simulate instances of an object other than its base state unless they are present on the map. You can generate them by right clicking an object and selecting "generate instance from state/direction". This function has an unwanted feature in which a generated object sometimes has a tag added automatically. These tags can cause error with certain features of the game during a round, and need to be removed. To check for it, right click an item on the map or in the menu, select "edit" and scroll to the "tag" line, which should be empty save for two doublequotes (""). If it's not (which is easy to tell since the tag is massive and bold, impossible to miss even scrolling at lightspeed), change it. Well maintained maps don't usually contain these, so you should be safe to copy-paste to your heart's content. As a tip, remember that all non-standard objects have their own entry in the menu, and having a tag is not standard at all for most object!
SpaceSmithers говорит: "At San's request, the Prefab section will be re-written to better suit modern expectations and definitions, and to account for SDMM."
So now we get to the basics of making a functioning room. First of all, you'll need to re-enable the area layer. Pick some area from the object tree, and cover your room in it. You can rename this area if you want (Really? We can manually edit the names of areas?), we'll do that later. Make sure the area isn't used anywhere else on the map. Each area should have one APC (Area Power Controller) in it. When creating an APC, the "auto_name" subtype will automatically name the APC to the area that it is in. Or, you can use the generic parent type and manually set its name variable. Other subtypes of APCs may include "unlocked" and "highcap". For testing, you might want to use a "highcap" variant that stores more energy, since we don't have a power source yet. Alternatively, you can change the "cell_type" variable to /obj/item/stock_parts/cell/infinite for infinite power (Source: It came to me in a dream. Untested.). If there are no directional types for the APC you're using, you can use the Nudge and Dir menu from earlier to adjust it. In a normal power system, you'd connect the APC up to all the others and the station's generator via SMES cells, but we'll do that later. For now you have a basic room that is powered and starts with enough air to breathe happily. You can put an air canister in if you think you'll consume all the oxygen, or somesuch.
Important Note: There are nudge_x and nudge_y variables in the editor, as well as various z-axis variables. Don't ever change these, they're not used in SS13 and break things.(Needs to be re-written for SDMM's nudge menu.)
To be able to actually spawn into a room, you'll want to place spawners. You'll see these as the big red X symbols on the default map, for each role. There are also blue Xs for xeno spawn locations (pretty sure spawners now use fancy sprites for their respective spawns) and the spawns for all latecomers on the arrival shuttle.(old/irrelevant, shuttles are not placed onto station maps anymore.) Stick in a spawn_late somewhere in your room for now.
(may change for redundancy reasons)
To actually test your map and be able to screw around in it as an admin, you'll have to compile it. The easiest way to do this is through Github Desktop, where you will open the repository in your external editor by clicking the "Open in Visual Studio Code" button. If this is not present, change your default editor in the options to Visual Studio Code. In Visual Studio Code, press F5 to both compile and launch the game. Full permissions are automatically granted as "localhost".
The best possible training is through experience. From here on out, you can make whatever you like, really. Copying the default map and working out how everything works isn't too hard and is fairly rewarding. You could just tweak the default one if you like. The first thing I made was a small shuttle - you can see this at the bottom. Just tweak and add stuff and you'll work out how almost everything works fairly easily. Poke around with both Github Desktop and StrongDMM. For explanations of wiring, piping, and atmos, ask away on the mapping channel of our discord or on the forums.
SpaceSmithers говорит: "This section will be overhauled. It may not be exhaustive, however. It will probably just describe key points such as monitored meters, mixing, common errors, etc. Similar to how it is currently."
Each station should have a full set of these - or at the bare minimum, one for N2, one for O2 and a third tank to filter dangerous gases into.
Файл:Atmos mapping.jpgLeft to right: N2, O2, Airmix. The canisters inside are just for decoration.
Each gas tank needs:
Outside: A tank computer and a gas filter to pick what gases will be filtered into it.
Inside: A gas injector (input), a vent pump (output), a gas sensor and a specific turf.
The tank computer controls the input/output and receives data from the gas sensor.
The specific turf creates the gases that will be inside each tank - the gas canister is just for decoration.
Let's take a look at the MetaStation N2 tank:
Tank computer: /obj/machinery/computer/atmos_control/tank/nitrogen_tank
SpaceSmithers говорит: "IMPORTANT: I don't want a repeat of the old guide; this is not the place to dump random shuttle code documentation. This is a mapping guide. Keep things simple and clear for mappers. If you want to document shuttle code, comment in the code itself or make a separate, dedicated wiki page."
There are two types of shuttle docks:
stationary == places where the shuttle can dock
mobile == placed on shuttles
Mobile ports will dock directly on top of stationary ports.
Sometimes listed as its own type of port, transit ports /obj/docking_port/stationary/transit are automatically generated in a dedicated transit z-level, so you don't have to worry about that.
For places like arrivals and departures, we will have to add a /obj/docking_port/stationary for each, and manually edit in some variables for them to work. It's a good idea to have an updated, pre-existing map open in your workspace to reference or copy.
Before we do anything, lets identify some of the variables we will likely be seeing.
dir: The direction of the port.
If a shuttle's mobile docking port direction is different than the stationary docking port's direction, the shuttle and all items on it will be rotated accordingly.
This rotates the entire plane. Other variables, like width and height, are relative to this direction. This means that on a docking port facing west or east (dir = 4 or 8 respectively), height will be horizontal on the mapping workspace, and width will be vertical.
height: The size of covered area, parallel to dir.
width: The size of covered area, perpendicular to dir.
name: A name string for the port. This name will be visible on shuttle consoles, Shuttle-Manipulator admin verb, and during debugging.
roundstart_template: The template that will spawn on this port when the map initializes. Used on docks for arrivals, escape pods, and more.
shuttle_id (formerly id): Identification variable. Mandatory for certain ports.
IMPORTANT: For standard stations, you MUST use these exact strings for the listed areas, or else they will not function. Stub? double-check all instances of shuttle_id in case i missed some.
Arrivals dock: "arrival_stationary"
On-station dock for centcom ferry: "ferry_home"
Emergency Shuttle Dock: "emergency_home"
Cargo Dock: "cargo_home"
On-station Whiteship dock: "whiteship_home"
Auxiliary Base Construction: "aux_base_zone"
A stationary port is strict with its width and height variables when deciding if a shuttle can dock there. They should generally be greater than or equal to the dimensions of the shuttle that wants to dock. If a shuttle is larger than the stationary port's dimensions, it will outright refuse to dock. When testing your map, debug/admin tools such as the Shuttle-Manipulator verb will be a tremendous asset.
The stationary ports for the labor shuttle, mining shuttle, public mining shuttle, and the auxiliary base zone each have their own, unique subtypes. These are presets and should not be edited, except for their direction.
Escape pods utilize two unique stationary port types for each pod; one is the escape_pod subtype to spawn the pod itself (which should go unedited except for its direction), and also the random subtype. When the map initializes, the random ports are automatically teleported to a random spot in lavaland (or the icemoon if using the respective icemoon subtype). These spots are reserved for emergency launches when the station is on red or delta alert levels. Random ports need a shuttle_id for pods to dock, and generally use the following naming scheme: "pod_lavaland", "pod_2_lavaland", "pod_3_lavaland", and so on.
Most stationary ports generally face the shuttle or face away from the thing the shuttle docks with, but not always, as it depends on the position of the mobile port on the shuttle. If you're unsure where to place the docks, its always a good idea to use another pre-existing map as a reference. Also remember that mobile ports park directly on top of stationary ports, and will also rotate to adopt their dir.
The mobile port variables are quite different from their stationary counterpart. Lets go through them:
The width, height, dwidth, and dheight are all generated automatically.
Many existing shuttles in the codebase do have these variables edited in despite not being required.
name: Name your spacecraft! Will be printed in consoles and also station-wide announcements if its an escape shuttle.
preferred_direction: The direction the shuttle appears to travel in. Changes the parallax animation.
port_direction: Relative direction of the docking port from the front of the shuttle. If you rotate the ship so that it points north, what direction will the mobile port be facing?
You should cover your entire shuttle with one or more proper subtypes of /area/shuttle, especially if its an escape shuttle with a brig on it. This ensures that everything works and moves properly. Otherwise, your shuttle may encounter unwanted errors or claim turfs within the bounding box that shouldn't be moving with your shuttle.
Some shuttles should be using specialized subtypes of the mobile docking port, like arrivals and emergency shuttles. Be sure to check these subtypes before settling with the generic one, or else they may not work as expected.
This section can get a bit confusing at first, but it will get better as it goes along. The area of the docking port is not centered at the dock itself; at first, the dock will be at the (0,0) coordinate of the area, which we will label as the origin point. Its important to note that the entire grid, along with the origin point, will rotate with the docking port's direction (dir), just like other variables.
Port Dir
Origin point (0,0) location
1 (North)
Bottom-left
2 (South)
Top-right
4 (East)
Top-left
8 (West)
Bottom-right
SpaceSmithers говорит: "This table (that I, myself, made) might be misplaced or outright unnecessary. I'll come back to decide its fate at another time."
dwidth and dheight define the relative position of the docking port in its own covered area by measuring from the origin point (0,0). Since we're calculating the distance from the origin point, a (0,0) coordinate, the tile with origin point itself does not count for these measurements.
To the average mapper, all of this technical jargon is incomprehensible. We'll use some visual diagrams to help explain what it all means.
Docking port reference guide. Click to expand.
Displayed is an example port facing in four different directions. We can see how everything rotates as the port's dir changes, such as width and height, its delta counterparts, and the tile marking the (0,0) origin point. Lets look at dwidth and dheight and note how it measures from the origin point (0,0) to the docking port, and how the tile with the origin point is not counted. Measuring these tiles for this example port, we see that dwidth is 3 and dheight is 4. If there's anything you should pick up from this section, reference this image to determine where and how you should be measuring.
Metastation's Arrival Dock.
Lets apply this knowledge. Here in this image we have Metastation's arrivals dock. You can see the area it covers with its width and height variables. Since the port is rotated to the west, width, height, and the origin point (0,0) are all rotated as well. In the image, you can see how dwidth is measured from the (0,0) tile. The dheight variable goes unedited in this case, because the dock is 0 tiles away height-wise from the (0,0) point, and the default value is already 0.
Setting the offset for where the docking port is relative to the covered area is important for making sure shuttles can fit within the respective bounds. Without dwidth and dheight, the dock would always be stuck in the corner at the origin point, and certain shuttles would fail to dock properly. This is especially true for docks that support interchangeable shuttles that differ in size, like departures.
SpaceSmithers говорит: "Work in-progress. Documented from maps.dm, map_config.dm, and more. Certain entries could use examples or more depth."
Your map should come with a JSON configuration file placed in the "_maps" folder, especially if its utilizes Multi-Z. This config file points the game to where your map is located, the map's name, what shuttles will be used, and more. All listings will be case-sensitive. Lets go through some of the more common configuration types.
version: Version tracking was introduced in pull #53663, but goes unused in the /tg/ codebase. Set this to "1" like every other map.
map_name: The official name for your map. Will be referenced in the stat-panel or external hooks like the Discord bots.
map_path: The folder where the map .dmm file is located. The "_maps" folder will be the root, so this string should look something like "map_files/YourStation",.
map_file: The filename for your map that is found in the above folder. Example: YourStation.dmm.
shuttles: This entry will be a list. These are the shuttles available for changing:
cargo: The cargo shuttle.
ferry: The ferry generally used by admins that travels between Central Command and the main station during the round.
whiteship: The whiteship that will spawn in space somewhere for those explorers.
emergency: The Escape Shuttle. Remember that this is interchangeable during the round via communications consoles, unless allow_custom_shuttles is set to false.
planetary: If the map is planetary, set this to "1".
space_ruin_levels: Planetary maps should include this and have it set to "0"
space_empty_levels: Planetary maps should include this and have it set to "0"
job_changes: This will expand into a list consisting of job titles, which will list again into changes for that job. Some jobs like Captain and Cook have unique modifiers exclusive only to them.
Captain
special_charter: Adding this variable will replace the charter with a banner representing the claim to a celestial body. IceboxStation has this set to "moon", while Kilostation and Tramstation have this set to "asteroid".
Cook
additional_cqc_areas: Extra areas for the Cook's close quarters combat abilities. An example entry would be ["/area/station/service/bar", "/area/station/commons/lounge"], extending the range to both the Bar and the general Lounge areas.
The following modifiers can be used for any job, such as Station Engineer or Prisoner.
spawn_positions: Sets the amount of positions that can be filled at roundstart.
total_positions: Sets the total amount of positions available after roundstart. Roundstart positions will still be filled to the number defined in spawn_positions, even if this variable is set to a lower number. If both of these variables are set to zero, the respective job will not be listed in either preferences or the late-join menus.
additional_access: Grants extra access to the respective job. Grant the Clown armory access. See jobs.dm for help with access.
additional_minimal_access: Grants extra access to the respective job when the station is under-staffed. IMPORTANT: These are two separate lists and do not stack. This means that during a skeleton crew, only the accesses listed here will be granted, and those under the regular additional_access will not carry over.
TEST: Setting traits in .json will not retain default Z-level linkage? See this PR fixing Kilostation's space exploration by manually re-adding z linkage.
Defines listed under trait are for configuring the map's Z levels. For example, designating where levels of a Multi-Z map are relative to the others, enabling weather, mining, ruins, and more. Important: If you are adding/modifying any z-trait to a config file, you must include Linkage because the default is not retained, resulting in an 'invisible wall' effect to the map's edges.
trait:
"Linkage": Defines how z-levels are traversed at a map's edge. Stations in space use "Cross", while planetary stations are set to "null". When nulled, hitting a map's edge does nothing.
"Secret": Boolean. Does this z-level prevent ghosts from observing it?
"No Phase": Boolean. Forbids teleporting and such. True for the CentCom level.
"No X-Ray": Boolean. Forbids xray, meson, thermal vision.
"Bombcap Multiplier": Number. Multiplier for the bombcap. KiloStation, a lower-pop map, has this set to 0.7.
"allow_custom_shuttles": Boolean. If set to false, the Purchase Shuttle button on communications consoles will be removed.
Multi-Z: turf definitions and z-level and traits are required for Multi-Z maps.
SpaceSmithers говорит: "I'll add a section showcasing one or more full config JSON files to demonstrate proper formatting, with comments explaining their functions."
SpaceSmithers говорит: "Untouched section. It may become overwritten or obsolete."
Multi-Z is a feature which allows a station map to have multiple Z-levels layered on top of each other, behaving as a single station with multiple floors. This feature is currently in use on the Tramstation and IceboxStation maps. A station's multiple levels can be bundled into one map file, or in several seperate files. The traits section of the map configuration json tells SS13 how to link the maps together.
If you are building station rooms on a lower Z level, ensure that a turf of some type is mapped on the Z-Level above the room to function as a “ceiling”. You can check the coordinates in the Mapping Editor to ensure you map over the correct dimensions of the room. When running the server to test the map, you can go to the Debug tab and hit “Mapping Verbs - Enable”, go to Mapping tab and hit Show ATs. If the list is empty, you are good.
Earlier versions of Multi-Z did not require a baseturf to be defined under each Z-Level’s traits in the config JSON. Each level must now have a baseturf set.
The maploader will not load and link a map file without areas or turfs defined. An empty space (nothing but baseturf) map will runtime. If you are adding a Z-level to an existing map, be aware of this.
SS13 will cache a map’s configuration JSON file in data\next_map.json. If you alter a map’s configuration JSON locally, you must also clear this file by using the change-map verb in game, deleting the file, or replacing it with your updated JSON file
.
(assuming you've downloaded it) under the dropdown. A prompt from the application will open; find a clean folder to locally copy your repository and click Clone. This may take a few minutes. Another prompt will appear asking: "How are you planning to use this fork?" You will want to select "To contribute to the parent project". This will make creating Pull Requests easier.
. For every individual project you work on and submit a Pull Request for, you want to be on a brand new branch. Feel free to name it whatever you want, can be as goofy or as organizational as you want. It’s your fork, after all.
stationary == places where the shuttle can dock
mobile == placed on shuttles
docking port, and how the tile with the origin point is not counted. Measuring these tiles for this example port, we see that 