Tilengine: a retro 2D engine with scanline raster effects

The scanline renderer is the point

Tilengine is an open source, cross-platform 2D graphics engine for creating classic and retro games with tile maps, sprites and palettes, and the sentence that explains the whole design is the one about its unique scanline based rendering algorithm.

That algorithm makes raster effects a core feature, and the README is explicit that this is a technique used by many games running on real 2D graphics chips. It is not a filter applied to a finished frame. It is the structure of the renderer.

The difference matters. On a machine with a 2D graphics chip, the console drew one scanline at a time, and the chip had registers that could shift the horizontal position of the output, change the palette lookup, mask pixels or repeat them. A game could make the whole screen wobble because the hardware could wobble the scanline. A modern renderer that draws a frame into a texture and blits it has no such lever, so the same effect has to be reconstructed as a post effect, or as a shader, and it usually looks like a filter rather than like the hardware.

In Tilengine the render parameters can be modified between scanlines, which is what the feature list means by true raster effects: modify render parameters between scanlines.

The other core idea is that Tilengine can be used as a slave renderer inside an existing framework, or on its own with the built-in SDL based windowing for quick tests. That split matters for anyone who already has a game loop, an asset pipeline or an input system and does not want to replace them.

The library is written in portable C, C99, and is licensed under MPL 2.0, which the feature list describes as free for any project, including commercial ones, and it allows console development.

The feature list is a design statement

Reading the features in order tells you what kind of engine this is.

The rendering capabilities come first. Background layer scaling and rotation, sprite scaling, several blending modes for layers and sprites, pixel accurate sprite against sprite and sprite against layer collision detection, and the special effects, which are per-column offset, mosaic, per-pixel displacement and CRT emulation. The collision detection being pixel accurate rather than box based is what makes a retro game feel right, since the hitboxes of a sprite and the visible pixels of a sprite are the same thing on a console.

The asset side follows. Assets are loaded from open standard file formats, and graphic assets can be created or modified procedurally at run time, which is the feature that makes raster effects more than a post pass. A wave distortion applied to a background is a per-scanline parameter change, not a texture effect.

The last two entries are the ones a project of this kind often skips. There is support for packaged assets with optional AES-128 encryption, so a game can ship its art in a single encrypted package rather than loose files. And the MPL 2.0 licence is called out as allowing console development, which matters because closed platform rules about what you may ship and how you may license your engine are a real constraint.

The performance claim is specific in the feature list rather than vague, with all samples running at 60 fps with CRT emulation enabled on a Raspberry Pi 3. That is a meaningful benchmark, since the CRT emulation is the expensive part and the Raspberry Pi 3 is the weakest hardware anyone would target.

Getting the binaries, or building it yourself

The recommended route is prebuilt packages from itch.io, and the README explains why in a phrase, they contain the required dependencies to run.

Building from source is the other route, and the dependencies are SDL2 and libpng, which you have to provide yourself for your target platform.

On Debian based Linux that is a two package install, libpng-dev and libsdl2-dev, and on Windows you are expected to assemble a directory of headers and import libraries, with the libpng headers, the libpng import library, the SDL2 headers and the SDL2 import library placed under the src directory in a layout the table specifies. If that is painful, the itch.io downloads include a pre-packaged archive of the headers and libraries for both 32 and 64 bit platforms.

macOS has the sharpest edge, and the README is unusually direct about it. Tilengine depends on SDL2 being installed in Framework format on the system, and the Homebrew port will not work, so you download the disk image from the SDL releases page instead.

That is a real limitation for a developer on a Mac, because the framework layout is what a signed, bundled application needs, and a Homebrew install is what most people have. The workaround is documented, but it is a manual step every Mac developer performs.

Building the samples, and the window you get

The samples live in the samples folder and are C programs, so you need a compiler suite, GCC on Linux, MinGW or Visual Studio Community on Windows, and the Xcode command line tools on macOS, which need an Apple ID.

Building them is a make invocation, with the Windows variant using the mingw32 make.

> mingw32-make

> make

The window the engine opens is where the engine's own conventions show through, and the three key bindings are worth knowing because they are the same in every sample.

Escape closes the window. Alt with Enter toggles between full screen and windowed. And Backspace toggles the built-in CRT effect, which is enabled by default.

That last one is a design statement rather than a convenience. The CRT effect is on by default, which means the default look of every Tilengine sample is the era-correct look, and the effect is one keypress away for anyone who wants the clean image.

The samples themselves are the documentation for the engine's capabilities, and the file names in the samples directory read as a feature list. There is a Mode7 sample, which is the pseudo 3D background technique from the 16 bit era, a layer window sample, a layer circle sample for circular layer masks, a scaling sample, a shadow sample, a colour cycle sample, a benchmark sample, and complete small games, an actor, a boss, a platformer, a racer, a forest, an explosion, a ship and an enemy.

Your first program, in seven steps

The walkthrough in the README is a complete program, and it is the fastest way to see what the engine's API feels like.

#include "Tilengine.h"

void main(void) {
    TLN_Tilemap foreground;

    TLN_Init (400, 240, 1, 0, 0);
    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 ();
}

The listed steps behind it are the reference manual in miniature. Initialise the engine with a resolution of 400 by 240, one layer, no sprites and no palette animations. Load a tilemap, the asset that holds background layer data. Attach the tilemap to the allocated background layer. Create a display window with default parameters, windowed, auto scale and the CRT effect enabled. Run the window loop, drawing the display each iteration until the window is closed. Release the allocated resources.

The API shape is the notable part. Every call is a TLN_ prefix and a verb, the engine owns its resources and you deinit it, and the window loop is three lines. That is the streamlined API the feature list claims, and it is visible in the sample rather than asserted.

Compiling it is a single command per platform, linking against the shared library on Linux and the dynamic library on macOS, with the include path pointing at the include directory.

Assets, bindings and the missing editor

Two things to expect and one thing you will have to supply yourself.

Tilengine is just a programming library that does not come with any editor, and the documentation says so plainly. The files it loads are made with standard open source tools, and the samples come bundled with ready to use assets, so the workflow is: use your own art pipeline, export to the open formats Tilengine reads, and drop the files in.

The documentation is Doxygen based, generated from the source, with the API reference on the project site. There is a PDF of the manual in the repository root as well, which is the sort of thing that has not been generated in years but has not been removed either.

The bindings section is the part that extends the engine beyond C. The engine is a C library, and a bindings layer means it can be driven from a language with a nicer development experience, which matters because a retro game engine and an editor plus a scripting language is a common pairing. The repository also carries a Visual Studio solution alongside the CMake build, a pkg-config file, a CMake package configuration file, a test directory and an install directory with the install script and a Windows batch variant.

The state of the project is worth noting too. There are no GitHub releases for it, so the versioning is in the changelog at the root, and the last push to the repository was on 2026-08-27. The build badge still points at a Travis configuration at the repository root, which is a sign of a project whose infrastructure is older than its code.

Editorial conclusion

Adopt Tilengine if you are writing a 2D game in C and want a renderer that behaves like a 16 bit console, because the scanline pipeline gives you per column offsets, mosaic, displacement and CRT emulation for free, and the API is small enough to learn in an afternoon. Do not adopt it if you need a modern engine with a scene graph, physics or a scripting layer, since this is a graphics library and nothing more. Before you build, install SDL2 and libpng in the development form, and on macOS download the SDL2 framework, since the Homebrew port does not work with this build.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. megamarc/Tilengine on GitHub
4. Project website
5. README