Guide to Mapping - Warpers

Warpers are invisible tiles which cause a player to be transported from one location to another. The most obvious example of this would be a door on the overworld which takes the player to the interior of a building once it is stepped on. For newcomers to the mapping process these can seem rather intimidating to implement as they do require the mapper to actually write code, but the code in question is actually very simple and easily learned.

The code for warpers is located in trace-alter-map/assets/code/objects/warpers/, wherein it is split across a number of different folders and files related to different areas. For the majority of projects, the relevant warper code is located within the /districts/ folder separated into different files for each district (e.g: the warper code for any caves and buildings located in District 12 is located within the file district_12_warpers.dm). Some districts may be referred to via older development titles (e.g: The Historic District is referred to as “City”, Downtown is “Inner City/Skyscrapers”, and the Outskirts are “Country”) but by taking a glance at the code within and reading the names of certain warpers or by comparing them to the names of warpers placed in the world via the map tool you can deduce what the name of any location you're uncertain about is called.

These files can be edited with BYOND DreamMaker which will likely be the default program set by Windows, however the use of a text editor designed for programming such as Notepad++ is often preferable for readability and ease of use. It is important you do not use a word processor such as Microsoft Office or LibreOffice when editing code as these programs insert a large amount of invisible special characters for their formatting which will break the code entirely.

• warpTo - This specifies what other warper tile the character will be sent to once they step on the warper. Generally warpers work in pairs, with entrance tiles using the exit tiles as their destination and vice versa. Usage example: warpTo = /obj/warpers/city_warpers/bar/leave_bar_1

• displayText - This specifies where the warper says it leads when the player moves their cursor over it and also what the game displays at the top left of the screen once they enter it. This should only be used for interiors however; if the warper leads back to the overworld then it should use the isExit variable instead. Usage example: displayText = “Ascension Group HQ”

• isExit - This specifies that this warper leads back to the Overworld. Usage example: isExit = true

• bound_height - This specifies the height of the warper in pixels from the bottom. If not set, this will default to 32, which is the height of a single tile in Byond. Generally this is only used to create half-sized warpers positioned on the southern edge of tiles. Usage Example: bound_height = 16

• stepDir - This specifies the direction the character will emerge towards when they appear on the other side. It's important to set this correctly otherwise characters may be spawned inside walls or out of bounds. If a warper's destination spawns the player at the bottom edge of a room, then the stepDir should be set to NORTH so that they emerge above the lower boundary, and similarly, if a warper would spawn a player coming out of a door from a wall, then the stepDir should be set to SOUTH so they appear beneath the doorway. Usage Example: stepDir = NORTH

For the sake of demonstrating how to create a new warper, let's say we want to create a warper between a south-facing building door on the Outskirts part of the overworld and a theoretical building interior we have just created depicting a small cafe. Warpers generally work as pairs of “entrances” and “exits” which each refer to one another as their destinations.

The first step is to open the warper file for the region we are working with, in this case it would be country_warpers.dm. Within country_warpers.dm you will see a bunch of existing entities all arranged in a nested fashion in which every entry which is nested one step further inwards is said to belong to a group defined by the above entry. At the very start of the file, we see obj/warpers is the first entry which simply states that everything that follows is a warper object, then country_warpers which is the category for Outskirts warpers, then a bunch of entries for individual buildings which all contain definitions for entrances and exits.

To add our new building, we'll want to create a new line at the end of the document and indent it to align with the other declarations of buildings. In keeping with the format, we would title it “small_cafe”. Next, we want to define the entrance and exit for that building, so we'll indent one notch further on the next line as these will belong to the small_cafe entry. Now, as mapped, the exterior of the cafe only has a single tile wide door which serves as the entrance, but the interior has a 2 tile wide doormat which serves as the exit, so we are going to need 3 warper tiles total. You might wonder why we need to define a third tile for the extra exit tile - “couldn't I just use the same exit tile twice?” you're probably asking. The issue there is that the warper tiles reference each other as their destinations, which means that if two exit tiles exist with the same name in the world, then the entrance warper tile is pointing to two instances of the same tile at once and can't figure out which one the player is supposed to go to. So, with this in mind, our three defined tiles will be “enter_cafe”, “exit_cafe_1”, and “exit_cafe2”.

Now, beneath each of these entries we need to begin filling in the variables which define what they do. Indenting one step beneath each, we start with the “warpTo” variable. This defines where the warper tile we are currently working on will send the player. So, when the player steps on the entrance tile, we want it to send them to where the exit is on the interior of the building, so we'll want to use the address of the first exit warper. The address of the warper is got by combining all the definitions they have been grouped within together, so in this case we'll want to use the address /obj/warpers/country_warpers/small_cafe/exit_cafe_1. Next, we want the warper to display the name of the cafe when the player moves their cursor over the door, so on the next line we can add displayText = “Cozy Cafe”. These alone are all we need to do for our entrance, so now we can move on to our exits.

Because there's only a single tile on the other side, we can give both of our exit tiles the same destination, warpTo = /obj/warpers/country_warpers/small_cafe/entrance. Because they are sending our players back to the overworld however, we don't use the displayText variable, but instead the simpler isExit = true variable, which should automatically detect where in the overworld the player is sent and set things accordingly. Our exit is at the bottom of the building we have just mapped, and so we don't want it to occupy an entire tile and be too obtrusive on the interior space, so we can make it half-sized by adding the variable bound_height = 16 to each of them. This helps make it feel more like the player is stepping down into an unseen exit and isn't getting abruptly whisked away if they step too close to the tile. Finally, we want to make sure the player emerges in the correct direction when they appear on the other side - to do this, we add the variable stepDir = NORTH to the entrance definition stepDir = SOUTH to each exit definition.

Now, with those definitions created, save your changes to the file and then open the mapkit anew. Compile the code anew (Ctrl+K) and the warpers you have defined should now appear in the sidebar of the map editor under obj > warpers > country_warpers > small_cafe. All that remains is to place the entrance warper tile on the door you intend to be your entrance (making sure to remove any dense tile that was previously there) and to place each exit over the 2 tile doormat of the interior (and because the entrance warper sends the player to the warper defined as exit_cafe_1, place that one on whichever side you would rather players emerge into the building from).

And there you go, you've successfully created warp tiles!