(WIP) Non-Coder Away Site Mapping Guide

[kyres1]

This is a beginner contributor and code-illiterate guide to adding map content to Aurora. This mainly focuses on overmap sites and ships, but lots can cross over between other ways to contribute.

To start off, no coding experience is required to use git as our server's contributors can. Virtually anybody regardless of software literacy can contribute as a result.

This guide will cover how to set up the most basic method of using a Git client, how to keep it updated easily, what you need to map, and how to make a pull request to submit it all.

Before you do anything at a level like this, first get your tools together. These tools are not all mandatory but will make life magnitudes easier for you.

Fork - A git client that is free and simple. This guide uses this client, but many others are like it. Many others also cost extortionate amounts of money, so this is a good pick.

Microsoft VSC (visual studio code) - Another method of editing the code you will need to adjust to make things work. This has an inbuilt debugging feature that speeds up your work massively. It also lets you search the entire code instantly which will become utterly invaluable when you need to look at something else for reference. You should download a Dreammaker extension for this once you get the opportunity, it’ll help you get accustomed to things faster.

StrongDMM - The only mapping editor you should be using. If you edit maps using dream make instead, expect your work to be slow and for easily-avoided problems to appear. 

Explaining the Process for Dummies

Once you have everything together, the rest of the set-up is a mostly one time process. After this guide, updating your code is reduced to a single button press, and keeping track of things is simple. The next steps will explain how to get there.

To make things understandable, "repo" implies repository, or a specific folder or collection that you update in parts. So, the "Aurora repo" would be our primary public code that contains the game's data.

Your work process as a contributor, even at most higher levels of coding, is basically entirely merging your own changes with the "master" branch, AKA the branch the server runs the game on.

To do this, you basically make changes on your LOCAL repo (your PC or workstation), send those changes to your "remote" (an Aurora repo cloned to your account on Github), and you can then easily compare the changes; after which you can open a PR to submit your changes for review.

Getting started 

First thing's first, make a Github account to push your changes under.

After that, you'll need to make your own "workspace" where you can send your changes to Github before trying to merge it with the main code. This is the "remote" as said above.

To get your remote, you need to clone the Aurora code into your own copy. Hitting “Fork” in the top right of the repository will clone it under your account, which is where all changes you make will be pushed to when you commit local changes to the remote.

Downloading and installing the code

The next important step is to get this new workspace on your PC. Like said above, you’ll clone your repository now; to do this, open Fork (the Git program you’re using) and press the “clone” button at the top left. Copy and paste the URL of your new fork on Github into the relevant field when cloning to download your custom fork to your PC. This will probably take a while.
When your client is ready to go completely, things will look like this:

Spoiler

 

Once things are like the above, and you check out (AKA select) the “master” branch, proceed to the next page.

---

Using Fork - important basics

To start almost any project you’ll begin here, you want to start with two essentials;

For one, update your “master” branch so you don’t end up with avoidable conflicts immediately. Doing this is, in this context, accomplished by “fast-forwarding” your master branch to the latest version. Always fast-forward once you see a “X commits behind” symbolized like below next to your “master” branch.

Simply right-click on the master branch as it appears in your branch list, and press “fast-forward to aurora/master.” 

You don’t need to update your remote (on Github)’s “master” branch; just the one on your PC works fine.

Once that’s done, nothing else should be present where the “X commits behind” was.

You must (absolutely mandatory) make a separate branch for every PR you intend to make if you’re a casual non-coding contributor. You really don’t want to screw with your master branch in any way unless someone with more sense tells you to; this’ll irreparably make your PRs break, and you’ll end up having to reinstall and repeat most of the steps here, not to mention re-doing all of your ruined work.

So, to begin your first project, do exactly that. Right click the “master” branch on your list, and press “New Branch.” These things can be deleted or remade as needed, but once you delete a branch, it’s not possible to get it back. These can be named whatever you want to remember them.

When you check out your branch, the git magic begins. Every change you make within the local folders you opened with Fork will be tracked in Fork itself. Every edit to any files that aren’t manually ignored will be reflected under this tab in your Fork program;

You can test this by doing anything to the files inside of the code. Delete, drag, drop. It doesn’t matter much; if it changes, it’ll show up as a local change. If you’ve done something locally that you don’t want to keep, you can go to the “Local Changes” area here and discard it care-free. Discarding changes is literal here; that means the changes themselves revert, and you’re not deleting a file (unless the change was adding it to begin with.)

The important part here is that you don’t commit changes you can’t revert manually. Reverting changes using git is a more complex process than a simple discard, so once you commit something, it’s committed. Only committed changes can be pushed to your remote, however, and only pushed changes can be made into pull requests on the Aurora public repo.

So, for example, you edit a hat to be red. The hat was originally blue, and the code made it so. If you haven’t committed these changes, you can simply right click the changed file here, and discard them; this’ll return the hat to being blue in the code rather than just deleting the file you changed. Liberally use discards to learn using temporary methods!

Once that's all done, you can get started on the mapping aspect on the next page.

 

---

Starting mapping - important basics

Before getting to mapping, you’ll need to understand at least vaguely how to copy-paste the code that makes the maps work.

Two things will be your best friends in figuring this out; Runtime Station and Visual Studio Code. If you’ve followed the Aurorastation README’s installation guide, you’ll know where the config file is (it’s in the config folder); go to it and change the FORCE_MAP to “runtime”. You’ll want the rest of the installation, like giving yourself host perms too. Otherwise, testing is not going to be possible.

Runtime station boots a lot faster than normal maps and lets you forcibly spawn away sites and ships to test faster. Forcing those things to spawn is a slightly different approach which will be tackled in the example mapping section.

You can open any .dm (code), .dmi (icon) or .dmm (map) file in the Aurora code to automatically see the folder trees from Dreammaker, provided you followed the installation steps in the README correctly. You will not be opening .dm or .dmm files with Dreammaker in this guide, though! It’s best you get used to using different tools because of that. Icon files are fine to edit in Dreammaker, though

If you’re making a new map file entirely, make sure to make it from StrongDMM’s “Create Map” button, and set the format to TGM. This is MANDATORY!

Making your testing away site

To get the fastest idea of how this all works, you’ll be making an example site with this guide.

Begin your work while your branch is selected on Fork by making the sub-folder, with your away site’s name, in the away site folder. The path itself will end up being,

Aurora.3\maps\away\away_site\(insert_name_here)

From there, if you’re not feeling entirely confident, you can simply copy-paste files in your file explorer over from the “placeholder_site” away site found in the same root folder. After that, follow the naming convention and change those files over to your new away site’s name. This is currently in a WIP pull request you can find here https://github.com/Aurorastation/Aurora.3/pull/16652

To repeat : if you’re making a new map file entirely, make sure to make it from StrongDMM’s “Create Map” button, and set the format to TGM. This is MANDATORY!

Mapping functions - things to avoid

As far as meta features go for mapping, you want to avoid three of the big mistakes new mappers make.

1. You can not swap apostrophes (‘) for quotes (“) in variables, either in code or in map files. Period. Otherwise, you are going to have to convert the map to a text file, and manually fix it, wherever it is!
2. Where there is space or otherwise empty turfs or areas, you want to use two unique things; “/turf/template_noop” and “/area/template_noop”. In short, it will improve your map’s performance a lot.

Once you're done here, the next page will get started with proper mapping.

---

Actually mapping - helpers, pointers

A huge part of contribution is to copy what exists to see how it works, and get comfortable with it before you start getting new ideas. Mapping is not exempt from this, so expect to be copy pasting… a lot. A lot, a lot! Especially if you don’t understand certain systems.

Some majorly confusing systems will be illustrated below to help people better understand how to actually work with these things.

Areas

Areas are the features that assign power grids and various monitors to rooms. Areas can be as big or as small as you possibly want. However, there are several major takeaways in mapping areas;

1. Areas don’t change ingame. Without some special, and typically very buggy methods, your mapped-in areas are final unless you change them again with mapping.
2. Atmosphere must be consistent throughout singular areas. Otherwise, your map will fail checks.
3. Space areas (including template_noop) can be sealed or given an atmosphere, but you can’t give them gravity and lots of features get very buggy. If it’s space, expect it to stay in space.

Some nifty features of areas;

1. Areas can have optionally simulated power and lighting. Atmosphere is not controlled by the area, contrarily.
2. All turrets in an area will be controlled via any turret controllers you place in the area. This means you can’t have turret controllers outside of their designated area. You can get around this by making separate areas for the turrets and their control panel.
3. All atmosphere monitoring systems tie “alerts” to entire areas; so if you trigger an air alarm in an area, every single alarm in that area will go off, and every emergency shutter will drop.

You should add unique areas to code for away sites following the format that most away sites offer.

 

Power

Power is rather self explanatory. This is governed by two things; areas and cabling. Cables are two-way conduits, so however you link them, as long as power is being made from one source, it’s going wherever else it’s connected. Areas allow for wireless features like wall machines and lightbulbs to receive power from APCs, which on the other hand require cables directly linked to work.

Since it’s so simple, all you need to know is to link generation equipment like solars/RTGs/reactors to SMES, which link to APCs. SMES store more charge than APCs and automagically distribute it as needed to the APCs connected to it.

Here’s a visual guide for how a minimum reactor setup works.

Spoiler

CABLE KNOTS : You need these to go under connection points. These can overlap wires themselves, they just need to connect at their base to work.

REACTOR : This is your power source. As long as you shove fuel in it, it puts power into the reactor cable.

TERMINAL : A piece to an SMES.

SMES : Where all the reactor’s power is stored and distributed automagically to machinery that is connected.

REACTOR AREA : This area defines the machines that should be stored in your reactor’s area specifically.

EVERY OTHER AREA : Every other area has a limit of  1 APC per. Everything you don’t want in the reactor room goes in these.

Atmospherics

Atmospherics is slightly more complicated, so if you’re unfamiliar with the system, avoid overcomplicating things.

Simplifying it, you inhale air (O2, N2) and exhale CO2. So, to make a livable atmospheric system at a minimum, you’ll need to fill it with air and take out the CO2. Every functioning away site where possible should adhere to this system, if it’s not a derelict, natural formation or otherwise hindered from having an atmosphere.

The only difference between the above system and the Horizon’s atmospherics is that the Horizon can exclusively extract certain gasses or pump those gasses into vents. It also has a lot more gas variety it can store. This is all unnecessary for this guide, so please consult the guide below for a full description of what’s necessary.

Spoiler

STATIC TANK : Your primary source of air, this can be swapped with an air can + a connector if you really want.

VENTS/SCRUBBERS: These automatically (so long as they have power) output air and intake things that are not air, like CO2. Make sure they’re connected to their respective sources/outputs to work!

WASTE CAN: Where your scrubbed/filtered gasses go when the scrubbers gobble them up from the ambient atmosphere. These can fill up over the course of a round and will manually require emptying, but that’s not really a problem. You can optionally hook a pressure pump to it to maximize the potential scrubbing, but this is already accomplished by scrubbers pretty well.

UNIVERSAL ADAPTER: To connect any kind of pipe to any other kind you’ll need this, always.

SUPPLY REGULATOR: This has a set pressure from vent sensors that comes coded with the machine. While you can adjust this, you shouldn’t, because it automatically distributes as much air is needed to exactly fill the rooms with the vents as it’s consumed.

ANY ALARM : Alarms allow for, well, alarms to go off, and to control an entire area’s vents/scrubbers manually. Pretty important.

And there you have it - a less-than-comprehensive look at away site mapping. This is probably not done, but right now the only essential thing missing is the PR for the placeholder site being merged.

Ping me on discord if there's any discrepancies!

[OolongCow]

I actually did need to ask about TGM format and didn't see it mentioned elsewhere, so thanks. This helped.