Back to homepage
LuaOverview
History
Overview of the Lua API
Updated Mon, 12 Oct 2020 02:12:20 +0200 by Wuzzy

Lua API: Overview

This page is a brief overview of how the Lua API in Hedgewars is structured. For a beginner's guide, see LuaGuide.

How Hedgewars handles Lua scripts

Hedgewars supports Lua scripts for two similar tasks: Define tutorial missions, campaign missions or provide special map behaviour for precreated maps. It is also used for multiplayer scripts to create new game styles.

Missions

Missions are located within text files inside share/hedgewars/Data/Missions/ . The game will list all files with the .lua extension inside this directory in the missions and campaigns selection screens. You’ll find some scripts within this directory that contain several comments on the script lines and what they do.

See Missions for details.

Special maps

In addition to tutorial missions predrawn maps (maps not created using the random map creator) may contain a single lua script file named map.lua . If it’s there, it will be used once the map is played. This way it’s possible to play maps alone or over the internet using custom goals. Mission maps can be found in singleplayer mode under the “training” button and in multiplayer mode, it is selectable as a map type.

See also PresetMaps for more information about such maps.

How Lua scripts are used

Several parts of script files are executed multiple times. In general, the whole script file is read while loading the map. Declarations as well as function calls outside functions are executed at once. Later on the game will call special predefined function names at special occassions such as the creation of new game objects (called “gears”).

Important things to know

It is possible to play missions in multiplayer. However this requires all participating players to have the exact same version of the map files, including the map.lua script file. If this isn’t the case the game will probably desync and “kick” at least the one player using a different version of the map files. To avoid problems when running prepackaged maps, you should never modify any maps provided with the Hedgewars default package. Instead, create a copy of the existing map and modify this one. Feel free to share your work on the forums.

Another thing to note is the current status of our scripting implementation. Similar to the whole game, this is still work in progress and we can’t guarantee that scripts working in this version will run in future revisions of the game as we might extend, change or rename parts of the scripting engine.

Scripting rules

To make sure your script is functional on multiple systems and for online play, some simple but important development rules need to be followed. See LuaRules.

Global variables/constants

Global variables are used by the game to interact with the scripts by passing and retrieving their values. While some of the variables are never read by the engine some allow you to modify the engine’s behaviour, e.g. the theme to be used for the current map.

A list of globals can be found in LuaGlobals.

Functions called by the game: Event handlers

After successfully loading the Lua script, the game will call event functions on different occasions. To be used, they have to use the exact same name as defined in the Lua API.

A list of event handlers can be found in LuaEvents.

Data types

This section defines some commonly used non-primitive parameter types which are used in multiple functions.

Color

Some functions take a color parameter.

Colors are stored in RGB or RGBA format and are specified as a three- or four-byte number, respecively. In 3-byte (RGB) colors, each byte represents a color component. The value 0 means no intensity and 255 is largest intensity of the component. The first byte is for the red component, the second byte for the green component and the third byte for the blue component. Four-byte (RGBA) colors use the first 3 bytes for the color components (like for the 3-byte colors) and the fourth byte is used for opacity, where 255 means maximum opacity and 0 means fully transparent (also called the “alpha channel”).

Specifying the color number becomes much easier if you write it in hexadecimal notation.

Examples for RGB (3-byte) colors: c = 0x000000 -- black (R, G, B are all 0) c = 0xFF0000 -- red c = 0x00FF00 -- green c = 0x0000FF -- blue c = 0xFFFFFF -- white c = 0x808080 -- gray (50%)

Hint: On http://www.colorpicker.com/ you find a color-picking tool for getting RGB colors easily.

Coordinates

Every position on the map can be addressed with Cartesian coordinates: X and Y. Those are integers.

  • X is the horizontal axis. It starts at 0 on the left side of the map and increases when you go right
  • Y is the vertical axis. It starts at 0 at the top of the map and increases when you go downwards

X and Y can be negative when you go above or left of the map boundaries.

Some global variables contain important coordinates, see LuaGlobals.