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.

• 

  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

sorry this is unformatted i am lazy

• var-editing is useful for

custom descriptions

slight pixel shifts

mass-shifting all objects of a type to be consistent with each other

maybe use pixel-shifting a poster as an example and changing the description on a food item or something idk

is not useful for

mass pixel shifts of objects with already standardized pixel shifts to fit perspective walls (ie, fire alarms).

keeps consistency with other maps/work in the repo

work smarter, not harder! use the assets you're given and save some time!

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.

• You will need to go back in in your code editor after you do this and clean out any mentions of req_access_txt that are set to null; this is technically redundant information! But setting them to null when working in the editor allows you to group doors together temporarily while you have the editor open and flag them to quickly and easily search for them in your code editor afterwards.

---

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 prefab, here's the spot for you. You need to make sure when you save your prefab to your branch, you save it under the goonstation > assets > maps > prefabs folder!

• Prefabs are little randomly spawned locations, either for expeditions to Space, the Trench, or potentially other planets. Most prefabs will occupy a .DMM file no bigger that 30 tiles wide by 30 tiles high, though some variance may be in order. You need at least a 1-tile buffer around the edges of the prefab, so if you were to make a square prefab on a 30-tile by 30-tile map file, the dimensions of the actual prefab building itself would only be 29 tiles high by 29 tiles wide.

• Keep note of how many tiles high and how many tiles wide your map area is; you will need these dimensions for setting up you prefab generation later.

• It's a good idea to start with a single theme for your idea. Many prefabs contain little pieces of lore and flavor and are designed around that. Past examples of prefabs can be found on the GitHub, and include:

• The Space Ranch
• The Torpedo Deposit
• The Space Casino
• The Candy Shop
• Von Ricken

All of these can serve as self-contained adventure areas. Most of what you'd make could use assets already included in the Goonstation Repository, but you will probably also need to make some of your own unique assets in order to get your story across. For example, the Candy Shop prefab has its own soundtrack, and the Space Casino prefab has its own special Bar Buddy and slot machines.

• For objects like the Space Casino's slot machines, you can modify a parent object that already exists in the code. In the case of the slot machines, you can see the parent type of the slot machine underlined below:

• The underlined portion represents the parent object type. By appending /item to the end of it, it creates a new sub-type of slot machine that you can customize for your prefab. Remember to keep your naming conventions understandable and straightforward so others looking at the work can understand what it is. If you're adding many new assets, it might be a good idea to create your own separate .DM file in VSCode, name it according to the prefab it relates to, and put any new object types you're making into there. If someone has to go back and edit your file, everything will be bundled together.

If you're having trouble figuring out what shape the prefab should take, you might want to try sketching it on paper first, or you can try making more than one different mock-up of it in your map editor. Working from the walls in can be useful in figuring out the right size and arrangement of everything.

Once you've completed your prefab, you need to spawn it in to test it.

1. You should have your prefab saved under the goonstation > assets > maps > prefabs folder.

2. You need to navigate to the code > area.dm file in VSCode

• Once there, you are going to create a new area type for your prefab.

Do so by making a new area type, like so: /area/prefab/cool_prefab

Then, specify the name of the prefab area. This is how it will appear on jump options for ghosts and admins, and in-game, so make sure the name is the 'official' name of your prefab!

Make sure that when you add your new prefab area, you add it under the right section; prefabs are organized in area.dm based on whether they're space or Trench prefabs.

• After you create the area for your prefab, re-open the prefab in your map editor and cover all the tiles that are a part of the prefab with the area you made. Save your work.

3. Navigate to code > modules > worldgen > prefabs.dm. You will need to add a block that follows the naming convention you established for your prefab area in Step 2; so in our case, the block would be contained under cool_prefab.

• Looking at the prefabs already in the files, you need to set the parameters for your prefab's generation. This includes the maximum number of your prefab that can be found during one round (which should probably be 1).
• Then, set the probability that your prefab will appear on a given round. Most prefabs have between a 15-30% chance of spawning. If your prefab has more desirable gear in it or a particularly novel story, you might want to have a lower chance for it to spawn so the experience remains unique and not overused.
• You need to set the prefab path to the actual map file you've saved under the goonstation > assets > maps > prefabs folder. For our sample prefab, this would be "assets/maps/prefabs/prefab_cool_prefab.dm".
• Then, you need to specify the dimensions of the prefab's height and width. This determines how it fits together with other prefabs and if it can spawn in certain areas during the generation of the randomized Z-levels.

To test your prefab in-game, you need to set the probability under the world generation file to 100. Remember to set it back to your desired probability once you are done testing.

When you're ready, save all your work and commit it to your branch, then open a Pull Request for review.

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, posters, 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-edge 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:

---