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
- 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
- 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...
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_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, 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/c 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
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 name_of_the_sample.py, for example:
> python platformer.py
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 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 with its three main languages. All programs are equivalent and do the same things:
- 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/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:
> 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
Create a file called test.py in Tilengine/samples/python folder, and type the following code:
import tilengine as tln
engine = tln.Engine.create(400, 240, 1, 0, 20)
engine.set_load_path("../assets/sonic")
foreground = tln.Tilemap.fromfile("sonic_md_fg1.tmx")
engine.layers[0].setup(foreground)
window = tln.Window.create()
while window.process():
window.draw_frame()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 test.py
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);
engine.Layers[0].SetMap(background);
int frame = 0;
Window window = Window.Create(null, 0);
while (window.Process ())
{
window.DrawFrame(frame);
frame++;
}
engine.Deinit();
}
}Open a console window in the C# samples folder and type the following commands:
> mcs test.cs Tilengine.cs
> mono test.exe
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:
- 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