Getting started

This guide takes you through writing a simple application using Tilengine. The application will initialize the engine, create a window, load a background layer and a sprite, and exit when the user closes the window. This guide will introduce a few of the most commonly used functions, but there are many more.

Step by step

Including the Tilengine header

In the source files of your application where you use Tilengine, you need to include the header file:

#include "Tilengine.h"

Initializing the engine

First step is initialize the engine with TLN_Init. This takes the following parameters, that will remain constant and cannot be changed once the engine is initialized:

TLN_Init(480, 272, 4, 64, 0);

This creates a framebuffer of 480x272 pixels, 4 background layers, 64 sprites and no palette animations.

Creating a window

By default Tilengine doesn't create a window when it's initialized, because it is designed to act as a slave renderer for any framework or environment. However it also provides its own window environment.

To create a window, call TLN_CreateWindow after having called TLN_Init:

This creates a default window. There are some key bindings:

  • Press Esc to close the window
  • Press Alt + Enter to toggle full-screen/windowed
  • Press Backspace to toggle on/off built-in CRT effect (default on)

Loading a tilemap

Tilemaps with the layout of backgrounds are stored inside .tmx files. Each .tmx file can contain many tilemap and object layers. To load one, call TLN_LoadTilemap with the filename and the name of the layer to load, and returns a TLN_Tilemap handler:

TLN_Tilemap background = TLN_LoadTilemap ("ruff_n_tumble.tmx", NULL);

Setting the layer

Once the tilemap is loaded, it must be assigned to one of the available background layers with TLN_SetLayerTilemap, passing the layer index and the loaded tilemap:

TLN_SetLayerTilemap(0, background);

Scrolling the background layer

By default the tilemap is aligned to the top-left corner of the screen (position 0,0). To move it to another position, use TLN_SetLayerPosition passing the layer index and the [x, y] position inside the tilemap:

This advances the viewport of layer 0 32 pixels to the right.

Loading a spriteset

Spritesets containing the animation frames for a sprite are contained inside .png files with layout information in associated .txt, .csv, or .json text files. They're loaded with TLN_LoadSpriteset passing the .png file, and return a TLN_Spriteset handler:

TLN_Spriteset character = TLN_LoadSpriteset("ruff1.png");

Setting the sprite

Once the spriteset is loaded, it must be assigned to one of the available spritest with TLN_SetSpriteSet, passing the sprite index and the loaded spriteset:

TLN_SetSpriteSet(0, character);

Moving the sprite around

By default, the sprite is initialized at position 0,0, (top left corner). To move it to another location, use TLN_SetSpritePosition passing the sprite index, and the, x,y screen coordinates:

TLN_SetSpritePosition(0, 160, 192);

Setting the sprite image

A spriteset contains many frames of animation. By default a sprite is assigned the first image of the spriteset. Images in a spriteset are referenced with their index, starting from 0. Indexes can be obtained from sprite name with TLN_FindSpritesetSprite and assigned with TLN_SetSpritePicture passing sprite index and frame index:

int frame = TLN_FindSpritesetSprite(spriteset, "standing1");

A good practice is to cache the indexes of required frames so they don't need to be searched every time.

Running the window loop

On each frame the window must be updated with TLN_ProcessWindow, which returns true until the user requests closing the window, and the frame must be rendered with TLN_DrawFrame. Parameter "frame" is deprecated and can be left as 0:

while (TLN_ProcessWindow()) {

The window will continue active until closed or Esc key is pressed.

Putting it together

Now it's possible to create a simple program that initializes the engine, creates a window, and sets up a background layer and a sprite loaded from asset files:

Source code

#include "Tilengine.h"
void main(void) {
TLN_Tilemap background;
TLN_Spriteset character;
/* init engine and window */
TLN_Init(480, 272, 4, 64, 0);
TLN_CreateWindow (NULL, 0);
/* setup background layer */
background = TLN_LoadTilemap ("ruff_n_tumble.tmx", NULL);
TLN_SetLayerTilemap (0, background);
/* setup sprite */
character = TLN_LoadSpriteset("ruff1.png");
TLN_SetSpriteSet(0, character);
TLN_SetSpritePosition(0, 160, 192);
/* loop until close */
/* release resources */


To build for Linux, just link with libTilengine.so library:

gcc test.c -lTilengine -o test

Building for Windows requires linking to Tilengine.lib:

gcc test.c Tilengine.lib -o test.exe

Final result

bool TLN_CreateWindow(const char *overlay, int flags)
Creates a window for rendering.
Definition: Window.c:383
TLN_Spriteset TLN_LoadSpriteset(const char *name)
Loads a spriteset from an image png and its associated atlas descriptor.
Definition: LoadSpriteset.c:121
bool TLN_DeleteSpriteset(TLN_Spriteset Spriteset)
Deletes the specified spriteset and frees memory.
Definition: Spriteset.c:170
bool TLN_SetSpriteSet(int nsprite, TLN_Spriteset spriteset)
Assigns the spriteset and its palette to a given sprite.
Definition: Sprite.c:70
struct Spriteset * TLN_Spriteset
Definition: Tilengine.h:262
bool TLN_SetLayerTilemap(int nlayer, TLN_Tilemap tilemap)
Configures a tiled background layer with the specified tilemap.
Definition: Layer.c:134
void TLN_DeleteWindow(void)
Deletes the window previoulsy created with TLN_CreateWindow() or TLN_CreateWindowThread()
Definition: Window.c:480
void TLN_Deinit(void)
Deinitialises current engine context and frees used resources.
Definition: Tilengine.c:219
bool TLN_DeleteTilemap(TLN_Tilemap tilemap)
Deletes the specified tilemap and frees memory.
Definition: Tilemap.c:336
bool TLN_SetSpritePosition(int nsprite, int x, int y)
Sets the sprite position in screen space.
Definition: Sprite.c:171
bool TLN_SetSpritePicture(int nsprite, int entry)
Sets the actual graphic to the sprite.
Definition: Sprite.c:202
struct Tilemap * TLN_Tilemap
Definition: Tilengine.h:260
TLN_Engine TLN_Init(int hres, int vres, int numlayers, int numsprites, int numanimations)
Initializes the graphic engine.
Definition: Tilengine.c:57
void TLN_DrawFrame(int frame)
Draws a frame to the window.
Definition: Window.c:1011
TLN_Tilemap TLN_LoadTilemap(const char *filename, const char *layername)
Loads a tilemap layer from a Tiled .tmx file.
Definition: LoadTilemap.c:171
bool TLN_SetLayerPosition(int nlayer, int hstart, int vstart)
Sets the position of the tileset that corresponds to the upper left corner.
Definition: Layer.c:547
int TLN_FindSpritesetSprite(TLN_Spriteset spriteset, const char *name)
Returns a reference to the palette associated to the specified spriteset.
Definition: Spriteset.c:253
bool TLN_ProcessWindow(void)
Does basic window housekeeping in signgle-threaded window.
Definition: Window.c:592