6 min read


This article guides you through the process of creating tilemaps and changing them at runtime in the Duality game engine.

A Few Words about the Duality Game Engine

Duality is an open source, Windows-only 2D game engine based on OpenGL and written entirely in C#. Despite being a non-commercial project, it is a rather mature product because it has been around since 2011. It has also proved to be capable of delivering professional games. Obviously, the feature bucket is somewhat limited compared to the major proprietary engines. On the other hand, this fact makes Duality an excellent learning tool, because the user often needs to implement logic on a lower level and also has the opportunity to inspect the source code of the engine. Thus I would recommend this engine to game developers with an intermediate skill level, who’d like to have a take on open source and are not afraid of learning by doing.

This article does not describe the inner workings of Duality in detail because these are well-explained on the GitHub wiki of the project. If you are not familiar with the engine, please consider reviewing some of the key concepts described there.

The repository containing the finished project is available on GitHub.

Required tools

First things first: Duality editor only supports Windows at the moment. You will need a C# compiler and a text editor. Visual Studio 2013 or higher is recommended, but Xamarin Studio/MonoDevelop also works. Duality itself is written in C# 4, but this tutorial uses language features introduced in C# 6.

Creating a new project and initializing the Tilemap plugin

Downloading the Duality binaries

The latest binary package of the engine is available on its main site. Unlike most game engines, it does not need a setup process. In fact, every single project is a self-contained application, including the editor. This might seem strange at first, but this architecture makes version control, migration, and having different engine versions for different projects very easy.

On top of this, it is also a self-building application. When you unzip the downloaded file, it contains only one executable: DualityEditor.exe. At its first run, it downloads the required packages from the main repository. It is based on the industry-standard NuGet format, and the packages are actually stored on NuGet.org.

After accepting the license agreement and proceeding through the automated package install, the following screen should show up:


The usage of the editor application named Dualitor is intuitive; however, if you are not familiar with it yet, the quick start guide might be worth checking out.

Adding the Tilemaps plugin to the project

Duality has a modular architecture. Thus, every piece of distinct functionality is organized in modules, or, using the official terminology, plugins. Practically, every plugin is a .NET assembly that Duality loads and uses.

There are two types of plugins: core plugins provide in-game functionality and services and are distributed with the game. On the other hand, editor plugins are used by Dualitor, and usually provide some sort of editing or content management functionality which aids the developer in creating the game.

Now let’s install the Tilemaps plugin. It’s done via the Package Management window, which is available from the File menu. The following steps describe the installation process:

  1. Select the ‘Online Repository’ item from the ‘View’ dropdown.
  2. Select the Tilemaps (Editor) entry from the list. Since it depends on the Tilemaps (Core) package, the latter will be installed as well.
  3. Click on ‘Install’. This downloads the two packages from the repository.
  4. Click on ‘Apply’. Dualitor restarts and loads the plugins.

    Installing the Tilemaps plugin

Tileset resource and Tilemap GameObject

Creating the Tileset resource

Resources are the asset holder objects in Duality. They can be simple imported types such as bitmap information, but some, like the Tileset resource we are going to use now, are generated by the editor. It contains information about rendering, collision, and autotiling properties, as well as a reference to the actual pixel data to be rendered. This pixel data is contained in another resource: the Pixmap. Let’s start with a very simple tileset that consists of two solid color tiles, sized 32 x 32.


Download this .png file, and drop it in the Project View. A new Pixmap is created.

Next, create a new Tileset from the context menu of the Project View:

Add Tileset

At this point, the Tileset Resource does not know which Pixmap it should use. First, open the Tileset Editor window from the View menu on the menu bar. The same behavior is invoked when the Tileset is double-clicked in the Project View. The following steps describe how to establish this link:

  1. Select the newly created Tileset in the Tileset Editor.
  2. Add a new Visual Layer by clicking on the little green plus button.
  3. Select the ‘Main Texture’ layer, if it’s not already selected.
  4. Drag and drop the Pixmap named ’tileset’ into the ‘SourceData’ area. Since the default value of the tile size is already 32 x 32, there is no need to modify that.
  5. Click on ‘Apply’ to recompile the Resource.

A quicker way to do this is by just selecting the ‘Create Tileset’ option from the Pixmap’s context menu, but it is always nice to know what happens in the background.

Linking the Pixmap and the Tileset resource

Instantiating a Tilemap

Duality, similar to many engines, uses a Scene-GameObjectComponent model of object hierarchy. To display a tilemap in the scene, a GameObject is needed, with two components attached to it: a Tilemap and a TilemapRenderer. The former contains the actual tilemap information, that is, which tile is located at a specific position.

Creating this GameObject is very easy; just drag and drop the Tileset Resource from the Project View to the Scene View. Switch back to the Camera #0 window from the Tileset Editor, and you should see a large green rectangle, which is the tilemap itself. Notice that a new GameObject called ‘TilemapRenderer’ appears in the Scene View, and it has 3 components attached: a Transform, a Tilemap, and a TilemapRenderer.

To edit the Tilemap, the Camera #0 window mode has to be set to ‘Tilemap Editor’. After doing that, a new window named ‘Tile Palette’ appears. The Tileset can be edited with multiple tools—feel free to experiment with them!

Editing the Tilemap

To be continued

In the second part of this tutorial, some C# coding is involved. We will create a custom component to change the tilemap dynamically.


Lőrinc Serfőző is a software engineer at Graphisoft, the company behind the BIM solution ArchiCAD. He is studying mechatronics engineering at the Budapest University of Technology and Economics, an interdisciplinary field between the more traditional mechanical engineering, electrical engineering, and informatics, and has quickly grown a passion toward software development. He is a supporter of open source and contributes to the C# and OpenGL-based Duality game engine, creating free plugins and tools for users.


Please enter your comment!
Please enter your name here