Skip to content
Free 2D graphics engine with raster effects for retro/classic style game development
C Other
  1. C 99.5%
  2. Other 0.5%
Branch: master
Clone or download

Latest commit

megamarc * Adds FLAG_MASKED, deprecates TLN_EnableSpriteMasking
* Adds TLN_EnableSpriteFlag, deprecates TLN_SetSpriteFlags and TLN_ConfigSprite
* TLN_SetTilemapTile: acceps NULL as TLN_Tile parameter for setting an empty tile
* Updates documentation, adds diagrams
Latest commit 68ee0ef May 22, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
docs * Adds FLAG_MASKED, deprecates TLN_EnableSpriteMasking May 22, 2020
include * Adds FLAG_MASKED, deprecates TLN_EnableSpriteMasking May 22, 2020
src * Adds FLAG_MASKED, deprecates TLN_EnableSpriteMasking May 22, 2020
.gitattributes First public commit Sep 6, 2015
.gitignore Tilengine 2.0 LGPL Jul 4, 2018
.travis.yml * Fixes /samples/Makefile LIBPATH pointing to correct lib path /lib/l… Apr 16, 2020 Release 2.8.4 May 12, 2020
LICENSE Updates main May 16, 2020
Tilengine.pdf Linux amd64 build Jan 18, 2017
Tilengine.png Release 1.15 - Major project reorganisation Aug 6, 2017
Tilengine.sln Project reorganisation Oct 10, 2018
install * Updates documentation sections Apr 26, 2020
install.bat Updates deploy Oct 25, 2018
test.png Release 1.15 - Major project reorganisation Aug 6, 2017
tilengine-config.cmake Unified install and makefile, cmake + pkg-config Aug 16, 2017
tilengine.pc Unified install and makefile, cmake + pkg-config Aug 16, 2017

Tilengine logo

Tilengine - The 2D retro graphics engine

License: MPL 2.0 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)
  • MPL 2.0 license: free for any project, including commercial ones, allows console development
  • 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
  • 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...
  • Supports packaged assets with optional AES-128 encryption

Getting binaries

Download from

The recommended way to get prebuilt binaries ready to install, run and test samples is grabbing them from official download. Just download the package for your platform, they contain required dependencies to run.

Build from source

You can also build the library from source. Tilengine requires SDL2 and libpng to build, you must provide these libraries yourself depending on your target platform.


You must provide development libraries:

Put the following files inside the src directory:

Path Files
src\libpng libpng headers
src\libpng\$(Platform) libpng.lib import library
src\sdl\SDL2 SDL2 headers
src\sdl\lib\$(Platform) SDL2.lib import library

NOTE: If you're having problems setting up these dependencies, you can download them already pre-packaged from downloads, file is It contains headers and libraries for both 32 and 64 bit platforms.

Debian-based linux

Just install standard packages libpng-dev and libsdl2-dev

Apple OSX

SDL2 development libraries for OSX can be download here:

Running the samples

C samples are located in Tilengine/samples 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

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 that does the following:

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


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

#include "Tilengine.h"

void main(void) {
    TLN_Tilemap foreground;

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

    TLN_CreateWindow (NULL, 0);
    while (TLN_ProcessWindow()) {
        TLN_DrawFrame (0);

    TLN_DeleteTilemap (foreground);
    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:


> gcc test.c -o test.exe -I"../include" ../lib/Win32/Tilengine.dll
> test.exe


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

Apple OS X

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


Doxygen-based documentation and API reference can be found in the following link:

Editing assets

Tilengine is just a programming library that doesn't come with any 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:

Creating packages

To create a package with all the assets, the add-on tool ResourcePacker must be used. It's a Windows command-line tool that creates packages with files keeping the same directory structure. Tilengine has built-in support for loading assets from these packages just as if they still were stand-alone files.


There are bindings to use Tilengine from several programming languages:

Language Binding
C/C++ Native support, no binding required
Python PyTilengine
C# CsTilengine
Pascal PascalTileEngine
FreeBasic FBTilengine
Java JTilengine


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

You can’t perform that action at this time.