Solarus 1.1 released!

The new version of Solarus is available now!

The main change of Solarus 1.1 is that there are no more hardcoded menus in the engine: the dialog box and the game-over menu are now fully scripted in your quest with the Lua API. There are a lot of other new features and improvements, as well as bug fixes, so it is recommended to upgrade.

Our games ZSDX and ZSXD were also upgraded to give you up-to-date examples of games. ZSDX is now available in simplified Chinese and traditional Chinese (beta). Thanks Sundae and Rypervenche! Note that a Spanish version of ZSXD is also in progress (thanks Xexio!).

Solarus 1.1 also improves portability and performance. This allows us to release the Android and OpenPandora versions of our games. They will be available in the next few days!

Here is the full changelog. 80 github issues were resolved for Solarus 1.1 and 20 more for ZSDX and ZSXD 1.7 so this is a huge list!

Changes in Solarus 1.1

New features:

  • Add a very short sample quest with free graphics and musics (#232, #318).
  • Allow scripted dialog boxes (#184).
  • Allow a scripted game-over menu (#261).
  • Replace the old built-in dialog box by a very minimal one.
  • Remove the old built-in game-over menu.
  • Remove the old built-in dark rooms displaying (#205).
  • New entity: separators to visually separate some regions in a map (#177).
  • New type of ground: ice (#182).
  • New type of ground: low walls (#117).
  • Blocks and thrown items can now fall into holes, lava and water (#191).
  • Kill enemies that fall into holes, lava and water (#190).
  • Allow quest makers and users to set the size of the playing area.
  • Allow maps to have a default destination entity (#231).
  • A game can now start without specifying an initial map and destination.
  • Stairs inside a single floor can now go from any layer to a next one (#178).
  • The channel volume of  .it musics can now be changed dynamically (#250).
  • The tempo of  .it musics can now be changed dynamically (#250).
  • Allow Lua to manipulate files directly (#267).
  • New syntax of sprites, easier to read and parse (#168).
  • New syntax of project_db.dat, easier to read and parse (#169).
  • languages.dat no longer exists. Languages are in project_db.dat now (#265).
  • The quest archive can now also be named (#293).

Lua API changes that introduce incompatibilities (see the migration guide):

  • map:is_dialog_enabled() is replaced by game:is_dialog_enabled().
  • map:start_dialog() is replaced by game:start_dialog().
  • Remove map:draw_dialog_box(), no longer needed.
  • Remove map:set_dialog_style(): replace it in your own dialog box system.
  • Remove map:set_dialog_position(): replace it in your own dialog box system.
  • Remove map:set_dialog_variable(): use the info param of game:start_dialog().
  • Make map:get_entities() returns an iterator instead of an array (#249).
  • Replace map:set_pause_enabled() by game:set_pause_allowed().
  • Make the enemy:create_enemy() more like map:create_enemy() (#215).
  • Remove sol.language.get_default_language(), useless and misleading (#265).
  • Remove sol.main.is_debug_enabled().
  • Remove map:get_light() and map:set_light() (#205).
  • In game:get/set_ability(), ability “get_back_from_death” no longer exists.
  • Empty chests no longer show a dialog if there is no on:empty() event (#274).

Lua API changes that do not introduce incompatibilities:

  • game:get/set_starting_location(): map and destination can now be nil.
  • hero:teleport(): make destination optional (maps now have a default one).
  • map:create_teletransporter(): make destination optional.
  • Add a function
  • Make map:get_camera_position() also return the size of the visible area.
  • Add a method entity:is_in_same_region(entity).
  • Add a method entity:get_center_position().
  • Add methods entity:get_direction4_to(), entity:get_direction8_to() (#150).
  • Add a method game:get_hero().
  • Add methods hero:get/set_walking_speed() (#206).
  • Add hero:get_state() and hero:on_state_changed() (#207).
  • Add events separator:on_activating() and separator:on_activated() (#272).
  • Add methods enemy:is/set_traversable() (#147).
  • Add a method enemy:immobilize() (#160).
  • Add on_position_changed() to all entities, not only enemies (#298).
  • Add on_obstacle_reached() to all entities, not only enemies (#298).
  • Add on_movement_changed() to all entities, not only enemies (#298).
  • Add on_movement_finished() to all entities, not only enemies/NPCs (#298).
  • target_movement:set_target(entity) now accepts an x,y offset (#154).
  • Add a method game:is_pause_allowed().
  • Add a method map:get_ground() (#141).
  • Add a method map:get_music() (#306).
  • Add an optional parameter on_top to
  • Add sprite:on_animation_changed() and sprite:on_direction_changed() (#153).
  • Add a function sol.input.is_key_pressed().
  • Add a function sol.input.is_joypad_button_pressed().
  • Add a function sol.input.get_joypad_axis_state().
  • Add a function sol.input.get_joypad_hat_direction().
  • Add functions (#175).
  • Add a function (#146).
  • Add a function
  • Add a function
  • Add functions for .it files (#250).
  • Add functions for .it files (#250).
  • Return nil if the string is not found in sol.language.get_string().
  • sol.language.get_dialog() is now implemented.
  • Add a function game:stop_dialog(status) to close the scripted dialog box.
  • Add an event game:on_dialog_started(dialog, info).
  • Add an event game:on_dialog_finished(dialog).
  • Add functions game:start_game_over() and game:stop_game_over (#261).
  • Add events game:on_game_over_started(), game:on_game_over_finished (#261).
  • Add sol.file functions: open(), exists(), remove(), mkdir() (#267).

Bug fixes:

  • Fix map menus not receiving on_command_pressed/released() events.
  • Fix camera callbacks never called when already on the target (#308).
  • Fix a crash when adding a new menu during a menu:on_finished() event.
  • Fix a crash when calling hero:start_victory() without sword.
  • Fix an error when loading sounds (#236). Sounds were working anyway.
  • Fix a possible memory error when playing sounds.
  • Fix blocks that continue to follow the hero after picking a treasure (#284).
  • Fix on_obtained() that was not called for non-brandished treasures (#295).
  • Jumpers can no longer be activated the opposite way when in water.
  • Jumpers are now activated after a slight delay (#253).
  • Sensors no longer automatically reset the hero’s movement (#292).
  • Correctly detect the ground below the hero or any point.
  • Don’t die if there is a syntax error in dialogs.dat.
  • Show a better error message if trying to play a Solarus 0.9 quest (#260).
  • Remove built-in debug keys. This can be done from Lua now.
  • Remove the preprocessor constant SOLARUS_DEBUG_KEYS.
  • Call on_draw() before drawing menus.
  • Fix .it musics looping when they should not.
  • Log all errors in error.txt (#287).

Changes in Solarus Quest Editor 1.1

  • Add a GUI to automatically upgrade quest files to the latest format (#247).
  • Remove the initial prompt dialog to open a quest (#264).
  • Replace non-free images by new icons (#245).
  • Add tooltips to the add entity toolbar.
  • Simplify the add entity toolbar by showing only one icon per entity type.
  • Survive when images cannot be found (#256).
  • Create more content when creating a new quest (#258, #279).
  • Improve error messages.
  • Fix a crash when creating a destructible without tileset selected (#283).
  • Fix the sprite field disabled in the NPC properties dialog (#303).


These improvements involve changes that introduce some incompatibilities in both the format of data files (sprites, project_db.dat, languages.dat) and the Lua API (the dialog box and the game-over menu are scripted now!). Make a backup, and then see the migration guide on the wiki to know how to upgrade.

Changes in Zelda Mystery of Solarus DX 1.7

New features:

  • Add simplified Chinese and traditional Chinese translations (beta).
  • Replace .spc musics by .it ones (much faster) (#17).
  • Add an animated Solarus logo from Maxs (#57).

Bug fixes:

  • Fix savegames created with Solarus 0.9 but that were never run.
  • Fix a slight alignment issue with the hurt animation of the hero.
  • Fix a small breach in dungeon 9 4F in the timed chest room (#4).
  • Fix easy infinite rupees in the waterfall cave (#13).
  • Fix low health beeping playing at final screen (#56).
  • Add a teletransporter from south lake to the cave under the waterfall (#10).
  • Dungeon 7 boss: the player could get stuck in the boss room (#6).
  • Dungeon 7 boss: change the misleading hurt sound of the tail (#7).
  • Dungeon 7: help the player be aligned correctly to obtain the boss key (#8).
  • Dungeon 3 2F: fix two switches that disappeared when activating them.
  • Dungeon 2 boss: fix tile disappearing issue (#14).
  • Dungeon 9 2F: fix a minor graphical issue.

Changes in Zelda Mystery of Solarus XD 1.7

New features:

  • Replace .spc musics by .it musics (faster) and remove unused ones.
  • Add an animated Solarus logo from Maxs.

Bug fixes:

  • Fix savegames created with Solarus 0.9 but that were never run.
  • Fix a slight alignment issue with the hurt animation of the hero.
  • Dungeon 1 3F: fix “attempt to compare number with nil” in counter 36 (#3).
  • Dungeon 2 1F: fix an enemy not counting in WTF room.

Customizable game-over menu!

The last built-in menu is not built-in anymore in Solarus 1.1!

Now, when the life of the player reaches zero, an event game:on_game_over_started() is called. The game is suspended and you can show whatever you want. You can make a dialog that lets the player chose between “Continue” or “Save and quit”. Or you can make a more elaborate game-over menu like in our games, where a fairy saves the player if he has one in a bottle.

And if you don’t define the event, game:on_game_over_started(), then the engine just restarts the game.

The Solarus 1.1 roadmap is close to its end. 50 issues were solved and 1 is still open. Now I am testing both games (ZSDX and ZSXD) to check everything because there was some refactoring done to upgrade to Solarus 1.1, and some C++ code was replaced by Lua code (most importantly, the dialog box and the game-over menu).

Solarus Wiki

Christopho began to make video tutorials about how to make a game with Solarus. However, these tutorials are, for the moment, only in French. To help the community to get the basis of Solarus, a Wiki where everyone can contribute has been set up. We use Dokuwiki, a free and open-source file-based wiki engine.

Currently there is almost nothing on the Wiki, but we are working on it, and we hope you too !

Ice, low walls and other improvements about grounds

Two new types of grounds (or terrains) are now implemented in Solarus 1.1, as well as improvements in the detection of the ground.

  • Ice ground: tiles that make the hero slide, with some sort of inertia.
  • Low walls: obstacles that can only be traversed by projectiles like thrown items, the boomerang, arrows and flying enemies.

I also improved the code that detects the kind of ground of a point. Before, it only worked with the hero, and did not always correctly take into account dynamic entities that may change the ground, like dynamic tiles. (And the code was too complex!)

Now, the ground is correctly detected, including when it gets changed by dynamic tiles (even with moving dynamic tiles). Last but not least, this new detection algorithm works for any coordinates (not only the hero). Therefore, enemies and thrown items can now fall into holes and drown into water or lava!

These improvements and the two new kinds of tiles were demanded for a long time. I hope you will enjoy them!

Solarus Forums

Since the Solarus 1.0 release, several people suggested that we create a forum.

Here it is!

We hope that the forum will be very useful for people who use the Solarus engine. You will be able to talk about developing your own games, get help, share knowledge, scripts and game resources. It will also be a place to present your projects to the community. We are open to any suggestion!

New entity type: separators

I have finished another new feature for Solarus 1.1: you can now separate a map in different regions. When you are in a region, you cannot see adjacent regions. And when you touch the limit of the region, the camera scrolls to the region on the other side.

You can use this feature to visually separate rooms that are in the same map. In ZSDX, when you are in a room of a dungeon, you can also see parts of the adjacent rooms. If you want to only show the current map (like in Zelda ALTTP), it is possible now. With the quest editor, you create a separator, which is a vertical or horizontal bar that you place on your map.

Separators implictly define regions on your map. Thus, you can also use this feature to make a minimap that shows the visited rooms of the dungeon.

Customizable dialogs!

This is a very important new feature of Solarus 1.1. The dialog box system is now fully scriptable using the Lua API! It means that you can now make any feature you want to your dialogs, like changing the font, the color, the text alignment, adding images or sprites, making questions with multiple possible choices…

The syntax of the dialog files does not change, expect that any custom property is allowed in a dialog. Actually, only the dialog id and the text are mandatory. Everything else (the icon, whether there is a question, whether the dialog can be skipped…) is now seen as additional, custom properties of your quest.

If you don’t make a scripted dialog box in Lua, the engine shows a minimal dialog box without decoration. But it is recommended to make your own one!

Here is an example of a small map script with a non-playing character that shows a simple dialog when the hero talks to him:

local map = ...

function some_npc:on_interaction()
  -- Remember that you specify a dialog id, not directly the text to show.
  -- The text is defined in the dialogs.dat file of the current language.

Here is a more complex example, with an NPC that asks a question. This example assumes that your dialog box system can ask questions to the player, and returns the answer as a boolean value.

local map = ...
local game = map:get_game()

function another_npc:on_interaction()
  game:start_dialog("give_me_100_rupees_please", function(answer)
    if answer then
      if game:get_money() >= 100 then

The new dialog API is very flexible. When you show a dialog, you can pass a parameter to your custom dialog box system (this feature is not used in this example), and symmetrically, your custom dialog box system can return a result (like the answer selected by the player in this example).

Fore more details, see the documentation of game:start_dialog() in the Solarus Lua API.

New format of project_db.dat

Since Solarus 0.9.0, the format of most data files is being changed to be more readable, easier to parse and more homogeneous.

In Solarus 1.0, good progress has been made in this direction, especially with the new format of maps. Three formats of data files remain to be changed: the strings.dat language file, the sprite sheet files and the quest resource list file. I plan to change them all in Solarus 1.1.

And the work is now finished for the quest resource list file (project_db.dat). This file defines the list of resources (maps, tilesets, sprites, musics, sounds, enemies…) and allows the quest editor to show them and edit them. The new format looks like this:

map{     id = "outside",      description = "Outside World" }
map{     id = "hero_house",   description = "House of the hero" }
map{     id = "shop",         description = "Shop" }
map{     id = "dungeon_1_1f", description = "Dungeon 1 - First floor" }
map{     id = "dungeon_1_2f", description = "Dungeon 1 - Second floor" }

tileset{ id = "overworld",    description = "Overworld" }
tileset{ id = "house",        description = "House" }
tileset{ id = "dungeon",      description = "Dungeon" }

sound{   id = "door_closed",  description = "Door closing" }
sound{   id = "door_open",    description = "Door opening" }
sound{   id = "enemy_hurt",   description = "Enemy hurt" }
sound{   id = "jump",         description = "Jumping" }
sound{   id = "treasure",     description = "Treasure" }

item{    id = "sword",        description = "Sword" }
item{    id = "bow",          description = "Bow" }
item{    id = "arrow",        description = "Arrows (x1 / x5 / x10)" }

enemy{   id = "soldier",      description = "Soldier" }
enemy{   id = "dragon",       description = "Dragon" }

Note that the quest editor fully supports the modification of this file since Solarus 1.0.2. More information about this quest resource list file is available on the documentation pages.

More importantly, I added to the quest editor a system to upgrade automatically your data files when their format changes. Whenever a new version Solarus is released, if the format of data files has changed, the quest editor will upgrade them for you.

Maps have now a default destination entity

Here is a small improvement that will ease the life of quest creators in Solarus 1.1, the future version of the engine.

You will be able to set a destination entity as the default one of the map. It means that whenever a teletransporter (or some Lua code) sends the hero to a map without specifying a destination entity, the hero will arrive on the default destination. If no destination was explicitly set as the default one, then the first one of the map is the default one.

Many maps are very small in a game (like a house in a village) and contain only one destination. In these cases, you no longer have to give a name to the destination and to link a teletransporter to this destination name. In the map of the village, you can make a teletransporter that goes to that map and leave its destination parameter unspecified.

When you create a new savegame, the starting map and the starting destination on that map also become optional in Solarus 1.1. If you don’t call game:set_starting_location(), the game starts on the first map declared in the resource list and with the default destination entity of that map.

This change is not the most important new feature of Solarus 1.1, but it will reduce the risk of errors and improve flexibility!

Controlling the quest size to obtain maximum portability

Many new features are planned for Solarus 1.1. I will talk about the important ones whenever I implement them.

The one I have been working on for the last few days is an important improvement for quest makers, for players and also for people who compile the engine on various systems.

In Solarus 1.0, the size of the visible space that appears on the screen (we call this the “quest size”) is a constant defined at compile time: by default, 320×240.  This “quest size” is how much content of the map you can see when playing. It should not be confused with the video mode of the screen: the video mode just defines how this 320×240 quest space is rendered on the screen: directly in a window, stretched or scaled to 640×480, in fullscreen or not, etc.

The main problem of this approach is that everything is decided at compilation time. As the creator of a quest, you have no control over the screen size and your game is just supposed to adapt itself with any size. Which is just not possible. You don’t want a game area of 1000×1000 because the player could see way too much content of your maps! Still, you may want to allow different sizes (like 400×240) so that the game fills the entire space of wide screens, using square pixels and without vertical black bars.

To solve the problem, in Solarus 1.1, you will be able to set the range of sizes that your quest allows.

If you are okay to allow people with a wide screen to see more content that others, you can set a range of sizes in your quest properties file (quest.dat):

 solarus_version = "1.1",
 write_dir = "my_quest",
 title_bar = "My incredible quest",
 normal_quest_size = "320x240", -- Works on most configurations.
 min_quest_size = "320x200",    -- Might make fullscreen compatible with more systems.
 max_quest_size = "400x240",    -- Suited for wide screens, including mobile devices like Pandora.

Of course, your maps and your menus will have to adapt correctly to any value inside this range. So it requires more work, but your game will be more portable. There is a new Lua function to help you with that.

At runtime, the user can choose his quest size with a command-line option. A default quest size can also be set at compilation time. If the size requested is not in the range allowed by your quest, then normal_quest_size is used instead.

Then, Solarus does the complicated work for you :). It automatically detects the appropriate resolutions to render this size at best for each video mode (fullscreen, with scaling, etc.). So you don’t have to worry about that part. Besides, the Lua API of video modes does not change at all.

If you prefer that all people play your quest with the exact same visible area, set all three sizes to the same value, or just define normal_quest_size (by default, min and max take the normal value):

 solarus_version = "1.1",
 write_dir = "my_quest",
 title_bar = "My incredible quest",
 normal_quest_size = "320x240", -- Only one allowed quest size.