Mapping ABC

Read tips and guides about teeworlds-related subjects (mapping, compiling, ..).
Posts: 1133
Joined: Mon May 05, 2014 7:30 pm
Clan: Eagle

Mapping ABC

Post by Index »

Mapping ABC
written by Index (last updated on 2021/02/05)
LINK LIST with more detailed tutorials (viewtopic.php?f=16&t=2420)
Discord Server (
Teeworlds is a free and open-source game (, therefore its developed by the whole community. Surely that includes the >1200 maps released on the official ddnet servers. This thread should serve as a starting point to the whole mapping sphere. It covers the teeworlds editor and some general advice about mapping. There are links to further explanations and in-depth tutorials.

All information are without warranty, could be duplicated and contradictory or outdated.
There are ongoing efforts to improve this thread, until then its under construction (0% proof-read).

Mapping in general and especially making an enjoyable ddrace map is definitely not easy. It needs a lot of practise (read as: trial and error) and you may not succeed at the first attempt. But don't be disappointed. I could barely place some tiles about two years ago and now I write this. So it’s all about not giving up and constantly trying. Eventually you'll get better and maybe we see your map on the official servers someday :3

More information about the actual release on public servers of your finished maps are not here, please refer to: SETUP
You should use the offical ddnet client ( for mapping! It’s easier to acess all the additional features and you already have the right entities. However you don’t have to use it, the normal ddrace client or a similiar one should work as well. Just note, that you probably have to manually add the right entites files then (probably outdated as of ddnet v11.x). The official teeworlds client (0.7.x) is NOT supported and recommended.

After executing the client, you can open the editor with pressing <CTRL> + <LSHIFT> + <E> or by clicking the gear-icon (⚙) in the upper-right corner. You should have a basic understanding of the ddrace entites (accesible within the red-marked square).
If not, there are guides to get you started (viewtopic.php?f=73&t=1440).

This function shows you the area that is visible ingame.

Resolution doesn't matter, aspect ratio does. You have 16:10 (1680x1050, 1920x1200). Other common aspect ratios are 16:9 (1280x720, 1920x1080), 4:3 (1024x768, 1600x1200) and 5:4 (1280x1024). Your map should work with all of them.
The red proof rectangle shows you what a player with 5:4 aspect ratio will see. The green rectangle is 16:10, that should be your resolution. The white shape around is the maximum a player can see regardless of resolution. 16:9 is the widest resolution that lets you see further in Teeworlds, so anything higher than that, and your top is just cut off instead. In the other extreme you have to consider totally square resolution.

This divides the working space into small squares, you may know that function from any image editing program. It allows you to seamlessly connect different quads, like jungle_background or desert_mountain.

Tiles and Quads are the base of your map. EXPLAIN

After appending (click on 'Layers' to switch to 'Images', then Add) the mapres you can select them (RMB, Image, then hold <SPACE>). If you used a custom image (not in the official mapres directory, red undermarked) you have to embded it, otherwise it's not visible ingame.
Layer Clipping is used to only display a layer or quad in a certain area of the map. You can enable it by right-clicking a layer and then select Use Clipping>Yes. Now change the ClipW (Width) and ClipH (Height) values and you’ll see a red square in the left upper corner. That’s the area where your layer content will be visible. Alter the position of the new square with the ClipX (horizontal) and ClipY (vertical) values.

Quad-Layers are basically scaleable png-images. While you can transform any attached png-image (and tileset) into a quad, you should know about some technical limitations. The width and height should always be a multiple of 64 and the images should be prepared for use in teeworlds (viewtopic.php?f=16&t=4940). With that in mind, just create a new quad layer, right-click select the attached image and place it.

Also there are advanced features (eg. viewtopic.php?f=16&t=3152). In short: You can select one red square and press shift (LMB + Shift) after adding the quad. While dragging your mouse the image will now zoom in. With that you can easily select specific parts of an tileset or image. If you do that with two red points selected (LMB + Shift), then you can transform the lenght or height of the quad. You can do this with almost any tileset and/or image. So for example, you want to have any ingame emote (hearts, zzZ etc) as an ingame quad: Just copy the emoticons.png (teeworlds/data) to your mapres folder, add the image to your map and follow the steps above.

Tile-Layers are mostly for the so-called tilesets. It's like placing selected parts of a bigger image on your map. They are sectioned into 16x16 squares that can be selected individually.

You can download custom tilesets and quads (see below) or just create your own. The resources for that are widely available (viewtopic.php?f=16&t=2431). There are also certain tools, that can improve the quality of your used tilesets and quads. Furthermore it fixes minor bugs with transparancy.


With that being said, don't get silly ! Always think about quad and tileset management. You don’t want use 52352 different images. Often you can use the same tileset for many things, like freeze and marked areas. There are also many pre-made tilesets and quite a few of them includes freeze and/or alphabets. So you do not have to use one tileset for freeze, one for unfreeze and one for your text. Always try to keep the amount of embded images as low as you can. Best example for a really good tileset management is ddnet-tiles. It includes freeze tiles, which you can use for all kind of marked areas including freeze, unfreeze, tune zones and so on. Furthermore it comes with game tile markers, a finish line, arrows and even numbers for small hint messages. So you only need this one tileset for almost all layers of your map. This will greatly reduce your file size and the map is better organized.

Also note that surely you can use different tilesets and create unique and unusal looks with the right images. But alwas remember the overall graphic-style of teeworlds. There might be exceptions, but generally speaking a hyper-realistic tileset is NOT recommended.
Realism Tilesets vs TeeworldsShow
This was a response by me (Index) to some ideas posted a few years ago..
Realistic tilesets, yeah those are really rare in teeworlds. As far as I can remember I've never seen such an overly detailed map. But I think that's not only because it's really time-consuming and fps-killing but also because this realistic style doesn't fit to the overall graphic style of teeworlds. In my opinion tw is a simple 2d game with schematic tilesets and maybe some nice envelopes. I mean, even the skins are mostly just simple graphics without photorealistic elements. So all in all, I would play a map with so many details but I don't think that there should be more than one or two maps with such high detailed tilesets.
Next thing are 3d tilesets. Hmm, I know what you mean and I can imagine a map with that feature, but again it's really time-consuming and as you already said only a few players can really play the map, for all the others without the possibility to view the 3d effects with a special glass it would be just annyoing (imo). So yeah, nice idea as well but also not a great thing to do.
Ok, so last thing is the moving tileset. I think that's the best idea and the fact that there are already quite a few maps that have those 'animations' shows that this is doable and also playable for most of the players (If the framerate should drop for someone, he can easily disable HD and play with just one visible layer for example). So, I quickly played the map AntNest and I have to say that I love it. It's so good and although it's a really simple map concerning the gameplay I enjoyed walking around. I don't really how the effects there were archieved (didn't have time to view the map in editor) but I think that there should be definitely some maps with those 'animations' in the future. About the other two examples (Saavik's Move and your walk-test): Well, Saaviks map is quite nice and if that idea is converted into a nice map with more layers and details then it should be as good as AntNest. So that's the right way. But to be honest, I don't know what you did with walk_test (again, I didn't view the map in editor yet) but that's kinda weird, it seems like you move like ten times faster and jump super high without any tunes :o I mean, wtf. I'll deifintely take a look at this map later in the editor, because somehow that's completely mindblowing. There are so many stunning things you can achieve with just tilesets. It's amazing and I'm looking forward to see some of the ideas in a real map and maybe some other ideas as well in the future.
Now to the ddrace-exclusive features. Almost all ddrace maps use teleporters. They are an essential part of many maps.
Basically you have two different kind of teleporters: checkpoint tele (cp) and normal tele. Both in a red and blue version.
You place a FROM teleporter with any number (e.g. 1, chosen in the top toolbar of the editor while tele layer is selected) of any color somewhere. Then you place a yellow TO teleporter with the same number somewhere and it should teleport you there now.

Here are a few tips on how to place teleporters in your map.
Normally you should always use red teles except:
1) It is required to hook your partner even after a tele (eg dummydrag parts)
2) It is required to get speed for a jump

Red teles stop any movement and cut your hook.
Blue teles do not stop your movement and do not cut your hook.

Do not use checkpoint teleporters (cp tele) if it is not necessary.
You might create some unwanted cheats with them, it’s harder to go back and your mapping structure is more complicated. Nevertheless there are exceptions, a few mappers managed to use cp teles wisely and created unique maps like PurpleViolence by Vasten100 or Lawrence by Themix.

You should consider adding unfreeze at almost all TO-tele tiles. It increases the playability and you don’t have to wait for hours.
You should always avoid too many teleporters if it's not needed. Countless tele tiles may cause lags for people with lower GPUs with enabled entties.
You should place them on tile above the ground and always add multiple TO if possible.

This layer is mostly used for switches like doors or (moving) lasers. Nevertheless you can also use it for time-based freeze and many other different things. The number of the switch allows you to combine multiple tiles with each other. It’s basically the same as teleporter numbers. The delay value always indicates the duration in seconds (or the amount of things, if you use the ddnet exclusive 'jumps' feature for example).
You can also activate and deactivate other things like weapons and deepfreeze with it.

As an often used example you can create freeze with x seconds duration via the switch layer (x=delay).

With the speedup layer you can create a speed arrow. The force value indicates the strenght, numbers >20 are usually not necessary and you should prevent them. With the max speed value you can limit the maximum amount of speed a tee can potentially get. That’s useful if you placed a few arrows next to each other and the tee would get an insane amount of speed if he passes all of them.
Arows always point to the right (>>), that’s the basic direction and you need to change the angle value for another direction. The arrow will spin clock-wise by the amount/degrees (°) you choosed. So for instance, if you want a left pointed arrow (<<) you have to enter 180 (the original arrow spinned by 180°), maximum value for that is obviously 359.

That feature allows you to play sound files in your map. Basically they are handled like images, you can embded them and then select them with the sound layer. That function is ddnet exclusive and you’ll need the official ddnet client to use and hear the sounds ingame.

This layer applies certain zones in your map, where the physics of the game or other basic behavements can be altered. The changes are written in a .cfg map. The feature is ddnet exclusive and you need the official ddnet client to use tune zones in your map but not for playing a map with tune zones.

Envelopes can be used for many things. Basically there are two different kind of envelopes (three with ddnet client): Position, Color (and Sound).
With the Position Envelopes you can create basic movements along the X and/or Y axis including rotations.
The Color Envelopes can be used to create a color sequences or just one color that appears and disappears again using the alpha curve (opacity). Even the sunrays of a sun are created using these color envelopes.
The Sound Envelopes are used to play custom sound files.
Detailed Envelopes Tutorial (by TheDerero,

Automapper is a help for all the lazy mappers out there, it helps you place the tiles in your map. Just use it with an already made .rule file for a popular (standard) tileset or create your own rules and use automapper with any image you want.
Set up own automapper rules (by jxsl13,

You don't have to begin with an empty map all the time. Sometimes it’s nice to combine two or more maps. Doing that is quite easy. Open a map, use File>Append and select another map that you want to add. You cannot append the game group. That means, all the layers of this group won’t be added to the other map. However, all other groups, layers, images, sounds and envelopes are copied to the other map. Note, that this can lead you to 6346436 unused images and envelopes. So, be sure to clean that up before or after you append the maps.

The sections above should cover all relevant aspects to finally create your first standard map or at least get on the right track for it. But it doesn't end here, there are many unique ways to utilize these tools and in the last eight years the mapping style developed drastically. In the following paragraphs I'll try to give you some inspiration with different map types. Sometimes the maps also alter some server / standard tw-pysic settings, so there are more detailed tutorials on that as well.

Ok, you may have seen maps like TakeUrLugage by Tuna & Index or Skychase by SickCunt. These are basically solo maps, only one tee can finish it but you’ll need a ‘dummy’ to reach the finish (therefore called dummy maps). Over the years this type got especially popular.
Here is one way how to properly map deepfreeze at the start line.
Solo maps mostly use the ddrace features but you can play and finish them alone. They should be not too short (<1:00 min) and the main weapon is not always the grenade launcher (otherwise you might be interested in race maps and other communities, like Obviously these characteristics are not that strict, they are just the main differences to other solo teeworlds modifications. If you create a solo map you don’t need to add the solo on/off game tiles, most solo servers (including ddnet) are already configured right.

And surely there are always a few outliners. That means maps, that have something totally unique or used all the editor possibilities in a really fancy way. I want to give you a few examples of (mostly old) maps, that impressed ME. That's just a selection and you should definitely play through the varitey of ddnet and find your favourites. With that in mind I want to mention Flappy Bird by Saavik, SpaceIsKey by Kintaro* & Delo and HDP_OnOff by El Futuro.

Once you find an interesting example map, feel free to just open it in the editor (<ESC>, [gear-icon] > Open current map) to investigate the underlying structure. There is no shame in learning from others or even using it, just be sure to credit properly and ask for permission if possible ._. Another inspirational source with many explanations is Saavik's Showroom (viewtopic.php?f=44&t=58).

That's it, hope it helped you to BE A BETTER MAPPER.
Thanks for reading and feel free to use the forum and discord for further questions, discussions and so on. We're always happy to give any help and get feedback (:


Who is online

Users browsing this forum: No registered users and 1 guest