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.
- Features
- Getting binaries
- Installing
- Running the samples
- The tilengine window
- Creating your first program
- Documentation
- Editing assets
- Creating packages
- Bindings
- Contributors
- 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
The best way to get prebuilt binaries ready to run is grabbing them from official itch.io acount: https://megamarc.itch.io/tilengine. Just download the package for your platform. You can also find prebuilt binaries and their dependencies inside the /lib directory
You can also build the library from source. It's very easy:
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 and run the following command:
> make
After build, libTilengine.so 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: https://www.libsdl.org/release/SDL2-2.0.5.dmg. Homebrew port won't work, use the official DMG file instead.
C samples are located in Tilengine/samples folder. To build them you need the gcc compiler suite, and/or Visual C++ in windows.
- Linux: the GCC compiler suite is already installed by default
- Windows: you must install MinGW or Visual Studio Community
- Apple OS X: You must install Command-line tools for Xcode. An Apple ID account is required.
Once installed, open a console window in the C samples folder and type the suitable command depending on your platform:
> mingw32-make
> make
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)
The following section shows how to create from scratch and execute a simple tilengine application that does the following:
- Reference the inclusion of Tilengine module
- Initialize the engine with a resolution of 400x240, one layer, no sprites and 20 animation slots
- Set the loading path to the assets folder
- Load a tilemap, the asset that contains background layer data
- Attach the loaded tilemap to the allocated background layer
- Create a display window with default parameters: windowed, auto scale and CRT effect enabled
- Run the window loop, updating the display at each iteration until the window is closed
- 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;
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:
> gcc test.c -o test.exe -I"../include" ../lib/Win32/Tilengine.dll
> test.exe
> gcc test.c -o test -lTilengine -lm
> ./test
> 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: http://www.tilengine.org/doc
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:
- Source code: VSCode, Notepad++...
- Graphics: GIMP, Grafx2, Paint.NET, or any graphic editor with 8-bit (256 colors) png support
- Backgrounds: Tiled Map Editor is the official editor
- Sprites: Online tool Lesy SpriteSheet
- Sequences: Any standard XML editor
To create a package with all the assets, the open-source tool ResourcePacker must be used. It's a corss-platform, easy to use 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