Getting Started

Whenever you start work on a project in Xentu, you should create a folder to host the files within.

Every game you create needs a game.lua file that contains game code, and an optional config.toml file to configure how the engine should behave as it loads. You can also include a game.ico if you wish to set an app icon for your game.

Here is good example of how you can structure the files for a project:

config.toml
game.lua
game.ico
images/texture1.png
sounds/hit1.wav

Make sure you place these files in a unique folder, not just on your desktop, or in the documents folder. Keeping your files tidy, will make sure you don’t run into problems later down the road when you try to share your game with others.



The config.toml file

When Xentu launches, it looks for a config.toml file to configure the game window. The configuration is written using the TOML file format. Here is an example of how one of these files looks:

[general]
game_title = 'Brick Breaker'
screen_width = 1280
screen_height = 720
update_frequency = 60
vsync = true
fullscreen = false

[viewport]
width = 800
height = 600
mode = 1

For now the [general] and [viewport] groups are the only built-in ones that have some rules. For example the engine will throw an error if you use anything but a rational integer for screen_width or screen_height.

The TOML file format.

This format was chosen to allow you can provide end users the ability to configure your game further, by reading custom set config values later in your game code.


Here is a list of commands that you can use in the [general] group:

Key

Data Type

Description

game_title

string

The title of the game window.

game_author

string

The author of the game.

screen_width

integer

The width of the window in pixels.

screen_height

integer

The height of the window in pixels.

update_frequency

integer

The target number of update calls per-second.

vsync

boolean

Enable or disable vertical sync.

fullscreen

boolean

Enable or disable full-screen on load.

Here is a list of commands that you can use in the [viewport] group:

Key

Data Type

Description

width

integer

The width of the viewport in pixels.

height

integer

The height of the viewport in pixels.

mode

integer

The size mode of the viewport

The viewport is the rendered canvas. If the viewport is smaller than the screen, then black borders will appear. If the viewport is larger, then the rendered game will be clipped.

Setting the mode decides where to place the viewport. The valid values are 0 for normal (top left), 1 to place the viewport in the centre of the screen, or 2 to stretch the viewport to all 4 corners.



The game.lua file

When Xentu launches, it looks for a game.lua file to execute. Here is an example of how this file could look:

game.on("init", function()
   -- load a tilemap
   map = assets.load_tilemap("desert.tmx")
   layer = map.get_layer(0)

   -- set the background color.
   renderer.set_clear_color( Color.fromHex('#5f7988') )
end)


-- the update event.
game.on("update", function()
   -- do nothing for now
end)

-- the drawing event.
game.on("draw", function()
   renderer.clear()
   renderer.begin()
   -- draw a layer [layer, x, y]
   renderer.draw_tilemap_layer(layer, 0, 0)
   renderer.present()
end)

This example loads a TMX file created with the Tiled map editor. On the “init” event, a reference to the first layer is created, then we ask the game to render that layer over and over in the “draw” event.