---
# System prepended metadata

title: Mapping Guide

---

This is not going to be an absolute comprehensive guide!!
San, a /tg/station Maptainer and Maintainer has a guide/reference book that's quite useful to look at which can be found [here](https://hackmd.io/@tgstation/ry4-gbKH5#san7890’s-Mapping-Reference-Collection-WIP). It'll cover certain things in more detail than what this guide will do.

First and foremost, you **do not** need to be a coder to map. However, it does help to know how to read typepaths (which'll be explained later).

# Github Application
You need a Github interface to be able to start contributing with mapping. [Github Desktop](https://desktop.github.com) is the quickest and easiest way to get started. 

After downloading Github Desktop, this is where your mapping journey will begin.

1. Make a Github account, or log in to it if you aren't already

Obvious step, but make sure you're logged in or create an account to get started.

---

2. Fork the TaleStation repository

![](https://hackmd.io/_uploads/SkbbRXXoh.png)

![](https://hackmd.io/_uploads/rkmXAm7on.png)
*In this specific example, choosing an owner only appears if you're apart of an organization. In this case, a fork has already been created for this account.*

"Forking" is best described as "copying" the repository. This usually takes a moment to get started. You can call the fork whatever you want, as well as keeping, changing or reemoving the descrption. You'll also have the option to JUST copy the `master` branch. It's recommended to do this so your fork doesn't become cluttered with branches. 

---

3. Use Github Desktop to "clone" this fork to your local computer

![](https://hackmd.io/_uploads/BkXQkVmsh.png)
![](https://hackmd.io/_uploads/rkGBk4Qoh.png)

From here, you can choose where you want to put your repo. It's best to keep all your SS13 repos within one folder, or organized together. Hey, it's good to keep things organized!

From there, you can now start contributing, for the most part. 

![](https://hackmd.io/_uploads/B11feVXi3.png)

**!! NEVER MAKE PRS OFF YOUR MASTER BRANCH UNLESS YOU WANT TO HATE CONTRIBUTING !!**

This happens, sometimes, and can create a nightmare for you to fix. Always, ALWAYS, make branches when you want to make and push changes. It's **OKAY** to edit files on your master branch. **DO NOT** confirm these changes however. Do not commit them, do not push them.

# Your First Pull Request
Once you've made a branch on your local machine, made some edits, commited them and pushed them to your local, now you're ready to start contributing fully.
Just something of note, Pull Requests are always referred to as "PR(s)"

*For more information on how to push changes to GitHub, please ask! Not everyone uses the same GitHub interface, so an example would not be sufficent information.*

1. Navigate to the TaleStation repository (or your fork)

It doesn't matter where you go, since it'll prompt you no matter what.
![](https://hackmd.io/_uploads/H190LGts2.png)
*From here, click "Compare & pull request"*

---

2. From there, fill out the PR template

It's helpful to name your PR something ABOUT your changes/idea. Long, obtuse PR names are really annoying. Try to keep them short and sweet if you can.
![](https://hackmd.io/_uploads/r13BwzKo2.png)
*In this example, this PR was made off the Master Branch of TaleStation. When comparing `base:master <- compare`, it'll show your fork and branch instead. More options will appear if you have commit access to other forks.*

Here are some helpful titles for your PRs:

- Map PRs should have their map name in the header; [PubbyStation], [LimaStation]
- If not map specific, you can use; [Shuttles], [Ruins] 
- Putting [NO GBP] in your title will flag your PR as unable to gain or lose GBP. This is usually when you're fixing an error you made.
- Putting [DNM] in your title will flag your PR as "DO NOT MERGE". Consider drafting your PR (see below this list) to ensure Maintainers don't accidentally merge your PR.

![](https://hackmd.io/_uploads/ryirOGYo2.png)
*The draft button is located under the reviewers tab*

![](https://hackmd.io/_uploads/SJTwdGYjn.png)
*Undrafting your PR can be found at the bottom, below intergrations*

---

3. You can view your changes before creating your PR, as well as commits.

It's helpful to know what you've changed, as sometimes things that weren't meant to get changed get in. It happens!

![](https://hackmd.io/_uploads/H13GYfYsn.png)
*In this screenshot, split mode is being used to view the "diff" (difference in code). Your view be unified (where the changes are shown together). This is entierly preference.*

![](https://hackmd.io/_uploads/rkpTvvo_a.png)
*In this screenshot you can see the commits on a branch as well. They'll always be visible under the PR template. You can also see anyone else if they're contributed to the branch.

# Github Terminology
There was some jargon used up there. It's hard to explain things if you don't understand the words! That might be why some of those sentenaces were wonky to read. Here's some common terminonolgy used:

## Commit

A commit is basically some sort of "changes". These are viewable on Github, pending you "pushed" them to a branch.

![](https://hackmd.io/_uploads/HkyYlEQo2.png)
*For example, these are all commits on the Master Branch of TaleStation*

## Master / Master Branch

Master/Master Branch (now called Main on newer repositories) is where the "game" is per-se. Master is what everything (usually) is merged into.
This may not be the case when you fork if you're strictly copying the "master" branch.

## Push / Pull

"Pushing" is what it sounds. You're "sending" your changes to your branch. After you've committed them, they become "staged". You can either revert the commit, or push them.

"Pulling" is also what it sounds like. You can "request" changes from a branch (NOTE: This is not the same as "requesting changes" on Github). This is how you can update a branch (by pulling master into your branch, thus, updating it!).

## Merge Conflict

A Merge Conflict is basically a "your changes" vs "our changes". Merge conflicts for maps will be discussed later in detail, but this is all you need to know for now.

## Branches

Think of Branches as a different copy of master. Every. Single. Time. This is how you can make changes and contribute. Each "branch" can be a copy of one another (usually master). Never PR using the same branch all the time. Make new branches everytime you go to contribute!

## Typepath(s)

This isn't really a Github applicable term, but there's no where else to put it. A typepath, for mapping, usually refers to an item. A table, for example, would look something like `/obj/structure/table`.

# StrongDMM
StrongDMM, commonly called SDMM, is the mapping program mappers use. Yes, Byond comes with a built-in mapping tool. Please don't use it.

You can find a download [here](https://github.com/SpaiR/StrongDMM/releases) under its releases.

You can also find a [Getting Started Guide](https://hackmd.io/@tgstation/SyVma0dS5#StrongDMM-and-You-The-Basics). This'll help explain the ins and outs of SDMM.

However, there are two "different" versions of SDMM, referreed to as SDMM 1.0 and 2.0. There is some feature differences between the two (1.0 has built-in updatepaths, while 2.0 supports multi-z rendering). Hot keys are also different, so consider committing to using one over the other and not both.

# Mapping Terminology
Mapping uses distinct terminology like Github. It helps to understand what some words might mean.

## Subtypes
A subtype is a "new" item created from an old item. For example, `/obj/item/couch` is the typepath for couch. `/obj/item/couch/bench` is the typepath for bench. `Bench` inhereits all the properties from `couch`, so, the only thing that would need to be changed are the name, icon and description (if applicable). Other variables may need to be changed if needed.

![](https://hackmd.io/_uploads/rJnO3pwin.png)
*Here are some subtypes for request_consoles. Directionals would spawn the item already nudged in the indicated direction.*

## Variable Edits / Var Edits

Commonly referred to as Var Edits, Variable Edits is the term given to editing the variables on an item. It should be noted, however, extensive var edits is **prohibited** and you should be subtyping things. In some cases, some items (buttons, cameras) have extensive var edits. This is fine. However, if you were to var edit a door and give it a new icon, you would be asked to subtype it.
Its bad practice to extensively var edit something to great lengths.

![](https://hackmd.io/_uploads/SyzD2Tvin.png)
*Here's some var edits for a Request Console in the Bridge Officer's office.*

## Turf

Turf refers to the floor and walls. There's two types, `open` (passable) and `closed` (non-passable). Var editing these (outside a few niche cases) is strictly prohibited, and subtyping them is absolutely necessary.

![](https://hackmd.io/_uploads/SyN4n6win.png)
*All the open and closed turf of LimaStations SM chamber. Note the outlines for the area defines.*

## Area
Area is what it refers to. 

![](https://hackmd.io/_uploads/Skiy2pDj2.png)
*Areas take controll of everything inside them. Thats why some SM setups, like this one on LimaStation, has one area leaking out. Its so the Air Alarm can control the vents in the chamber.*

# Mapping Tools
Mappers have a few useful and handy tools at their disposal. The two tools they'll be most familiar with is `UpdatePaths` and `Resolve Map Conflicts`.

There are also some other, lesser used tools for some edge cases, such as `I Forgot To Map Merge` and `Run Before Comitting`. These were tools used to convert how maps are saved in code, before SDMM. When mapping in Dream Maker, Byond saves maps as [Ascii art](https://hackmd.io/@tgstation/ry4-gbKH5#BYOND-level-Explanation). SDMM saves them in "keys", which is what these two bat files do (converting them). SDMM does it automatically, so these files aren't required/used as much anymore.

### UpdatePaths
/tg/station has a complete guide on how to use UpdatePaths [HERE](https://github.com/tgstation/tgstation/tree/master/tools/UpdatePaths). This guide will not cover it indepth, but a general glance of how to use it.

UpdatePaths is used to change "A" to "B" in a very simplistic term. It can, however, be much more verbose than that. It's used to update a typepath to a new one, in the event someone changed the old typepath. This helps mappers with open map PRs to reduce any regression or accidental deletion that may happen.

The most basic syntax for an updatepath is as follows

```

/obj/fo/bar : /obj/item/foo/bar

```

In this instance, `/obj/fo/bar` is being changed to `/obj/item/foo/bar`. In /tg/s guide, it'll go over much more advanced syntaxs, how to target specific variables and so on. It's recommended to look over that to get a better understanding of this tool.

### Resolve Map Conflicts

*This section would benefit from screenshots! Ping Jolly66 on the Discord if you wish to contribute*

Resolving map conflicts are usually automatic and easy. Sometimes, you run into problems.

san7890, a /tg/station maintainer has written a guide on this topic, which goes more in depth. You can find it [HERE](https://hackmd.io/@tgstation/ry4-gbKH5#Assured-Merge-Conflict-Resolution)

1. First, you must navigate to `../name_of_repo_on_disc/tools/mapmerge2`

![](https://hackmd.io/_uploads/BJxcOviO6.png)
*This is the contents of the folder.*

2. Secondly, run `Resolve Map Conflicts.bat`

![](https://hackmd.io/_uploads/BkJ3dws_a.png)
*Resolution of conflicts is usually automatic and MOST small changes can be done automatically by the script.*

3. Third, a terminal will open up. If all goes well, the terminal will display as such. If not, it'll display issues.

*This section would benefit from a screenshot. Ping Jolly66 on the Discord to contribute!*

4. Fourth, you will need to open the specified map files. Similar to code merge conflicts, there will be a visible "your" vs "our" changes. A merge conflict marker will be put between multiple sets of objects. This is the merge conflict that must be solved manually. If confused, consult a Maptainer.

*This section would benefit from a screenshot. Ping Jolly66 on the Discord to contribute!*