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.