Documenting Lua

This article covers working with Lua for engine developers. For adding the library to your Recoil game, refer to the Working with Lua guide.

The Lua library is a collection of type definitions that can be included in Recoil games to provide intellisense and type checking. It is found in the recoil-lua-library repo.

The library is generated from doc comments within the project.

Generating the library

Automatic library generation

The library is generated by the Generate Lua library workflow . This workflow runs automatically every time a PR is merged.

Manually generating the library

To test library generation locally, install mise and run from doc/site:

# Generate the library into rts/Lua/library/generated.
mise run lua_library

# Generate the library and check it for errors.
mise run lua_check

The commands are defined in doc/site/mise.toml.

Doc comments

Doc comments within CPP files

Special comments blocks are parsed by lua-doc-extractor and converted into definition files.

Lua doc comments start with /***.

/***
 * Get features inside a rectangle area on the map
 *
 * @function Spring.GetFeaturesInScreenRectangle
 *
 * @param left number
 * @param top number
 * @param right number
 * @param bottom number
 * @return nil|number[] featureIDs
 */
int LuaUnsyncedRead::GetFeaturesInScreenRectangle(lua_State* L)
{
 // C++ code
}

These comments are mostly copied directly into the Lua library, but some code generation is required. For these custom tags must be used.

Markdown is supported in all text.

A description goes above the tags it describes, or on the tag’s own line. Text on the lines below a tag is not part of that tag’s description.

Authored library files

Hand-authored library files exist in /rts/Lua/Library/. These are appropriate to use when a Lua type is used in multiple CPP files.

All files under /rts/Lua/Library/ are directly copied into the library when the workflow runs.

Annotations

Full list of annotations.

For annotation-aware completion and diagnostics while you write, install the EmmyLua plugin for your editor.

Common annotations

• @function
• @table
• @param
• @return
• @field

Types

List of types

Common types

• integer
• nil
• any
• boolean
• string
• number (for floating point numbers)
• integer
• table<,>

table<string, true>

Unions

Union types can be specified with |.

string|boolean|number

Suffix with ? as a shorthand for a union with nil, e.g. string? is equivalent to string|nil.

Arrays

An array type is expressed as type[].

• number[] — Array of numbers.
• string?[] — Array of string or null.
• number|string[] — A single number, or an array of strings.
• (number|string)[] — An array with a mix of number and string.

Examples

Function

• Must have a @function TableName.FunctionName tag.
• Can have any amount of description. This goes before the tags.
• Specify parameters with @param parameterName type Description...
• Specify return type with @return type name Description...
• For multiple returns use one per line.
• @param and @return descriptions are a single line, on the tag’s line. Longer explanations, lists of accepted values and examples go in the function description.

/***
 * Add two integers together.
 *
 * This function will add two numbers together and return the result.
 *
 * ```lua
 * local totalHeight = Math.Add(legLength, upperBodyHeight)
 * ```
 *
 * @function Math.Add
 *
 * @param a integer The first number.
 * @param b integer The second number.
 * @return integer result The sum of `a` and `b`.
 */

Aliases

If a function is exported to two Lua functions, you can give it two @function tags:

/***
 * @function Spring.GetLocalPlayerID
 * @function Spring.GetMyPlayerID
 * @return integer playerID
 */
int LuaUnsyncedRead::GetLocalPlayerID(lua_State* L)

Class

Structured data is expressed as a class. This represents a table with expected key/value pairs.

• Must have a @class ClassName tag. This name becomes a type that can be used in annotations. The class description goes above it.
• Fields are specified by @field fieldName type Description.... A longer field description can go on the lines above the field.

/***
 * Describes an RGB color value.
 *
 * @class Color
 *
 * @field red number The red value.
 * @field green number The green value.
 * @field blue number The blue value.
 */

/***
 * @function ColorUtility.LerpColor
 * @param from Color
 * @param to Color
 * @param value number The mix (in range `[0,1]`) of colors to combine. `1` will return `to` and `0` will return `from`.
 * @return Color color
 */

Table

A global table can be defined like so:

/***
 * @table Spring
 */

This will define a table. This table can then be referenced in a function name e.g. @function Spring.MyFunction.

A table of constants can also be expressed using @field:

/***
 * @table CoolNumbers
 * @field Pi number
 * @field SixtyNine integer
 * @field FourTwenty integer
 */