Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
257 lines (216 sloc) 9.87 KB

Tilengine logo

Tilengine - The 2D retro graphics engine

License: LGPL v3 Build Status

Tilengine is an open source, cross-platform 2D graphics engine for creating classic/retro games with tile maps, sprites and palettes. Its unique scanline-based rendering algorithm makes raster effects a core feature, a technique used by many games running on real 2D graphics chips.



  • Written in portable C (C99)
  • LGPL v2.1 license: free for any project, including commercial ones
  • Cross platform: available builds for Windows (32/64), Linux PC(32/64), Mac OS X and Raspberry Pi
  • High performance: all samples run at 60 fps with CRT emulation enabled on a Raspberry Pi 3
  • Multiple language bindings: C/C++, C#, Python, Java, Pascal
  • Streamlined, easy to learn API that requires very little lines of code
  • Built-in SDL-based windowing for quick tests
  • Integrate inside any existing framework as a slave renderer
  • Loads assets from open standard standard file formats
  • Create or modify graphic assets procedurally at run time
  • True raster effects: modify render parameters between scanlines
  • Background layer scaling and rotation
  • Sprite scaling
  • Several blending modes for layers and sprites
  • Pixel accurate sprite vs sprite and sprite vs layer collision detection
  • Special effects: per-column offset, mosaic, per-pixel displacement, CRT emulation...

Getting binaries

Download from

The best way to get prebuilt binaries ready to run is grabbing them from official acount: Just download the package for your platform.

Build from source

You can also build the library from source.


First you'll need to provide libpng and SDL2 development libraries (headers and binaries) into the suitable folders inside the /src_lib folder. They're not distributed with Tilengine source. See readme.txt files inside /src_lib/libpng and /src_lib/sdl for detailed instructions.
Open the /Tilengine.sln project, you'll need Visual Studio Community. x86 and x64 targets provided.


Prerequisites: you'll need GNU Make and GCC toolchain, and development libraries for png and SDL2. To install required packages, open a terminal window and run the following command:

> sudo apt-get install build-essential libpng-dev libsdl2-dev

To build the library itself, open a terminal window in /src_lib and run the following command:

> make

After build, file will be placed in /Tilengine/lib folder.


After building from source, open a console window in Tilengine root directory and type the suitable command depending on your platform:


> install


> sudo ./install

Note for OS X users: Tilengine depends on having SDL2 in Framework format installed on your system, that by default is not installed. Please download it here: Homebrew port won't work, use the official DMG file instead.

Running the samples


C samples are located in Tilengine/samples/c folder. To build them you need the gcc compiler suite, and/or Visual C++ in windows.

Once installed, open a console window in the C samples folder and type the suitable command depending on your platform:


> mingw32-make


> make


Python samples are located in Tilengine/samples/python folder. Make sure that Python v2 or v3 is installed on your system before proceeding.

Open a terminal window in the python samples folder, and run any sample by typing python, for example:

> python


C# samples are located in Tilengine/samples/csharp folder. Make sure that Mono or .NET Framework (Windows only) is installed on your system. The following guide assumes Mono usage, please check Microsoft website for .NET Framework related info. C# has separate build and run steps like C, but these steps are the same on all platforms, as in Python.

In order to build the provided sample, open a console window in the C# samples folder and type the following command:

> mcs *.cs

This will produce Platform.exe that can be run with this command:

> mono Platformer.exe

The tilengine window

The following actions can be done in the created window:

  • Press Esc to close the window
  • Press Alt + Enter to toggle full-screen/windowed
  • Press Backspace to toggle built-in CRT effect (enabled by default)

Creating your first program

The following section shows how to create from scratch and execute a simple tilengine application with its three main languages. All programs are equivalent and do the same things:

  1. Reference the inclusion of Tilengine module
  2. Initialize the engine with a resolution of 400x240, one layer, no sprites and 20 animation slots
  3. Set the loading path to the assets folder
  4. Load a tilemap, the asset that contains background layer data
  5. Attach the loaded tilemap to the allocated background layer
  6. Create a display window with default parameters: windowed, auto scale and CRT effect enabled
  7. Run the window loop, updating the display at each iteration until the window is closed
  8. Release allocated resources



Create a file called test.c in Tilengine/samples/c folder, and type the following code:

#include "Tilengine.h"

void main(void)
    TLN_Tilemap foreground;
    int frame = 0;

    TLN_Init (400,240,1,0,20);
    TLN_SetLoadPath ("../assets/sonic");
    foreground = TLN_LoadTilemap ("sonic_md_fg1.tmx", NULL);
    TLN_SetLayer (0, NULL, foreground);

    TLN_CreateWindow (NULL, 0);
    while (TLN_ProcessWindow())
        TLN_DrawFrame (frame);
        frame += 1;

    TLN_Deinit ();

Now the program must be built to produce an executable. Open a console window in the C samples folder and type the suitable command for your platform:

Windows 32-bit

> mingw32-gcc test.c -o test.exe -I"../../include" ../../lib/win32/Tilengine.lib
> test.exe

Linux (32-bit, 64-bit or Raspberry Pi)

> gcc test.c -o test -lTilengine -lm
> ./test

Apple OS X

> gcc test.c -o test "/usr/local/lib/Tilengine.dylib" -lm
> ./test


Create a file called in Tilengine/samples/python folder, and type the following code:

import tilengine as tln

engine = tln.Engine.create(400, 240, 1, 0, 20)
foreground = tln.Tilemap.fromfile("sonic_md_fg1.tmx")

window = tln.Window.create()
while window.process():

Python does not need separate build/run steps, and unlike C language, the procedure is the same for any platform. Just open a console window in the python samples folder and type the following command:

> python


Create a file called test.cs in Tilengine/samples/csharp folder, and type the following code:

using Tilengine;

class Test
    static void Main(string[] args)
        Engine engine = Engine.Init(400,240,1,0,20);
        engine.LoadPath = "../assets/sonic";
        Tilemap background = Tilemap.FromFile("Sonic_md_fg1.tmx", null);

        int frame = 0;
        Window window = Window.Create(null, 0);
        while (window.Process ())

Open a console window in the C# samples folder and type the following commands:

> mcs test.cs Tilengine.cs
> mono test.exe

Editing assets

Tilengine doesn't come with an editor, but the files it loads are made with standard open-source tools. Samples come bundled with several ready-to-use assets, but these are the tools you'll need to edit or create new ones:


These people contributed to tilengine:

@turric4an - the Pascal wrapper
@davideGiovannini - help with the Linux-x86_64 port
@shayneoneill - help with the OS X port
@adtennant - provided cmake and pkg-config support
@tvasenin - improved C# binding
@tyoungjr - LUA/FFI binding