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. This is a V language binding for Tilengine.
- Tilengine - The 2D retro graphics engine
- Contents
- Features
- Getting binaries
- 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. The binding is MIT license
- Cross platform: available builds for Windows (32/64), Linux PC(32/64), MacOS 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 recommended way to get prebuilt binaries ready to install, run and test samples is grabbing them from official itch.io download. Just download the package for your platform, they contain required dependencies to run.
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 can find the source code here : https://github.com/megamarc/Tilengine
You must provide development libraries:
- SDL: https://www.libsdl.org/download-2.0.php
- libpng: http://gnuwin32.sourceforge.net/packages/libpng.htm
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 itch.io downloads, file is windows_libs.zip. It contains headers and libraries for both 32 and 64 bit platforms.
Just install standard packages libpng-dev and libsdl2-dev
Tilengine depends on having SDL2 in Framework format installed on your system. Homebrew port won't work. Download the latest dmg here: https://github.com/libsdl-org/SDL/releases.
First, you need to build the library from source. See the previous point for more information.
Just put the DLL you compiled into the same directory as your executable.
Execute the install script from the Tilengine repository as administrator.
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 no palette animations
- 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.v, and type the following code:
module main
import tilengine
import math
fn main() {
// We init the engine
tilengine.init(400, 240, 1, 0, 0)
// This will be called once the function ends
defer { tilengine.deinit() }
// We declare and initialize the foreground tilemap
foreground := tilengine.loadtilemap("assets/sonic/Sonic_md_fg1.tmx", "")
// This will be called once the function ends
defer { tilengine.deletetilemap(foreground) }
// Offset used for animation
mut offset := 0.0
// Pointer to offset
mut offset_ptr := &offset
// Raster callback. We capture the pointer to the offset
callback := fn [mut offset_ptr](line int) {
// Frequency of the sine
freq := 2.0
// Clipping the offset value
if *offset_ptr >= (freq * 2 * math.pi * f32(tilengine.getwindowheight()))
{
// Don't worry, I know what I do, and I check if pointer is nil
// So no segfault
unsafe {
if offset_ptr != nil
{
*offset_ptr = 0.0
}
}
}
// We set the position of the layer
tilengine.setlayerposition(
0,
int(math.sin((freq * 2 * math.pi * f32(line) + *offset_ptr)/f32(tilengine.getwindowheight())) * 16),
0
)
}
// We set the callback up
tilengine.setrastercallback(callback)
// We set the tilemap to layer 0
tilengine.setlayertilemap(0, foreground)
// Let's create the window!
tilengine.createwindow("",
[
tilengine.WindowFlags.cwf_vsync,
tilengine.WindowFlags.cwf_s2
])
// A title for the window
tilengine.setwindowtitle("Tilengine on V!!")
// Main loop
for tilengine.processwindow() {
tilengine.drawframe(0)
}
}
Now the program must be built to produce an executable. Open a console window and type the suitable command:
> v test.v
> test.exe
To compile for emscripten, you need to follow a few steps :
- Download and install Emscripten
- Compile the Emscripten version of Tilengine
- Avoid closures in your V program, otherwise it won't work!
- Download this HTML file : https://github.com/megamarc/Tilengine/blob/html5/samples/shell_minimal.html
- compile with :
emcc -O1 -I"{Dir_To_Your_Tilengine.h}" -L"{Dir_To_Your_Tilengine_WASM_Lib}" -lz -lpng -lSDL2 -lTilengine --shell-file shell_minimal.html .\testem.c -o -o {Out_Folder}/out.html --preload-file {Path_To_Your_Assets}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, tiles & sprites: Aseprite, Piskel, Grafx2...
- Maps: Tiled Map Editor
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 |
| C# | CsTilenginePure |
| Pascal | PascalTileEngine |
| FreeBasic | FBTilengine |
| Java | JTilengine |
| Rust | tilengine-sys |
| LuaJIT | tilengine_libretro (libretro core) |
| Ring | RingTilengine |
| Nim | nim-tilengine |
| V | V-Tilengine |
These kind users 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
@vonhoff - provided CsTilenginePure binding