Chapter 03. First steps

Table of Contents

First steps

Initialize

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 10_tilemaps.md "chapter 10". 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 14_bitmaps.md "chapter 14". 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 12_palettes.md "chapter 12". 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:

Cleanup

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