IntroductionThis is a continuation of my thread "How 2 Code 4 Bay". Apparently some people have trouble figuring out mapping. This short guide aims to help, and show people that mapping is actually pretty easy once you get the hang of it. I will assume that you are already familiar with git and github in general. If not, see the previously mentioned guide that should provide fairly accurate quick start guide on how to set up your local development environment, using SourceTree as git client. For the purpose of this guide, i will assume that you already have a branch set up in which you can perform your changes. TheoryFirst some boring theory, but please bear with me. Map files are, essentially, large text files stored in pretty specific format. First we have a set of tile definitions that acts as a dictionary. In simplified way, this dictionary tells the game that "aaa" is, for example, an empty space tile. "aab" can be a reinforced wall tile with south facing intercom on it, and so on. Each unique tile by contents has its identifier in the map file. This part is followed by actual map, that contains tiles represented by the keys i mentioned before - these look like long rows of text, for example "aaaaabaaa" would, using our above example, be a reinforced wall with intercom, surrounded by two space tiles to the left and right. MapmergeNow that we know the theory, it is time for me to introduce you to your new friend - the map merge tool. Due to nature of maps which i mentioned above, even a small change can lead to conflicts when multiple people touch the same map file. To minimize risk of conflicts (there is not much that can be done when multiple people touch the same tile), few mapmerge tools exist. The newest one is JMerge, a mapmerge tool written in Java, that can be found in tools/jmerge/ folder. The usage is pretty easy. Before you make your changes, run the "Prepare maps" script, and once your changes are performed, run the "Clean maps" script. While it is very easy to do, failure to run this script will probably result in your eventual PR being rejected, if you commit an uncleaned map file, so it is important to remember to run these scripts every time you make changes. While it is possible to recover changes when you forget to do so, it is a bit harder so i won't be covering it in this basic guide. Editor Thankfully, editing maps is fairly easy. BYOND comes with decent built-in editor for these. Use the code editor as usual, and open one of the map files you want to edit. The interface is fairly intuitive. To the left, where files usually are, is the item browser. You can search for various objects in here, using the type path. There is also a search bar, however keep in mind that it works on type path of the object you are searching for, not on the object's name. You can click any of the objects in this browser to select it, which will show some information and allow you to pick a specific instance of this object to map in through the detail panel right next to the item browser. Keep in mind that these instances may look the same, but they differ in some way - in the form of manually edited variables. A nice example are APCs - which usually have four instances, one for each direction. This detail panel also allows you to select your drawing mode - this is done by those three little buttons under the list of available instances. The map itself can be moved around either with arrow keys, scroll bars around the edges, or by interacting with the "mini-map" view. Keep in mind that things in general look smaller in the map editor than how they feel in the game - that is due to the fact that game has certain level of zoom, while the editor is limited to 50% or 100% zoom levels. Take a while to experiment with the map editor. Fairly easy tasks include mapping in a new tool or object, such as a missing light or a piece of furniture. Some tasks are trickier, and require you to edit the variables on that object. This is done by selecting the object via right clicking on the tile that contains this object (note: some objects are offset by a tile or two, so you may have to click on adjacent tiles as well), and selecting the edit option. This will edit this particular object's variables. Tasks that require this are of moderate difficulty, such as linking airlocks or remote control buttons. You can also, for example, change access restrictions on airlocks. High difficulty tasks are generally renovations of any kind. This usually means you have to touch pipes, wires, and areas. Before you do this, i personally recommend playing in engineering, so you know how power and atmospherics works - it helps a lot, as i might not explain all that you are going to need in this guide. PowerPower is fairly straightforward to map. First of all, remember that every area needs a single APC. Multiple APCs per area won't work, and no APC is not recommended either as that will mean all electronics in the area won't work (though there are some logical exceptions, such as the outer hull which is technically an area as well). If you know the area has high power drain, you might want to use one of the higher powered APC variants - these start with better cells. For extreme importance areas, use the "critical" variants of APCs, which are more resistant to electrical storms, grid checks and similar effects. Typical usage includes telecommunications or AI chamber. SMESes are grid-level power storages. Usually you won't have to touch these unless you are making larger changes. There's multiple types of SMESes defined, so pick one that most suits your application. SMESes take power from one or more terminals that have to be manually mapped in, and output it to a knotted wire on the tile they are on. This all is connected by cables. Cable colour scheme is pretty straightforward as well - red is the main network, connecting power source SMESes (engine, solars) to substations. Yellow cables connect power generators (TEGs, solar panels, PACMANs,...) to their respective SMES storage. Green are subgrids, connecting substation SMESes to APCs around the ship. Cyan cables are smaller sub-grids, such as Atmospherics, AI core, Telecommunications, and Engine. Try to respect this color scheme when mapping cables. To connect a machine, there has to be a cable "knot" underneath it. A knot will connect to all other knots on the same tile, however it will not connect to smooth cables that run through the tile the knot is on. AtmosphericsAtmospherics is another fairly important thing when mapping. Each area should, ideally, have a vent and scrubber pair or multiple (use your common judgement, depending on the size of the area and how frequented it is). Furthermore, each independent section has to have its own air alarm (so if the room is split in two by emergency shutters or doors, both sides of the room need one). Vents take air from connected pipe line and inject it to the room. They are, in fact, pumps so they can refill the room even when the pressure in input pipe line is lower than pressure in the room. By default they are set to target pressure of 101kPa (one atmosphere). Vents are usually connected to the air supply pipeline (blue offset pipes). Scrubbers clean undesired gases from the environment and output them into the pipeline they are connected to. What gases are filtered out can be changed through an air alarm. They should be connected to scrubbers pipeline (red offset pipes). Always double check that you have no openings left in the pipelines once you finish mapping them. A "dead end" without end cap or any other kind of device at the end will result in gas leak. Save frequentlyThis is very important, and i cannot stress this more. Save your work frequently as the editor lacks an auto-save feature. It is sometimes prone to crashing, which would result in loss of your work. You can use the CTRL + S shortcut for this. There is also a CTRL + Z shortcut for "undo", which is useful as well. ConclusionHopefully this guide helped you. I didn't cover all topics - as mapping is very broad, however you should be able to make at least rudimentary map changes now. Keep in mind that when you are in doubt you can always ask here on the forums, or on #codershuttle IRC channel, alternatively feel free to send me a PM with your question, i will try to address it if possible. All you have to do now is to run the map cleaning script, and commit your changes as usual. As a last recommendation, if you are making larger PR with a complex feature, i recommend separating the map change part and code part as much as possible. Map conflicts still tend to happen easily, and every hour of your PR being open is a hour in which a conflicting PR can be merged. If you think your PR may be contentious, i recommend trying to get an approval for the code part, before you even work on the map part. Even better, if situation allows it, try to code it in such way that will allow you to PR the map changes in an independent PR. DisclaimerThis guide may eventually become outdated. I am going to try to keep it up to date, but i am giving no guarantees. When in doubt, ask the development staff. Suggestions on how to improve the guide are welcome. Forum moderators: I took the liberty of stickying this so its next to the coding guide's thread, feel free to remove the sticky status if you feel its unnecessary.