### Create and Start a Custom Hero State

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/custom-states.md

This example demonstrates how to create a custom state object, configure its properties (allowing movement but fixing direction), and then start this state on the hero. Use this when built-in states do not offer sufficient control over hero behavior.

```lua
-- Create a custom state object.
local state = sol.state.create()

 -- Set up its properties.
state:set_can_control_movement(true)
state:set_can_control_direction(false)

-- Associate it to the hero.
hero:start_state(state)
```

--------------------------------

### Basic main.lua Script

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/files-specs/main-script.md

This example demonstrates the basic structure of a main.lua script, including functions for when the quest starts and finishes.

```lua
-- This function is called when Solarus starts.
function sol.main.on_started()
  print("Welcome to my quest.")
end

-- This function is called when Solarus stops or is reset.
function sol.main.on_finished()
  print("See you!")
end
```

--------------------------------

### Install MkDocs and Plugins

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/README.md

Install the necessary dependencies for MkDocs and its plugins using pip from the requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Solarus with Make

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/compilation.md

Install compiled Solarus libraries, executables, and headers using the 'install' rule. This command may require administrative privileges for default locations.

```bash
make install
```

--------------------------------

### Quest Properties File Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/files-specs/properties-file.md

Example of a `quest.dat` file demonstrating various properties, including quest size definitions.

```Lua
quest {
  solarus_version = "2.0",
  title = "My incredible quest",
  write_dir = "my_incredible_quest",
  short_description = "This is the best game ever",
  long_description = [[Travel the world and save the princess.
You will encounter great characters, epic battles and awesome puzzles.]],
  author = "John Doe",
  quest_version = "1.0",
  initial_release_date = "20250401",
  release_date = "",
  website = "http://www.example.com",
  normal_quest_size = "320x240",
  min_quest_size = "320x240",
  max_quest_size = "320x240",
  license = "GPL v3",
  languages = { "fr", "en", "es" },
  min_players = 1,
  max_players = 4,
  genres = { "Action", "Aventure" },
  age = "all",
  controls = 7,
  dynamic_timestep = false,
  subpixel_camera = false,
}
```

--------------------------------

### Install GLAD Headers

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/third_party/glad/CMakeLists.txt

Installs the GLAD and KHR platform headers to a specified destination within the project's header installation path.

```cmake
install(
  DIRECTORY
    "${CMAKE_CURRENT_SOURCE_DIR}/include/glad"
    "${CMAKE_CURRENT_SOURCE_DIR}/include/KHR"
  DESTINATION
    "${SOLARUS_HEADERS_INSTALL_DESTINATION}/solarus/third_party"
)
```

--------------------------------

### Example Shader Description File

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/files-specs/shader-data-file.md

This example demonstrates the syntax for a shader description file, specifying the vertex and fragment shader files to use, along with a scaling factor.

```lua
shader {
  vertex_file = "scale2x.vertex.glsl",
  fragment_file = "scale_2x.fragment.glsl",
  scaling_factor = 2,
}
```

--------------------------------

### Release Session Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/release-workflow.md

Example session demonstrating the steps involved in releasing a new version, including exporting a token, downloading artifacts, listing files, uploading packages, and creating a release.

```shell
$ export GITLAB_TOKEN=$(< /path/to/file-with-token)

$ tools/releaser.sh job download-artifact v2.0.0 mingw-x64-package release-2.0.0/
Archive:  /tmp/tmp.BmUDuIVNxi/artifact.zip
  inflating: release-2.0.0/solarus-cli-v2.0.0-windows-x64.zip

$ ls -1 release-2.0.0/
notes.md
solarus-cli-v2.0.0-windows-x64.zip
solarus-launcher-v2.0.0-macos-arm64.dmg
solarus-launcher-v2.0.0-windows-x64.zip
solarus-v2.0.0-windows-x64.zip

$ tools/releaser.sh package upload 2.0.0 release-2.0.0/*.zip release-2.0.0/*.dmg
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-cli-v2.0.0-windows-x64.zip
{"message":"201 Created"}
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-launcher-v2.0.0-windows-x64.zip
{"message":"201 Created"}
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-v2.0.0-windows-x64.zip
{"message":"201 Created"}
uploading file for generic package solarus/2.0.0: release-2.0.0/solarus-launcher-v2.0.0-macos-arm64.dmg
{"message":"201 Created"}

$ tools/releaser.sh release create 2.0.0 release-2.0.0/notes.md
release created: v2.0.0 (1c69f3d7ec133eaff28c22d756170eba69a520b0)
```

--------------------------------

### Install Qt6 on macOS

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/editor/readme.md

Use Homebrew to install the Qt6 framework on macOS. This command installs the necessary Qt6 base package.

```bash
brew install qt@6
```

--------------------------------

### Start Random Path Movement for NPC

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/movements/random-path-movement.md

This example demonstrates how to initiate a random path movement for an NPC when a map starts. It assumes an NPC named 'bob' exists on the map.

```lua
-- Example of code from a map script.
-- Assume that there is an NPC called "bob" on this map.
function sol.map:on_started()
  -- The map has just started: make bob walk.
  bob:start_movement(sol.movement.create("random_path"))
end
```

--------------------------------

### Release Notes Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/release-workflow.md

Example of a release notes file for version v2.0.0, including version, date, highlights, and changelog link.

```markdown
## Solarus 2.0.0 (2025-04-01)

The multiplayer and dark mode update is finally here!

* Watch the [release trailer](https://www.youtube.com/watch?v=X_hJDhWXxU8) for details.
* New [documentation website](https://docs.solarus-games.org/) available.
* Visit the [Solarus Games website](https://solarus-games.org/) for more information.

Changelog: <https://gitlab.com/solarus-games/solarus/-/blob/v2.0.0/changelog.md?ref_type=tags>
```

--------------------------------

### Build and Install Solarus

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/editor/readme.md

Build and install the Solarus engine before compiling the editor. Ensure you are in the solarus directory and have created a build subdirectory.

```bash
cd solarus
mkdir build
cd build
cmake ..
sudo make install
```

--------------------------------

### Install Qt6 on Windows (MSYS2)

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/editor/readme.md

Install the Qt6 framework using the pacman package manager within a UCTR64 MSYS2 environment on Windows. This command installs base, SVG, and tools modules.

```bash
pacman --noconfirm --needed -S \
  mingw-w64-ucrt-x86_64-qt6-base \
  mingw-w64-ucrt-x86_64-qt6-svg \
  mingw-w64-ucrt-x86_64-qt6-tools
```

--------------------------------

### Install solarus-run Executable

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/cli/CMakeLists.txt

Installs the solarus-run executable to a specified destination directory on the system.

```cmake
install(TARGETS solarus-run
  RUNTIME DESTINATION "${SOLARUS_EXECUTABLE_INSTALL_DESTINATION}"
)
```

--------------------------------

### Example Quest Database File

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/files-specs/database-file.md

This snippet shows a complete example of a valid quest database file, defining various game resources and their properties. It is typically managed by the Solarus Editor.

```lua
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" }

language{ id = "en",           description = "English" }

font{     id = "8_bit",        description = "8 bit font" }

file{     path = "sprites/enemies/soldier.dat", author = "John", license = "CC BY-SA 4.0" }
file{     path = "sprites/enemies/soldier.png", author = "John", license = "CC BY-SA 4.0" }
file{     path = "sprites/enemies/dragon.dat",  author = "Jack", license = "CC BY-SA 4.0" }
file{     path = "sprites/enemies/dragon.png",  author = "Jack", license = "CC BY-SA 4.0" }
```

--------------------------------

### Example GitLab CI Download URL for Quest Releases

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/tutorials/manual/building-quest-package.md

This is an example URL format for directly downloading a quest release package generated by GitLab CI. Replace placeholders with your specific username, quest name, and tag.

```txt
https://gitlab.com/<username>/<quest-name>/-/jobs/artifacts/<tag>/raw/<quest-name>-<tag>?job=quest-package
```

--------------------------------

### Install hqx header file

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/third_party/hqx/CMakeLists.txt

Installs the main hqx header file to the specified destination for external use.

```cmake
install(
  FILES
    "${CMAKE_CURRENT_SOURCE_DIR}/src/hqx.h"
  DESTINATION
    "${SOLARUS_HEADERS_INSTALL_DESTINATION}/solarus/third_party"
)
```

--------------------------------

### Install Manual Page on Unix

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/cli/CMakeLists.txt

Conditionally installs the solarus-run manual page (man6) to the appropriate system directory when on a Unix-like system (excluding macOS).

```cmake
if(UNIX AND NOT APPLE)
  install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/man/solarus-run.6"
    DESTINATION "${SOLARUS_MANUAL_INSTALL_DESTINATION}/man6"
  )
endif()
```

--------------------------------

### Install Windows Dependencies with MSYS2

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/launcher/CONTRIBUTING.md

Installs required development tools and libraries for building Solarus on Windows using MSYS2.

```sh
pacman --noconfirm --needed -S \
    git \
    mingw-w64-ucrt-x86_64-cmake \
    mingw-w64-ucrt-x86_64-gcc \
    mingw-w64-ucrt-x86_64-glm \
    mingw-w64-ucrt-x86_64-libmodplug \
    mingw-w64-ucrt-x86_64-libvorbis \
    mingw-w64-ucrt-x86_64-luajit \
    mingw-w64-ucrt-x86_64-ninja \
    mingw-w64-ucrt-x86_64-openal \
    mingw-w64-ucrt-x86_64-physfs \
    mingw-w64-ucrt-x86_64-pkgconf \
    mingw-w64-ucrt-x86_64-SDL2 \
    mingw-w64-ucrt-x86_64-SDL2_image \
    mingw-w64-ucrt-x86_64-SDL2_ttf \
    mingw-w64-ucrt-x86_64-qt6-base \
    mingw-w64-ucrt-x86_64-qt6-tools
```

--------------------------------

### Tileset Data File Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/files-specs/tileset-data-file.md

A sample tileset file demonstrating background color and multiple tile pattern definitions.

```lua
background_color { 104, 184, 104 }
```

```lua
tile_pattern {
  id = "path_dirt",
  ground = "traversable",
  default_layer = 0,
  x = 32,
  y = 0,
  width = 16,
  height = 16,
}
```

```lua
tile_pattern {
  id = "ocean",
  ground = "deep_water",
  default_layer = 0,
  x = { 0, 8, 16 },
  y = { 32, 32, 32 },
  width = 8,
  height = 8,
}
```

```lua
tile_pattern {
  id = "parallax_tree",
  ground = "traversable",
  default_layer = 0,
  x = 320,
  y = 448,
  width = 16,
  height = 24,
  scrolling = "parallax",
}
```

--------------------------------

### Specific GitLab CI Download URL Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/tutorials/manual/building-quest-package.md

A concrete example of a GitLab CI download URL for a quest release, demonstrating the format with actual values for username, quest name, and tag.

```txt
https://gitlab.com/jean-pierre/legend-of-zora/-/jobs/artifacts/v1.3.2/raw/legend-of-zora-v1.3.2?job=quest-package
```

--------------------------------

### Install GUI Dependency Packages for Solarus

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/compilation.MSYS2.md

Installs additional packages required for building the GUI components of Solarus, such as the Solarus Launcher and Editor. This includes Qt6 base, SVG, and tools.

```bash
pacman --noconfirm --needed -S \
    mingw-w64-ucrt-x86_64-qt6-base \
    mingw-w64-ucrt-x86_64-qt6-svg \
    mingw-w64-ucrt-x86_64-qt6-tools
```

--------------------------------

### game:start()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/game.md

Runs the game. This is typically called from the savegame menu or to restart the current game.

```APIDOC
## game:start()

### Description
Runs this game. This function is typically called from your savegame menu, when the player chooses its savegame file. If another game was running, it is stopped automatically because only one game can be running at a time. You can also call this function to restart the current game itself, even if it was not saved recently (saved data will not be reset). This may be useful to restart the game after the [game-over sequence](#gameon_game_over_started).

### Method
`game:start()`

### Parameters
None
```

--------------------------------

### hero:start_running

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/hero.md

Makes the hero start running.

```APIDOC
## `hero:start_running()`

### Description
Makes the hero run.
```

--------------------------------

### Install Debian Dependencies

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/launcher/CONTRIBUTING.md

Installs necessary build tools and libraries for Solarus on Debian-based Linux distributions.

```sh
apt update
apt install --no-install-recommends \
    build-essential \
    cmake \
    pkgconf \
    libsdl2-dev \
    libsdl2-image-dev \
    libsdl2-ttf-dev \
    libglm-dev \
    libluajit-5.1-dev \
    libphysfs-dev \
    libopenal-dev \
    libvorbis-dev \
    libmodplug-dev \
    qt6-base-dev \
    qt6-base-dev-tools \
    qt6-tools-dev
```

--------------------------------

### menu:on_started()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/menus.md

Called when your menu is started. This event is triggered when `sol.menu.start()` is called.

```APIDOC
## menu:on_started()

### Description
Called when your menu is started.

This event is triggered when you call [`sol.menu.start()`](#solmenustartcontext-menu-on_top).

### Method
Callback Event

### Endpoint
N/A

### Parameters
None
```

--------------------------------

### Start Dialog with Callback and Conditional Logic

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/game.md

Starts a dialog that asks a question and provides a callback function to handle the player's answer. This allows for interactive dialogs where the game state changes based on player input.

```lua
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
        game:remove_money(100)
        game:start_dialog("thanks")
      else
        sol.audio.play_sound("wrong")
        game:start_dialog("not_enough_money")
      end
    else
      game:start_dialog("not_happy")
    end
  end)
end
```

--------------------------------

### Glad Generator URL Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/third_party/glad/README.md

Example URL for generating Glad source files. This URL specifies the OpenGL profile, language, specification, loader, API versions, and extensions.

```plaintext
https://glad.dav1d.de/#profile=core&language=c&specification=gl&loader=on&api=gl%3D3.0&api=gles2%3D2.0&extensions=GL_ARB_framebuffer_object&extensions=GL_ARB_vertex_array_object
```

--------------------------------

### music:play

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/audio/music.md

Starts playing the music associated with the music object.

```APIDOC
## music:play()

### Description
Starts playing the music.

### Method
`play`
```

--------------------------------

### Argument Documentation: Enum Values

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/CONTRIBUTING.md

Example of documenting an argument that accepts specific string values, including default and descriptions.

```markdown
`<argument_name>` (string<argument_optionality>)
: <argument_description>

    - `"<value>"` (default): <value_description>
    - `"<value>"`: <value_description>
```

--------------------------------

### Movement Methods

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/movements/index.md

Common methods available for all movement types, including getting type, starting, stopping, and managing position and suspension.

```APIDOC
## movement:get_type()

### Description
Returns the type of movement.

### Return Value
- string - The type of this movement. Can be one of: "straight_movement", "random_movement", "target_movement", "path_movement", "random_path_movement", "path_finding_movement", "circle_movement", "jump_movement", "pixel_movement".

## movement:start(object_to_move, [callback])

### Description
Starts this movement on an object. The movement will be applied until it finishes or is replaced. It does not matter if the movement gets out of scope.

### Parameters
#### Path Parameters
- **object_to_move** ([map entity](../map-entities/index.md), [drawable object](../drawable-objects/index.md) or table) - Required - The object to move. It may be a map entity, a drawable object or a table with two fields `x` and `y`.
- **callback** (function, optional) - A function to call when the movement finishes.

## movement:stop()

### Description
Stops this movement and detaches it from the object that was moved.

## movement:get_xy()

### Description
Returns the coordinates of the object controlled by this movement.

### Return Value
- number - X coordinate.
- number - Y coordinate.

## movement:set_xy(x, y)

### Description
Sets the coordinates of the object controlled by this movement.

### Parameters
#### Path Parameters
- **x** (number) - Required - X coordinate to set.
- **y** (number) - Required - Y coordinate to set.

## movement:is_suspended()

### Description
Returns whether this movement is currently suspended.

### Return Value
- boolean - `true` if the movement is suspended.

## movement:get_ignore_suspend()

### Description
Returns whether the movement should continue even when the [game](../game.md) is suspended. This setting only has an effect for movements attached to a [map entity](../map-entities/index.md) during a game. The default value is `false`.

### Return Value
- boolean - `true` to continue the movement even when the game is suspended.

## movement:set_ignore_suspend([ignore])

### Description
Sets whether the movement should continue even when the [game](../game.md) is suspended.

### Parameters
#### Path Parameters
- **ignore** (boolean, optional, default: `true`) - `true` to continue the movement even when the game is suspended.
```

--------------------------------

### Map Initialization Script Example

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map.md

This Lua script demonstrates basic map initialization. It plays music and shows a dialog when the player enters the map.

```lua
-- First, we put the parameter into a variable called "map".
-- (In Lua, the notation "..." refers to the parameter(s) of the script.)
local map = ...
local game = map:get_game()

-- Event called when the player enters the map, at initialization time.
function map:on_started()

  -- Play an evil music.
  sol.audio.play_music("evil")
end

-- Event called when the player takes control, after the opening transition.
function map:on_opening_transition_finished()

  -- Show an evil welcome dialog.
  game:start_dialog("welcome_to_darkness")
end

```

--------------------------------

### Serve Solarus Documentation Locally

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/AGENTS.md

Serve the Solarus project documentation locally using MkDocs. This command requires installing dependencies first and is useful for previewing changes.

```bash
# Install dependencies
pip install -r requirements.txt

# Serve locally
mkdocs serve
```

--------------------------------

### Start a Timer with an Anonymous Function

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/timers.md

An equivalent to the named function example, using an anonymous function for the callback. This is useful for short, one-off timer actions.

```lua
-- Equivalent code using an anonymous function.
sol.timer.start(1000, function()
  sol.audio.play_sound("secret")
end)
```

--------------------------------

### sol.main.load_settings([file_name])

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/general-features.md

Loads and applies user preferences (language, video, audio) from a settings file. Requires a valid quest write directory to be set.

```APIDOC
## sol.main.load_settings([file_name])

### Description
Loads and applies built-in settings from a file previously saved with `sol.main.save_settings()`. This includes user preferences like language, video mode, and audio volume. Individual settings can also be modified via the Lua API.

Note: A valid quest write directory must be set, otherwise a Lua error will occur.

### Parameters
#### Parameters
- **file_name** (string, optional, default: "settings.dat") - The settings file to read, relative to the quest write directory.

### Return Value
(boolean) - `true` if settings were successfully loaded and applied.
```

--------------------------------

### Install macOS Dependencies with Homebrew

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/compilation.md

Install necessary development packages for Solarus on macOS using the Homebrew package manager. Ensure XCode is installed for the OS X SDK.

```bash
brew install cmake ninja sdl2 sdl2_image sdl2_ttf luajit lua@5.1 libvorbis libmodplug physfs glm openal-soft
```

--------------------------------

### sol.main:on_started()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/general-features.md

This event is called at the beginning of the program's execution or after a reset. It's typically used to initialize the game, such as displaying a title screen or starting a new game.

```APIDOC
## sol.main:on_started()

### Description
Called at the beginning of the program's execution or after a reset. This is where you can initiate the game's initial state, like a title screen or language selection.

### Method
Event Callback

### Parameters
None
```

--------------------------------

### Install Debugging Dependency Packages for Solarus

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/compilation.MSYS2.md

Installs the GDB debugger package, which is required for debugging Solarus builds in MSYS2.

```bash
pacman --noconfirm --needed -S \
    mingw-w64-ucrt-x86_64-gdb
```

--------------------------------

### sol.main.do_file(script_name)

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/general-features.md

Loads and runs a Lua file into the current context.

```APIDOC
## sol.main.do_file(script_name)

### Description
Loads and runs a Lua file into the current context. This function is a replacement to the usual Lua function `dofile()`. The difference is that it looks for a file in the quest tree and also in the [quest write directory](#solmainset_quest_write_dirquest_write_dir). The quest write directory is tried first. The file must exist.

### Parameters
#### Path Parameters
- **script_name** (string) - Required - Name of the Lua file to load (with or without extension), relative to the data directory or the write directory of your quest.

### Notes
- `require()` is the recommended way to load code from another file as it does not parse the file again every time it is called.
```

--------------------------------

### sol.menu.start

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/menus.md

Starts a menu in a given context, making it active and allowing it to receive events. The menu's lifetime is determined by its context.

```APIDOC
## sol.menu.start(context, menu, [on_top])

### Description
Starts a menu in a context. The Solarus engine will then call the appropriate events on your menu until it is stopped.

### Parameters
#### Context
- **context** (map or game or table) - Required - The context your menu will belong to. Determines the lifetime of your menu.
  - If a [map](./map.md) menu, drawn above the map surface, stopped when the player goes to another map.
  - If a [game](./game.md) menu, global to all maps, persists across map changes as long as the game is running.
  - If a [main](./general-features.md) menu, global to the whole program, can exist outside a game.
  - If the context is another menu, its lifetime is limited to this other menu (nested menus).
#### Menu
- **menu** (table) - Required - The menu to activate. Must contain callback functions (events).
#### On Top
- **on_top** (boolean) - Optional, default: `true` - Whether this menu should be drawn on top of other existing menus of the same context or behind them.
  - If `true`, `on_draw()` is called last.
  - If `false`, `on_draw()` is called first.
```

--------------------------------

### Install Qt6 Dependencies on Debian/Ubuntu

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/editor/readme.md

Install required Qt6 development packages on Debian-based Linux distributions. These packages are necessary for building applications with Qt6.

```bash
sudo apt update
sudo apt install --no-install-recommends \
  qt6-base-dev \
  qt6-base-dev-tools \
  qt6-tools-dev \
  qt6-tools-dev-tools \
  qt6-l10n-tools \
  libqt6opengl6-dev \
  libqt6svg6-dev
```

--------------------------------

### game:on_started

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/game.md

Callback event triggered when the game begins running, including restarts.

```APIDOC
## game:on_started()

### Description
Called when this game starts running (including when you restart the same game).

### Method
Not applicable (Lua event callback)
```

--------------------------------

### Fragment Shader Example with Built-in Variables

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/shaders.md

An example of a GLSL fragment shader utilizing Solarus's built-in uniforms such as `sol_texture`, `sol_input_size`, `sol_output_size`, and `opacity`.

```glsl
uniform sampler2D sol_texture;
uniform vec2 sol_input_size;
uniform vec2 sol_output_size;
uniform int sol_time;
uniform float opacity;

void main() {
    vec2 tex_coord = gl_TexCoord[0].st;
    vec4 tex_color = texture2D(sol_texture, tex_coord);
    
    // Example: Make pixels brighter based on time
    float brightness_factor = 1.0 + sin(float(sol_time) / 60.0) * 0.5;
    tex_color.rgb *= brightness_factor;
    
    gl_FragColor = tex_color * opacity;
}
```

--------------------------------

### Build MkDocs Website

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/README.md

Build the static website for deployment. This command first removes the existing public directory and then generates the new site.

```bash
rm -rf ./public
mkdocs build --site-dir public
```

--------------------------------

### Install Solarus Dependencies on Ubuntu

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/compilation.md

Installs necessary development libraries for compiling Solarus on Debian-based systems like Ubuntu. Ensure you have CMake and a C++17 compliant compiler.

```bash
apt update
apt install --no-install-recommends \
    build-essential \
    cmake \
    pkgconf \
    libsdl2-dev \
    libsdl2-image-dev \
    libsdl2-ttf-dev \
    libglm-dev \
    libluajit-5.1-dev \
    libphysfs-dev \
    libopenal-dev \
    libvorbis-dev \
    libmodplug-dev
```

--------------------------------

### Vertex Shader Example with Built-in Variables

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/shaders.md

An example of a GLSL vertex shader demonstrating the use of Solarus's built-in variables like `sol_vertex`, `sol_tex_coord`, and `sol_mvp_matrix`.

```glsl
attribute vec2 sol_vertex;
attribute vec2 sol_tex_coord;
attribute vec4 sol_color;

uniform mat4 sol_mvp_matrix;

void main() {
    gl_Position = sol_mvp_matrix * vec4(sol_vertex, 0.0, 1.0);
    gl_TexCoord[0] = vec4(sol_tex_coord, 0.0, 0.0);
    gl_FrontColor = sol_color;
}
```

--------------------------------

### camera:start_manual()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/camera.md

Switches the camera to the 'manual' state, allowing for direct control. The camera also automatically enters this state if a movement is initiated on it.

```APIDOC
## camera:start_manual()

### Description
Switches the camera to manual state. The camera automatically switches to manual state if you start a movement on it.

### Note
The camera automatically switches to manual state if you start a [movement](../movements/index.md#movementstartobject_to_move-callback) on it.
```

--------------------------------

### Manually Build Quest Package with Zip

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/tutorials/manual/building-quest-package.md

Compress the 'data' folder and its contents into a Zip archive and rename it to .solarus. Ensure the 'zip' utility is installed.

```bash
zip -r your-quest.solarus path/to/your/quest/data
```

--------------------------------

### Example Tile Pattern Definition

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/files-specs/tileset-data-file.md

Defines a tile pattern with its ID, ground type, layer, dimensions, and repeat mode. This example shows how to configure a vertically repeatable tile pattern.

```lua
tile_pattern {
  id = "wall.1",
  ground = "wall",
  default_layer = 0,
  x = 64,
  y = 48,
  width = 24,
  height = 16,
  repeat_mode = "vertical",
}
```

--------------------------------

### Run MkDocs Locally

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/README.md

Serve the MkDocs website locally to preview changes. Navigate to the website directory before running the command.

```bash
mkdocs serve
```

--------------------------------

### Get camera bounding box using map:get_camera():get_bounding_box()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/tutorials/migration/from-v1-4-to-v1-5.md

The `map:get_camera_position()` function is deprecated. In Solarus 1.5, the camera is an entity, so you should use `map:get_camera():get_bounding_box()` to get its bounding box.

```lua
map:get_camera():get_bounding_box()
```

--------------------------------

### Build Solarus Documentation

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/AGENTS.md

Build the static Solarus project documentation into the './public' directory using MkDocs. This command is used to generate the final documentation files for deployment.

```bash
mkdocs build --site-dir public
```

--------------------------------

### Setting a Path Movement

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/movements/path-movement.md

Demonstrates how to create and configure a path movement for an NPC. This snippet shows setting a custom path and speed, then starting the movement.

```lua
function scared_cat:on_interaction()
  -- The hero is talking to me: run away!
  sol.audio.play_sound("meow")
  local movement = sol.movement.create("path")
  -- This path is arbitrary, it's just an example (North and then West).
  movement:set_path{2, 2, 2, 2, 2, 2, 4, 4, 4, 4}
  movement:set_speed(80)
  self:start_movement(movement)
end
```

--------------------------------

### Install Core Dependency Packages for Solarus

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/compilation.MSYS2.md

Installs essential packages required for building Solarus using MSYS2. This includes development tools like git, CMake, GCC, and libraries for audio, graphics, and scripting.

```bash
pacman --noconfirm --needed -S \
    git \
    mingw-w64-ucrt-x86_64-cmake \
    mingw-w64-ucrt-x86_64-gcc \
    mingw-w64-ucrt-x86_64-glm \
    mingw-w64-ucrt-x86_64-libmodplug \
    mingw-w64-ucrt-x86_64-libvorbis \
    mingw-w64-ucrt-x86_64-luajit \
    mingw-w64-ucrt-x86_64-ninja \
    mingw-w64-ucrt-x86_64-openal \
    mingw-w64-ucrt-x86_64-physfs \
    mingw-w64-ucrt-x86_64-pkgconf \
    mingw-w64-ucrt-x86_64-SDL2 \
    mingw-w64-ucrt-x86_64-SDL2_image \
    mingw-w64-ucrt-x86_64-SDL2_ttf
```

--------------------------------

### Running a Quest with solarus-run from .solarus file

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/tutorials/getting-started/creating-a-quest.md

Use this command to launch a Solarus quest distributed as a .solarus file. This is the recommended method for distributing quests to players.

```bash
solarus-run path/to/your/quest.solarus
```

--------------------------------

### camera:get_zoom

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/camera.md

Gets the zoom factors of the camera.

```APIDOC
## camera:get_zoom()

### Description
Gets the zoom factors of the camera.

### Response
#### Success Response
- **Return value 1** (number) - Scaling of the camera along x axis.
- **Return value 2** (number) - Scaling of the camera along y axis.
```

--------------------------------

### state:on_started

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/custom-states.md

Callback function called when this state begins. It receives information about the previous state.

```APIDOC
## state:on_started(previous_state_name, previous_state)

### Description
Called when this state starts.

### Parameters
#### Path Parameters
- **previous_state_name** (string or nil) - Optional - Name of the state that was active before.
- **previous_state** (state or nil) - Optional - Custom state object that was active before, if it was a custom one, nil otherwise.

### Method
`state:on_started`
```

--------------------------------

### entity:on_movement_started(movement)

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/index.md

Called when a movement is started on this entity.

```APIDOC
## entity:on_movement_started(movement)

### Description
Called when a movement is started on this entity.

### Parameters
#### Path Parameters
- **movement** ([movement](../movements/index.md)) - Required - The movement that was just started on this entity.
```

--------------------------------

### Create Release with Notes

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/release-workflow.md

Creates a new release in the GitLab repository, linking assets from the package registry. Requires a version number and a file containing release notes.

```bash
releaser.sh release create 2.0.0 release-2.0.0/notes.md
```

--------------------------------

### camera:get_rotation

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/camera.md

Gets the camera rotation around its center.

```APIDOC
## camera:get_rotation()

### Description
Gets the camera rotation around its center.

### Response
#### Success Response
- **Return value** (number) - Rotation angle, positive is counter-clockwise.
```

--------------------------------

### block:get_direction()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/block.md

Gets the restricted movement direction of the block, if any.

```APIDOC
## block:get_direction()

### Description
Returns the direction the block can be moved to, if it is restricted to a specific direction.

### Method
`block:get_direction()`

### Return Value
- (number or `nil`) - A direction between `0` (East) and `3` (South), or nil if this block is not restricted to a specific direction.
```

--------------------------------

### Start Dialog with Runtime Info and Callback

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/game.md

Initiates a dialog where dynamic information is passed via the 'info' parameter, allowing for personalized messages. A callback handles the dialog's completion, enabling two-way communication between the map script and the dialog system.

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

function another_npc:on_interaction()
  local how_much = math.random(100)
  game:start_dialog("give_me_x_rupees_please", how_much, function(answer)
    if answer then
      if game:get_money() >= how_much then
        game:remove_money(how_much)
        -- ... The rest is unchanged.
```

--------------------------------

### sol.main.get_elapsed_time()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/general-features.md

Returns the simulated time elapsed since Solarus was started.

```APIDOC
## sol.main.get_elapsed_time()

### Description
Returns the simulated time elapsed since Solarus was started. This corresponds to real time, unless the system is too slow to play at normal speed.

### Return Value
- **number**: The number of simulated milliseconds elapsed since the beginning of the program.

### Notes
- This time is not reset when you call `sol.main.reset()`.
```

--------------------------------

### Project Initialization

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/launcher/CMakeLists.txt

Initializes the CMake build system and defines project metadata like name, languages, version, and homepage.

```cmake
cmake_minimum_required(VERSION 3.19.0)

project("solarus-launcher"
  LANGUAGES CXX
  VERSION 2.1.0
  HOMEPAGE_URL "https://www.solarus-games.org"
  DESCRIPTION "Game Launcher for Solarus Quests"
)
```

--------------------------------

### sol.video.set_window_size(width, height)

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/video.md

Sets the dimensions of the game window.

```APIDOC
## sol.video.set_window_size(width, height)

### Description
Sets the size of the window.

### Parameters
#### Path Parameters
- **width** (number) - Required - Width of the window in pixels.
- **height** (number) - Required - Height of the window in pixels.

### Notes
See [`sol.video.get_window_size()`](#solvideoget_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.
```

--------------------------------

### Create and Play Music

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/audio/music.md

Creates a music object from a given ID and starts playing it. Ensure the music file exists in the 'musics' directory.

```lua
local my_music = sol.music.create("my_music_id")
my_music:play()
```

--------------------------------

### sprite:get_animation()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/drawable-objects/sprite.md

Gets the name of the currently active animation for the sprite.

```APIDOC
## sprite:get_animation()

### Description
Returns the name of the current animation of this sprite.

### Return Value
- (string): Name of the current animation.
```

--------------------------------

### Build Solarus with Ninja

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/AGENTS.md

Build the Solarus engine, including the core library and the command-line executable, using the Ninja build system. This command should be run from the build directory.

```bash
ninja
```

--------------------------------

### state:is_started

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/custom-states.md

Checks if the custom state has been started and is currently active on an entity.

```APIDOC
## state:is_started

### Description
Returns whether this state is started, that is, if it was activated on an entity (see [`hero:start_state()`](./map-entities/hero.md#herostart_statestate)) and is not finished yet.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Return Value
* `boolean`: `true` if the state is started.

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### sound:play

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/audio/sound.md

Starts playing the sound effect associated with the sound object.

```APIDOC
## sound:play()

### Description
Starts playing the sound effect.
```

--------------------------------

### sol.main.save_settings([file_name])

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/general-features.md

Saves the current built-in settings (language, video, audio) to a file for later restoration. Requires a valid quest write directory.

```APIDOC
## sol.main.save_settings([file_name])

### Description
Saves the current built-in settings into a file, which can be reloaded later with `sol.main.load_settings()` to restore them. This includes user preferences such as language, video mode, and audio volume. Individual settings can also be modified via the Lua API.

Note: A valid quest write directory must be set, otherwise a Lua error will occur.

### Parameters
#### Parameters
- **file_name** (string, optional, default: "settings.dat") - The settings file to read, relative to the quest write directory.

### Return Value
(boolean) - `true` if settings were successfully saved.
```

--------------------------------

### timer:is_suspended_with_map()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/timers.md

Checks if this timer gets automatically suspended when the map is suspended.

```APIDOC
## timer:is_suspended_with_map()

### Description

Returns whether this timer gets automatically suspended when the [map](./map.md) is suspended.

### Method

`timer:is_suspended_with_map()`

### Parameters

None

### Response

#### Success Response

- **return value** (boolean) - `true` if this timer gets suspended when the map is suspended.
```

--------------------------------

### Example: Enemy Movement and Sprite Direction

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/movements/index.md

Demonstrates how to create a random movement for an enemy and update its sprite's direction based on the movement's trajectory changes.

```lua
-- Example of code from an enemy script.

-- This function is called when the enemy should start or restart its movement.
function enemy:on_restarted()

  -- Create a movement that makes random straight trajectories.
  local movement = sol.movement.create("random")

  -- This function is called when the trajectory has changed.
  function movement:on_movement_changed()
    -- The angle of the movement has changed: update the sprite accordingly.
    local direction = movement:get_direction4()
    enemy:get_sprite():set_direction(direction)
  end

  movement:start(enemy)
end
```

--------------------------------

### destructible:get_modified_ground()

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/map-entities/destructible.md

Gets the type of ground that this destructible object modifies on the map.

```APIDOC
## destructible:get_modified_ground()

### Description
Returns the ground defined by this destructible object on the map. The presence of a destructible object can modify the ground of the map. The ground is usually "wall", but it may sometimes be "traversable", or for example "grass" to make the destructible object traversable too but with an additional grass sprite below the hero.

### Return Value
- `string`: The ground defined by this destructible object. See [`map:get_ground()`](../map.md#mapget_groundx-y-layer) for the list of possible grounds.
```

--------------------------------

### Get Music Volume

Source: https://gitlab.com/solarus-games/solarus/-/blob/dev/doc/docs/lua-api/audio/music.md

Retrieves the current volume level of the music instance.

```lua
local current_volume = my_music:get_volume()
```