Solarus Wiki

A wiki for the Solarus engine community

User Tools

Site Tools


tutorial:getting_started

Chap. 2Table of Contents

Chapter 1 - Getting Started

Welcome to this tutorial allowing you to develop your own game from the beginning with the Solarus engine! In this first part, we will see how to configure the engine to launch the title screen of your game. This title screen will consist of only one image.

Prerequisites

You must have Java (minimum Java 7) installed on your machine to run the quest editor. Be aware that this editor will be undergoing a redesign and that it will be totally independent of java soon. The engine does not need anything special to run, the various libraries it depends on are included when downloading or installing according to your system.

To create a quest, you will have to program your maps and menus scripts in the Lua programming language. This series of tutorials will explain the Lua language as you go along with the Lua functions available in Solarus, but it is still necessary to know some basics of programming (whatever the language). If you want to learn the Lua language, we recommend the book Programming in Lua.

Download the Engine

First you need to download the Solarus engine. At the time of writing this tutorial, the latest version available is version 1.0.4, but you can follow the tutorial even with a newer version. In the version numbers, we will mostly ignore the third digit because it only ever introduces bug fixes, not incompatibilities. So we'll talk about version 1.0.

Solarus 1.0 still has some hard-coded elements, or elements you can not modify. These elements consist of the dialog box and the game-over screen. These elements can be customized in version 1.1, which has not yet been released at the time of writing. In addition, some files will have to be modified by hand because the quest editor does not yet allow to edit them graphically. This series of tutorials will explain how to do this.

Download the Solarus Engine.

In this tutorial, we will describe the procedure to follow if you are running Windows, but the procedure is similar across all operating systems.

The downloaded files are in archive format and not executable. Extract this archive wherever you want. For practical reasons, the folder used in this tutorial will be C:\Solarus. The archive contains two folders and the two license/readme files. The first folder named solarus contains the engine (an executable file). The second one, called solarus_quest_editor, contains the quest editor, a software to modify maps, tilesets, sprites, everything related to your game.

Once the files are extracted, if you try to start the game, an error occurs. This is because the engine needs a specific folder to be able to launch: a folder named data containing the quest itself. The engine has created an error.txt file that will help you in your development. This file contains the error messages that occurred when the engine was last started. This file is very important and you will have to learn how to read it.

For the current error, the current contents of error.txt are:

No quest was found in the directory '.'. To specify your quest's path, run: C:\Solarus\solarus.exe path/to/quest

This message means that since you did not specify a quest file by launching the game, the engine took the current directory as the default (represented by a “.”), but did not find a quest file, therefore nothing can be launched. You could create the quest record by hand, but it would be an extremely long and tedious job. That is why the second file of the archive exists, namely solarus_quest_editor.

Creating Your Quest

In this folder, run the file starting with solarus-editor. Here, it will ask you to choose the “root” folder of your project, that is to say the folder including the “data” folder, the latter containing the files of your quest. As you do not have any yet, exit this window (this window will be removed from the editor in Solarus 1.1). You get to the rather empty interface for now, Solarus Quest Editor, the quest editor. Make QuestNew quest , and choose the C:\Solarus\solarus folder where the engine is located (for convenience reasons because remember: it will search for the quest folder in the current directory).

As you can see, the editor tells you that some files still need to be created/modified by hand, but these files will be created directly in future versions. More precisely, the subfolders necessary for the proper operation of the game will be created automatically from 1.1. To begin, you will need to modify the quest.dat file. It is currently filled with default information.

Configuring Your Quest

To modify the quest.dat file that is located in data with your preferred text editor (Notepad++ is highly recommended). This file is a data file used by the engine, the syntax resembles Lua very closely, but it is actually a data file and not code at all. Here are the contents of the file when it was created by the quest editor:

quest{
  -- Format of your quest data files. You should not change this unless you
  -- know what you are doing.
  solarus_version = "1.0",
 
  -- Directory where your quest will write its savegames and setting files.
  -- It will be a subdirectory of '$HOME/.solarus/', automatically created by
  -- the engine. Its name should identify your quest, to avoid confusion with
  -- other Solarus quests that might also be installed on the user's machine.
  -- You must define it before you can use savegames or setting files.
  -- Uncomment the line below and set its value to the name of that directory:
  -- write_dir = "",
 
  -- Title of the window. You should probably put the title of your game here.
  title_bar = "A game made with Solarus. Edit quest.dat to change this title!",
}

Let's analyze this file. All the lines that start with - are what are called comment lines, that is, they will not be interpreted by the engine. In the configuration files, comments are not extremely useful, because you will not edit them often, and the engine should eventually manage them all. In your code, however, you SHOULD write comments as often as you write code, because code that seems logical to you at one moment after thinking about it for three hours, but if you come back a few months later to make a change and haven't commented on your code, you'll find yourself having to devote three hours to figure out what you were trying to accomplish with this code. In this file, the comments especially help let the people who have just created their quests know what to do.

The fourth line indicates the version of the engine the quest will use. Here solarus_version = 1.0, so the game will be compatible with the Solarus 1.0 engine.

Line 12 is a comment, but you have to uncomment it: the folder you specify will be your quest backup folder. This allows you to do multiple quests and prevents backups from overwriting each other. The name you put in this variable will be in your_user_folder/.solarus/. For example, on Windows, if the logged-in user is named John, and the name given in write_dir is “my_game”, the backups will be in C:\Users\John\.solarus\my_game. On Linux, it will be in ~/.Solarus/my_game. This folder is a hidden folder, so do not forget to show them if you want to access the backup directory. For this tutorial, we will write in the folder “tuto_solarus”

Line fifteen is the name that will be displayed in the title bar of the game. Let's say you put “My First Quest!” for example. Save the file and try to start the game. If you see “?” Instead of accents, your file was saved in the wrong format. All data files used by Solarus must be encoded in UTF-8. If you are on Notepad ++, do Encoding → Convert to UTF-8 (without BOM). The “without BOM” is important, otherwise you will encounter a fatal error because an invisible character will be inserted at the beginning of the file. Note that you can also change the title of this window at any time in the game through a specific function. So you can customize the title according to where the hero is, and so on.

The file at the end looks like this:

quest{
  -- Format of your quest data files. You should not change this unless you
  -- know what you are doing.
  solarus_version = "1.0",
 
  -- Directory where your quest will write its savegames and setting files.
  -- It will be a subdirectory of '$HOME/.solarus/', automatically created by
  -- the engine. Its name should identify your quest, to avoid confusion with
  -- other Solarus quests that might also be installed on the user's machine.
  -- You must define it before you can use savegames or setting files.
  -- Uncomment the line below and set its value to the name of that directory:
  write_dir = "tuto_solarus",
 
  -- Title of the window. You should probably put the title of your game here.
  title_bar = "My First Quest!",
}

As you can see, the game launches on a black screen, because your quest is empty: it has just been created. The only thing you have changed is where the backups will be written and what title your game will have. Let's make this into a title screen, just to dress it up a bit.

A Title Screen

This won't be a real menu we are going to do, but rather just display an image to start with. You can use any picture you want to do this. In our case we will use this picture. To do this, we will write our first lines of programming in Lua, but first you'll need to copy the image you just downloaded into data\sprites (you have to create the folder by hand for version 1.0, while version 1.1 will initialize The files at the creation of the quest). Go to main.lua next to quest.dat. Here is the code it contains:

-- This is the main Lua script of your project.
-- You will probably make a title screen and then start a game.
-- See the Lua API! http://www.solarus-games.org/solarus/documentation/
 
-- Below is just an example of quest that does almost nothing.
-- Feel free to change this!
function sol.main.on_started()
  -- This function is called when Solarus starts.
  print("Welcome to my quest.")
end
 
function sol.main.on_finished()
  -- This function is called when Solarus stops or is reset.
  print("See you!")
end

Let's take a look at this new file again. The first six lines are comments generated by the quest editor at creation. There are then two functions: sol.main.on_started() and sol.main.on_finished(). It is necessary to know that in Lua, everything is a table, and the syntax “something.value” means that the element “value” is accessed in the “something” chart. Here, sol refers to the Solarus engine, which contains several elements including main. This main will call functions by itself: at startup it will call on_started and when the game is closed, it will call on_finished.

First, we will declare a local variable in the file, which will contain our image. So just add, apart from the already existing functions (eg after on_started to line 17):

local title_img = sol.surface.create("title_img.png")

What did we just do? We created a variable called “title_img”, and then created a surface that is stored in this variable. To create the surface, we call the function sol.surface.create with the name of the image to be loaded as the only parameter. The fact that this variable is outside of any function causes it to be initialized even before sol.main.on_started can be called. Now that we have our image, we will be able to display it. To do this, we will write a new function just below the creation of the variable:

function sol.main:on_draw(screen)
  title_img:draw(screen)
end

Again, let's take a look at what we just did. We just defined one of the functions provided by the engine, this function is called on_draw and is part of sol.main. The engine will call this function repeatedly to say “draw what you need to draw on this screen”. And when the engine goes to ask for it, we tell it “you take the image title_img that we created, and you draw it on the screen”. Hence the only line of this function title_img:draw(screen). Our function on_draw takes a parameter, the screen, which is sent automatically by the engine because, as we established earlier, it is the engine that calls your function on_draw.

At this point, we already notice that there are two main categories of functions in Solarus according to the sense in which they are called:

  • The functions provided by Solarus and that your Lua scripts can call, like sol.surface.create() or title_img:draw(screen).
  • The functions that you define yourself and that Solarus automatically calls (when they exist), such as sol.main:on_draw(screen).

These functions have a name that always starts with “on_”, and we call them events.

All of these functions, including events, are documented in the Solarus Reference API.

Note that for some functions, we use syntax with the symbol colon, like this: object:function(). In fact, using object:function() is just a shortcut to say object.function(object). The functions on_started and on_finished should also be in the format with “:” instead of “.”. This is an inconsequential oversight that will undoubtedly be rectified in Solarus 1.1.

If you save and run the game, you should see your image displayed. You'll notice that the image is drawn from the top left corner of the screen. This is because, as you did not specify where to display the image, it is displayed at 0, 0. That is, the top left corner of the image is at the top-left coordinates of the screen. You can change these coordinates, for example by putting title_img:draw(screen, 20, 50). Restart the game and you will see the difference by yourself. Have fun doing some coordinate tests to better understand position, and remember, the coordinates are always relative to the top left corner.

Here is the main.lua file you have:

-- This is the main Lua script of your project.
-- You will probably make a title screen and then start a game.
-- See the Lua API! http://www.solarus-games.org/solarus/documentation/
 
-- Below is just an example of quest that does almost nothing.
-- Feel free to change this!
function sol.main.on_started()
  -- This function is called when Solarus starts.
  print("Welcome to my quest.")
end
 
function sol.main.on_finished()
  -- This function is called when Solarus stops or is reset.
  print("See you!")
end
 
local title_img = sol.surface.create("title_img.png")
function sol.main:on_draw(screen)
  title_img:draw(screen, 20, 50)
end

Exercice

We are not going to do a very complicated exercise here. Knowing that the screen size is 320 × 240 (so: 320 pixels wide by 240 high), and that the image that is provided is 120 × 120, first find the coordinates to put the image in the bottom right corner, then find the coordinates to center the image in width and height, in such a way that you divide the screen in half.

Solution

Putting the image at the bottom right is very simple because you just have to take the size of the screen (here 320 × 240) and subtract the size of the image (120 × 120) to get the correct coordinates. So, putting title_img:draw(screen, 320 - 120, 240 - 120) puts the picture in the bottom right corner. To put the image in the middle, you can't simply divide the screen size by two, as this would put the top left corner of the image in the center of the screen. So we have to put title_img:draw(screen,(320 - 120) / 2, (240 - 120) / 2).

You will notice that you can put the operations in the parameters, because it helps to understand the logic of what you put there. You could put the result just as quickly, but as soon as you change the size of the game screen, the coordinates will no longer be valid. It would be ideal to replace the hard figures (320 and 240) of the screen with data received dynamically, and to do the same for the image, but this version will suffice for this chapter.

Chap. 2 : The First MapTable of Contents

tutorial/getting_started.txt · Last modified: 2018/12/22 14:14 (external edit)