First steps


First of all, you have to include the header at the top of the file:

#include "Tilengine.h

To initialize the engine, use the function TLN_Init to set the framebuffer resolution, and the number of layers, sprites, and animators. Once set, these values are immutable and cannot be changed. For example, to set a 400x240 framebuffer with 2 layers, 80 sprites and no animations -Sega Genesis setup- you should do:

TLN_Init (400,240, 2,80,0);

Setting the background

The background is what is shown when there isn't any layer or sprite at a given location. Tilengine supports two types of backgrounds: solid color and static bitmap. By default the background is black color.

Solid color background

To set a solid color there is the function TLN_SetBGColor that takes the three components of a RGB color, between 0 and 255. For example to set a dark blue background you can do:

TLN_SetBGColor (0,32,96);

It is also possible to set the background color defined inside a tilemap object with the TLN_SetBGColorFromTilemap function. Tilemaps may specify a default background color that can be used here. To see how to load and manipulate tilemaps, please refer to Tilemaps section. For now, to load a tilemap called "tilemap.tmx" and use its default background color, you have to do the following:

TLN_Tilemap tilemap = TLN_LoadTilemap ("tilemap.tmx");

Bitmap background

To set a bitmap, there is the function TLN_SetBGBitmap that takes the TLN_Bitmap reference of a loaded bitmap. To see how to load an manipulate bitmaps, please refer to Bitmaps section. For now, to load a bitmap called "Background.png" and set it as the background, you have to do the following:

TLN_Bitmap background = TLN_LoadBitmap ("Background.png");
TLN_SetBGBitmap (background);

It's possible to change the default palette provided by the bitmap. To do so, use the TLN_SetBGPalette function that takes a TLN_Palette object. To see how to load and manipulate palettes, please refer to Palettes section. Assuming you have an alternative palette file called "Background.act", do the following to set it:

TLN_Palette palette = TLN_LoadPalette ("Background.act");
TLN_SetBGPalette (palette);

Disabling background

It is possible to disable background at all if you know that the last layer covers the entire screen without holes, to gain some performance:

Setting the assets path

By default tilengine loads all graphic assets in the same directory where the executable is. If you want to set your assets in a structured tree of folders -which is recommended-, you can set it with the TLN_SetLoadPath function. It accepts relative or absolute paths, and interprets slash and backslash as path separator on any platform. For example:

TLN_SetLoadPath ("./assets/level1");

Error handling

Most functions in tilengine return either a reference to a requested object, or a boolean value signaling if the operation was successful or not. When an operation fails you can get an specific error code with the TLN_GetLastError, whereas the TLN_GetErrorString returns a string with a description about the requested error code:

int error = TLN_GetLastError ();
char* description = TLN_GetErrorString (error);
printf ("Last operation returned with code %d: %s\n", error, description);

Getting runtime info

Tilengine keeps track about the memory being used, the number of assets, the framebuffer size, etc:


Tilengine does sanity check on each parameter and silently ignores a function call when there are some mistakes on the parameters (indexes out of range, wrong object types, etc). Each function that can fail returns a false boolean that can be further examinated with TLN_GetLastError and TLN_GetErrorString. However this approach requires much work and manual test when something isn't working as expected. To ease the debugging of your program, Tilengine supports writing messages to the standard output. This behavior is selected with TLN_SetLogLevel, with three possible values:

Value Effect
TLN_LOG_NONE Doesn't output anything (default value)
TLN_LOG_ERRORS Print only wrong function calls
TLN_LOG_VERBOSE Print wrong function calls and every asset creation/destruction
/* enable basic logging, just errors: */
/* force an error: "Tilengine: Invalid object address is (nil)" */
TLN_SetLayer (0, NULL, NULL);


Once done, you should explicitly close tilengine to release memory and resources:

Multiple contexts

Since release 2.0.0, Tilengine supports multiple instances using a global context mechanism. The TLN_Init function returns a handler to a newly created context (a TLN_Engine object), that is selected as active by default. To change the active context use the TLN_SetContext function, passing the handler of the desired context. To delete a context, use TLN_DeleteContext.

TLN_Engine instance1 = TLN_Init(480, 240, 2,8, 0); /* instance 1 */
TLN_Engine instance2 = TLN_Init(360, 160, 1,8, 0); /* instance 2 */
/* do stuff on instance 1: */
/* ... do your stuff with regular TLN_xxx functions */
/* do stuff on instance 2: */
/* ... do your stuff with regular TLN_xxx functions */
/* release */


This is a quick reference of related functions in this chapter:

Function Quick description
TLN_GetVersion Returns library version
TLN_Init Creates a Tilengine rendering context
TLN_Deinit Destroys the current rendering context
TLN_SetContext Selects the active context
TLN_GetContext Returns the active context
TLN_DeleteContext Destroys the specified context
TLN_SetLoadPath Sets defautl load path for asset loading
TLN_GetWidth Returns the width of the created framebuffer
TLN_GetHeight Returns the height of the created framebuffer
TLN_GetNumObjects Returns the number of runtime assets
TLN_GetUsedMemory Returns the amount of memory used by runtime assets
TLN_GetNumLayers Returns the number of requested layers
TLN_GetNumSprites Returns the number of requested sprites
TLN_SetBGColor Sets the default background color
TLN_SetBGColorFromTilemap Sets the background color as defined in a given tilemap
TLN_DisableBGColor Disables use of background color
TLN_SetBGBitmap Sets a static background bitmap
TLN_SetBGPalette Sets the palette of the static background bitmap
TLN_SetLogLevel Sets the verbosity of debug messages
TLN_GetLastError Returns the code of last error
TLN_GetErrorString Returns the string value of a given error code
bool TLN_SetBGColorFromTilemap(TLN_Tilemap tilemap)
Sets the background color from a Tilemap defined color.
Definition: Tilengine.c:533
bool TLN_SetLayer(int nlayer, TLN_Tileset tileset, TLN_Tilemap tilemap)
Configures a background layer with the specified tileset and tilemap.
Definition: Layer.c:45
bool TLN_DeleteContext(TLN_Engine context)
Deletes explicit context.
Definition: Tilengine.c:222
void TLN_SetLoadPath(const char *path)
Sets base path for TLN_LoadXXX functions.
Definition: LoadFile.c:38
void TLN_DisableBGColor(void)
Disales background color rendering. If you know that the last background layer will always cover the ...
Definition: Tilengine.c:552
void TLN_Deinit(void)
Deinitialises current engine context and frees used resources.
Definition: Tilengine.c:206
TLN_Bitmap TLN_LoadBitmap(const char *filename)
Load image file (8-bit BMP or PNG)
Definition: LoadBitmap.c:204
TLN_Error TLN_GetLastError(void)
Returns the last error after an invalid operation.
Definition: Tilengine.c:712
struct Tilemap * TLN_Tilemap
Definition: Tilengine.h:244
const char * TLN_GetErrorString(TLN_Error error)
Returns the string description of the specified error code.
Definition: Tilengine.c:730
TLN_Engine TLN_Init(int hres, int vres, int numlayers, int numsprites, int numanimations)
Initializes the graphic engine.
Definition: Tilengine.c:56
bool TLN_SetContext(TLN_Engine context)
Sets current engine context.
Definition: Tilengine.c:178
void TLN_SetLogLevel(TLN_LogLevel log_level)
Sets logging level for current instance.
Definition: Tilengine.c:266
TLN_Palette TLN_LoadPalette(const char *filename)
Loads a palette from a standard .act file.
Definition: LoadPalette.c:46
Definition: Tilengine.h:371
struct Bitmap * TLN_Bitmap
Definition: Tilengine.h:249
TLN_Tilemap TLN_LoadTilemap(const char *filename, const char *layername)
Loads a tilemap layer from a Tiled .tmx file.
Definition: LoadTilemap.c:156
struct Engine * TLN_Engine
Definition: Tilengine.h:241
struct Palette * TLN_Palette
Definition: Tilengine.h:245
bool TLN_SetBGPalette(TLN_Palette palette)
Changes the palette for the background bitmap.
Definition: Tilengine.c:593
bool TLN_SetBGBitmap(TLN_Bitmap bitmap)
Sets a static bitmap as background.
Definition: Tilengine.c:570
void TLN_SetBGColor(uint8_t r, uint8_t g, uint8_t b)
Sets the background color.
Definition: Tilengine.c:521