For quest makers
For Solarus developers
For quest makers
For Solarus developers
This is an old revision of the document!
The game starts and loads the quest well enough, but you are only on a title screen, because your quest is almost empty. In this tutorial, we will see how to create a map and launch the game on this map. We will use the quest editor a lot because its main purpose is the creation of maps.
You will first need to get the basic resources you'll need to run the engine. You could create these resources completely on your own, but what you want here is to start a game quickly, so we'll provide you with resources to make a game similar to Zelda: A Link to the Past. Let's look at what these resources contain.
First, let's explain what a tile is , in French a tile : they are elements of basic decors, which possess certain properties (is it a wall? Is it animated?). A map is composed of a multitude of tiles. In summary, each time you see a decorative element, it is a tile. And these tiles can be placed on several “levels” in the map (low, intermediate and high layer, in the software in English these are the low, intermediate and high layer). We will return to the diapers in a forthcoming chapter.
The quest editor allows the cutting of a tileset, a tileset being a set of several tiles forming part of the same skin, for example the skin of a particular house or dungeon. Creating a tileset is an easy but long and somewhat tedious exercise. Again, we will address this in a forthcoming chapter. For now, you can download the tileset we need here. Unzip this file and put its contents under data\tilesets.
Tiles are not the only entities present on a map. There are also enemies, doors, chests, npcs, bushes, teleporters, etc. These entities can, for the most part, be represented on the map by sprites. A sprite is an animation constructed by a succession of still images. For example, when the hero walks, it is a succession of still images, the animation is not “real”. A bit like an animated gif, these are images that, put together end to end, give the illusion of animation. Note that not all sprites are necessarily animated, there are sprites composed of a single image (eg grass).
The Solarus engine needs two files to define a sprite: a .png file that contains all the images that make up the animation, and a .dat file that shows where each image in the .png file is located And what is the delay between each image. The same .png file can contain the images of several sprites, such as the shield that has its three possible evolutions in the same .png image. The inverse can also be true: for sprites with many different animations, the animations can be separated into several .png files.
Although the quest editor now allows the editing of sprites, this chapter is not devoted to sprites, and we advise you to download the minimum resources needed by the engine here. Unpack this file and match the subdirectories of the data folder . Replace all the requested files, it will not hurt your tilesets files (if they have disappeared, put them back).
The archive contains Game Over music, imposed by the engine in version 1.0 because the game-over menu is hard-coded. (With version 1.1, the game-over menu is fully customized, but this tutorial is still only covering 1.0.) Music can be in SPC format (not recommended), IT format (recommended) or OGG format. The first two formats are very specific to the games, see the Wikipedia links for more information. The last format is very simple to use but does not allow advanced or complex loops: it will just loop on all the music (intro included if there is one). Converters to OGG are easy to find, while SPC and IT require specific software.
The engine also requires the presence of a number of sound files. They are also in the archive.
In the quest editor, we will right click on the Tileset folder and make New tileset. We have downloaded tilesets from the world of light (light_world), but the engine and the editor do not yet know that they exist, because they must be indicated in the list of resources. The first dialog box asks you for the id of the tileset. As shown on the screen, set “light_world”. As you will have noticed, the id is the name of the files of tileset without extension. Therefore, the filenames and the id must match. The files being light_world.dat, light_world.entities.png and light_world.tiles.png , The common core of these three files is light_world. This is the ideal id.
The second dialog box prompts for a user-friendly name. This is an easier name to remember for an end user. This is the name that will appear in all your options for using this tileset in the editor, where the id is only the name of the file. All the resources in the tree to the left of the quest editor work on this principle: you will see just after that by doing a new map, it will ask for the id and the user-friendly name. Put what you want as a user-friendly name for this tileset, we will refer to it in future as the “outer world”.
If the editor says it can't open the .dat file, search for and manually edit the ground setting for
wall_bottom_right_water. Do the same for the entries
water_bottom_left, but make sure the new entries match the directions of the old directions. In newer versions of the editor, these specific tile types were changed
If you double-click on the newly created tileset, you will see how the whole tileset is arranged: it is composed of a multitude of elements, sometimes tiny (the smallest is 8 * 8 pixels), sometimes enormous. By right-clicking on one of the elements, you will see its ground properties with their description.
Now that the tileset is filled in, you can create a map. Right click on maps and select New Map. This time, you get to pick the id. The file created will have this name with a extension .dat. This can be anything you want, for example “test_map”. It is advisable to make file names without accents and without spaces to allow your game to work on any file system. The name of the map is requested in the second dialog, and it can be whatever you want, but we'll refer to this later as “test map”. In the latest editor, the new map will automatically select your first available tileset in your list of tilesets, but you can choose whichever tileset you'd like. For now though, we should only be using the “World Outside” tileset we set up earlier. Note that, like tilesets, you can “fill in” an already existing map,meaning that your existing map.dat file will be detected.
By default, maps are 320 × 240 pixels in size and are completely empty. Next we'll see how the interface works and what each element is used for.
With all this information, you must know what you have to do first, if it's not already set: define what tileset you want to use for this map. Since we do not have many choices for now, use the tileset “World Outside”. Do not forget also to indicate a world, here we can put “outside” for example. Once this is done, you can add the tiles you want on the map, simply click on the tile you want, and place it where you want by clicking once on the map on the map . Here are some tips:
With these tricks, you have enough to place a few small trees like these:
One last thing before you start the next part: put a destination (the first icon in the feature creation toolbar) on the map. The destinations are used to indicate to the engine where to send the hero during a teleportation but also at the start of the game. The destination system allows you to be more flexible than just entering coordinates, because it avoids having to modify coordinates When you move your scenery. On the other hand, the name of the destination must not change, otherwise someone who has a backup on the old name of this destination will not be able to start the game in this area correctly. Make sure you're aware of this when you rename maps or destinations!
Once the destination is set, double-click it or press the Enter key to display its properties. Enter an identifier in “Name”, for example “start”, then press OK. Now we have a nice map. Example of what you can do:
But if we launch the game now, we remain on our title screen, because we have not launched a game. So we will do a little (very little) programming.
Reminder of the previous tutorial: in main.lua , you had two functions defaulted by the engine. You can delete them now because they do not serve us (here is the content to delete, line 4 to 16):
-- 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
What we are going to do here instead is that when the Space key is pressed, we will start the game. Here is the corresponding code:
function sol.main:on_key_pressed(key) -- We want to start the game if space is pressed. if key == "space" then -- Load or create the game from file save1.dat. local game = sol.game.load("save1.dat") -- Not necessary in solarus 1.1: set the hero's location when the game starts. game:set_starting_location("test_map", "start") -- Start the game. game:start() end end
Here is the usual analysis of this function, although it is correctly commented. First line: this is the function called by the engine when a key on the keyboard is pressed, with the name of the key as parameter (for the Space key , the name is
space). So, we check that the name of the key is indeed space , if that is the case we create the part. The function
sol.game.load allows you to initialize or load a backup. Understand that if the file you specify does not exist, the engine creates a new one. The line just after is required only with Solarus 1.0, because it does not guess in which map and to which destination to launch the game. In Solarus 1.1, the default map is the first map in the map list, and in each map, A default destination can be specified.
game:set_starting_location Here, the function takes two parameters: the id of the map (thus “test_map”) and the destination in this map (the only one that was created, “start”). Once these formalities are completed, the game is requested to start the game via game:start.
If you try to start the game by pressing the space bar, you will have a disappointment. Indeed, the function
sol.main is constantly being called by the engine, and so the title screen does not disappear! To remedy this, we will slightly modify the code we wrote in the previous tutorial. We will put the variable
game of this file at the same level as the variable
title_img, and we will display the title screen only when this variable is empty. Here are the contents of the file after these changes:
-- 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/ local game -- Variable containing the game local title_img = sol.surface.create("title_img.png") -- Draw the title screen only if there is no game set. function sol.main:on_draw(screen) if game == nil then -- Draw the title_img on the center of the screen title_img:draw(screen, (320-120)/2, (240-120)/2) end end -- Function to load the game when Space is pressed. function sol.main:on_key_pressed(key) if key == "space" then -- Set the variable game (declared above). game = sol.game.load("save1.dat") -- Not necessary in solarus 1.1: set the hero's location when the game starts. game:set_starting_location("test_map", "start") -- Start the game. game:start() end end
Information about what we have just done: we have just added an if statement in the display function of the title screen; in this if statement, there is the keyword nil, which means an empty value. This is the equivalent of null in PHP, Java, C, and many other programming languages. The only change we have made in the function we added in this chapter is that there is no longer the local keyword in front of
game = sol.main.load(“save1.dat”) because we do not want to declare a new variable but use The one declared above in the file.
No exercise on this chapter! We'll do another on the next one, but for now just have fun with the tiles on a map: you have the basics to create mapsthat should at least be interesting to browse. You can still download the resulting quest file if you wish.