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
- Contributors
- 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
- 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...
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 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 folder. They're not distributed with Tilengine source. See readme.txt files inside /src/libpng and /src/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 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:
> mingw32-gcc test.c -o test.exe -I"../include" ../lib/win32/Tilengine.lib
> 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
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