User:Nefarious6th/Mapping

This is a guide for getting started in mapping, a one-stop shop for terminology, tools, and process explanations.

Getting Started

Regardless of if you're coding, mapping, spriting, or doing soundediting, you'll need to set up a local copy of the Goonstation Code Repository on your PC. To do so, follow the steps detailed in ZeWaka's Goonstation Development Guide exactly, and you'll get your local copy set up. You'll also have the ability to push your changes to your remote branch on GitHub to eventually open a Pull Request and have your work reviewed.

The process for submitting a Pull Request on GitHub is also the same whether you're working on coding, mapping, spriting, or sounds. When you open a Pull Request in the main repository, the labeller bots will automatically tag it with `[mapping]` based on the files you've changed.

When you make a map, all station maps in the game are 300 by 300 tiles, and only have 1 Z-Level. Current map format to save in is TGM, which is spaced out, easier to read, and easier to edit from VSCode or GitHub down the road. You can set which file format your work saves in either under File > Export or File > Preferences.

Before you open up your map editor, it might be useful to doodle a rough map layout so you can build in a more organized fashion. Most maps start as doodles.

• File:Example.jpg

  Dr. Cogwerks's first sketch for Cogmap2 (photo courtesy of Dr. Cogwerks)

Where to Start

Making a map, a fully-functional, ready-for-review, good map, takes hundreds of hours. Most substantial maps including Destiny and Donut 3 took their creators half a year to make. To be brief: a map is a long-term project that requires patience and many iterations of design and testing to get right.

Because the amount of time to invest in a map is so significant, it might be hard to know where to start. An excellent place for beginning mappers to learn about fleshing out concepts into full areas and hone their technical skills is making prefabs, those fun little places in the Mining Level or Trench that are often themed around a single idea and contain some unique story or loot. The majority of prefabs are at most 30 tiles wide by 30 tiles tall. They're saved in a special spot in the repository just for prefabs, under the assets > maps > prefabs folder. Poke around in there to see currently implemented prefabs, and see the More on Prefabs section when you're ready to begin.

Your Editor and You

What editors are there even out there? What are the parts of an editor?

To be brief, there's three primary editors: Dream Maker, StrongDMM, and FastDMM2, which you can find out more about each one in the Mapping Programs and Formats section. They're all slightly different but each one has the same couple of components: the Map Window, an Environment Tree, and a Variable Editor.

• 

  Dream Maker's map inset

• 

  StrongDMM's Environment Tree

• 

  FastDMM2's Variable Editor

Map Window

This is where the work is done; this is the actual map itself that you click to place objects onto. Dream Maker comes with a little map inset as well; StrongDMM and FastDMM2 just have the single map view.

Environment Tree

The Environment Tree is where you can browse the assets in the Goonstation environment. This is the collection of every coded object and turf, and the sprites associated. You can filter what you're looking for with the search function. Click an object within the Tree itself to make it active so that when you click in the Map Window, you place that type of object.

Variable Editor

The Variable Editor allows for you to change properties of an object like the offset on a tile, whether it is moveable or not, and the names and descriptions of objects players will see when they examine them in game. An edited variable is indicated in the Editor by either bold or highlighted text. StrongDMM will also show you the changed variables in a previewer whenever you right-click and make active any object. To access the Editor, right-click on an instance of an object and select "Edit". More on how to var-edit can be seen in the Var-editing section below.

Var-editing

Terminology and Basics

There's a couple of important terms and differentiations to be made when mapping, particularly when comparing some assets versus others. This section provides a crash-course on everything you need to know to successfully make a functioning map.

Here are the different parts that make up a map:

• A turf is the core of the map; these are both Walls and Floors
• An object is all the stuff that goes inside the map and the rooms you make, notably Doors, Windows and Furniture, but also any machinery, wires, and landmark spawns too.
• An area is a zoning specification for a map; this is how you define Departments, but also some special functions like which areas are protected during radiation blowouts, or which areas are protected by machines like turrets.

Some other essentials to know about specific object types and what their paths mean:

Walls, Floors, and Windows

• There are two types of walls, floors, and windows: reinforced and just standard. Reinforced walls have extra durability over standard walls from a mapper's viewpoint, and require more effort and interaction to break down from a player's perspective.

• There are also then additional subtypes of walls and floors, Simulated and Unsimulated (discussed under each, respectively)

Walls

• Reinforced walls are used on maps in rotation for high-security areas, like the walls of the Armory, Departmental Head's Offices and Quarters, and the Engine Room. The use of reinforced walls in these places means it's harder for players to break into these places by deconstructing the walls, but in the case of the Engine Core, it also means that if the Engine explodes from normal operation, the walls are not as likely to break down.

• Reinforced walls are also used on any external walls on maps in current rotation. In other words, if the wall borders on empty space, it's best to make it a reinforced wall. Events like Meteors or breaching attempts from Nukies hit these walls first, and they should offer some protection to the station as a first line of defense.

• Simulated walls are used anywhere you want players to be able to interact with that wall, whether it's deconstructing or bombing it. Station areas should be simulated to allow for players to dismantle and put back pieces of the station; it's a sandbox game after all!

• Auto walls are the standard walls used on all modern maps in rotation. The "auto" implies the nature of how they connect with adjacent walls of similar types. You want walls to look continuous, so you will want to use auto walls.

---

Floors

• Reinforced flooring is a special type of flooring that has a black hexagonal pattern on it; this should be used under any Engine Cores, for the same reasons you would want to use reinforced walls. Podbays also use this flooring, as they're prone to exploding Space Pods and welder tanks.

• The path for this type of flooring is under /turf/simulated/floor/engine

• Simulated flooring is like simulated walls; those are tiles that players can interact with and change, whether it's plating the tiles in pizza, prying them up with crowbars, or bombing them. Station tiles should be simulated.

• There are also variations of each type of tile that are simulated and airless. These tiles should only be used in places you want to intentionally be uninhabitable, like broken apart and breached wrecks that start the round as such, like on Horizon. If you don't intend for people to have to wear a mask and use oxygen tanks to access an area, do not use these tiles.

---

Windows

• There are windows, and then there are wingrille spawners. Wingrille spawners both place windows and grilles on a tile, and make sure that the grille layers under a window. But, if you intend to have a window without a grille under it, you will need to use windows of types under /obj/window/auto.

• Crystal wingrilles are an even more durable type of window made from plasma glass, that come as reinforced windows over grilles.

• You can electrify windows, which is essential for high-security areas like the Brig or Captain's Quarters, to make breaking a window to get in non-trivial.

• To electrify windows, you need to first have a grille on the tile the window will be on (remember: wingrilles will spawn the grille automatically for you!)

• Then, you need a wire knot placed on the tile the grille is on. The grille is what actually conducts the electricity to the tile with the window on it. The knot then needs to be connected to a wire network that is powered (by the Engine or Solars).

• There are little quarter-tile windows called "thindows", and while they on their own aren't buggy or inconsistent in their behavior anymore, they're in a top-down perspective and don't match with most of the game's modern sprites, walls, doors, and human players, so they're not recommended for use.

<- Thindow spawner; don't use! <- Window spawner; do use!

• Wingrille spawners for plasma glass thindows are a darker purple than the true window ones (these appear more like a bubblegum pink).

<- Thindow spawner; don't use! <- Window spawner; do use!

• Wingrille spawners for normal glass thindows have hollow centers on them; modern full wingrille spawners have filled-in centers.

---

Anything Else I Need to Know?

Yes, actually! For walls and windows there's further variants of the reinforced versions of each called Tuff Stuffs. These are reinforced walls/windows with pre-defined extra explosion and damage resistances tacked onto them.

• Some maps use tuff stuffs around critical areas like the Engine Core on Clarion and Destiny, or critical windows that might be prone to sustaining lots of damage like on Donut 3. They can be good for being extra sure an area can handle normal usage in the course of the round (works of Toxins mischief aside).

• Tuff stuffs, though pre-defined, are var-edited, which means that the variables that are attributed to them are edited directly in the map editor and not in the code. Because of this, and because of the mechanics of construction in-game, this means players cannot build walls/windows with the same resistance as tuff stuffs

• What this means even further is that if a catastrophic bomb goes off somewhere you do have tuff stuffs in and breaks them, player repairs will not be able to get that part of the station back to the same level of durability and protection as it is initially in a round. This isn't such a bad thing, it's just to understand why they exist and why they should be used selectively.

---

Wires and Pipes

You have your walls, you have your floors, and you have your windows. What's next?

Wires

• Wires or cables are sort of like the veins of a station! If you can imagine an Engine as the heart, the thing that's keeping all the departments and nooks and crannies operating, then the wires are what connect the two. Wires serve a dual purpose on maps:

• Wires deliver power into the station. The pathway for this is to have wires connect the Engine to an SMES unit. The SMES functions like a backflow-prevention device. When you wire an Engine to an SMES, you're saying that the power coming from the Engine is only going to go into the SMES; the Engine's not going to draw from the SMES. More on this in The Engine and The Wirenet.

• Wires also connect networked items together and allow for interactions between multiple machines, or machines and players. They're important for many Research systems like ArtLab and Telescience, and Mechanics systems like packethacking. Also, some machines have to be connected to the network in order the receive power. This is detailed in The Wirenet.

• Why do these wires have all these edited variables?

• If you're seeing more than one set of edited variables for a type of wire, then you should look for the wires in the Variable Editor that only have one set of edited variables. Wires with d1 and d2 variables attached are older. The "d1" and "d2" indicate the directionality of the wire, but this information no longer has to be stored as an edited instance of a wire, which means the "d1" and "d2" fields on the wires in a map editor are redundant. Wires with "d1" and "d2" variables set occasionally will cause problems and magically change directions. Removing the two variables also makes the actual map file shorter and easier to read, review, and revise.

---

Pipes

---

Machinery and Furniture

Doors

• Doors are included in machinery and perhaps the most important machines. You'll find all doors listed as subtypes of airlock, whether they're unpowered or powered. Which brings us to the next point...

• Powered doors start the round on, draw charge from the nearby APC, and correctly are used only by people witht the right access level. Unpowered doors are the opposite: they start off, need to be pried open, and won't check for access levels. You might, limitedly, need to use unpowered doors for some places if you're making pre-fabs or wrecks, and can make them unpowered by var-editing requires_power to 0.

• Likewise, you can toggle whether a door starts bolted or not by changing the locked variable to 1 and changing the icon_state of the door to [nameofdoortype]_locked. If you check out the two grey doors on Kondaru by the Aviary, you can see how this works. The bolted one into the abandoned room has the icon_state set as generic_locked, and the normal unbolted one south of it is set to generic_closed.

---

We're Done With Doors Now, Right?

No! We have to talk about spawners.

• Spawners are of two types: firedoor spawners and access spawners.

• Firedoor spawners do what they sound like: they spawn perspective firedoors over airlocks and automatically set them to the right direction. They're red hollow boxes with a big "F" in them and are under the path /obj/firedoor_spawn.

• It's worth it to note that firedoors can be put over doors, but in some maps like Destiny, they're also used to break up long hallways just in case so fires in one section of the ship don't spread to the whole ship.

• It's also worth mentioning that openable windoors over desks can also have firedoors over them, if you're about fire safety.

• Access spawners come in colors coded for each department and are two hollow squares with one inside the other. You place these on the perspective airlocks to set the access requirements for them.

• Access spawners work on an OR basis. What this means is that if you were to put two spawners on a door together, say /obj/access_spawn/bar and /obj/access_spawn/kitchen, you can create a door that can be accessed by anyone with Bar access OR with Kitchen access, versus a place that requires both Bar AND Kitchen access. Use this when you're making things like tables for produce to transfer between Hydroponics and the Kitchen, or for raw materials to transfer between Cargo Bay and Mining.

• Not all doors work with access spawners. Why? Older doors and ones that aren't used standard might have a value in the field req_access_txt, which overrides the access spawner. To fix this and make these doors usable, set the value of req_access_txt to null.

---

Okay, Now We're Done With Doors?

Nope! Let's talk about door-linking (and object linking in general)!

---

Machines

• Machines are anything electronic, lights, vending machines, computers, Cloning, all the Artifact Research machines, and more. Machines also include APCs, which must be wired into a powernet that connects to an SMES, and from which all other machines draw their power.

• For lights, you'll want to play around with lighting styles, but generally, incandescent lights (/obj/machinery/light/incandescent) are brighter than most other types.

• You can atmospherically light areas of the station using cool and warm incandescent ligts. Ocean maps like Manta and Oshan use a lot of cool' incandescent lights on normal hallways and in maintenances; the blue light plays nicely with the ocean surroundings!

Furniture

• Furniture is what it sounds like; all the stuff you put into a room.

<- non-auto tables <- auto tables

• The only note of importance here is that some pieces of furniture like tables have an auto version. They work like auto walls do too, connecting nearby tables of similar types into one continuous table.

Areas

Landmarks

Details And Wrapping Up

More on Prefabs

If you have a novel idea and are ready to try your hand at making a pref.....

Okay but How do I Actually Make Map

General order of map creation should be something like:

• Basic skeleton of turfs (walls, floors)

• Objects in rooms (airlocks, machinery, etc)

• Area placement (important for APCs, teleportation, etc)

• Wiring (including APCs) and disposals

• Detail work; lighting + switches, access spawners, firelock stuff, door names, bot waypoints, teleporter beacons etc.

It's okay to look at existing maps for reference when configuring objects, but it's heavily recommended you create new instances of objects and change any necessary variables when making your map - this is less likely to introduce unintended consequences, and makes you more familiar with var-editing.

SAVE. Also, Save.

Whenever you make any change that took any amount of time, save and make sure there's a backup. Dream Maker can sometimes corrupt maps, or simply not save your work, and you'll either lose part of your map or break the whole thing.

If you don't have some sort of fancier version control (i.e. Git) that automatically keeps revisions when you save the map, you can make a backup by doing "save as" and adding a version number to the filename, i.e. mapname_ver(number). You can move the map into the goonstation > maps folder once you're ready to Pull Request your map.

Design Tips and Fundamentals

There's some things about map design to keep in mind when creating.

1. Maps are living documents

Making a thematic map shaped like your favorite animal could be really silly and fun, a bit like a puzzle, even; but the shape of the map will affect the design flexibility you have currently while making the map, as well as the flexibility you and others will have down the road when revising or expanding the map. Some maps like Destiny and Manta struggle with this. When new content is added or new population demands arise, it's hard to accomodate within the bounds of strictly defined shapes. It's even harder when you're also obligated to mirror any expansions and retain symmetry within the map. If medical needs a section removed and is on one side of the map, you'd have to look at removing a mirror section on the other side of the map, and the department there might not have anything that can be removed.

2. Try to utilize varying room styles and shapes

It's pretty hard to say that squares on maps might not cut it when the rest of the game graphics themselves are...squares. But it's true! A map of all squares, though industrious and probable for true-to-life space station crafting, isn't going to be as interesting for players to explore or work in. Use unique shapes where you can. Where you do have squared-off rooms, think about what you can do within the room itself to change the shape up.

Footprints are important to this too. Which of the below do you think looks and works better?

Some sample chemistry lab layouts

The bottom one has all the tables and machines shoved up against walls. In fact, all the chemists working at any of the stations are going to be staring at a wall! Now look at the top one. There's more interesting protrusions of lab benches into the center of the room, and a better utilization of the space provided. This also means there's more counterspace in general and more area to place objects like beakers, droppers, and goggles. Even though the room is a rectangle, the intrusions of things like the shower and lab benches help to change the shape of it as it's experienced by players. There's stuff to navigate around, surfaces to place things on, and new opportunities to interact with others since people face each other when they're working in the space.

3. Location, location, location

This is true generally, but let's talk about location of things within a room, specifically things that go on walls. Goonstation sprites are in a 3/4ths slanted perspective, and what that means is that walls that are south-facing have "the most" surface area, given the perspective we're approaching this from is 3/4ths. East- and west-facing walls have less, and north-facing walls seem to have almost none at all. Walls at the top edge of the room have more space for things, and you should use it as such! Fire alarms, air monitors, and posters are all large wall-mounted sprites that might look best on those top-edg walls. Things like lights, some buttons, light and blind switches are smaller and look okay on left or right edge walls too. There are very few things that look good on bottom-edge walls, aside from lights, potted plants, and wall-mounted disposal chutes. Prioritize how you use your top-edge wall space with this in mind.

4. Vertical space =/= horizontal space

A tile is a tile is a tile is a tile, right? A 3x3 is equivalent no matter which corner you start from, yeah?

Not quite. At least, not for this particular game. The BYOND client display window is wider than it is taller. What on Abzu does this have to do with mapping, you say? It means when a player has their client up, they're going to see more of the environment around them horizontally (going Left-to-Right around their character), versus vertically (going Top-to-Bottom). And while 12 tiles wide is the same number of tiles as 12 tiles long, the range of those tiles you can see either above or below the center point of the game screen is noticably less than those to either your left or right. This makes vertical hallways seem extended, and can lead to mostly-vertical departments feeling more sprawling. Think about this particularly when planning your primary hallways and major departments like Medical and Security, places where movement is (almost) everything.

A few little bends in an otherwise straight vertical hall can change the space and allow players strategic points where they can see more ahead of or behind them than they might otherwise have been able to.

Networks

Your map is going to have to include a few different networks to function correctly.

Your networks are:

The Engine

The Wirenet

Disposals

Mail Network

I Have a Map and It Seems to Work, Now What?

For a general checklist, reference the Goonstation Map Submission Guidelines - they're an excellent source of ways to validate your map's functionality. As a rule of thumb, if your map hasn't been tested, there's something wrong with it - don't be afraid to ask for help fixing or testing things. Note that your map must meet all the requirements listed in the first section if you want it to be considered for review!

Room-by-Room Checklist

Generally, this is the stuff you need for each room, and you can repeat this checklist and review for every single room when looking at your map in the Map Window.

[ ]An APC, connected to the powernet
[ ]Lights
[ ]Doors with access spawners
[ ]Firedoors over doors and any windoors
[ ]Linked door controls and pod or blast doors
[ ]Switches for lights and blinds
[ ]Intercoms (not mandatory for every room, but should be plentiful)
[ ]Security Cameras (again, not mandatory for every room, but should be plentiful)
[ ]Fire alarm
[ ]Wired data terminals for all wired machinery
[ ]Perform a tile check and verify tiles are all simulated correctly and have air

[ ]Air alarm (optional)

What Is This about a Disposal Pipe Tester?

To test your disposal systems, Haine and Spyguy made a handy little proc you can call as an admin to test if they actually work as intended! To use it:

• Use the Advanced ProcCall verb (found in the Debug tab assuming you've already made yourself an admin.)
• Run /proc/test_disposal_system. Next, enter the X and Y coordinates of where stuff that goes in a disposal pipe is supposed to go, right at the end of whatever disposal pipe adventure you've created. Usually this will be the final conveyor belt right at the crusher door.
• Wait a bit and you will be notified in your debug logs whether the test succeeded or failed.

Other Quality Assurance and Bug Testing Tools

Mapping Programs and Formats

This is your toolkit to use in making maps. Any of these programs work in creating maps that can be Pull Requested into Goonstation's Repository.

• DreamMaker: This is the standard map editor that you get when you download BYOND. It has hotkeys for different functions and the ability to move individual objects on a tile without having to delete and then re-place them, but loading the environment tree takes some time and it is prone to crashing.
• StrongDMM: A map editor with a minimalist interface that also has hotkeys for different functions and a navigable editing tree. It doesn't, however, allow you to move individual objects and re-place them without deleting them entirely. Will sometimes crash.
• FastDMM2: A browser-based editor that has a minimally encroaching interface, but lacks some of the environment tree readability and hotkeys of the other two programs.

Staying Up to Date

If you're working on an older map, or your map project has been ongoing for a little while, you may run into a window like this:

---