User:Vire/Guide to Mapping Environment

A guide to minimizing tears

The existing documentation for mapping on tgstation was written by many people, with no particular level of knowledge in mind, and has become a collection of random anecdotes from various mappers. While full of useful information, these guides do not tell someone how to get started and often reference tools that are now obsolete, broken, or should not be used. This guide is intended for new mappers who have not used any SS13 development tools before, and for coders who are faced with the indignity of having to edit maps.

Although this guide is aimed at tgstation, most of the content should be applicable to most tg downstreams, or any other codebases which use the TGM map format.

This will be for modern Windows. If you are using Linux, you are capable of figuring this out on your own.

https://tgstation13.org/wiki/Guide_to_mapping

Installation of the Necessary Software

This will assume that you have played SS13 recently, and therefore have a working version of BYOND installed which can compile tgstation. If your BYOND does not work for some reason, consult #coderbus for the current working version and grab it from the BYOND website.

1. Get a Github Account

Head over to Github and register an account. All tgstation development is done on github. You will need an account and a fork of tgstation on the site to contribute. Under Account settings -> Email Settings github will give you a "@users.noreply.github.com" email address. Copy this to a notepad, as you will need it to set up your git client in the next step (PICS NEEDED)

After you've collected your noreply email from your github settings, navigate over to the tgstation repo and click the fork button in the upper right hand corner of the screen. This will create your personal fork of tgstation at http://github.com/YOURUSERNAME/tgstation. This is where you will push your changes before creating a PR. (PICS NEEDED)

2. Install Git

Git is a piece of version control software. It allows many people to work on a project like tgstation at the same time without overwriting each others changes, or breaking the codebase. Git is a piece of command line software, but there are many guis that wrap around it. If you have not used git before, you should pick one of the recommended guis. If you are a coder, you likely use git bash, or already have git set up in your preferred way.

You need to set up your name and email address that you will use with git. These will become part of the public commit history of the project. If you are not comfortable using your regular email, use the "@users.noreply.github.com" github supplies you with when you create an account (Under Account Settings -> Email on github.com).

A word of caution: Even though a gui is recommended, particularly when it comes to mapping, there are steps which are best done in the command line (Git Bash). All GUIs come with git bash, so you do not have to install it seperately. Most often times when asking for with git issues, it will be provided in the form of git bash commands. These commands are universal between git installations, where the steps in a UI might be very different depending on which UI they picked. In particular, resolving merge conflicts with maps should be done in git bash.

TODO: Setup instructions for each recommended git client

Recommended

(PICS NEEDED)Github Desktop - Github desktop is a free, basic git gui intended to work with github.com. It is a good choice if you have never used git before and have no idea what you are doing with it.

(PICS NEEDED)Fork - Fork is a Commercial Nagware git gui. It has an extremely simple layout, making it very easy to see what you are doing, and to learn git.

Use with Caution

(PICS NEEDED)GitKraken has a very loud UI which frequently confuses new users, while also being very slow. We often see

Git Bash - Command line git. This is installed with most GUIs and can be installed alone as well. Many git tutorials only provide instructions for git bash, because they are the same on all installations.

Not Recommended

(PICS NEEDED)TortoiseGit Used to be recommended in some older guides before better git guis came out. Now a bit of a meme.

3. Clone tgstation locally

Once you have installed git and set it up, clone https://github.com/tgstation/tgstation/. By default on windows this should be C:\Users\YOURUSERNAME\tgstation, but you can place the tgstation folder wherever you prefer.

You now should have a full set up of the three repositories needed to work on tgstation:

• A local repository on your hard disk default C:\Users\YOURUSERNAME\tgstation
• A remote repository at github.com/YOURGITHUBNAME/tgstation
• The upstream master repository at github.com/tgstation/tgstation

Depending on the git gui you chose, you may need

4. Install Visual Studio Code

VS Code is an open source text editor created and distributed by Microsoft. It is available for Windows and most Unix-like operating systems. VS Code allows the use of a number of plugins which make working with DM code much easier. While mapping generally doesn't involve editing code files, from time to time you will need to read them to find a repathed objects' new path, to create a map json file, or to edit map related settings.

Once you have installed VSCode launch the program, choose File -> Open Workspace and open the folder you cloned tgstation into, by default C:\Users\YOURUSERNAME\tgstation. VS Code will ask you if you trust this repository, and wish to install its recommended tools and plugins. Choose yes. (NEED PICS)

5. Set up Mapmerge

This is the most critical step in the entire process. If you do not set up mapmerge2 properly, it will not run on each commit. You WILL hard conflict on each minor mapping change and you WILL have to redo your changes 25 times before your PR gets merged.

Mapmerge2 is a set of scripts created by Spacemaniac to make dealing with map files less terrible. Mapmerge2 has several functions, the two most important of which are to force map files into the TGM format (this is now directly supported by most map editors), and to automatically resolve certain merge conflicts that commonly occur with map files.

Open your local repository (default C:\Users\YOURUSERNAME\tgstation) and navigate to tools\hooks and locate the install.bat file. Double click to run and it will add mapmerge as a pre-commit hook to your git environment. This means that every time you commit or merge, mapmerge will be run on any changed map files automatically. (NEED PICS)

A word of caution: mapmerge2 does not always intelligently resolve the three way diffs in map conflicts. It will sometimes revert changes in both branches. This seems to be more common in very large, very complicated conflicts. Be aware of the size and complexity of the merge you are handling - a department revamp is more likely to hit this and someone moving an air vent. Visually review the changed map in your map editor before pushing changes.

6. Download StrongDMM

(NEED PICS) Created and maintained by SpaiR, StrongDMM is the recommended, modern map editor for .dmm files. This program is what the vast majority of mappers now use.

Download sdmmlauncher.exe from the github repository. This program automatically downloads and launches SDMM. You should move this file out of your downloads folder, and somewhere safe, such as C:\Users\YOURUSERNAME\sdmmlauncher.exe and pin the application to your start menu or task bar to launch it.

Remember, you need to open tgstation.dme in a map editor before you open a map file! The .dme file tells the map editor what all the sprites and objects are.

Other map editors

Map editors other than StrongDMM are not recommended. Expect less support to be available at a minimum

(NEED PICS) DreamMaker is installed by default as an IDE for BYOND, and is technically usable if you think that Windows 98SE was the height of computer development.

(NEED PICS) FastDMM2 is a web based map editor created by Monster. FastDMM2 requires no software to install, and can work directly with github remotes, or local repos. Its handling of multi-z maps is noted to be particularly good. Do not use FastDMM2's built in ability to create a PR on github against tgstation master. You will make an un-mergeable mess and you will not be able to fix it

Get Mapping

You're now ready to map. This is the basic workflow, you may need to refer to the manual for the git client you chose in step 1 to find out how to do these things.

• Using your git tool of choice, create a branch on your local repository
• Checkout the branch you created
• Make changes to the map in your editor and save them
• Commit those changes to the branch on your local repo
• When ready, push your branch to your remote repository
• Go to github.com and click the giant button that pops up to create a PR against tgstation/master
• Fill out the PR template and hit submit