Solarus quests  1.5
Quest maker's reference
Video

sol.video allows you to manage the window and to change the video mode.

The area where the game takes place has a fixed size called the quest size. The quest size is in a range specified in quest.dat. This quest size defines how much content the player can see on the map. It is usually 320x240, but some systems may prefer other sizes, like 400x240 on Android. You should set a range of quest sizes in the quest properties files: this is a good idea for portability. However, it requires more work from the quest designer: in particular, you have to implement menus and a HUD that can adapt to any size in this range. Note however that the quest size never changes after the program is started.

At runtime, the video mode can be changed. The video mode determines whether a pixel scaling algorithm is applied to the image, and which one.

Any video mode can be played in windowed mode or in fullscreen. When the user plays in fullscreen, the quest image is automatically stretched and keeps the same pixel ratio, possibly by adding black borders.

The video mode can be saved and loaded with the global settings, as well as the language and the volume, independently of any savegame (see sol.main.load_settings()).

Video modes are identified by strings in the Lua API. The following modes are implemented:

  • "normal" (default): The quest screen is unchanged. In windowed mode, the image is stretched by a factor of 2.
  • "scale2x": The quest screen is scaled by a factor of 2 with the Scale2X algorithm.
  • "hq2x": The quest screen is scaled by a factor of 2 with the hq2x algorithm.
  • "hq3x": The quest screen is scaled by a factor of 3 with the hq3x algorithm.
  • "hq4x": The quest screen is scaled by a factor of 4 with the hq4x algorithm.

In windowed mode, the user and the scripts can resize the window. The image is then automatically stretched and keeps the same pixel ratio, possibly by adding black borders.

Functions of sol.video

sol.video.get_window_title()

Returns the text of the title bar of the window.

  • Return value (string): The window title.

sol.video.set_window_title(window_title)

Sets the text of the title bar of the window.

By default, the window title is set to the title of your quest followed by its version. Both these properties are indicated in the quest.dat file.

  • window_title (string): The window title to set.

sol.video.get_mode()

Returns the current video mode.

  • Return value (string): Name of the video mode (see the list above).

sol.video.set_mode(video_mode)

Sets the current video mode.

  • video_mode (string): Name of the video mode (see the list above).
Remarks
When the quest is run from the Solarus GUI, the user can also change the video mode from the menus of the GUI.

sol.video.switch_mode()

Sets the next video mode in the list of video modes supported.

You can use this function if you want to change the video mode without specifying which one to use. The fullscreen flag is never changed by this function.

sol.video.is_mode_supported(video_mode)

Returns whether a video mode is supported.

  • video_mode (string): Name of a video mode (see the list above).

sol.video.get_modes()

Returns an array of all video modes supported.

  • Return value (table): An array of names of all video modes supported.

sol.video.is_fullscreen()

Returns whether the current video mode is fullscreen.

  • Return value (boolean): true if the video mode is fullscreen.

sol.video.set_fullscreen([fullscreen])

Turns on or turns off fullscreen, keeping an equivalent video mode.

  • fullscreen (boolean, optional): true to set fullscreen (no value means true).
Remarks
When the quest is run from the Solarus GUI, the user can also switch fullscreen from the menus of the GUI.

sol.video.is_cursor_visible()

Returns whether the mouse cursor is currently visible.

  • Return value (boolean): true if the mouse cursor is currently visible.

sol.video.set_cursor_visible([cursor_visible])

Shows or hides the mouse cursor, keeping an equivalent video mode.

  • visible_cursor (boolean, optional): true to show mouse cursor (no value means true).

sol.video.get_quest_size()

Returns the size of the quest screen.

This quest size is fixed at runtime. It is always in the range of allowed quest sizes specified in quest.dat.

The quest size is independent from the video mode: video modes are just various methods to draw the quest on the window.

  • Return value 1 (number): Width of the quest screen in pixels.
  • Return value 2 (number): Height of the quest screen in pixels.

sol.video.get_window_size()

Returns the size of the window.

The quest image has a fixed size determined when the program starts. This quest image is then stretched on the window, and the size of the window size can be changed by the user or by sol.video.set_window_size(). Black borders are added if necessary to keep the correct pixel ratio.

When the window is in fullscreen, this function returns the size to be used when returning to windowed mode.

By default, the size of the window depends on the video mode. If no scaling algorithm is used (that is, in "normal" mode), the window size is initially twice the quest size to avoid a too small window. If a scaling algorithm is used, the scaling factor is naturally applied to the window size. For example, with hq2x, if your quest size is 320x240, the window will initially have a size of 640x480.

  • Return value 1 (number): Width of the window in pixels.
  • Return value 2 (number): Height of the window in pixels.

sol.video.set_window_size(width, height)

Sets the size of the window.

See sol.video.get_window_size() for a detailed description of the window size.

When the window is in fullscreen, this function still works: the changes will be visible when returning to windowed mode.

Note that when the video mode is changed, the window size is reset to its default value for the new video mode.

  • Return value 1 (number): Width of the window in pixels.
  • Return value 2 (number): Height of the window in pixels.

sol.video.reset_window_size()

Restores the size of the window to its default value.

The default size of the window depends on the video mode: see sol.video.get_window_size() for a detailed explanation.

When the window is in fullscreen, this function still works: the changes will be visible when returning to windowed mode.