Lua API Reference

Globals

property COBSCALE integer

[source]

table Encoding

Lua Encoding API

[source]

function DecodeBase64(text)

Parameters

text : string - Text to decode

Returns

decoded : string - Decoded text

Decodes a base64 string

[source]

Decodes a base64 encoded string. If it encounters invalid data, it stops and returns whatever it parsed so far.

function DecodeBase64Url(text)

Parameters

text : string - Text to decode

Returns

decoded : string - Decoded text

Decodes a base64url string

[source]

Decodes a base64url encoded string. If it encounters invalid data, it stops and returns whatever it parsed so far.

function EncodeBase64(text, stripPadding)

Parameters

text : string - Text to encode
stripPadding : boolean? - Remove padding (`=` characters) at the end when 'true'. Defaults to `true`.

Returns

encoded : string - Encoded text

Encodes a base64 string

[source]

function EncodeBase64Url(text)

Parameters

text : string - Text to encode

Returns

encoded : string - Encoded text

Encodes a base64url string

[source]

function IsValidBase64(text)

Parameters

text : string - Text to validate

Returns

valid : boolean - Whether the text is valid base64

Validates a base64 string

[source]

function IsValidBase64Url(text)

Parameters

text : string - Text to validate

Returns

valid : boolean - Whether the text is valid base64url

Validates a base64url string

[source]

table Engine

Engine specific information.

[source]

property buildFlags string

Gets additional engine buildflags, e.g. “Debug” or “Sync-Debug”

property commitsNumber string

Number of commits after the latest named release, non-zero indicates a “dev” build

property featureSupport FeatureSupport

Table containing various engine features as keys; use for cross-version compat

property gameSpeed number

Number of simulation gameframes per second

property textColorCodes TextColorCode

Table containing keys that represent the color code operations during font rendering

property version string

“Major.Minor.PatchSet” for releases, “Major.Minor.PatchSet-CommitNum-gHash branch” otherwise

property versionFull string

“Major.Minor.PatchSet” for releases, “Major.Minor.PatchSet-CommitNum-gHash branch” otherwise. Will also include (buildFlags), if there’re any.

property versionMajor string

Major part of the named release version

property versionMinor string

Minor part of the named release version

property versionPatchSet string

Build number of the named release version

property wordSize number

Indicates the build type always 64 these days

table Game

Game specific information

[source]

property armorTypes table<(string|integer),(integer|string)>

(bidirectional)

    example: {
      [1]  = amphibious,   [2] = anniddm,     [3] = antibomber,
      [4]  = antifighter,  [5] = antiraider,  [6] = atl,
      [7]  = blackhydra,   [8] = bombers,     [9] = commanders,
      [10] = crawlingbombs, ...

      ["amphibious"]   = 1, ["anniddm"]    = 2, ["antibomber"] = 3
      ["antifighter"]  = 4, ["antiraider"] = 5, ["atl"]        = 6
      ["blackhydra"]   = 7, ["bombers"]    = 8, ["commanders"] = 9
      ["crawlingbombs"]= 10, ...
    }

property captureEnergyCostFactor number

property constructionDecay boolean

property constructionDecaySpeed number

property constructionDecayTime number

property envDamageTypes table

Containing {def}IDs of environmental-damage sources

property extractorRadius number

property fireAtCrashing number

property fireAtKilled number

property gameDesc string

property gameMutator string

property gameName string

property gameShortName string

property gameSpeed number

Number of simulation gameframes per second

property gameVersion string

property ghostedBuildings boolean

property gravity number

property mapChecksum string

property mapDamage boolean

property mapDescription string

= string Game.mapHumanName

property mapHardness number

property mapName string

property mapSizeX number

in worldspace/opengl coords. Divide by Game.squareSize to get engine’s “mapDims” coordinates

property mapSizeZ number

in worldspace/opengl coords. Divide by Game.squareSize to get engine’s “mapDims” coordinates

property mapX number

property mapY number

property maxPlayers number

property maxTeams number

property maxUnits number

property metalMapSquareSize number

The resolution of metalmap (for use in API such as Spring.GetMetalAmount etc.)

property modChecksum string

property multiReclaim number

property reclaimAllowAllies boolean

property reclaimAllowEnemies boolean

property reclaimFeatureEnergyCostFactor number

property reclaimMethod number

property reclaimUnitEfficiency number

property reclaimUnitEnergyCostFactor number

property reclaimUnitMethod number

property repairEnergyCostFactor number

property requireSonarUnderWater boolean

property resurrectEnergyCostFactor number

property springCategories table<string,integer> 

    example: {
      ["vtol"]         = 0,  ["special"]      = 1,  ["noweapon"]     = 2,
      ["notair"]       = 3,  ["notsub"]       = 4,  ["all"]          = 5,
      ["weapon"]       = 6,  ["notship"]      = 7,  ["notland"]      = 8,
      ["mobile"]       = 9,  ["kbot"]         = 10, ["antigator"]    = 11,
      ["tank"]         = 12, ["plant"]        = 13, ["ship"]         = 14,
      ["antiemg"]      = 15, ["antilaser"]    = 16, ["antiflame"]    = 17,
      ["underwater"]   = 18, ["hover"]        = 19, ["phib"]         = 20,
      ["constr"]       = 21, ["strategic"]    = 22, ["commander"]    = 23,
      ["paral"]        = 24, ["jam"]          = 25, ["mine"]         = 26,
      ["kamikaze"]     = 27, ["minelayer"]    = 28, ["notstructure"] = 29,
      ["air"]          = 30
    }

property squareSize number

Divide Game.mapSizeX or Game.mapSizeZ by this to get engine’s “mapDims” coordinates. The resolution of height, yard and type maps.

property startPosType number

property textColorCodes TextColorCode

Table containing keys that represent the color code operations during font rendering

property tidal number

property transportAir number

property transportGround number

property transportHover number

property transportShip number

property waterDamage number

property windMax number

property windMin number

table gl

Callouts for OpenGL API

Only setters and getters for OpenGL usage in Recoil, see GL for constants.

[source]

(See: )

function ActiveFBO(fbo, func, ...)

Parameters

fbo : FBO
func : fun(…)
... : any - args

[source]

function ActiveFBO(fbo, target, func, ...)

Parameters

fbo : FBO
target : GL?
func : fun(…)
... : any - args

[source]

function ActiveShader(shaderID, func, ...)

Parameters

shaderID : integer
func : function
... : any - Arguments

Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments.

Can be used in NON-drawing events (to update uniforms etc.)!

[source]

function ActiveTexture(texNum, func, ...)

Parameters

texNum : integer
func : function
... : any - Arguments to the function.

[source]

function AddAtlasTexture(texName, subAtlasTexName)

Parameters

texName : string
subAtlasTexName : string

[source]

function AddFallbackFont(filePath)

Parameters

filePath : string - VFS path to the file, for example "fonts/myfont.ttf". Uses VFS.RAW_FIRST access mode.

Returns

success : boolean

Adds a fallback font for the font rendering engine.

Fonts added first will have higher priority. When a glyph isn’t found when rendering a font, the fallback fonts will be searched first, otherwise os fonts will be used.

The application should listen for the unsynced ‘FontsChanged’ callin so modules can clear any already reserved display lists or other relevant caches.

Note the callin won’t be executed at the time of calling this method, but later, on the Update cycle (before other Update and Draw callins).

[source]

function AlphaTest(enable)

Parameters

enable : boolean

[source]

function AlphaTest(func, ref)

Parameters

func : GL
ref : number

Specify the alpha test function.

[source]

function AlphaToCoverage(enable)

Parameters

enable : boolean

[source]

function BeginEnd(primMode, fun, ...)

Parameters

primMode : GL
fun : unknown
... : any - Arguments passed to function.

[source]

function BeginText(userDefinedBlending)

Parameters

userDefinedBlending : boolean? - When `true` doesn't set the gl.BlendFunc automatically. Defaults to `false`.

Begin a block of text commands.

[source]

Text can be drawn without Start/End, but when doing several operations it’s more optimal if done inside a block.

Also allows disabling automatic setting of the blend mode. Otherwise the font will always print with BlendFunc(GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA).

(See: )

function Billboard()

[source]

function BindImageTexture(unit, texID, level, layer, access, format)

Parameters

unit : integer
texID : string? - (nil breaks any existing binding to the image unit)
level : integer? - (Default: 0)
layer : integer? - (nil binds the entire texture(array/cube), an integer binds a specific layer, ignored by gl if the texture does not support layered bindings)
access : GL? - (Default: GL.READ_WRITE) Accepts `GL.READ_ONLY`, `GL.WRITE_ONLY` or `GL.READ_WRITE`.
format : integer - (Example: GL.RGBA16F)

[source]

For format parameters refer to https://registry.khronos.org/OpenGL-Refpages/gl4/html/glBindImageTexture.xhtml and https://beyond-all-reason.github.io/RecoilEngine/lua-api/types/GL#rgba32f

Example uses local my_texture_id = gl.CreateTexture(…)

– bind layer 1 of my_texture_id if it supports layered bindings to image unit 0 gl.BindImageTexture(0, my_texture_id, 0, 1, GL.READ_WRITE, GL.RGBA16F)

– bind all layers of my_texture_id if it supports layered bindings to image unit 0 gl.BindImageTexture(0, my_texture_id, 0, nil, GL.READ_WRITE, GL.RGBA16F)

– unbind any texture attached to image unit 0 gl.BindImageTexture(0, nil, nil, nil, nil, GL.RGBA16F)

function BlendEquation(mode)

Parameters

mode : GL

[source]

function BlendEquationSeparate(modeRGB, modeAlpha)

Parameters

modeRGB : GL
modeAlpha : GL

[source]

function BlendFunc(src, dst)

Parameters

src : GL
dst : GL

[source]

function BlendFuncSeparate(srcRGB, dstRGB, srcAlpha, dstAlpha)

Parameters

srcRGB : GL
dstRGB : GL
srcAlpha : GL
dstAlpha : GL

[source]

function Blending(enable)

Parameters

enable : boolean

[source]

function Blending(mode)

Parameters

mode : ("add"|“alpha_add”|“alpha”|“reset”|“color”|“modulate”…)

[source]

function Blending(src, dst)

Parameters

src : GL
dst : GL

[source]

function BlitFBO(x0Src, y0Src, x1Src, y1Src, x0Dst, y0Dst, x1Dst, y1Dst, mask, filter)

Parameters

x0Src : number
y0Src : number
x1Src : number
y1Src : number
x0Dst : number
y0Dst : number
x1Dst : number
y1Dst : number
mask : number? - (Default: GL_COLOR_BUFFER_BIT)
filter : number? - (Default: GL_NEAREST)

needs GLAD_GL_EXT_framebuffer_blit

[source]

function BlitFBO(fboSrc, x0Src, y0Src, x1Src, y1Src, fboDst, x0Dst, y0Dst, x1Dst, y1Dst, mask, filter)

Parameters

fboSrc : FBO
x0Src : number
y0Src : number
x1Src : number
y1Src : number
fboDst : FBO
x0Dst : number
y0Dst : number
x1Dst : number
y1Dst : number
mask : number? - (Default: GL_COLOR_BUFFER_BIT)
filter : number? - (Default: GL_NEAREST)

needs GLAD_GL_EXT_framebuffer_blit

[source]

function CallList(listIndex)

Parameters

listIndex : integer

[source]

function ChangeTextureParams(texName, params)

Parameters

texName : string
params : Texture

[source]

function Clear(bits, val)

Parameters

bits : GL - `GL.DEPTH_BUFFER_BIT` or `GL.STENCIL_BUFFER_BIT`.
val : number

[source]

function Clear(bits, r, g, b, a)

Parameters

bits : GL - `GL.COLOR_BUFFER_BIT` or `GL.ACCUM_BUFFER_BIT`.
r : number
g : number
b : number
a : number

[source]

function ClearAttachmentFBO(target, attachment, clearValue0, clearValue1, clearValue2, clearValue3)

Parameters

target : number? - (Default: `GL.FRAMEBUFFER`)
attachment : (GL|Attachment) - (e.g. `"color0"` or `GL.COLOR_ATTACHMENT0`)
clearValue0 : number? - (Default: `0`)
clearValue1 : number? - (Default: `0`)
clearValue2 : number? - (Default: `0`)
clearValue3 : number? - (Default: `0`)

Returns

success : boolean

needs Platform.glVersionNum >= 30 Clears the “attachment” of the currently bound FBO type “target” with “clearValues”

[source]

function ClearFallbackFonts()

Returns

: nil

Clears all fallback fonts.

See the note at ‘AddFallbackFont’ about the ‘FontsChanged’ callin, it also applies when calling this method.

[source]

function ClipDistance(clipId, enable)

Parameters

clipId : integer
enable : boolean

[source]

function ClipPlane(plane, enable)

Parameters

plane : integer
enable : boolean

[source]

function ClipPlane(plane, equation0, equation1, equation2, equation3)

Parameters

plane : integer
equation0 : number
equation1 : number
equation2 : number
equation3 : number

[source]

function Color(r, g, b, a)

Parameters

r : number - Red.
g : number - Green.
b : number - Blue.
a : number? - (Default: `1.0`) Alpha.

[source]

function Color(color)

Parameters

color : rgba - Color with alpha.

[source]

function Color(color)

Parameters

color : rgb - Color.

[source]

function ColorMask(rgba)

Parameters

rgba : boolean

Enable or disable writing of frame buffer color components.

[source]

function ColorMask(red, green, blue, alpha)

Parameters

red : boolean
green : boolean
blue : boolean
alpha : boolean

Enable or disable writing of frame buffer color components.

[source]

function ConfigMiniMap(px, py, sx, sy)

Parameters

px : integer
py : integer
sx : integer
sy : integer

[source]

function CopyToTexture(texName, xoff, yoff, x, y, w, h, target, level)

Parameters

texName : string
xoff : integer
yoff : integer
x : integer
y : integer
w : integer
h : integer
target : GL?
level : GL?

[source]

function CreateFBO(fboDesc)

Parameters

fboDesc : FBODescription

Returns

fbo : FBO

[source]

function CreateList(func, ...)

Parameters

func : fun()
... : any - Arguments to the function.

[source]

function CreateQuery()

Returns

query : any

[source]

function CreateRBO(xsize, ysize, data)

Parameters

xsize : integer
ysize : integer
data : CreateRBOData

Returns

: RBO

[source]

function CreateShader(shaderParams)

Parameters

shaderParams : ShaderParams

Returns

shaderID : integer

Create a shader.

[source]

function CreateTexture(xsize, ysize, texture)

Parameters

xsize : integer
ysize : integer
texture : Texture

Returns

texName : string?

[source]

function CreateTexture(xsize, ysize, zsize, texture)

Parameters

xsize : integer
ysize : integer
zsize : integer
texture : Texture

Returns

texName : string?

[source]

function CreateTextureAtlas(xsize, ysize, allocType)

Parameters

xsize : integer
ysize : integer
allocType : integer?

Returns

texName : string

[source]

function Culling(enable)

Parameters

enable : boolean

[source]

function Culling(mode)

Parameters

mode : GL

Enable culling and set culling mode.

[source]

function DeleteFBO(fbo)

Parameters

fbo : FBO

This doesn’t delete the attached objects!

[source]

function DeleteList(listIndex)

Parameters

listIndex : integer

[source]

function DeleteQuery(query)

Parameters

query : any

[source]

function DeleteRBO(rbo)

Parameters

rbo : RBO

[source]

function DeleteShader(shaderID)

Parameters

shaderID : integer

Deletes a shader identified by shaderID

[source]

function DeleteTexture(texName)

Parameters

texName : string

Returns

: boolean

[source]

function DeleteTextureAtlas(texName)

Parameters

texName : string

Returns

: boolean

[source]

function DeleteTextureFBO(texName)

Parameters

texName : string

Returns

: boolean

[source]

function DepthClamp(enable)

Parameters

enable : boolean

[source]

function DepthMask(enable)

Parameters

enable : boolean

Enable or disable writing into the depth buffer.

[source]

function DepthTest(enable)

Parameters

enable : boolean

Enable or disable depth test.

[source]

function DepthTest(depthFunction)

Parameters

depthFunction : GL

Enable depth test and specify the depth comparison function.

[source]

function DispatchCompute(numGroupX, numGroupY, numGroupZ, barriers)

Parameters

numGroupX : integer
numGroupY : integer
numGroupZ : integer
barriers : integer? - (Default: `4`)

[source]

function DrawFuncAtUnit(unitID, useMidPos, fun, ...)

Parameters

unitID : integer
useMidPos : boolean? - (Default: `true`)
fun : unknown
... : any - Arguments passed to function.

[source]

function DrawGroundCircle(posX, posY, posZ, radius, resolution)

Parameters

posX : number
posY : number
posZ : number
radius : number
resolution : integer

[source]

function DrawGroundCircle(posX, posY, posZ, radius, resolution, slope, gravity, weaponDefID)

Parameters

posX : number
posY : number
posZ : number
radius : number
resolution : integer
slope : number
gravity : number
weaponDefID : integer

[source]

function DrawGroundCircle(x0, z0, x1, z1, useNorm, useTxcd)

Parameters

x0 : number
z0 : number
x1 : number
z1 : number
useNorm : nil - No longer used.
useTxcd : boolean? - (Default: `false`)

[source]

function DrawGroundCircle(x0, z0, x1, z1, useNorm, tu0, tv0, tu1, tv1)

Parameters

x0 : number
z0 : number
x1 : number
z1 : number
useNorm : nil - No longer used.
tu0 : number
tv0 : number
tu1 : number
tv1 : number

[source]

function DrawListAtUnit(unitID, listIndex, useMidPos, scaleX, scaleY, scaleZ, degrees, rotX, rotY, rotZ)

Parameters

unitID : integer
listIndex : integer
useMidPos : boolean? - (Default: `true`)
scaleX : number? - (Default: `1.0`)
scaleY : number? - (Default: `1.0`)
scaleZ : number? - (Default: `1.0`)
degrees : number? - (Default: `0.0`)
rotX : number? - (Default: `0.0`)
rotY : number? - (Default: `1.0`)
rotZ : number? - (Default: `0.0`)

[source]

function DrawMiniMap(defaultTransform)

Parameters

defaultTransform : boolean? - (Default: `true`)

[source]

function EdgeFlag(flag)

Parameters

flag : boolean

[source]

function EndText()

[source]

function Feature(featureID, doRawDraw, useLuaMat, noLuaCall)

Parameters

featureID : integer
doRawDraw : boolean? - (Default: `false`)
useLuaMat : integer?
noLuaCall : boolean? - (Default: `false`) Skip the `DrawFeature` callin.

Draw the feature, applying transform.

[source]

function FeatureMultMatrix(featureID)

Parameters

featureID : integer

[source]

function FeaturePiece(featureID, pieceID)

Parameters

featureID : integer
pieceID : integer

[source]

function FeaturePieceMatrix(featureID, pieceID)

Parameters

featureID : integer
pieceID : integer

[source]

function FeaturePieceMultMatrix(featureID, pieceID)

Parameters

featureID : integer
pieceID : integer

[source]

function FeatureRaw(featureID, doRawDraw, useLuaMat, noLuaCall)

Parameters

featureID : integer
doRawDraw : boolean? - (Default: `false`)
useLuaMat : integer?
noLuaCall : boolean? - (Default: `true`) Skip the `DrawFeature` callin.

Draw the unit without applying transform.

Also skips the DrawFeature callin by default so any recursion is blocked.

[source]

function FeatureShape(featureDefID, teamID, rawState, toScreen, opaque)

Parameters

featureDefID : integer
teamID : integer
rawState : boolean? - (Default: `true`)
toScreen : boolean? - (Default: `false`)
opaque : boolean? - (Default: `true`) If `true`, draw opaque; if `false`, draw alpha.

[source]

function FeatureShapeTextures(featureDefID, push)

Parameters

featureDefID : integer
push : boolean - If `true`, push the render state; if `false`, pop it.

[source]

function FeatureTextures(featureID, push)

Parameters

featureID : integer
push : boolean - If `true`, push the render state; if `false`, pop it.

[source]

function FinalizeTextureAtlas(texName)

Parameters

texName : string

Returns

: boolean

[source]

function Finish()

[source]

function Flush()

[source]

function Fog(enable)

Parameters

enable : boolean

[source]

function FogCoord(coord)

Parameters

coord : number

[source]

function Frustum(left, right, bottom, top, near, far)

Parameters

left : number
right : number
bottom : number
top : number
near : number
far : number

[source]

function GenerateMipmap(texName)

Parameters

texName : string

[source]

function GetActiveUniforms(shaderID)

Parameters

shaderID : integer

Returns

activeUniforms : ActiveUniform[]

Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, …).

[source]

function GetAtlasTexture(texName, subAtlasTexName)

Parameters

texName : string
subAtlasTexName : string

Returns

x1 : number
x2 : number
y1 : number
y2 : number

[source]

function GetAtmosphere()

Returns

lightDirX : number
lightDirY : number
lightDirZ : number

[source]

function GetAtmosphere(param)

Parameters

param : (“fogStart”|“fogEnd”|“pos”|“fogColor”|“skyColor”|“sunColor”…)

Returns

: any …

[source]

function GetEngineAtlasTextures(atlasName)

Parameters

atlasName : ("$explosions"|"$groundfx")

Returns

atlasTextures : table<string,float4> - Table of x1,x2,y1,y2 coordinates by texture name.

[source]

function GetEngineModelUniformDataDef(index)

Parameters

index : number

Returns

glslDefinition : string

[source]

Return the GLSL compliant definition of ModelUniformData structure (per Unit/Feature buffer available on GPU)

function GetEngineModelUniformDataSize(index)

Parameters

index : number

Returns

sizeInElements : number
sizeInBytesOnCPU : number

[source]

Return the current size values of ModelUniformData structure (per Unit/Feature buffer available on GPU)

function GetEngineUniformBufferDef(index)

Parameters

index : number

Returns

glslDefinition : string

[source]

Return the GLSL compliant definition of UniformMatricesBuffer(idx=0) or UniformParamsBuffer(idx=1) structure.

function GetFixedState(param, toStr)

Parameters

param : string
toStr : boolean? - (Default: `false`)

Returns

enabled : boolean
values : any …

[source]

function GetGlobalTexCoords()

Returns

xstart : number
ystart : number
xend : number
yend : number

[source]

function GetGlobalTexNames()

Returns

List : string[] - of texture names.

[source]

function GetMapRendering(key)

Parameters

key : string

Returns

value : any …

[source]

function GetMatrixData(type, index)

Parameters

type : GL - Matrix type (`GL.PROJECTION`, `GL.MODELVIEW`, `GL.TEXTURE`).
index : integer - Matrix index in range `[1, 16]`.

Returns

The : number - value.

Get value at index of matrix.

[source]

function GetMatrixData(type)

Parameters

type : GL - Matrix type (`GL.PROJECTION`, `GL.MODELVIEW`, `GL.TEXTURE`).

Returns

The : [Matrix](#type-Matrix)4x4 - matrix.

[source]

function GetMatrixData(index)

Parameters

index : integer - Matrix index in range `[1, 16]`.

Returns

The : number - value.

[source]

function GetMatrixData(name)

Parameters

name : MatrixName - The matrix name.

Returns

The : [Matrix](#type-Matrix)4x4 - matrix.

[source]

function GetNumber(pname, count)

Parameters

pname : GL
count : integer? - (Default: `1`) Number of values to return, in range [1, 64].

Returns

: number …

Get the value or values of a selected parameter.

[source]

function GetQuery(query)

Parameters

query : any

Returns

count : integer

[source]

function GetScreenViewTrans()

Returns

x : number
y : number
z : number

[source]

function GetShaderLog()

Returns

infoLog : string

Returns the shader compilation error log. This is empty if the shader linking failed, in that case, check your in/out blocks and ensure they match.

[source]

function GetShadowMapParams()

Returns

x : number
y : number
z : number
w : number

[source]

function GetString(pname)

Parameters

pname : GL

Get a string describing the current OpenGL connection.

[source]

function GetSun()

Returns

lightDirX : number
lightDirY : number
lightDirZ : number

[source]

function GetSun(param, mode)

Parameters

param : (“pos”|“dir”|“specularExponent”|“shadowDensity”|“diffuse”|“ambient”…)
mode : (“ground”|“unit”) - (Default: `"ground"`)

Returns

data1 : number?
data2 : number?
data3 : number?

[source]

function GetTextHeight(text)

Parameters

text : string

Returns

height : number
descender : number
lines : integer

[source]

function GetTextWidth(text)

Parameters

text : string

Returns

width : number

[source]

function GetUniformLocation(shaderID, name)

Parameters

shaderID : integer
name : string

Returns

locationID : GL

Returns the locationID of a shaders uniform. Needed for changing uniform values with function gl.Uniform.

[source]

function GetVAO()

Returns

vao : VAO? - The VAO ref on success, else `nil`

Example:

local myVAO = gl.GetVAO()
if myVAO == nil then Spring.Echo("Failed to get VAO") end

[source]

function GetVBO(bufferType, freqUpdated)

Parameters

bufferType : GL? - (Default: `GL.ARRAY_BUFFER`) The buffer type to use. Accepts the following: - `GL.ARRAY_BUFFER` for vertex data. - `GL.ELEMENT_ARRAY_BUFFER` for vertex indices. - `GL.UNIFORM_BUFFER` - `GL.SHADER_STORAGE_BUFFER`
freqUpdated : boolean? - (Default: `true`) `true` to updated frequently, `false` to update only once.

Returns

VBO : VBO?

Example:

local myVBO = gl.GetVBO()
if myVBO == nil then Spring.Echo("Failed to get VBO") end

[source]

(See: )

function GetViewRange()

Returns

nearPlaneDist : number
farPlaneDist : number
minViewRange : number
maxViewRange : number

[source]

function GetViewSizes()

Returns

x : number
y : number

[source]

function GetWaterRendering(key)

Parameters

key : string

Returns

value : any …

[source]

function HasExtension(ext)

Parameters

ext : string

Returns

: boolean

[source]

function IsValidFBO(fbo, target)

Parameters

fbo : FBO
target : GL?

Returns

valid : boolean
status : number?

[source]

function Light(light, enable)

Parameters

light : integer
enable : boolean

[source]

function Light(light, pname, param)

Parameters

light : integer
pname : GL
param : GL

[source]

function Light(light, pname, r, g, b, a)

Parameters

light : integer
pname : GL
r : number
g : number
b : number
a : number?

[source]

function Lighting(enable)

Parameters

enable : boolean

[source]

function LineStipple(enable)

Parameters

enable : boolean

[source]

function LineStipple(ignoredString)

Parameters

ignoredString : string - The value of this string is ignored, but it still does something.

[source]

function LineStipple(factor, pattern, shift)

Parameters

factor : integer
pattern : integer
shift : integer?

[source]

function LineWidth(width)

Parameters

width : number

[source]

function LoadIdentity()

[source]

function LoadMatrix(matrix)

Parameters

matrix : string

[source]

function LoadMatrix(matrix)

Parameters

matrix : [Matrix](#type-Matrix)4x4

[source]

function LoadMatrix()

Returns

m11 : number
m12 : number
m13 : number
m14 : number
m21 : number
m22 : number
m23 : number
m24 : number
m31 : number
m32 : number
m33 : number
m34 : number
m41 : number
m42 : number
m43 : number
m44 : number

[source]

function LogicOp(enable)

Parameters

enable : boolean

[source]

function LogicOp(opCode)

Parameters

opCode : GL

Specify a logical pixel operation for rendering.

[source]

function Material(material)

Parameters

material : Material

[source]

function MatrixMode(mode)

Parameters

mode : GL

[source]

function MemoryBarrier(barriers)

Parameters

barriers : integer? - (Default: `4`)

[source]

function MultiTexCoord(texNum, coord)

Parameters

texNum : integer
coord : (number)

[source]

function MultiTexCoord(texNum, coord)

Parameters

texNum : integer
coord : xy

[source]

function MultiTexCoord(texNum, coord)

Parameters

texNum : integer
coord : xyz

[source]

function MultiTexCoord(texNum, coord)

Parameters

texNum : integer
coord : xyzw

[source]

function MultiTexCoord(texNum, s, t, r, q)

Parameters

texNum : integer
s : number
t : number?
r : number?
q : number?

[source]

function MultiTexEnv(texNum, target, pname, value)

Parameters

texNum : integer
target : GL
pname : GL
value : number

[source]

function MultiTexEnv(texNum, target, pname, r, g, b, a)

Parameters

texNum : integer
target : GL
pname : GL
r : number? - (Default: `0.0`)
g : number? - (Default: `0.0`)
b : number? - (Default: `0.0`)
a : number? - (Default: `0.0`)

[source]

function MultiTexGen(texNum, target, state)

Parameters

texNum : integer
target : GL
state : boolean

[source]

function MultiTexGen(texNum, target, pname, value)

Parameters

texNum : integer
target : GL
pname : GL
value : number

[source]

function MultiTexGen(texNum, target, pname, r, g, b, a)

Parameters

texNum : integer
target : GL
pname : GL
r : number? - (Default: `0.0`)
g : number? - (Default: `0.0`)
b : number? - (Default: `0.0`)
a : number? - (Default: `0.0`)

[source]

function MultMatrix(matrixName)

Parameters

matrixName : string

[source]

function MultMatrix(matrix)

Parameters

matrix : [Matrix](#type-Matrix)4x4

[source]

function MultMatrix(m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44)

Parameters

m11 : number
m12 : number
m13 : number
m14 : number
m21 : number
m22 : number
m23 : number
m24 : number
m31 : number
m32 : number
m33 : number
m34 : number
m41 : number
m42 : number
m43 : number
m44 : number

[source]

function Normal(v)

Parameters

v : xyz

[source]

function Normal(x, y, z)

Parameters

x : number
y : number
z : number

[source]

function ObjectLabel(objectTypeIdentifier, objectID, label)

Parameters

objectTypeIdentifier : GL - Specifies the type of object being labeled.
objectID : integer - Specifies the name or ID of the object to label.
label : string - A string containing the label to be assigned to the object.

Labels an object for use with debugging tools. May be unavailable and nil if the platform doesn’t support the feature.

[source]

function Ortho(left, right, bottom, top, near, far)

Parameters

left : number
right : number
bottom : number
top : number
near : number
far : number

[source]

function PointParameter(atten0, atten1, atten2, sizeMin, sizeMax, sizeFade)

Parameters

atten0 : number
atten1 : number
atten2 : number
sizeMin : number?
sizeMax : number?
sizeFade : number?

[source]

function PointSize(size)

Parameters

size : number

[source]

function PointSprite(enable, enableCoordReplace, coordOrigin)

Parameters

enable : boolean
enableCoordReplace : boolean?
coordOrigin : boolean? - `true` for upper left, `false` for lower left, otherwise no change.

[source]

function PolygonMode(face, mode)

Parameters

face : GL
mode : GL

Select polygon rasterization mode.

[source]

function PolygonOffset(enable)

Parameters

enable : boolean

[source]

function PolygonOffset(factor, units)

Parameters

factor : number
units : number

[source]

function PopAttrib()

[source]

function PopDebugGroup()

Returns

: nil

Pops the most recent GL debug group from the stack (does NOT take the numerical ID from push). May be unavailable and nil if the platform doesn’t support the feature.

[source]

function PopMatrix()

[source]

function PushAttrib(mask)

Parameters

mask : GL? - (Default: `GL.ALL_ATTRIB_BITS`)

[source]

function PushDebugGroup(id, message, sourceIsThirdParty)

Parameters

id : integer - A numeric identifier for the group, can be any unique number.
message : string - A human-readable string describing the debug group. Will be truncated if longer than driver-specific limit
sourceIsThirdParty : boolean - Set the source tag, true for GL_DEBUG_SOURCE_THIRD_PARTY, false for GL_DEBUG_SOURCE_APPLICATION. default false

Returns

: nil

Pushes a debug marker for debugging tools such as nVidia nSight 2024.04, see https://registry.khronos.org/OpenGL-Refpages/gl4/html/glPushDebugGroup.xhtml .

May be unavailable and nil if the platform doesn’t support the feature.

Groups are basically named scopes similar to tracy’s, and are pushed/popped independently from GL attribute/matrix push/pop (though of course makes sense to put them together).

Tools are known to struggle to see the annotation for FBOs if they are raw bound.

[source]

function PushMatrix()

[source]

function PushPopMatrix(matMode1, func, ...)

Parameters

matMode1 : GL
func : fun()
... : any - Arguments to the function.

[source]

function PushPopMatrix(func, ...)

Parameters

func : fun()
... : any - Arguments to the function.

[source]

function RawBindFBO(fbo, target, rawFboId)

Parameters

fbo : nil
target : GL? - (Default: `GL_FRAMEBUFFER_EXT`)
rawFboId : integer? - (Default: `0`)

Returns

: nil

Bind default or specified via rawFboId numeric id of FBO

[source]

function RawBindFBO(fbo, target)

Parameters

fbo : FBO
target : GL? - (Default: `fbo.target`)

Returns

previouslyBoundRawFboId : number

[source]

function ReadPixels(x, y, w, h, format)

Parameters

x : integer
y : integer
w : 1
h : 1
format : GL? - (Default: `GL.RGBA`)

Returns

Color : number … - values (color size based on format).

Get single pixel.

[source]

function ReadPixels(x, y, w, h, format)

Parameters

x : integer
y : integer
w : 1
h : integer
format : GL? - (Default: `GL.RGBA`)

Returns

Column : number[][] - of color values (color size based on format).

Get column of pixels.

[source]

function ReadPixels(x, y, w, h, format)

Parameters

x : integer
y : integer
w : integer
h : 1
format : GL? - (Default: `GL.RGBA`)

Returns

Row : number[][] - of color values (color size based on format).

Get row of pixels.

[source]

function ReadPixels(x, y, w, h, format)

Parameters

x : integer
y : integer
w : integer
h : integer
format : GL? - (Default: `GL.RGBA`)

Returns

Array : number[][][] - of columns of color values (color size based on format).

Get row of pixels.

[source]

function Rect(x1, y1, x2, y2)

Parameters

x1 : number
y1 : number
x2 : number
y2 : number

[source]

function Rect(x1, y1, x2, y2, flipSCoords, flipTCoords)

Parameters

x1 : number
y1 : number
x2 : number
y2 : number
flipSCoords : boolean?
flipTCoords : boolean?

[source]

function Rect(x1, y1, x2, y2, s1, t1, s2, t2)

Parameters

x1 : number
y1 : number
x2 : number
y2 : number
s1 : number
t1 : number
s2 : number
t2 : number

[source]

function RenderToTexture(texName, fun, ...)

Parameters

texName : string
fun : unknown
... : any - Arguments to the function.

[source]

function ResetMatrices()

[source]

function ResetState()

[source]

function Rotate(r, x, y, z)

Parameters

r : number
x : number
y : number
z : number

[source]

function RunQuery(query)

Parameters

query : any

[source]

function SaveImage(x, y, width, height, filename, options)

Parameters

x : integer
y : integer
width : integer
height : integer
filename : string
options : SaveImageOptions?

Returns

success : boolean?

[source]

function Scale(x, y, z)

Parameters

x : number
y : number
z : number

[source]

function Scissor(enable)

Parameters

enable : boolean

[source]

function Scissor(x, y, w, h)

Parameters

x : integer
y : integer
w : integer
h : integer

[source]

function SecondaryColor(color)

Parameters

color : rgb

[source]

function SecondaryColor(r, g, b)

Parameters

r : number
g : number
b : number

[source]

function SetGeometryShaderParameter(shaderID, key, value)

Parameters

shaderID : integer
key : number
value : number

Returns

: nil

Sets the Geometry shader parameters for shaderID. Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri)

[source]

function SetTesselationShaderParameter(param, value)

Parameters

param : integer
value : integer

Returns

: nil

Sets the tesselation shader parameters for shaderID.

Needed by tesselation shader programs. (Check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri).

[source]

function ShadeModel(model)

Parameters

model : GL

[source]

function Shape(type, vertices)

Parameters

type : GL
vertices : VertexData[]

[source]

function SlaveMiniMap(newMode)

Parameters

newMode : boolean

[source]

function StencilFunc(func, ref, mask)

Parameters

func : GL - Specifies the test function. Eight symbolic constants are valid: `GL.NEVER`, `GL.LESS`, `GL.EQUAL`, `GL.LEQUAL`, `GL.GREATER`, `GL.NOTEQUAL`, `GL.GEQUAL`, and `GL.ALWAYS`. The initial value is `GL.ALWAYS`.
ref : integer - Specifies the reference value for the stencil test. `ref` is clamped to the range `[0, 2^n - 1]`, where `n` is the number of bitplanes in the stencil buffer. The initial value is `0`.
mask : integer - Specifies a mask that is ANDed with both the reference value and the stored stencil value when the test is done. The initial value is all `1`'s.

Set front and back function and reference value for stencil testing.

[source]

function StencilFuncSeparate(face, func, ref, mask)

Parameters

face : GL - Specifies whether front and/or back stencil state is updated. Three symbolic constants are accepted: `GL.FRONT`, `GL.BACK`, and `GL.FRONT_AND_BACK`. The initial value is `GL.FRONT_AND_BACK`.
func : GL - Specifies the test function. Eight symbolic constants are valid: `GL.NEVER`, `GL.LESS`, `GL.EQUAL`, `GL.LEQUAL`, `GL.GREATER`, `GL.NOTEQUAL`, `GL.GEQUAL`, and `GL.ALWAYS`. The initial value is `GL.ALWAYS`.
ref : integer - Specifies the reference value for the stencil test. `ref` is clamped to the range `[0, 2^n - 1]`, where `n` is the number of bitplanes in the stencil buffer. The initial value is `0`.
mask : integer - Specifies a mask that is ANDed with both the reference value and the stored stencil value when the test is done. The initial value is all `1`'s.

Set front and/or back function and reference value for stencil testing.

[source]

function StencilMask(mask)

Parameters

mask : integer - Specifies a bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all `1`'s.

Control the front and back writing of individual bits in the stencil planes.

[source]

function StencilMaskSeparate(face, mask)

Parameters

face : GL - Specifies whether the front and/or back stencil writemask is updated. Three symbolic constants are accepted: `GL.FRONT`, `GL.BACK`, and `GL.FRONT_AND_BACK`. The initial value is `GL.FRONT_AND_BACK`.
mask : integer - Specifies a bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all `1`'s.

Control the front and back writing of individual bits in the stencil planes.

[source]

function StencilOp(fail, zfail, zpass)

Parameters

fail : GL - Specifies the action to take when the stencil test fails. Eight symbolic constants are valid: `GL.KEEP`, `GL.ZERO`, `GL.REPLACE`, `GL.INCR`, `GL.INCR_WRAP`, `GL.DECR`, `GL.DECR_WRAP`, and `GL.INVERT`. The initial value is `GL.KEEP`.
zfail : GL - Specifies the stencil action when the stencil test passes, but the depth test fails. The initial value is `GL.KEEP`.
zpass : GL - Specifies the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. The initial value is `GL.KEEP`.

Set front and back stencil test actions.

[source]

function StencilOpSeparate(face, fail, zfail, zpass)

Parameters

face : GL - Specifies whether front and/or back stencil state is updated. Three symbolic constants are accepted: `GL.FRONT`, `GL.BACK`, and `GL.FRONT_AND_BACK`. The initial value is `GL.FRONT_AND_BACK`.
fail : GL - Specifies the action to take when the stencil test fails. Eight symbolic constants are valid: `GL.KEEP`, `GL.ZERO`, `GL.REPLACE`, `GL.INCR`, `GL.INCR_WRAP`, `GL.DECR`, `GL.DECR_WRAP`, and `GL.INVERT`. The initial value is `GL.KEEP`.
zfail : GL - Specifies the stencil action when the stencil test passes, but the depth test fails. The initial value is `GL.KEEP`.
zpass : GL - Specifies the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. The initial value is `GL.KEEP`.

Set front and/or back stencil test actions.

[source]

function StencilTest(enable)

Parameters

enable : boolean

[source]

function SwapBuffers()

[source]

function TexCoord(coord)

Parameters

coord : (number)

[source]

function TexCoord(coord)

Parameters

coord : xy

[source]

function TexCoord(coord)

Parameters

coord : xyz

[source]

function TexCoord(coord)

Parameters

coord : xyzw

[source]

function TexCoord(s, t, r, q)

Parameters

s : number
t : number?
r : number?
q : number?

[source]

function TexGen(target, state)

Parameters

target : GL
state : boolean

[source]

function TexGen(target, pname, value)

Parameters

target : GL
pname : GL
value : number

[source]

function TexGen(target, pname, r, g, b, a)

Parameters

target : GL
pname : GL
r : number? - (Default: `0.0`)
g : number? - (Default: `0.0`)
b : number? - (Default: `0.0`)
a : number? - (Default: `0.0`)

[source]

function Text(text, x, y, size, options)

Parameters

text : string
x : number
y : number
size : number
options : string? - concatenated string of option characters. - horizontal alignment: - 'c' = center - 'r' = right - vertical alignment: - 'a' = ascender - 't' = top - 'v' = vertical center - 'x' = baseline - 'b' = bottom - 'd' = descender - decorations: - 'o' = black outline - 'O' = white outline - 's' = shadow - other: - 'n' = don't round vertex coords to nearest integer (font may get blurry)

Returns

: nil

[source]

function TextEnv(target, pname, value)

Parameters

target : GL
pname : GL
value : number

[source]

function TextEnv(target, pname, r, g, b, a)

Parameters

target : GL
pname : GL
r : number? - (Default: `0.0`)
g : number? - (Default: `0.0`)
b : number? - (Default: `0.0`)
a : number? - (Default: `0.0`)

[source]

function Texture(texNum, enable)

Parameters

texNum : integer
enable : boolean?

Returns

: boolean

[source]

function Texture(enable)

Parameters

enable : boolean

Returns

: boolean

[source]

function Texture(texNum, image)

Parameters

texNum : integer
image : string

Returns

: boolean

[source]

function Texture(image)

Parameters

image : string

Returns

: boolean

[source]

function TextureInfo(texName)

Parameters

texName : string

Returns

textureInfo : TextureInfo

[source]

function Translate(x, y, z)

Parameters

x : number
y : number
z : number

[source]

function Uniform(locationID, f1, f2, f3, f4)

Parameters

locationID : (GL|string) - uniformName
f1 : number
f2 : number?
f3 : number?
f4 : number?

Sets the uniform float value at the locationID for the currently active shader. Shader must be activated before setting uniforms.

[source]

function UniformArray(locationID, type, uniforms)

Parameters

locationID : (integer|string) - uniformName
type : UniformArrayType
uniforms : number[] - Array up to 1024 elements

Sets the an array of uniform values at the locationID for the currently active shader.

Shader must be activated before setting uniforms.

[source]

function UniformInt(locationID, int1, int2, int3, int4)

Parameters

locationID : (integer|string) - uniformName
int1 : integer
int2 : integer?
int3 : integer?
int4 : integer?

Sets the uniform int value at the locationID for the currently active shader. Shader must be activated before setting uniforms.

[source]

function UniformMatrix(locationID, matrix)

Parameters

locationID : (integer|string) - uniformName
matrix : MatrixName - Name of common matrix.

Sets the a uniform mat4 locationID for the currently active shader.

Shader must be activated before setting uniforms.

Can set one one common matrix like shadow, or by passing 16 additional numbers for the matrix.

[source]

function UniformMatrix(locationID, matrix)

Parameters

locationID : (integer|string) - uniformName
matrix : number[] - A 2x2, 3x3 or 4x4 matrix.

Sets the a uniform mat4 locationID for the currently active shader.

Shader must be activated before setting uniforms.

Can set one one common matrix like shadow, or by passing 16 additional numbers for the matrix.

[source]

function Unit(unitID, doRawDraw, useLuaMat, noLuaCall, fullModel)

Parameters

unitID : integer
doRawDraw : boolean? - (Default: `false`)
useLuaMat : integer?
noLuaCall : boolean? - (Default: `false`) Skip the `DrawUnit` callin.
fullModel : boolean? - (Default: `true`)

Draw the unit, applying transform.

[source]

function UnitMultMatrix(unitID)

Parameters

unitID : integer

[source]

function UnitPiece(unitID, pieceID)

Parameters

unitID : integer
pieceID : integer

[source]

function UnitPieceMatrix(unitID, pieceID)

Parameters

unitID : integer
pieceID : integer

[source]

function UnitPieceMultMatrix(unitID, pieceID)

Parameters

unitID : integer
pieceID : integer

[source]

function UnitRaw(unitID, doRawDraw, useLuaMat, noLuaCall, fullModel)

Parameters

unitID : integer
doRawDraw : boolean? - (Default: `false`)
useLuaMat : integer?
noLuaCall : boolean? - (Default: `true`) Skip the `DrawUnit` callin.
fullModel : boolean? - (Default: `true`)

Draw the unit without applying transform.

Also skips the DrawUnit callin by default so any recursion is blocked.

[source]

function UnitShape(unitDefID, teamID, rawState, toScreen, opaque)

Parameters

unitDefID : integer
teamID : integer
rawState : boolean? - (Default: `true`)
toScreen : boolean? - (Default: `false`)
opaque : boolean? - (Default: `true`) If `true`, draw opaque; if `false`, draw alpha.

[source]

function UnitShapeTextures(unitDefID, push)

Parameters

unitDefID : integer
push : boolean - If `true`, push the render state; if `false`, pop it.

[source]

function UnitTextures(unitID, push)

Parameters

unitID : integer
push : boolean - If `true`, push the render state; if `false`, pop it.

[source]

function UnsafeState(state, func, ...)

Parameters

state : GL
func : fun()
... : any - Arguments to the function.

[source]

function UnsafeState(state, reverse, func, ...)

Parameters

state : GL
reverse : boolean
func : fun()
... : any - Arguments to the function.

[source]

function UseShader(shaderID)

Parameters

shaderID : integer

Returns

linked : boolean

Binds a shader program identified by shaderID. Pass 0 to disable the shader. Returns whether the shader was successfully bound.

[source]

function Vertex(v)

Parameters

v : xy

[source]

function Vertex(v)

Parameters

v : xyz

[source]

function Vertex(v)

Parameters

v : xyzw

[source]

function Vertex(x, y, z, w)

Parameters

x : number
y : number
z : number?
w : number?

[source]

function Viewport(x, y, w, h)

Parameters

x : integer
y : integer
w : integer
h : integer

[source]

table Platform

Platform specific information

[source]

property availableVideoModes PlatformVideoMode[]

[source]

property cpuBrand string

[source]

property cpuLogicalCores integer

[source]

property cpuPhysicalCores integer

[source]

property gladVersion string

[source]

property glewVersion string

[source]

property glHaveAMD boolean

[source]

property glHaveGL4 boolean

[source]

property glHaveGLSL boolean

[source]

property glHaveIntel boolean

[source]

property glHaveNVidia boolean

[source]

property glRenderer string

[source]

property glslVersion string

[source] Full version

property glslVersionNum string

[source]

property glslVersionShort string

[source] major.minor

property glSupportClipSpaceControl boolean

[source]

property glSupportDepthBufferBitDepth number

[source]

property glSupportFragDepthLayout boolean

[source]

property glSupportMSAAFrameBuffer boolean

[source]

property glSupportNonPowerOfTwoTex boolean

[source]

property glSupportRestartPrimitive boolean

[source]

property glSupportSeamlessCubeMaps boolean

[source]

property glSupportTextureQueryLOD boolean

[source]

property glVendor string

[source]

property glVersion string

[source] Full version

property glVersionNum integer

[source]

property glVersionShort string

[source] major.minor.buildNumber

property gpu string

[source] Full GPU device name

property gpuMemorySize number

[source] Size of total GPU memory in MBs; only available for “Nvidia”, (rest are 0)

property gpuVendor (“Nvidia”|“Intel”|“ATI”|“Mesa”|“Unknown”)

[source]

property hwConfig string

[source]

property macAddrHash string

[source]

property numDisplays integer

[source]

property osFamily (“Windows”|“Linux”|“MacOSX”|“FreeBSD”|“Unknown”)

[source]

property osName string

[source] full name of the OS

property osVersion string

[source]

property sdlVersionCompiledMajor number

[source]

property sdlVersionCompiledMinor number

[source]

property sdlVersionCompiledPatch number

[source]

property sdlVersionLinkedMajor number

[source]

property sdlVersionLinkedMinor number

[source]

property sdlVersionLinkedPatch number

[source]

property sysInfoHash string

[source]

property totalRAM number

[source] Total physical system RAM in MBs.

table RmlUi

Global functions for Recoil’s RmlUi implementation.

[source]

function AddTranslationString(key, translation)

Parameters

key : string
translation : string

Returns

success : boolean

Add a translation string.

[source]

function ClearTranslations()

Clear registered translations.

[source]

property Context RmlUi.Context

Holds documents and a data model.

The Context class has no constructor; it must be instantiated through the CreateContext() function. It has the following functions and properties:

[source]

property contexts RmlUi.Context[]

[source]

function CreateContext(name)

Parameters

name : string

Returns

nil : RmlUi.Context? - if failed.

Create a new context.

[source]

property default_action_phase RmlUi.defaultactionphase

[source]

property Document RmlUi.Document

Document derives from Element.

Document has no constructor; it must be instantiated through a Context object instead, either by loading an external RML file or creating an empty document. It has the following functions and properties:

[source]

property Element RmlUi.Element

Represents an element in the RmlUi document tree. This class cannot be constructed directly; use a Document object to instantiate elements. This is the foundational piece of the DOM.

[source]

property ElementForm RmlUi.ElementForm

[source]

property ElementFormControl RmlUi.ElementFormControl

[source]

property ElementFormControlInput RmlUi.ElementFormControlInput

[source]

property ElementFormControlSelect RmlUi.ElementFormControlSelect

[source]

property ElementFormControlTextArea RmlUi.ElementFormControlTextArea

[source]

property ElementProgress RmlUi.ElementProgress

[source]

property ElementPtr RmlUi.ElementPtr

Represents an owned element.

This type is mainly used to modify the DOM tree by passing the object into other elements. For example RmlUi.Element:AppendChild(). A current limitation in the Lua plugin is that Element member properties and functions cannot be used directly on this type.

[source]

property ElementTabSet RmlUi.ElementTabSet

[source]

property ElementText RmlUi.ElementText

[source]

property Event RmlUi.Event

An event that happens to an element.

[source]

property EventListener RmlUi.EventListener

Event listener interface

[source]

property EventParametersProxy RmlUi.EventParametersProxy

Keyboard and mouse input data associated with an event.

[source]

property font_weight RmlUi.font_weight

[source]

function GetContext(name)

Parameters

name : string

Returns

nil : RmlUi.Context? - if failed.

Get a context by name.

[source]

property key_identifier RmlUi.key_identifier

[source]

property key_modifier RmlUi.key_modifier

[source]

function LoadFontFace(file_path, fallback, weight)

Parameters

file_path : string
fallback : boolean?
weight : RmlUi.font_weight?

Returns

success : boolean

Load a font face.

[source]

function RegiserEventType(event_type, interruptible, bubbles, default_phase)

Parameters

event_type : string
interruptible : boolean?
bubbles : boolean?
default_phase : RmlUi.defaultactionphase?

Returns

: RmlUi.EventID

Register a new event type.

[source]

function RemoveContext(context)

Parameters

context : (string|RmlUi.Context)

Remove a context.

[source]

property RmlEventPhase RmlUi.RmlEventPhase

[source]

property RmlFocusFlag RmlUi.RmlFocusFlag

[source]

property RmlModalFlag RmlUi.RmlModalFlag

[source]

function SetDebugContext(context)

Parameters

context : (string|RmlUi.Context)

Set which context the debug inspector is meant to inspect.

[source]

function SetMouseCursorAlias(rml_name, recoil_name)

Parameters

rml_name : string - name used in rml script
recoil_name : string - name used in recoil

Converts the css names for cursors to the Recoil Engine names for cursors like RmlUi.SetMouseCursorAlias("pointer", 'Move'). Web devs tend to want to use specific words for pointer types.

[source]

property SolLuaDataModel RmlUi.SolLuaDataModel<T>

Handle for a data model.

It is a wrapper around the model table, marked as type T. You can access fields by using normal indexing, but for the moment, the only keys that work are strings. Any index done this way will automatically trigger a rerender. If you need to index any tables or subtables by anything not a string, you will need to use the underlying table, gotten with __GetTable. This will not trigger a rerender. To trigger a rerender manually, use _SetDirty, passing in the name of the top-level entry in your model table that you edited.

[source]

property Vector2f RmlUi.Vector2f

Two-dimensional float vector

[source]

(See: RmlUi.Vector2f)

property Vector2i [RmlUi.Vector](#type-RmlUi-Vector)2i

Two-dimensional integral vector.

[source]

property version string

[source] RmlUi version

table Script

property ALL_ACCESS_TEAM integer: -2

[source]

function DelayByFrames(frameDelay, fun)

Parameters

frameDelay : integer
fun : unknown

[source]

function GetCtrlTeam()

Returns

teamID : integer

[source]

function GetFullCtrl()

Returns

fullCtrl : boolean

[source]

function GetFullRead()

Returns

fullRead : boolean

[source]

function GetGlobal()

Returns

global : integer?

[source]

function GetName()

Returns

name : string

[source]

function GetReadAllyTeam()

Returns

allyTeamID : integer

[source]

function GetReadTeam()

Returns

teamID : integer

[source]

function GetRegistry()

Returns

registry : integer?

[source]

function GetSelectTeam()

Returns

teamID : integer

[source]

function GetSynced()

Returns

synced : boolean

[source]

function GetWatchAllowTarget(weaponDefID)

Parameters

weaponDefID : integer

Returns

watched : boolean - `true` if callins are registered, otherwise `false`.

Query whether weapon targeting callins are registered for a weaponDefID.

[source]

(See: )

function GetWatchExplosion(weaponDefID)

Parameters

weaponDefID : integer

Returns

watched : boolean - `true` if callins are registered, otherwise `false`.

Query whether explosion callins are registered for a weaponDefID.

[source]

(See: )

function GetWatchFeature(featureDefID)

Parameters

featureDefID : integer

Returns

watched : boolean - `true` if callins are registered, otherwise `false`.

Query whether any callins are registered for a featureDefID.

[source]

(See: )

function GetWatchProjectile(weaponDefID)

Parameters

weaponDefID : integer

Returns

watched : boolean - `true` if callins are registered, otherwise `false`.

Query whether projectile callins are registered for a weaponDefID.

[source]

(See: )

function GetWatchUnit(unitDefID)

Parameters

unitDefID : integer

Returns

watched : boolean - Watch status.

Query whether any callins are registered for a unitDefID.

[source]

(See: )

function GetWatchWeapon(weaponDefID)

Parameters

weaponDefID : integer

Returns

watched : boolean - True if watch is enabled for any weaponDefID callins.

Query whether any callins are registered for a weaponDefID.

[source]

Same as calling:

Script.GetWatchExplosion(weaponDefID) or Script.GetWatchProjectile(weaponDefID) or Script.GetWatchAllowTarget(weaponDefID)

(See: )

function IsEngineMinVersion(minMajorVer, minMinorVer, minCommits)

Parameters

minMajorVer : integer
minMinorVer : integer? - (Default: `0`)
minCommits : integer? - (Default: `0`)

Returns

satisfiesMin : boolean - `true` if the engine version is greater or equal to the specified version, otherwise `false`.

[source]

function Kill(killMessage)

Parameters

killMessage : string? - Kill message.

[source]

property NO_ACCESS_TEAM integer: -1

[source]

function SetWatchAllowTarget(weaponDefID, watch)

Parameters

weaponDefID : integer
watch : boolean - Whether to register or deregister.

Register or deregister weaponDefID for weapon targeting callins.

[source]

(See: )

function SetWatchExplosion(weaponDefID, watch)

Parameters

weaponDefID : integer
watch : boolean - Whether to register or deregister.

Register or deregister weaponDefID for explosion callins.

[source]

(See: )

function SetWatchFeature(featureDefID, watch)

Parameters

featureDefID : integer
watch : boolean - Whether to register or deregister.

Register or deregister featureDefID for expensive callins.

[source]

(See: )

function SetWatchProjectile(weaponDefID, watch)

Parameters

weaponDefID : integer - weaponDefID for weapons or -1 to watch for debris.
watch : boolean - Whether to register or deregister.

Register or deregister weaponDefID for expensive projectile callins.

[source]

(See: )

function SetWatchUnit(unitDefID, watch)

Parameters

unitDefID : integer
watch : boolean - Whether to register or deregister.

Register or deregister unitDefID for expensive callins.

[source]

(See: )

function SetWatchWeapon(weaponDefID, watch)

Parameters

weaponDefID : integer
watch : boolean - Whether to register or deregister.

Register or deregister weaponDefID for all expensive callins.

[source]

Equivalent to calling:

Script.SetWatchExplosion(weaponDefID)
Script.SetWatchProjectile(weaponDefID)
Script.SetWatchAllowTarget(weaponDefID)

Generally it’s better to use those methods to avoid registering uneeded callins.

(See: )

function UpdateCallin(name)

Parameters

name : string

[source]

table Spring

function AddFeatureDamage(featureID, damage, paralyze, attackerID, weaponID, impulseX, impulseY, impulseZ)

Parameters

featureID : integer
damage : number
paralyze : number? - (Default: `0`) equals to the paralyzetime in the WeaponDef.
attackerID : integer? - (Default: `-1`)
weaponID : integer? - (Default: `-1`)
impulseX : number?
impulseY : number?
impulseZ : number?

Apply damage to feature

[source]

Will trigger FeaturePreDamaged and FeatureDamaged callins.

Won’t do anything if paralyze is not zero, the feature is already marked for deletion, or in void.

If health goes below 0 and featureDef is destructable the feature will be deleted and a wreck created.

(See: )

function AddGrass(x, z)

Parameters

x : number
z : number

Returns

: nil

[source]

function AddHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Returns

newHeight : integer?

Can only be called in Spring.SetHeightMapFunc

[source]

function AddLightTrackingTarget()

[source]

function AddMapLight(lightParams)

Parameters

lightParams : LightParams

Returns

lightHandle : integer

[source]

requires MaxDynamicMapLights > 0

function AddModelLight(lightParams)

Parameters

lightParams : LightParams

Returns

lightHandle : number

[source]

requires MaxDynamicMapLights > 0

function AddObjectDecal(unitID)

Parameters

unitID : integer

Returns

: nil

[source]

function AddOriginalHeightMap(x, y, height)

Parameters

x : number
y : number
height : number

Returns

: nil

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

function AddSmoothMesh(x, z, height)

Parameters

x : number
z : number
height : number

Returns

height : number? - The new height, or `nil` if coordinates are invalid.

Can only be called in Spring.SetSmoothMeshFunc.

[source]

function AddTeamResource(teamID, type, amount)

Parameters

teamID : integer
type : ResourceName
amount : number

Returns

: nil

Adds metal or energy resources to the specified team.

[source]

function AddUnitDamage(unitID, damage, paralyze, attackerID, weaponID, impulseX, impulseY, impulseZ)

Parameters

unitID : integer
damage : number
paralyze : number? - (Default: `0`) equals to the paralyzetime in the WeaponDef.
attackerID : integer? - (Default: `-1`)
weaponID : integer? - (Default: `-1`)
impulseX : number?
impulseY : number?
impulseZ : number?

Returns

: nil

[source]

function AddUnitExperience(unitID, deltaExperience)

Parameters

unitID : integer
deltaExperience : number - Can be negative to subtract, but the unit will never have negative total afterwards

Returns

: nil

[source]

(See: )

function AddUnitIcon(iconName, texFile, size, dist, radAdjust)

Parameters

iconName : string
texFile : string
size : number?
dist : number?
radAdjust : number?

Returns

added : boolean

[source]

function AddUnitImpulse(unitID, x, y, z, decayRate)

Parameters

unitID : integer
x : number
y : number
z : number
decayRate : number?

Returns

: nil

[source]

function AddUnitResource(unitID, resource, amount)

Parameters

unitID : integer
resource : string - "m" | "e"
amount : number

Returns

: nil

[source]

function AddUnitSeismicPing(unitID, pindSize)

Parameters

unitID : integer
pindSize : number

Returns

: nil

[source]

function AddWorldIcon(cmdID, posX, posY, posZ)

Parameters

cmdID : integer
posX : number
posY : number
posZ : number

Returns

: nil

[source]

function AddWorldText(text, posX, posY, posZ)

Parameters

text : string
posX : number
posY : number
posZ : number

Returns

: nil

[source]

function AddWorldUnit(unitDefID, posX, posY, posZ, teamID, facing)

Parameters

unitDefID : integer
posX : number
posY : number
posZ : number
teamID : integer
facing : FacingInteger

Returns

: nil

[source]

function AdjustHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Add height to a point in the world.

[source]

function AdjustHeightMap(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number?

Returns

: nil

Add height to a rectangle in the world.

[source]

function AdjustOriginalHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Add height to a point in the original map height cache.

[source]

function AdjustOriginalHeightMap(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number

Add height to a rectangle area in the original map height cache.

[source]

function AdjustSmoothMesh(x, z, height)

Parameters

x : number
z : number
height : number

[source]

function AdjustSmoothMesh(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number

[source]

function AreHelperAIsEnabled()

Returns

enabled : boolean

[source]

function ArePlayersAllied(playerID1, playerID2)

Parameters

playerID1 : number
playerID2 : number

Returns

: boolean?

[source]

function AreTeamsAllied(teamID1, teamID2)

Parameters

teamID1 : number
teamID2 : number

Returns

: boolean?

[source]

function AssignMouseCursor(cmdName, iconFileName, overwrite, hotSpotTopLeft)

Parameters

cmdName : string
iconFileName : string - not the full filename, instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack
overwrite : boolean? - (Default: `true`)
hotSpotTopLeft : boolean? - (Default: `false`)

Returns

assigned : boolean?

Changes/creates the cursor of a single CursorCmd.

[source]

function AssignPlayerToTeam(playerID, teamID)

Parameters

playerID : integer
teamID : integer

Returns

: nil

Assigns a player to a team.

[source]

function BuggerOff(x, y, z, radius, teamID, spherical, forced, excludeUnitID, excludeUnitDefIDs)

Parameters

x : number
y : number
z : number? - uses ground height when unspecified
radius : number
teamID : integer
spherical : boolean? - (Default: `true`)
forced : boolean? - (Default: `true`)
excludeUnitID : integer?
excludeUnitDefIDs : number[]?

Returns

: nil

[source]

function CallAsTeam(teamID, func, ...)

Parameters

teamID : integer - Team ID.
func : fun(…) - The function to call.
... : any - Arguments to pass to the function.

Returns

The : any … - return values of the function.

Calls a function from given team’s PoV. In particular this makes callouts obey that team’s visibility rules.

[source]

function CallAsTeam(options, func, ...)

Parameters

options : CallAsTeamOptions - Options.
func : fun(…) - The function to call.
... : any - Arguments to pass to the function.

Returns

The : any … - return values of the function.

[source]

function CallCOBScript(unitID, funcName, retArgs, ...)

Parameters

unitID : integer
funcName : (integer|string)? - Function ID or name.
retArgs : integer - Number of values to return.
... : any - Arguments

Returns

: number …

[source]

function ClearFeaturesPreviousDrawFlag()

[source]

function ClearUnitGoal(unitID)

Parameters

unitID : integer

Returns

: nil

[source]

function ClearUnitsPreviousDrawFlag()

[source]

function ClearWatchDogTimer(threadName)

Parameters

threadName : string? - (Default: main)

Returns

: nil

[source]

function ClosestBuildPos(teamID, unitDefID, posX, posY, posZ, searchRadius, minDistance, buildFacing)

Parameters

teamID : integer
unitDefID : integer
posX : number
posY : number
posZ : number
searchRadius : number
minDistance : number
buildFacing : number - one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3

Returns

buildPosX : number
buildPosY : number
buildPosZ : number

[source]

function CreateDir(path)

Parameters

path : string

Returns

dirCreated : boolean?

[source]

function CreateFeature(featureDef, x, y, z, heading, teamID, featureID)

Parameters

featureDef : (string|integer) - name or id
x : number
y : number
z : number
heading : Heading?
teamID : integer?
featureID : integer?

Returns

featureID : integer? - returns nil if creation was unsuccessful

[source]

function CreateFeatureWreck(featureID, wreckLevel, doSmoke)

Parameters

featureID : integer
wreckLevel : integer? - (Default: `1`) Wreck index to use.
doSmoke : boolean? - (Default: `false`) Wreck emits smoke when `true`.

Returns

featureID : integer? - The wreck featureID, or nil if it couldn't be created or unit doesn't exist.

Create a wreck from a feature

[source]

function CreateGroundDecal()

Returns

decalID : number?

[source]

function CreateUnit(unitDef, posX, posY, posZ, facing, teamID, build, flattenGround, unitID, builderID)

Parameters

unitDef : (string|integer) - UnitDef name or ID.
posX : number
posY : number
posZ : number
facing : Facing
teamID : integer
build : boolean? - (Default: `false`) The unit is created in "being built" state with zero `buildProgress`.
flattenGround : boolean? - (Default: `true`) The unit flattens ground, if it normally does so.
unitID : integer? - Request a specific unitID.
builderID : integer?

Returns

unitID : integer? - The ID of the created unit, or `nil` if the unit could not be created.

[source]

(See: )

function CreateUnitWreck(unitID, wreckLevel, doSmoke)

Parameters

unitID : integer
wreckLevel : integer? - (Default: `1`) Wreck index to use.
doSmoke : boolean? - (Default: `true`) Wreck emits smoke when `true`.

Returns

featureID : integer? - The wreck featureID, or nil if it couldn't be created or unit doesn't exist.

Create a wreck from a unit

[source]

function DeleteProjectile(projectileID)

Parameters

projectileID : integer

Returns

: nil

Silently removes projectiles (no explosion).

[source]

function DeselectUnit(unitID)

Parameters

unitID : integer

Returns

: nil

[source]

function DeselectUnitArray(unitIDs)

Parameters

unitIDs : integer[] - Table with unit IDs as values.

Returns

: nil

Deselects multiple units.

[source]

function DeselectUnitMap(unitMap)

Parameters

unitMap : table<integer,any> - Table with unit IDs as keys.

Returns

: nil

Deselects multiple units.

[source]

function DestroyFeature(featureID)

Parameters

featureID : integer

Returns

: nil

[source]

function DestroyGroundDecal(decalID)

Parameters

decalID : integer

Returns

delSuccess : boolean

[source]

function DestroyUnit(unitID, selfd, reclaimed, attackerID, cleanupImmediately)

Parameters

unitID : integer
selfd : boolean? - (Default: `false`) makes the unit act like it self-destructed.
reclaimed : boolean? - (Default: `false`) don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
attackerID : integer?
cleanupImmediately : boolean? - (Default: `false`) stronger version of reclaimed, removes the unit unconditionally and makes its ID available for immediate reuse (otherwise it takes a few frames)

Returns

: nil

[source]

(See: )

function DiffTimers(endTimer, startTimer, returnMs, fromMicroSecs)

Parameters

endTimer : integer
startTimer : integer
returnMs : boolean? - (Default: `false`) whether to return `timeAmount` in milliseconds as opposed to seconds
fromMicroSecs : boolean? - (Default: `false`) whether timers are in microseconds instead of milliseconds

Returns

timeAmount : number

[source]

function DrawUnitCommands(unitID)

Parameters

unitID : integer

[source]

function DrawUnitCommands(unitIDs, tableOrArray)

Parameters

unitIDs : integer[] - Unit ids.
tableOrArray : false? - Set to `true` if the unit IDs should be read from the keys of `unitIDs`.

[source]

function DrawUnitCommands(unitIDs, tableOrArray)

Parameters

unitIDs : table<integer,any> - Table with unit IDs as keys.
tableOrArray : true - Set to `false` if the unit IDs should be read from the values of `unitIDs`.

Returns

: nil

[source]

function Echo(arg, ...)

Parameters

arg : any
... : any

Returns

: nil

Prints values in the spring chat console. Useful for debugging.

Hint: the default print() writes to STDOUT.

[source]

function EditUnitCmdDesc(unitID, cmdDescID, cmdArray)

Parameters

unitID : integer
cmdDescID : integer
cmdArray : CommandDescription

[source]

function ExtractModArchiveFile(modfile)

Parameters

modfile : string

Returns

extracted : boolean

[source]

function FindUnitCmdDesc(unitID)

Parameters

unitID : integer

[source]

function FixedAllies()

Returns

enabled : boolean?

[source]

function ForceLayoutUpdate()

Returns

: nil

[source]

function ForceTesselationUpdate(normal, shadow)

Parameters

normal : boolean? - (Default: `true`)
shadow : boolean? - (Default: `false`)

Returns

updated : boolean

[source]

function ForceUnitCollisionUpdate(unitID)

Parameters

unitID : integer

Returns

: nil

Prevent collision checks from working on outdated data

There’s a rare edge case that requires units to be in specific positions and being shot by specific weapons but which can result in shots ghosting through the unit. This is because the unit’s collision volume is stale. The movement.unitQuadPositionUpdateRate modrule controls this behaviour and can guarantee 100% correctness if set to 1, but the default value is 3 and large-scale games generally don’t want to set it so low. This function lets you guarantee success for important weapons regardless of how high the normal update rate is set.

[source]

function FreeUnitIcon(iconName)

Parameters

iconName : string

Returns

freed : boolean?

[source]

function GameOver(winningAllyTeamIDs)

Parameters

winningAllyTeamIDs : integer[] - A list of winning ally team IDs. Pass multiple winners to declare a draw. Pass no arguments if undecided (e.g. when dropped from the host).

Returns

Number : integer - of accepted (valid) ally teams.

Declare game over.

[source]

function GarbageCollectCtrl(itersPerBatch, numStepsPerIter, minStepsPerIter, maxStepsPerIter, minLoopRunTime, maxLoopRunTime, baseRunTimeMult, baseMemLoadMult)

Parameters

itersPerBatch : integer?
numStepsPerIter : integer?
minStepsPerIter : integer?
maxStepsPerIter : integer?
minLoopRunTime : number?
maxLoopRunTime : number?
baseRunTimeMult : number?
baseMemLoadMult : number?

Returns

: nil

[source]

function GetActionHotKeys(actionName)

Parameters

actionName : string

Returns

hotkeys : string[]?

[source]

function GetActiveCmdDesc(cmdIndex)

Parameters

cmdIndex : integer

Returns

: CommandDescription?

[source]

function GetActiveCmdDescs()

Returns

cmdDescs : CommandDescription[]

[source]

function GetActiveCommand()

Returns

cmdIndex : number?
cmdID : integer?
cmdType : number?
cmdName : string?

[source]

function GetActivePage()

Returns

activePage : number
maxPage : number

[source]

function GetAIInfo(teamID)

Parameters

teamID : integer

Returns

skirmishAIID : integer
name : string
hostingPlayerID : integer
shortName : string - When synced `"SYNCED_NOSHORTNAME"`, otherwise the AI shortname or `"UNKNOWN"`.
version : string - When synced `"SYNCED_NOVERSION"`, otherwise the AI version or `"UNKNOWN"`.
options : table<string,string>

[source]

function GetAllFeatures()

Returns

featureIDs : integer[]

[source]

function GetAllGroundDecals()

Returns

decalIDs : number[]

[source]

function GetAllUnits()

Returns

unitIDs : number[]

Get a list of all unitIDs

[source]

Note that when called from a widget, this also returns units that are only radar blips.

For units that are radar blips, you may want to check if they are in los, as GetUnitDefID() will still return true if they have previously been seen.

(See: )

function GetAllyTeamInfo(allyTeamID)

Parameters

allyTeamID : integer

Returns

: table<string,string>?

[source]

function GetAllyTeamList()

Returns

allyTeamIDs : integer[]

[source]

function GetAllyTeamStartBox(allyID)

Parameters

allyID : integer

Returns

xMin : number?
zMin : number?
xMax : number?
zMax : number?

[source]

function GetBoxSelectionByEngine()

Returns

isHandledByEngine : boolean - `true` if the engine will select units inside selection box on release, otherwise `false`.

Get if selection box is handled by engine.

[source]

(See: )

function GetBuildFacing()

Returns

buildFacing : FacingInteger

[source]

function GetBuildSpacing()

Returns

buildSpacing : number

[source]

function GetCameraDirection()

Returns

dirX : number
dirY : number
dirZ : number

[source]

function GetCameraFOV()

Returns

vFOV : number
hFOV : number

[source]

function GetCameraNames()

Returns

indexByName : table<string,integer> - Table where where keys are names and values are indices.

Get available cameras.

[source]

function GetCameraPosition()

Returns

posX : number
posY : number
posZ : number

[source]

function GetCameraRotation()

Returns

rotX : number - Rotation around X axis in radians.
rotY : number - Rotation around Y axis in radians.
rotZ : number - Rotation around Z axis in radians.

Get camera rotation in radians.

[source]

function GetCameraState(useTable)

Parameters

useTable : false

Returns

name : CameraName
depends : any … - on the current controller mode.

[source]

function GetCameraState(useTable)

Parameters

useTable : true? - (Default: `true`) Return a table instead of multiple values.

Returns

cameraState : CameraState

[source]

function GetCameraVectors()

Returns

: CameraVectors

[source]

function GetCEGID()

[source]

function GetClipboard()

Returns

text : string

[source]

function GetCmdDescIndex(cmdID)

Parameters

cmdID : integer

Returns

cmdDescIndex : integer?

[source]

function GetCOBScriptID(unitID, funcName)

Parameters

unitID : integer
funcName : string

Returns

funcID : integer?

[source]

function GetCommandQueue(unitID, count)

Parameters

unitID : integer
count : integer - Number of commands to return, `-1` returns all commands, `0` returns command count.

Returns

commands : Command[]

DEPRECATED: Use Spring.GetUnitCommands instead.

Get the commands for a unit.

[source]

Same as Spring.GetUnitCommands

function GetCommandQueue(unitID, count)

Parameters

unitID : integer
count : 0 - Returns the number of commands in the units queue.

Returns

cmdCount : integer - The number of commands in the unit queue.

DEPRECATED: Use Spring.GetUnitCommandCount instead.

Get the count of commands for a unit.

[source]

Same as Spring.GetUnitCommands

function GetConfigFloat(name, default)

Parameters

name : string
default : number? - (Default: `0`)

Returns

configFloat : number?

[source]

function GetConfigInt(name, default)

Parameters

name : string
default : number? - (Default: `0`)

Returns

configInt : number?

[source]

function GetConfigParams()

Returns

: Configuration[]

[source]

function GetConfigString(name, default)

Parameters

name : string
default : string? - (Default: `""`)

Returns

configString : number?

[source]

function GetConsoleBuffer(maxLines)

Parameters

maxLines : number

Returns

buffer : { priority: integer, text: string }[]

[source]

function GetCurrentTooltip()

Returns

tooltip : string

[source]

function GetDefaultCommand()

Returns

cmdIndex : integer?
cmdID : integer?
cmdType : integer?
cmdName : string?

[source]

function GetDrawFrame()

Returns

low_16bit : number
high_16bit : number

[source]

function GetDrawSeconds()

Returns

time : integer - Time in seconds.

[source]

function GetDrawSelectionInfo()

Returns

: boolean

[source]

function GetDualViewGeometry()

Returns

dualViewSizeX : number - in px
dualViewSizeY : number - in px
dualViewPosX : number - offset from leftmost screen left border in px
dualViewPosY : number - offset from bottommost screen bottom border in px

Get dual view geometry (minimap when enabled)

[source]

function GetFacingFromHeading(heading)

Parameters

heading : number

Returns

facing : FacingInteger

[source]

function GetFactoryBuggerOff(unitID)

Parameters

unitID : integer

[source]

function GetFactoryCommandCount(unitID)

Parameters

unitID : integer

Returns

The : integer - number of commands in the factory queue.

Get the number of commands in a factory queue.

[source]

(See: )

function GetFactoryCommands(unitID, count)

Parameters

unitID : integer
count : integer - Maximum amount of commands to return, `-1` returns all commands.

Returns

commands : Command[]

Get the number or list of commands for a factory

[source]

(See: )

function GetFactoryCommands(unitID, count)

Parameters

unitID : integer
count : 0 - Returns the number of commands in the factory queue.

Returns

The : integer - number of commands in the factory queue.

DEPRECATED: This overload is deprecated, use `Spring.GetFactoryCommandCount(unitId)` instead.

Get the count of commands for a factory.

[source]

(See: )

function GetFactoryCounts(unitID, count, addCmds)

Parameters

unitID : integer
count : integer? - (Default: `-1`) Number of commands to retrieve, `-1` for all.
addCmds : boolean? - (Default: `false`) Retrieve commands other than buildunit

Returns

counts : table<number,number>? - Build queue count by `unitDefID` or `-cmdID`, or `nil` if unit is not found.

Gets the build queue of a factory

[source]

function GetFeatureAllyTeam(featureID)

Parameters

featureID : integer

Returns

: number?

[source]

function GetFeatureAlwaysUpdateMatrix(featureID)

Parameters

featureID : integer

Returns

nil : boolean? - when featureID cannot be parsed

[source]

function GetFeatureBlocking(featureID)

Parameters

featureID : integer

Returns

isBlocking : boolean?
isSolidObjectCollidable : boolean?
isProjectileCollidable : boolean?
isRaySegmentCollidable : boolean?
crushable : boolean?
blockEnemyPushing : boolean?
blockHeightChanges : boolean?

[source]

function GetFeatureCollisionVolumeData(featureID)

Parameters

featureID : integer

Returns

: CollisionVolumeData?

[source]

function GetFeatureDefID(featureID)

Parameters

featureID : integer

Returns

: number?

[source]

function GetFeatureDirection(featureID)

Parameters

featureID : integer

Returns

frontDirX : number?
frontDirY : number?
frontDirZ : number?
rightDirX : number?
rightDirY : number?
rightDirZ : number?
upDirX : number?
upDirY : number?
upDirZ : number?

[source]

function GetFeatureDrawFlag(featureID)

Parameters

featureID : integer

Returns

nil : number? - when featureID cannot be parsed

[source]

function GetFeatureEngineDrawMask(featureID)

Parameters

featureID : integer

Returns

nil : boolean? - when featureID cannot be parsed

[source]

function GetFeatureFireTime(featureID)

Parameters

featureID : integer

Returns

fireTime : number? - in seconds, nil when featureID is invalid.

Get the feature current fire timer.

[source]

function GetFeatureHeading(featureID)

Parameters

featureID : integer

[source]

function GetFeatureHealth(featureID)

Parameters

featureID : integer

Returns

health : number?
defHealth : number
resurrectProgress : number

[source]

function GetFeatureHeight(featureID)

Parameters

featureID : integer

Returns

: number?

[source]

function GetFeatureLastAttackedPiece(featureID)

Parameters

featureID : integer

Returns

Last : (string|"")? - hit piece name
frame : integer? - it was last hit on, nil when featureID is not valid

[source]

function GetFeatureLuaDraw(featureID)

Parameters

featureID : integer

Returns

nil : boolean? - when featureID cannot be parsed

[source]

function GetFeatureMass(featureID)

Parameters

featureID : integer

Returns

: number?

[source]

function GetFeatureNoDraw(featureID)

Parameters

featureID : integer

Returns

nil : boolean? - when featureID cannot be parsed

[source]

function GetFeatureNoSelect(featureID)

Parameters

featureID : integer

Returns

: boolean?

[source]

function GetFeaturePieceCollisionVolumeData(featureID)

Parameters

featureID : integer

Returns

: CollisionVolumeData?

[source]

function GetFeaturePieceDirection(featureID, pieceIndex)

Parameters

featureID : integer
pieceIndex : integer

Returns

dirX : number?
dirY : number
dirZ : number

[source]

function GetFeaturePieceInfo(featureID, pieceIndex)

Parameters

featureID : integer
pieceIndex : integer

Returns

pieceInfo : PieceInfo?

[source]

function GetFeaturePieceList(featureID)

Parameters

featureID : integer

Returns

pieceNames : string[]

[source]

function GetFeaturePieceMap(featureID)

Parameters

featureID : integer

Returns

pieceInfos : table<string,number> - where keys are piece names and values are indices

[source]

function GetFeaturePieceMatrix(featureID)

Parameters

featureID : integer

Returns

m11 : number?
m12 : number
m13 : number
m14 : number
m21 : number
m22 : number
m23 : number
m24 : number
m31 : number
m32 : number
m33 : number
m34 : number
m41 : number
m42 : number
m43 : number
m44 : number

[source]

function GetFeaturePiecePosDir(featureID, pieceIndex)

Parameters

featureID : integer
pieceIndex : integer

Returns

posX : number?
posY : number
posZ : number
dirX : number
dirY : number
dirZ : number

[source]

function GetFeaturePiecePosition(featureID, pieceIndex)

Parameters

featureID : integer
pieceIndex : integer

Returns

posX : number?
posY : number
posZ : number

[source]

function GetFeaturePosition(featureID)

Parameters

featureID : integer

Returns

x : number?
y : number?
z : number?

[source]

function GetFeatureRadius(featureID)

Parameters

featureID : integer

Returns

: number?

[source]

function GetFeatureResources(featureID)

Parameters

featureID : integer

Returns

metal : number?
defMetal : number
energy : number
defEnergy : number
reclaimLeft : number
reclaimTime : number

[source]

function GetFeatureResurrect(featureID)

Parameters

featureID : integer

Returns

featureDefName : (string|"")?
buildFacing : FacingInteger - facing of footprint, 0 - 3

[source]

Returns nil if no feature found with ID.

function GetFeatureRootPiece(featureID)

Parameters

featureID : integer

Returns

index : number - of the root piece

[source]

function GetFeatureRotation(featureID)

Parameters

featureID : integer

Returns

pitch : number? - Rotation in X axis
yaw : number? - Rotation in Y axis
roll : number? - Rotation in Z axis

[source]

Note: PYR order

function GetFeatureRulesParam(featureID, ruleRef)

Parameters

featureID : integer
ruleRef : (number|string) - the rule index or name

Returns

value : (number|string)?

[source]

function GetFeatureRulesParams(featureID)

Parameters

featureID : integer

Returns

rulesParams : RulesParams - map with rules names as key and values as values

[source]

function GetFeatureSelectionVolumeData(featureID)

Parameters

featureID : integer

Returns

scaleX : number? - nil when unitID cannot be parsed
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
volumeType : number
useContHitTest : number
getPrimaryAxis : number
ignoreHits : boolean

[source]

function GetFeatureSeparation(featureID1, featureID2, direction)

Parameters

featureID1 : number
featureID2 : number
direction : boolean? - (Default: `false`) to subtract from, default featureID1 - featureID2

Returns

: number?

[source]

function GetFeaturesInCylinder(x, z, radius, allegiance)

Parameters

x : number
z : number
radius : number
allegiance : number?

Returns

featureIDs : number[]

[source]

function GetFeaturesInRectangle(xmin, zmin, xmax, zmax)

Parameters

xmin : number
zmin : number
xmax : number
zmax : number

Returns

featureIDs : number[]

[source]

function GetFeaturesInScreenRectangle(left, top, right, bottom)

Parameters

left : number
top : number
right : number
bottom : number

Returns

featureIDs : number[]?

Get features inside a rectangle area on the map

[source]

function GetFeaturesInSphere(x, y, z, radius)

Parameters

x : number
y : number
z : number
radius : number

Returns

featureIDs : number[]

[source]

function GetFeatureSmokeTime(featureID)

Parameters

featureID : integer

Returns

smokeTime : number? - in seconds, nil when featureID is invalid.

Get the feature current smoke timer.

[source]

function GetFeatureTeam(featureID)

Parameters

featureID : integer

Returns

: number?

[source]

function GetFeatureTransformMatrix(featureID)

Parameters

featureID : integer

Returns

m11 : number? - nil when featureID cannot be parsed
m12 : number
m13 : number
m14 : number
m21 : number
m22 : number
m23 : number
m24 : number
m31 : number
m32 : number
m33 : number
m34 : number
m41 : number
m42 : number
m43 : number
m44 : number

[source]

function GetFeatureVelocity(featureID)

Parameters

featureID : integer

Returns

x : number?
y : number?
z : number?
w : number?

[source]

Returns nil if no feature found with ID.

function GetFPS()

Returns

fps : number

[source]

function GetFrameTimeOffset()

Returns

offset : number? - of the current draw frame from the last sim frame, expressed in fractions of a frame

[source]

Ideally, when running 30hz sim, and 60hz rendering, the draw frames should have and offset of either 0.0 frames, or 0.5 frames.

When draw frames are not integer multiples of sim frames, some interpolation happens, and this timeoffset shows how far along it is.

function GetFrameTimer(lastFrameTime)

Parameters

lastFrameTime : boolean? - (Default: `false`) whether to use last frame time instead of last frame start

Returns

: integer

Get a timer for the start of the frame

[source]

This should give better results for camera interpolations

function GetFullBuildQueue(unitID)

Parameters

unitID : integer

Returns

buildqueue : table<number,number>? - indexed by unitDefID with count values

Returns the build queue

[source]

function GetGaiaTeamID()

Returns

teamID : integer

[source]

function GetGameFrame()

Returns

t1 : number - frameNum % dayFrames
t2 : number - frameNum / dayFrames

[source]

function GetGameName()

Returns

name : string

[source]

function GetGameRulesParam(ruleRef)

Parameters

ruleRef : (number|string) - the rule index or name

Returns

: number? - |string value

[source]

function GetGameRulesParams()

Returns

rulesParams : RulesParams - map with rules names as key and values as values

[source]

function GetGameSeconds()

Returns

seconds : number

[source]

function GetGameSpeed()

Returns

wantedSpeedFactor : number
speedFactor : number
paused : boolean

[source]

function GetGameState(maxLatency)

Parameters

maxLatency : number? - (Default: `500`) used for `isSimLagging` return parameter

Returns

doneLoading : boolean
isSavedGame : boolean
isClientPaused : boolean
isSimLagging : boolean

[source]

function GetGatherMode()

Returns

gatherMode : number

[source]

function GetGlobalLos(teamID)

Parameters

teamID : integer?

Returns

enabled : boolean

[source]

function GetGrass(x, z)

Parameters

x : number
z : number

Returns

: number

[source]

function GetGroundBlocked()

[source]

function GetGroundDecalAlpha(decalID)

Parameters

decalID : integer

Returns

alpha : number? - Between 0 and 1
alphaFalloff : number - Between 0 and 1, per second

[source]

function GetGroundDecalCreationFrame(decalID)

Parameters

decalID : integer

Returns

creationFrameMin : number?
creationFrameMax : number

[source]

Min can be not equal to max for “gradient” style decals, e.g. unit tracks

function GetGroundDecalMiddlePos(decalID)

Parameters

decalID : integer

Returns

posX : number?
posZ : number

[source]

function GetGroundDecalMisc(decalID)

Parameters

decalID : integer

Returns

dotElimExp : number?
refHeight : number
minHeight : number
maxHeight : number
forceHeightMode : number

[source]

Returns less important parameters of a ground decal

function GetGroundDecalNormal(decalID)

Parameters

decalID : integer

Returns

normal.x : number?
normal.y : number
normal.z : number

[source]

If all three equal 0, the decal follows the normals of ground at midpoint

function GetGroundDecalOwner(decalID)

Parameters

decalID : integer

Returns

value : integer? - If owner is a unit, then this is `unitID`, if owner is a feature it is `featureID + MAX_UNITS`. If there is no owner, then `nil`.

[source]

function GetGroundDecalQuadPos(decalID)

Parameters

decalID : integer

Returns

posTL.x : number?
posTL.z : number
posTR.x : number
posTR.z : number
posBR.x : number
posBR.z : number
posBL.x : number
posBL.z : number

[source]

function GetGroundDecalRotation(decalID)

Parameters

decalID : integer

Returns

rotation : number? - Rotation in radians.

[source]

function GetGroundDecalSizeAndHeight(decalID)

Parameters

decalID : integer

Returns

sizeX : number?
sizeY : number
projCubeHeight : number

[source]

function GetGroundDecalTexture(decalID, isMainTex)

Parameters

decalID : integer
isMainTex : boolean? - (Default: `true`) If `false`, return the normal/glow map.

Returns

texture : string?

[source]

function GetGroundDecalTextures(isMainTex, addFilenames)

Parameters

isMainTex : boolean? - (Default: `nil`). If `nil` - no filtering is done, if `false` - return normal/glow textures, if `true` - return main color textures.
addFilenames : boolean? - (Default: `false`). If `true` add the texture filenames in the second table

Returns

textureNames : string[] - All textures on the atlas and available for use in `SetGroundDecalTexture`.

[source]

(See: )

function GetGroundDecalTint(decalID)

Parameters

decalID : integer

Returns

tintR : number?
tintG : number
tintB : number
tintA : number

[source]

Gets the tint of the ground decal. A color of (0.5, 0.5, 0.5, 0.5) is effectively no tint

function GetGroundDecalType(decalID)

Parameters

decalID : integer

Returns

type : (“explosion”|“plate”|“lua”|“track”|“unknown”)?

[source]

function GetGroundExtremes()

Returns

initMinHeight : number
initMaxHeight : number
currMinHeight : number
currMaxHeight : number

[source]

function GetGroundHeight(x, z)

Parameters

x : number
z : number

Returns

: number

Get ground height

On sea, this returns the negative depth of the seafloor

[source]

function GetGroundInfo(x, z)

Parameters

x : number
z : number

Returns

ix : number
iz : number
terrainTypeIndex : number
name : string
metalExtraction : number
hardness : number
tankSpeed : number
kbotSpeed : number
hoverSpeed : number
shipSpeed : number
receiveTracks : boolean

[source]

function GetGroundNormal(x, z, smoothed)

Parameters

x : number
z : number
smoothed : boolean? - (Default: `false`) raw or smoothed center normal

Returns

normalX : number
normalY : number
normalZ : number
slope : number

[source]

function GetGroundOrigHeight(x, z)

Parameters

x : number
z : number

Returns

: number

Get ground height as it was at game start

Returns the original height before the ground got deformed

[source]

function GetGroupList()

Returns

where : table<number,number>? - keys are groupIDs and values are counts

[source]

function GetGroupUnits(groupID)

Parameters

groupID : integer

Returns

unitIDs : number[]?

[source]

function GetGroupUnitsCount(groupID)

Parameters

groupID : integer

Returns

groupSize : number?

[source]

function GetGroupUnitsCounts(groupID)

Parameters

groupID : integer

Returns

where : table<number,number>? - keys are unitDefIDs and values are counts

[source]

function GetGroupUnitsSorted(groupID)

Parameters

groupID : integer

Returns

where : table<number,number[]>? - keys are unitDefIDs and values are unitIDs

[source]

function GetHeadingFromFacing(facing)

Parameters

facing : FacingInteger

Returns

heading : number

[source]

function GetHeadingFromVector(x, z)

Parameters

x : number
z : number

Returns

heading : number

[source]

function GetInvertQueueKey()

Returns

queueKey : number?

[source]

function GetKeyBindings(keySet1, keySet2)

Parameters

keySet1 : string? - filters keybindings bound to this keyset
keySet2 : string? - OR bound to this keyset

Returns

: KeyBinding[]

[source]

function GetKeyCode(keySym)

Parameters

keySym : string

Returns

keyCode : number

[source]

function GetKeyFromScanSymbol(scanSymbol)

Parameters

scanSymbol : string

Returns

keyName : string

[source]

function GetKeyState(keyCode)

Parameters

keyCode : number

Returns

pressed : boolean

[source]

function GetKeySymbol(keyCode)

Parameters

keyCode : number

Returns

keyCodeName : string
keyCodeDefaultName : string - name when there are not aliases

[source]

function GetLastMessagePositions()

Returns

message : xyz[] - positions

[source]

function GetLastUpdateSeconds()

Returns

lastUpdateSeconds : number?

[source]

function GetLocalAllyTeamID()

Returns

allyTeamID : integer

[source]

function GetLocalPlayerID()

Returns

playerID : integer

[source]

function GetLocalTeamID()

Returns

teamID : integer

[source]

function GetLogSections()

Returns

sections : table<string,number> - where keys are names and loglevel are values. E.g. `{ "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }`

[source]

function GetLosViewColors()

Returns

always : rgb
LOS : rgb
radar : rgb
jam : rgb
radar2 : rgb

[source]

function GetLuaMemUsage()

Returns

luaHandleAllocedMem : number - in kilobytes
luaHandleNumAllocs : number - divided by 1000
luaGlobalAllocedMem : number - in kilobytes
luaGlobalNumAllocs : number - divided by 1000
luaUnsyncedGlobalAllocedMem : number - in kilobytes
luaUnsyncedGlobalNumAllocs : number - divided by 1000
luaSyncedGlobalAllocedMem : number - in kilobytes
luaSyncedGlobalNumAllocs : number - divided by 1000

[source]

function GetMapDrawMode()

Returns

: (“normal”|“height”|“metal”|“pathTraversability”|“los”)

[source]

function GetMapOption(mapOption)

Parameters

mapOption : string

Returns

value : string - Value of `modOption`.

[source]

function GetMapOptions()

Returns

mapOptions : table<string,string> - Table with options names as keys and values as values.

[source]

function GetMapSquareTexture(texSquareX, texSquareY, lodMin, luaTexName, lodMax)

Parameters

texSquareX : number
texSquareY : number
lodMin : number
luaTexName : string
lodMax : number? - (Default: lodMin)

Returns

success : boolean?

[source]

function GetMapStartPositions()

Returns

array : float3[] - of positions indexed by teamID

[source]

function GetMenuName()

Returns

name : string - name .. version from Modinfo.lua. E.g. "Spring: 1944 test-5640-ac2d15b".

[source]

function GetMetalAmount(x, z)

Parameters

x : integer - X coordinate in worldspace / `Game.metalMapSquareSize`.
z : integer - Z coordinate in worldspace / `Game.metalMapSquareSize`.

Returns

amount : number

Returns the amount of metal on a single square.

[source]

function GetMetalExtraction(x, z)

Parameters

x : integer - X coordinate in worldspace / `Game.metalMapSquareSize`.
z : integer - Z coordinate in worldspace / `Game.metalMapSquareSize`.

Returns

extraction : number

[source]

function GetMetalMapSize()

Returns

x : integer - X coordinate in worldspace / `Game.metalMapSquareSize`.
z : integer - Z coordinate in worldspace / `Game.metalMapSquareSize`.

[source]

function GetMiniMapDualScreen()

Returns

position : (“left”|“right”|false) - `"left"` or `"right"` when dual screen is enabled, otherwise `false`.

[source]

function GetMiniMapGeometry()

Returns

minimapPosX : number - in px
minimapPosY : number - in px
minimapSizeX : number - in px
minimapSizeY : number - in px
minimized : boolean
maximized : boolean

Get minimap geometry

[source]

function GetMiniMapRotation()

Returns

amount : number - in radians

Get minimap rotation

[source]

function GetModelPieceList(modelName)

Parameters

modelName : string

Returns

pieceNames : string[]?

[source]

function GetModelPieceMap(modelName)

Parameters

modelName : string

Returns

pieceInfos : table<string,number>? - where keys are piece names and values are indices

[source]

function GetModelRootPiece(modelName)

Parameters

modelName : string

Returns

index : number - of the root piece

[source]

function GetModKeyState()

Returns

alt : boolean
ctrl : boolean
meta : boolean
shift : boolean

[source]

function GetModOption(modOption)

Parameters

modOption : string

Returns

value : string - Value of `modOption`.

[source]

function GetModOptions()

Returns

modOptions : table<string,string> - Table with options names as keys and values as values.

[source]

function GetMouseButtonsPressed(button1, ...)

Parameters

button1 : integer - Index of the first button.
... : integer - Indices for more buttons.

Returns

Pressed : boolean … - status for the buttons.

[source]

Get pressed status for specific buttons.

function GetMouseCursor()

Returns

cursorName : string
cursorScale : number

[source]

function GetMouseStartPosition(button)

Parameters

button : number

Returns

x : number
y : number
camPosX : number
camPosY : number
camPosZ : number
dirX : number
dirY : number
dirZ : number

[source]

function GetMouseState()

Returns

x : number
y : number
lmbPressed : number - left mouse button pressed
mmbPressed : number - middle mouse button pressed
rmbPressed : number - right mouse button pressed
offscreen : boolean
mmbScroll : boolean

[source]

function GetNanoProjectileParams()

Returns

rotVal : number - in degrees
rotVel : number - in degrees
rotAcc : number - in degrees
rotValRng : number - in degrees
rotVelRng : number - in degrees
rotAccRng : number - in degrees

[source]

function GetNumDisplays()

Returns

numDisplays : number - as returned by `SDL_GetNumVideoDisplays`

[source]

function GetPieceProjectileParams(projectileID)

Parameters

projectileID : integer

Returns

explosionFlags : number? - encoded bitwise with SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
spinAngle : number
spinSpeed : number
spinVectorX : number
spinVectorY : number
spinVectorZ : number

[source]

function GetPixelDir(x, y)

Parameters

x : number
y : number

Returns

dirX : number
dirY : number
dirZ : number

[source]

function GetPlayerControlledUnit(playerID)

Parameters

playerID : integer

Returns

: number?

Returns unit controlled by player on FPS mode

[source]

function GetPlayerInfo(playerID, getPlayerOpts)

Parameters

playerID : integer
getPlayerOpts : boolean? - (Default: `true`) whether to return custom player options

Returns

name : string
active : boolean
spectator : boolean
teamID : integer
allyTeamID : integer
pingTime : number
cpuUsage : number
country : string
rank : number
hasSkirmishAIsInTeam : boolean
playerOpts : { [string]: string } - when playerOpts is true
desynced : boolean

[source]

function GetPlayerList(teamID, active)

Parameters

teamID : integer? - (Default: `-1`) to filter by when >= 0
active : boolean? - (Default: `false`) whether to filter only active teams

Returns

list : number[]? - of playerIDs

[source]

function GetPlayerRoster(sortType, showPathingPlayers)

Parameters

sortType : number? - return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5
showPathingPlayers : boolean? - (Default: `false`)

Returns

playerTable : Roster[]?

[source]

function GetPlayerRulesParam(playerID, ruleRef)

Parameters

playerID : integer
ruleRef : (number|string) - the rule index or name

Returns

value : (number|string)?

[source]

function GetPlayerRulesParams(playerID)

Parameters

playerID : integer

Returns

rulesParams : RulesParams - map with rules names as key and values as values

[source]

function GetPlayerStatistics(playerID)

Parameters

playerID : integer

Returns

mousePixels : number? - nil when invalid playerID
mouseClicks : number
keyPresses : number
numCommands : number
unitCommands : number

[source]

function GetPlayerTraffic(playerID, packetID)

Parameters

playerID : integer
packetID : integer?

Returns

traffic : number

[source]

function GetPositionLosState(posX, posY, posZ, allyTeamID)

Parameters

posX : number
posY : number
posZ : number
allyTeamID : integer?

Returns

inLosOrRadar : boolean
inLos : boolean
inRadar : boolean
inJammer : boolean

[source]

function GetPressedKeys()

Returns

where : table<(number|string),true> - keys are keyCodes or key names

[source]

function GetPressedScans()

Returns

where : table<(number|string),true> - keys are scanCodes or scan names

[source]

function GetProfilerRecordNames()

Returns

profilerNames : string[]

[source]

function GetProfilerTimeRecord(profilerName, frameData)

Parameters

profilerName : string
frameData : boolean? - (Default: `false`)

Returns

total : number - in ms
current : number - in ms
max_dt : number
time_pct : number
peak_pct : number
frameData : table<number,number>? - Table where key is the frame index and value is duration.

[source]

function GetProjectileAllyTeamID(projectileID)

Parameters

projectileID : integer

Returns

: number?

[source]

function GetProjectileDamages(projectileID, tag)

Parameters

projectileID : integer
tag : string - one of: "paralyzeDamageTime" "impulseFactor" "impulseBoost" "craterMult" "craterBoost" "dynDamageExp" "dynDamageMin" "dynDamageRange" "dynDamageInverted" "craterAreaOfEffect" "damageAreaOfEffect" "edgeEffectiveness" "explosionSpeed" - or - an armor type index to get the damage against it.

Returns

: number?

[source]

function GetProjectileDefID(projectileID)

Parameters

projectileID : integer

Returns

: number?

[source]

Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

function GetProjectileDirection(projectileID)

Parameters

projectileID : integer

Returns

dirX : number?
dirY : number?
dirZ : number?

[source]

function GetProjectileGravity(projectileID)

Parameters

projectileID : integer

Returns

: number?

[source]

function GetProjectileIsIntercepted(projectileID)

Parameters

projectileID : integer

Returns

: boolean?

[source]

function GetProjectileOwnerID(projectileID)

Parameters

projectileID : integer

Returns

: number?

[source]

function GetProjectilePosition(projectileID)

Parameters

projectileID : integer

Returns

posX : number?
posY : number?
posZ : number?

[source]

function GetProjectilesInRectangle(xmin, zmin, xmax, zmax, excludeWeaponProjectiles, excludePieceProjectiles)

Parameters

xmin : number
zmin : number
xmax : number
zmax : number
excludeWeaponProjectiles : boolean? - (Default: `false`)
excludePieceProjectiles : boolean? - (Default: `false`)

Returns

projectileIDs : number[]

[source]

function GetProjectilesInSphere(x, y, z, radius, excludeWeaponProjectiles, excludePieceProjectiles)

Parameters

x : number
y : number
z : number
radius : number
excludeWeaponProjectiles : boolean? - (Default: false)
excludePieceProjectiles : boolean? - (Default: false)

Returns

projectileIDs : number[]

[source]

function GetProjectileTarget(projectileID)

Parameters

projectileID : integer

Returns

targetTypeInt : number? - where string.byte('g') := GROUND string.byte('u') := UNIT string.byte('f') := FEATURE string.byte('p') := PROJECTILE
target : (number|float3) - targetID or targetPos when targetTypeInt == string.byte('g')

[source]

function GetProjectileTeamID(projectileID)

Parameters

projectileID : integer

Returns

: number?

[source]

function GetProjectileTimeToLive(projectileID)

Parameters

projectileID : integer

Returns

: number?

[source]

function GetProjectileType(projectileID)

Parameters

projectileID : integer

Returns

weapon : boolean?
piece : boolean

[source]

function GetProjectileVelocity(projectileID)

Parameters

projectileID : integer

Returns

velX : number?
velY : number?
velZ : number?
velW : number?

[source]

function GetRadarErrorParams(allyTeamID)

Parameters

allyTeamID : integer

Returns

radarErrorSize : number? - actual radar error size (when allyTeamID is allied to current team) or base radar error size
baseRadarErrorSize : number
baseRadarErrorMult : number

[source]

function GetRealBuildQueue(unitID)

Parameters

unitID : integer

Returns

buildqueue : table<number,number>? - indexed by unitDefID with count values

Returns the build queue cleaned of things the unit can’t build itself

[source]

function GetRenderFeatures(drawMask, sendMask)

Parameters

drawMask : DrawMask - (Default: `0`) Filter objects by their draw flags.
sendMask : true - Whether to send objects draw flags as second return

Returns

featureIDs : integer[]
drawFlags : DrawFlag[]

[source]

function GetRenderFeatures(drawMask, sendMask)

Parameters

drawMask : DrawMask - (Default: `0`) Filter objects by their draw flags.
sendMask : false? - Whether to send objects draw flags as second return

Returns

featureIDs : integer[]

[source]

function GetRenderFeaturesDrawFlagChanged(sendMask)

Parameters

sendMask : true - Whether to send objects draw flags as second return.

Returns

ids : integer[]
unitDrawFlags : DrawFlag[]

[source]

Gets a list of IDs of features that have had their draw flags changed, and the corresponding flags.

function GetRenderFeaturesDrawFlagChanged(sendMask)

Parameters

sendMask : false? - Whether to send objects draw flags as second return.

Returns

ids : integer[]

[source]

Gets a list of IDs of features that have had their draw flags changed, and the corresponding flags.

function GetRenderUnits(drawMask, sendMask)

Parameters

drawMask : DrawMask - (Default: `0`) Filter objects by their draw flags.
sendMask : true - Whether to send objects draw flags as second return

Returns

featureIDs : integer[]
drawFlags : DrawFlag[]

[source]

function GetRenderUnits(drawMask, sendMask)

Parameters

drawMask : DrawMask - (Default: `0`) Filter objects by their draw flags.
sendMask : false? - Whether to send objects draw flags as second return

Returns

featureIDs : integer[]

[source]

function GetRenderUnitsDrawFlagChanged(sendMask)

Parameters

sendMask : true - Whether to send objects draw flags as second return.

Returns

ids : integer[]
unitDrawFlags : DrawFlag[]

[source]

Gets a list of IDs of units that have had their draw flags changed, and the corresponding flags.

function GetRenderUnitsDrawFlagChanged(sendMask)

Parameters

sendMask : false? - Whether to send objects draw flags as second return.

Returns

ids : integer[]

[source]

Gets a list of IDs of units that have had their draw flags changed, and the corresponding flags.

function GetReplayLength()

Returns

timeInSeconds : number?

[source]

function GetScanSymbol(scanCode)

Parameters

scanCode : number

Returns

scanCodeName : string
scanCodeDefaultName : string - name when there are not aliases

[source]

function GetScreenGeometry(displayIndex, queryUsable)

Parameters

displayIndex : number? - (Default: `-1`)
queryUsable : boolean? - (Default: `false`)

Returns

screenSizeX : number - in px
screenSizeY : number - in px
screenPosX : number - in px
screenPosY : number - in px
windowBorderTop : number - in px
windowBorderLeft : number - in px
windowBorderBottom : number - in px
windowBorderRight : number - in px
screenUsableSizeX : number? - in px
screenUsableSizeY : number? - in px
screenUsablePosX : number? - in px
screenUsablePosY : number? - in px

Get screen geometry

[source]

function GetSelectedGroup()

Returns

groupID : integer

[source]

function GetSelectedUnits()

Returns

unitIDs : number[]

[source]

function GetSelectedUnitsCount()

Returns

selectedUnitsCount : number

Returns the amount of selected units

[source]

function GetSelectedUnitsCounts()

Returns

unitsCounts : table<number,number> - where keys are unitDefIDs and values are counts
the : integer - number of unitDefIDs

Get an aggregate count of selected units per unitDefID

[source]

function GetSelectedUnitsSorted()

Returns

where : table<number,number[]> - keys are unitDefIDs and values are unitIDs
the : integer - number of unitDefIDs

Get selected units aggregated by unitDefID

[source]

function GetSelectionBox()

Returns

left : number?
top : number?
right : number?
bottom : number?

Get vertices from currently active selection box

[source]

Returns nil when selection box is inactive

(See: )

function GetSideData(sideName)

Parameters

sideName : string - Case-insensitive side name.

Returns

startUnit : string?
caseName : string? - Original case side name.

[source]

function GetSideData(sideID)

Parameters

sideID : integer

Returns

sideName : string? - Lowercase side name.
startUnit : string?
caseName : string? - Original case side name.

[source]

function GetSideData()

Returns

sideArray : SideSpec[]

[source]

function GetSmoothMeshHeight(x, z)

Parameters

x : number
z : number

Returns

height : number

[source]

function GetSoundDevices()

Returns

devices : SoundDeviceSpec[] - Sound devices.

[source]

function GetSoundEffectParams()

[source]

function GetSoundStreamTime()

Returns

playTime : number
time : number

[source]

function GetSpectatingState()

Returns

spectating : boolean
spectatingFullView : boolean
spectatingFullSelect : boolean

[source]

function GetSyncedGCInfo(collectGC)

Parameters

collectGC : boolean? - (Default: `false`) collect before returning metric

Returns

GC : number? - values are expressed in Kbytes: #bytes/2^10

[source]

function GetTeamAllyTeamID(teamID)

Parameters

teamID : integer

Returns

allyTeamID : integer?

[source]

function GetTeamColor(teamID)

Parameters

teamID : integer

Returns

r : number? - factor from 0 to 1
g : number? - factor from 0 to 1
b : number? - factor from 0 to 1
a : number? - factor from 0 to 1

[source]

function GetTeamDamageStats(teamID)

Parameters

teamID : integer

Returns

damageDealt : number
damageReceived : number

Gets team damage dealt/received totals

[source]

Returns a team’s damage stats. Note that all damage is counted, including self-inflicted and unconfirmed out-of-sight.

function GetTeamInfo(teamID, getTeamKeys)

Parameters

teamID : integer
getTeamKeys : boolean? - (Default: `true`) whether to return the customTeamKeys table

Returns

teamID : integer?
leader : number
isDead : number
hasAI : number
side : string
allyTeam : number
incomeMultiplier : number
customTeamKeys : table<string,string> - when getTeamKeys is true, otherwise nil

[source]

function GetTeamList(allyTeamID)

Parameters

allyTeamID : unknown - (Default: `-1`)

Returns

teamIDs : number[] - List of team IDs.

Get all team IDs.

[source]

function GetTeamList(allyTeamID)

Parameters

allyTeamID : integer - The ally team ID to filter teams by. A value less than 0 will return all teams.

Returns

teamIDs : number[]? - List of team IDs or `nil` if `allyTeamID` is invalid.

Get team IDs in a specific ally team.

[source]

function GetTeamLuaAI(teamID)

Parameters

teamID : integer

Returns

: string

[source]

function GetTeamMaxUnits(teamID)

Parameters

teamID : integer

Returns

maxUnits : number
currentUnits : number?

Returns a team’s unit cap.

Also returns the current unit count for readable teams as the 2nd value.

[source]

function GetTeamOrigColor(teamID)

Parameters

teamID : integer

Returns

r : number? - factor from 0 to 1
g : number? - factor from 0 to 1
b : number? - factor from 0 to 1
a : number? - factor from 0 to 1

[source]

function GetTeamResources(teamID, resource)

Parameters

teamID : integer
resource : ResourceName

Returns

currentLevel : number?
storage : number
pull : number
income : number
expense : number
share : number
sent : number
received : number
excess : number

[source]

function GetTeamResourceStats(teamID, resource)

Parameters

teamID : integer
resource : ResourceName

Returns

used : number?
produced : number
excessed : number
received : number
sent : number

[source]

function GetTeamRulesParam(teamID, ruleRef)

Parameters

teamID : integer
ruleRef : (number|string) - the rule index or name

Returns

value : (number|string)?

[source]

function GetTeamRulesParams(teamID)

Parameters

teamID : integer

Returns

rulesParams : RulesParams - map with rules names as key and values as values

[source]

function GetTeamStartPosition(teamID)

Parameters

teamID : integer

Returns

x : number?
y : number?
x : number?

[source]

function GetTeamStatsHistory(teamID)

Parameters

teamID : integer

Returns

historyCount : integer? - The number of history entries, or `nil` if unable to resolve team.

Get the number of history entries.

[source]

function GetTeamStatsHistory(teamID, startIndex, endIndex)

Parameters

teamID : integer
startIndex : integer
endIndex : integer? - (Default: startIndex)

Returns

The : TeamStats[] - team stats history, or `nil` if unable to resolve team.

Get team stats history.

[source]

function GetTeamUnitCount(teamID)

Parameters

teamID : integer

Returns

count : number?

[source]

function GetTeamUnitDefCount(teamID, unitDefID)

Parameters

teamID : integer
unitDefID : integer

Returns

count : number?

[source]

function GetTeamUnits(teamID)

Parameters

teamID : integer

Returns

unitIDs : number[]?

[source]

function GetTeamUnitsByDefs(teamID, unitDefIDs)

Parameters

teamID : integer
unitDefIDs : (number|number[])

Returns

unitIDs : number[]?

[source]

function GetTeamUnitsCounts(teamID)

Parameters

teamID : integer

Returns

countByUnit : table<number,number>? - A table where keys are unitDefIDs and values are counts.

[source]

function GetTeamUnitsSorted(teamID)

Parameters

teamID : integer

Returns

unitsByDef : table<integer,integer> - A table where keys are unitDefIDs and values are unitIDs

[source]

function GetTeamUnitStats(teamID)

Parameters

teamID : integer

Returns

killed : number?
died : number
capturedBy : number
capturedFrom : number
received : number
sent : number

[source]

function GetTerrainTypeData(terrainTypeInfo)

Parameters

terrainTypeInfo : number

Returns

index : number
name : string
hardness : number
tankSpeed : number
kbotSpeed : number
hoverSpeed : number
shipSpeed : number
receiveTracks : boolean

[source]

function GetTidal()

Returns

tidalStrength : number

[source]

function GetTimer()

Returns

: integer

Get a timer with millisecond resolution

[source]

function GetTimerMicros()

Returns

: integer

Get a timer with microsecond resolution

[source]

function GetUnitAllyTeam(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

function GetUnitAlwaysUpdateMatrix(unitID)

Parameters

unitID : integer

Returns

nil : boolean? - when unitID cannot be parsed

[source]

function GetUnitArmored(unitID)

Parameters

unitID : integer

Returns

armored : boolean?
armorMultiple : number

[source]

function GetUnitArrayCentroid(units)

Parameters

units : table - { unitID, unitID, ... }

Returns

centerX : number
centerY : number
centerZ : number

Returns the centroid of an array of units

Returns nil for an empty array

[source]

function GetUnitBasePosition(unitID)

Parameters

unitID : integer

Returns

posX : number?
posY : number?
posZ : number?

[source]

The same as Spring.GetUnitPosition, but without the optional midpoint calculations.

(See: )

function GetUnitBlocking(unitID)

Parameters

unitID : integer

Returns

isBlocking : boolean?
isSolidObjectCollidable : boolean
isProjectileCollidable : boolean
isRaySegmentCollidable : boolean
crushable : boolean
blockEnemyPushing : boolean
blockHeightChanges : boolean

[source]

function GetUnitBuildeeRadius(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

Gets the unit’s radius for when targeted by build, repair, reclaim-type commands.

function GetUnitBuildFacing(unitID)

Parameters

unitID : integer

[source]

function GetUnitBuildParams(unitID)

Parameters

unitID : integer

[source]

function GetUnitCmdDescs(unitID)

Parameters

unitID : integer

[source]

function GetUnitCollisionVolumeData(unitID)

Parameters

unitID : integer

[source]

function GetUnitCommandCount(unitID)

Parameters

unitID : integer

Returns

The : integer - number of commands in the unit's queue.

Get the number of commands in a unit’s queue.

[source]

function GetUnitCommands(unitID, count)

Parameters

unitID : integer
count : integer - Maximum amount of commands to return, `-1` returns all commands.

Returns

commands : Command[]

Get the commands for a unit.

[source]

Same as Spring.GetCommandQueue

function GetUnitCommands(unitID, count)

Parameters

unitID : integer
count : 0 - Returns the number of commands in the units queue.

Returns

The : integer - number of commands in the unit queue.

DEPRECATED: This overload is deprecated, use `Spring.GetUnitCommandCount(unitId)` instead.

Get the count of commands for a unit.

[source]

function GetUnitCosts(unitID)

Parameters

unitID : integer

Returns

buildTime : number?
metalCost : number
energyCost : number

[source]

function GetUnitCostTable(unitID)

Parameters

unitID : integer

Returns

cost : ResourceCost? - The cost of the unit, or `nil` if invalid.
buildTime : number? - The build time the unit, or `nil` if invalid.

[source]

function GetUnitCurrentBuildPower(unitID)

Parameters

unitID : integer

[source]

function GetUnitCurrentCommand(unitID, cmdIndex)

Parameters

unitID : integer - unitID when invalid this function returns nil.
cmdIndex : integer? - (Default: `0`) Command index to get. If negative will count from the end of the queue, e.g. -1 will be the last command.

Returns

cmdID : CMD?
options : (integer|CommandOptionBit)?
tag : integer?
Command : number? … - parameters.

Get a command from a units command queue.

For factories, this function uses the command queue automatically assigned to new units.

[source]

(See: )

function GetUnitDefDimensions(unitDefID)

Parameters

unitDefID : integer

Returns

dimensions : UnitDefDimensions?

[source]

function GetUnitDefID(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

function GetUnitDirection(unitID)

Parameters

unitID : integer

Returns

frontDirX : number
frontDirY : number
frontDirZ : number
rightDirX : number
rightDirY : number
rightDirZ : number
upDirX : number
upDirY : number
upDirZ : number

[source]

function GetUnitDrawFlag(unitID)

Parameters

unitID : integer

Returns

nil : number? - when unitID cannot be parsed

[source]

function GetUnitEffectiveBuildRange(unitID, buildeeDefID)

Parameters

unitID : integer
buildeeDefID : integer - or nil

Returns

effectiveBuildRange : number - counted to the center of prospective buildee; buildRange if buildee nil

[source]

Useful for setting move goals manually.

function GetUnitEngineDrawMask(unitID)

Parameters

unitID : integer

Returns

nil : boolean? - when unitID cannot be parsed

[source]

function GetUnitEstimatedPath(unitID)

Parameters

unitID : integer

[source]

function GetUnitExperience(unitID)

Parameters

unitID : integer

Returns

xp : number - [0.0; +∞)
limXp : number - [0.0; 1.0) as experience approaches infinity

[source]

function GetUnitFeatureSeparation(unitID)

Parameters

unitID : integer

[source]

function GetUnitFlanking(unitID)

Parameters

unitID : integer

[source]

function GetUnitGroup(unitID)

Parameters

unitID : integer

Returns

groupID : integer?

[source]

function GetUnitHarvestStorage(unitID)

Parameters

unitID : integer

Returns

storedMetal : number
maxStoredMetal : number
storedEnergy : number
maxStoredEnergy : number

Get a unit’s carried resources

[source]

Checks resources being carried internally by the unit.

function GetUnitHeading(unitID, convertToRadians)

Parameters

unitID : integer
convertToRadians : boolean? - (Default: `false`)

Returns

heading : number

[source]

function GetUnitHealth(unitID)

Parameters

unitID : integer

Returns

health : number?
maxHealth : number
paralyzeDamage : number
captureProgress : number
buildProgress : number - between 0.0-1.0

[source]

function GetUnitHeight(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

function GetUnitInBuildStance(unitID)

Parameters

unitID : integer

Returns

inBuildStance : boolean

Is builder in build stance

[source]

Checks if a builder is in build stance, i.e. can create nanoframes. Returns nil for non-builders.

function GetUnitIsActive(unitID)

Parameters

unitID : integer

Returns

isActive : boolean?

[source]

function GetUnitIsBeingBuilt(unitID)

Parameters

unitID : integer

Returns

beingBuilt : boolean
buildProgress : number

[source]

function GetUnitIsBuilding(unitID)

Parameters

unitID : integer

Returns

buildeeUnitID : integer - or nil

Checks whether a unit is currently building another (NOT for checking if it’s a structure)

[source]

Works for both mobile builders and factories.

function GetUnitIsCloaked(unitID)

Parameters

unitID : integer

Returns

isCloaked : boolean?

[source]

function GetUnitIsDead(unitID)

Parameters

unitID : integer

Returns

: boolean?

[source]

function GetUnitIsStunned(unitID)

Parameters

unitID : integer

Returns

stunnedOrBuilt : boolean? - unit is disabled
stunned : boolean - unit is either stunned via EMP or being transported by a non-fireplatform
beingBuilt : boolean - unit is under construction

Checks whether a unit is disabled and can’t act

The first return value is a simple OR of the following ones, any of those conditions is sufficient to disable the unit.

Note that EMP and being transported are mechanically the same and thus lumped together. Use other callouts to differentiate them if you need to.

[source]

function GetUnitIsTransporting(unitID)

Parameters

unitID : integer

Returns

transporteeArray : integer[]?

Get units being transported

[source]

function GetUnitLastAttackedPiece(unitID)

Parameters

unitID : integer

[source]

function GetUnitLastAttacker(unitID)

Parameters

unitID : integer

[source]

function GetUnitLeavesGhost()

Returns

: number?

Get whether unit leaves static radar ghosts.

[source]

function GetUnitLosState(unitID, allyTeamID, raw)

Parameters

unitID : integer
allyTeamID : integer?
raw : true - Return a bitmask.

Returns

bitmask : (LosMask|integer)? - A bitmask of `LosMask` bits

Get unit los state (bitmask)

[source]

function GetUnitLosState(unitID, allyTeamID, raw)

Parameters

unitID : integer
allyTeamID : integer?
raw : false? - Return a table.

Returns

los : table<(“los”|“radar”…),boolean>? - A table of LOS state names as keys and booleans as values, or `nil` if `unitID` is invalid.

Get unit los state (table)

[source]

function GetUnitLuaDraw(unitID)

Parameters

unitID : integer

Returns

draw : boolean? - nil when unitID cannot be parsed

[source]

function GetUnitMapCentroid(units)

Parameters

units : table - { [unitID] = true, [unitID] = true, ... }

Returns

centerX : number
centerY : number
centerZ : number

Returns the centroid of a map of units

Returns nil for an empty map

[source]

function GetUnitMass(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

function GetUnitMaxRange(unitID)

Parameters

unitID : integer

Returns

maxRange : number

Get a unit’s engagement range

[source]

Returns the range at which a unit will stop to engage. By default this is the highest among the unit’s weapon ranges (hence name), but can be changed dynamically. Also note that unarmed units ignore this.

function GetUnitMetalExtraction(unitID)

Parameters

unitID : integer

Returns

metalExtraction : number?

[source]

function GetUnitMoveTypeData(unitID)

Parameters

unitID : integer

[source]

function GetUnitNanoPieces(unitID)

Parameters

unitID : integer

Returns

pieceArray : integer[]

Get construction FX attachment points

[source]

Returns an array of pieces which represent construction points. Default engine construction FX (nano spray) will originate there.

Only works on builders and factories, returns nil (NOT empty table) for other units.

function GetUnitNearestAlly(unitID, range)

Parameters

unitID : integer
range : number? - (Default: `1.0e9`)

Returns

unitID : integer?

[source]

function GetUnitNearestEnemy(unitID, range, useLOS)

Parameters

unitID : integer
range : number? - (Default: `1.0e9`)
useLOS : boolean? - (Default: `true`)

Returns

unitID : integer?

[source]

function GetUnitNeutral(unitID)

Parameters

unitID : integer

Returns

: boolean?

Checks if a unit is neutral (NOT Gaia!)

[source]

Note that a “neutral” unit can belong to any ally-team (ally, enemy, Gaia). To check if a unit is Gaia, check its owner team.

function GetUnitNoDraw(unitID)

Parameters

unitID : integer

Returns

nil : boolean? - when unitID cannot be parsed

[source]

function GetUnitNoGroup(unitID)

Parameters

unitID : integer

Returns

noGroup : boolean? - `true` if the unit is not allowed to be added to a group, `false` if it is allowed to be added to a group, or `nil` when `unitID` is not valid.

Check if a unit is not allowed to be added to a group by a player.

[source]

function GetUnitNoMinimap(unitID)

Parameters

unitID : integer

Returns

nil : boolean? - when unitID cannot be parsed

[source]

function GetUnitNoSelect(unitID)

Parameters

unitID : integer

Returns

noSelect : boolean? - `nil` when `unitID` cannot be parsed.

[source]

function GetUnitPhysicalState(unitID)

Parameters

unitID : integer

Returns

Unit : number - 's PhysicalState bitmask

[source]

function GetUnitPieceDirection(unitID, pieceIndex)

Parameters

unitID : integer
pieceIndex : integer

Returns

dirX : number?
dirY : number
dirZ : number

[source]

function GetUnitPieceInfo(unitID, pieceIndex)

Parameters

unitID : integer
pieceIndex : integer

Returns

pieceInfo : PieceInfo?

[source]

function GetUnitPieceList(unitID)

Parameters

unitID : integer

Returns

pieceNames : string[]

[source]

function GetUnitPieceMap(unitID)

Parameters

unitID : integer

Returns

pieceInfos : table<string,number>? - where keys are piece names and values are indices

[source]

function GetUnitPieceMatrix(unitID)

Parameters

unitID : integer

Returns

m11 : number?
m12 : number
m13 : number
m14 : number
m21 : number
m22 : number
m23 : number
m24 : number
m31 : number
m32 : number
m33 : number
m34 : number
m41 : number
m42 : number
m43 : number
m44 : number

[source]

function GetUnitPiecePosDir(unitID, pieceIndex)

Parameters

unitID : integer
pieceIndex : integer

Returns

posX : number?
posY : number
posZ : number
dirX : number
dirY : number
dirZ : number

[source]

function GetUnitPiecePosition(unitID, pieceIndex)

Parameters

unitID : integer
pieceIndex : integer

Returns

posX : number?
posY : number
posZ : number

[source]

function GetUnitPosErrorParams(unitID, allyTeamID)

Parameters

unitID : integer
allyTeamID : integer?

Returns

posErrorVectorX : number?
posErrorVectorY : number
posErrorVectorZ : number
posErrorDeltaX : number
posErrorDeltaY : number
posErrorDeltaZ : number
nextPosErrorUpdatebaseErrorMult : number
posErrorBit : boolean

[source]

function GetUnitPosition(unitID, midPos, aimPos)

Parameters

unitID : integer
midPos : boolean? - (Default: `false`) return midpoint as well
aimPos : boolean? - (Default: `false`) return aimpoint as well

Returns

basePointX : number?
basePointY : number
basePointZ : number
midPointX : number?
midPointY : number
midPointZ : number
aimPointX : number?
aimPointY : number
aimPointZ : number

[source]

function GetUnitRadius(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

function GetUnitResources(unitID)

Parameters

unitID : integer

Returns

metalMake : number?
metalUse : number
energyMake : number
energyUse : number

[source]

function GetUnitRootPiece(unitID)

Parameters

unitID : integer

Returns

index : number - of the root piece

[source]

function GetUnitRotation(unitID)

Parameters

unitID : integer

Returns

pitch : number - Rotation in X axis
yaw : number - Rotation in Y axis
roll : number - Rotation in Z axis

[source]

Note: PYR order

function GetUnitRulesParam(unitID, ruleRef)

Parameters

unitID : integer
ruleRef : (number|string) - the rule index or name

Returns

value : (number|string)?

[source]

function GetUnitRulesParams(unitID)

Parameters

unitID : integer

Returns

rulesParams : RulesParams - map with rules names as key and values as values

[source]

function GetUnitScriptNames(unitID)

Parameters

unitID : integer

Returns

where : table<string,number> - keys are piece names and values are piece indices

[source]

function GetUnitScriptPiece(unitID)

Parameters

unitID : integer

Returns

pieceIndices : integer[]

[source]

function GetUnitScriptPiece(unitID, scriptPiece)

Parameters

unitID : integer
scriptPiece : integer

Returns

pieceIndex : integer

[source]

function GetUnitSeismicSignature(unitID)

Parameters

unitID : integer

Returns

seismicSignature : number?

[source]

function GetUnitSelectionVolumeData(unitID)

Parameters

unitID : integer

Returns

scaleX : number? - nil when unitID cannot be parsed
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
volumeType : number
useContHitTest : number
getPrimaryAxis : number
ignoreHits : boolean

[source]

function GetUnitSelfDTime(unitID)

Parameters

unitID : integer

Returns

selfDTime : integer?

[source]

function GetUnitSensorRadius(unitID, type)

Parameters

unitID : integer
type : string - one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer

Returns

radius : number?

[source]

function GetUnitSeparation(unitID1, unitID2, direction, subtractRadii)

Parameters

unitID1 : number
unitID2 : number
direction : boolean? - (Default: `false`) to subtract from, default unitID1 - unitID2
subtractRadii : boolean? - (Default: `false`) whether units radii should be subtracted from the total

Returns

: number?

[source]

function GetUnitShieldState(unitID, weaponNum)

Parameters

unitID : integer
weaponNum : number? - Optional if the unit has just one shield

Returns

isEnabled : number - Warning, number not boolean. 0 or 1
currentPower : number

[source]

function GetUnitsInBox(xmin, ymin, zmin, xmax, ymax, zmax, allegiance)

Parameters

xmin : number
ymin : number
zmin : number
xmax : number
ymax : number
zmax : number
allegiance : number?

Returns

unitIDs : number[]

[source]

function GetUnitsInCylinder(x, z, radius)

Parameters

x : number
z : number
radius : number

Returns

unitIDs : number[]

[source]

function GetUnitsInPlanes(planes, allegiance)

Parameters

planes : Plane[]
allegiance : integer?

Returns

unitIDs : integer[]

[source]

Plane normals point towards accepted space, so the acceptance criteria for each plane is:

radius     = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)]  <=  0

function GetUnitsInRectangle(xmin, zmin, xmax, zmax, allegiance)

Parameters

xmin : number
zmin : number
xmax : number
zmax : number
allegiance : number?

Returns

unitIDs : number[]

[source]

function GetUnitsInScreenRectangle(left, top, right, bottom, allegiance)

Parameters

left : number
top : number
right : number
bottom : number
allegiance : number? - (Default: `-1`) teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4

Returns

unitIDs : number[]?

Get units inside a rectangle area on the map

[source]

function GetUnitsInSphere(x, y, z, radius)

Parameters

x : number
y : number
z : number
radius : number

Returns

unitIDs : number[]

[source]

function GetUnitStates(unitID)

Parameters

unitID : integer

Returns

: UnitState

[source]

function GetUnitStockpile(unitID)

Parameters

unitID : integer

Returns

numStockpiled : integer?
numStockpileQued : integer?
buildPercent : number?

[source]

function GetUnitStorage(unitID)

Parameters

unitID : integer

Returns

Unit : number - 's metal storage
Unit : number - 's energy storage

[source]

function GetUnitTeam(unitID)

Parameters

unitID : integer

Returns

: number?

[source]

function GetUnitTooltip(unitID)

Parameters

unitID : integer

Returns

: string?

[source]

function GetUnitTransformMatrix(unitID)

Parameters

unitID : integer

Returns

m11 : number? - nil when unitID cannot be parsed
m12 : number
m13 : number
m14 : number
m21 : number
m22 : number
m23 : number
m24 : number
m31 : number
m32 : number
m33 : number
m34 : number
m41 : number
m42 : number
m43 : number
m44 : number

[source]

function GetUnitTransporter(unitID)

Parameters

unitID : integer

Returns

transportUnitID : integer?

Get the transport carrying the unit

[source]

Returns the unit ID of the transport, if any. Returns nil if the unit is not being transported.

function GetUnitVectors(unitID)

Parameters

unitID : integer

Returns

front : float3?
up : float3
right : float3

[source]

function GetUnitVelocity(unitID)

Parameters

unitID : integer

[source]

function GetUnitViewPosition(unitID, midPos)

Parameters

unitID : integer
midPos : boolean? - (Default: `false`)

Returns

x : number? - nil when unitID cannot be parsed
y : number
z : number

[source]

function GetUnitWeaponCanFire(unitID)

Parameters

unitID : integer

[source]

function GetUnitWeaponDamages(unitID)

Parameters

unitID : integer

[source]

function GetUnitWeaponHaveFreeLineOfFire(unitID)

Parameters

unitID : integer

[source]

function GetUnitWeaponState(unitID, weaponNum, stateName)

Parameters

unitID : integer
weaponNum : number
stateName : string

Returns

stateValue : number

Check the state of a unit’s weapon

[source]

Available states to poll: “reloadFrame” (frame on which the weapon will be ready to fire), “reloadSpeed” (reload time in seconds), “range” (in elmos), “autoTargetRangeBoost” (predictive aiming range buffer, in elmos), “projectileSpeed” (in elmos/frame), “reloadTimeXP” (reload time after XP bonus, in seconds), “reaimTime” (frames between AimWeapon calls), “burst” (shots in a burst), “burstRate” (delay between shots in a burst, in seconds), “projectiles” (projectiles per shot), “salvoLeft” (shots remaining in ongoing burst), “nextSalvo” (simframe of the next shot in an ongoing burst), “accuracy” (INaccuracy after XP bonus), “sprayAngle” (spray angle after XP bonus), “targetMoveError” (extra inaccuracy against moving targets, after XP bonus) “avoidFlags” (bitmask for targeting avoidance), “ttl” (number of seconds a projectile should live) “collisionFlags” (bitmask for collisions).

The state “salvoError” is an exception and returns a table: {x, y, z}, which represents the inaccuracy error of the ongoing burst.

function GetUnitWeaponTarget(unitID, weaponNum)

Parameters

unitID : integer
weaponNum : integer

Returns

TargetType : 0 - none
isUserTarget : boolean

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

function GetUnitWeaponTarget(unitID, weaponNum)

Parameters

unitID : integer
weaponNum : integer

Returns

TargetType : 1 - unit
isUserTarget : boolean
targetUnitID : integer

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

function GetUnitWeaponTarget(unitID, weaponNum)

Parameters

unitID : integer
weaponNum : integer

Returns

TargetType : 2 - position
isUserTarget : boolean
targetPosition : float3

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

function GetUnitWeaponTarget(unitID, weaponNum)

Parameters

unitID : integer
weaponNum : integer

Returns

TargetType : 3 - projectileID
isUserTarget : boolean
targetProjectileId : integer

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

function GetUnitWeaponTestRange(unitID)

Parameters

unitID : integer

[source]

function GetUnitWeaponTestTarget(unitID)

Parameters

unitID : integer

[source]

function GetUnitWeaponTryTarget(unitID)

Parameters

unitID : integer

[source]

function GetUnitWeaponVectors(unitID)

Parameters

unitID : integer

[source]

function GetUnitWorkerTask(unitID)

Parameters

unitID : integer

Returns

cmdID : integer - of the relevant command
targetID : integer - if applicable (all except RESTORE)

Checks a builder’s current task

[source]

Checks what a builder is currently doing. This is not the same as Spring.GetUnitCurrentCommand, because you can have a command at the front of the queue and not be doing it (for example because the target is still too far away), and on the other hand you can also be doing a task despite not having it in front of the queue (for example you’re Guarding another builder who does). Also, it resolves the Repair command into either actual repair, or construction assist (in which case it returns the appropriate “build” command). Only build-related commands are returned (no Move or any custom commands).

The possible commands returned are repair, reclaim, resurrect, capture, restore, and build commands (negative buildee unitDefID).

function GetVectorFromHeading(heading)

Parameters

heading : number

Returns

x : number
z : number

[source]

function GetVideoCapturingMode()

Returns

allowRecord : boolean

[source]

function GetVidMemUsage()

Returns

usedMem : number - in MB
availableMem : number - in MB

[source]

function GetViewGeometry()

Returns

viewSizeX : number - in px
viewSizeY : number - in px
viewPosX : number - offset from leftmost screen left border in px
viewPosY : number - offset from bottommost screen bottom border in px

Get main view geometry (map and game rendering)

[source]

function GetVisibleFeatures(teamID, radius, icons, geos)

Parameters

teamID : integer? - (Default: `-1`)
radius : number? - (Default: `30`)
icons : boolean? - (Default: `true`)
geos : boolean? - (Default: `true`)

Returns

featureIDs : number[]?

[source]

function GetVisibleProjectiles(allyTeamID, addSyncedProjectiles, addWeaponProjectiles, addPieceProjectiles)

Parameters

allyTeamID : integer? - (Default: `-1`)
addSyncedProjectiles : boolean? - (Default: `true`)
addWeaponProjectiles : boolean? - (Default: `true`)
addPieceProjectiles : boolean? - (Default: `true`)

Returns

projectileIDs : number[]?

[source]

function GetVisibleUnits(teamID, radius, icons)

Parameters

teamID : integer? - (Default: `-1`)
radius : number? - (Default: `30`)
icons : boolean? - (Default: `true`)

Returns

unitIDs : number[]?

[source]

function GetWaterLevel(x, z)

Parameters

x : number
z : number

Returns

waterLevel : number

Get water level in a specific position

Water is currently a flat plane, so this returns the same value regardless of XZ. However water may become more dynamic at some point so by using this you are future-proof.

[source]

function GetWaterMode()

Returns

waterRendererID : integer
waterRendererName : string

[source]

(See: )

function GetWaterPlaneLevel()

Returns

waterPlaneLevel : number

Get water plane height

Water may at some point become shaped (rivers etc) but for now it is always a flat plane. Use this function instead of GetWaterLevel to denote you are relying on that assumption.

[source]

(See: )

function GetWind()

Returns

windSpeedX : number
windSpeedY : number - (Always 0)
windSpeedZ : number
windStrength : number - (Length of windSpeed)
windDirX : number - (Normalized windSpeed)
windDirY : number - (Always 0)
windDirZ : number

[source]

function GetWindowDisplayMode()

Returns

width : number - in px
height : number - in px
bits : number - per pixel
refresh : number - rate in Hz

Get main window display mode

[source]

function GetWindowGeometry()

Returns

winSizeX : number - in px
winSizeY : number - in px
winPosX : number - in px
winPosY : number - in px
windowBorderTop : number - in px
windowBorderLeft : number - in px
windowBorderBottom : number - in px
windowBorderRight : number - in px

Get main window geometry

[source]

function GiveOrder(cmdID, params, options, timeout)

Parameters

cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

: boolean

Give order to selected units.

[source]

function GiveOrderArrayToUnit(unitID, commands)

Parameters

unitID : integer - Unit ID.
commands : CreateCommand[]

Returns

ordersGiven : boolean - `true` if any orders were sent, otherwise `false`.

[source]

function GiveOrderArrayToUnit(unitID, commands)

Parameters

unitID : integer
commands : CreateCommand[]

Returns

ordersGiven : boolean

[source]

function GiveOrderArrayToUnitArray(unitIDs, commands, pairwise)

Parameters

unitIDs : integer[] - Array of unit IDs.
commands : CreateCommand[]
pairwise : boolean? - (Default: `false`) When `false`, assign all commands to each unit. When `true`, assign commands according to index between units and cmds arrays. If `len(unitArray) < len(cmdArray)` only the first `len(unitArray)` commands will be assigned, and vice-versa.

Returns

ordersGiven : boolean - `true` if any orders were sent, otherwise `false`.

[source]

function GiveOrderArrayToUnitArray(unitIDs, commands, pairwise)

Parameters

unitIDs : integer[] - Array of unit IDs.
commands : CreateCommand[]
pairwise : boolean? - (Default: `false`) When `false`, assign all commands to each unit. When `true`, assign commands according to index between units and cmds arrays. If `len(unitArray) < len(cmdArray)` only the first `len(unitArray)` commands will be assigned, and vice-versa.

Returns

unitsOrdered : integer - The number of units ordered.

[source]

function GiveOrderArrayToUnitMap(unitMap, commands)

Parameters

unitMap : table<integer,any> - A table with unit IDs as keys.
commands : CreateCommand[]

Returns

ordersGiven : boolean - `true` if any orders were sent, otherwise `false`.

[source]

function GiveOrderArrayToUnitMap(unitMap, commands)

Parameters

unitMap : table<integer,any> - A table with unit IDs as keys.
commands : CreateCommand[]

Returns

unitsOrdered : integer - The number of units ordered.

[source]

function GiveOrderToUnit(unitID, cmdID, params, options, timeout)

Parameters

unitID : integer
cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams? - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

: boolean

Give order to specific unit.

[source]

function GiveOrderToUnit(unitID, cmdID, params, options, timeout)

Parameters

unitID : integer
cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams? - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

unitOrdered : boolean

[source]

function GiveOrderToUnitArray(unitIDs, cmdID, params, options, timeout)

Parameters

unitIDs : integer[] - Array of unit IDs.
cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams? - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

ordersGiven : boolean - `true` if any orders were sent, otherwise `false`.

Give order to an array of units.

[source]

function GiveOrderToUnitArray(unitIDs, cmdID, params, options, timeout)

Parameters

unitIDs : integer[] - An array of unit IDs.
cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams? - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

unitsOrdered : integer - The number of units ordered.

[source]

function GiveOrderToUnitMap(unitMap, cmdID, params, options, timeout)

Parameters

unitMap : table<integer,any> - A table with unit IDs as keys.
cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams? - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

orderGiven : boolean

Give order to multiple units, specified by table keys.

[source]

function GiveOrderToUnitMap(unitMap, cmdID, params, options, timeout)

Parameters

unitMap : table<integer,any> - A table with unit IDs as keys.
cmdID : (CMD|integer) - The command ID.
params : CreateCommandParams? - Parameters for the given command.
options : CreateCommandOptions?
timeout : integer? - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Returns

unitsOrdered : integer - The number of units ordered.

Give order to multiple units, specified by table keys.

[source]

function HaveAdvShading()

Returns

useAdvShading : boolean
groundUseAdvShading : boolean

[source]

function HaveShadows()

Returns

shadowsLoaded : boolean

[source]

function InsertUnitCmdDesc(unitID, index, cmdDesc)

Parameters

unitID : integer
index : integer
cmdDesc : CommandDescription

Insert a command description at a specific index.

[source]

function InsertUnitCmdDesc(unitID, cmdDesc)

Parameters

unitID : integer
cmdDesc : CommandDescription

Insert a command description at the last position.

[source]

function IsAABBInView(minX, minY, minZ, maxX, maxY, maxZ)

Parameters

minX : number
minY : number
minZ : number
maxX : number
maxY : number
maxZ : number

Returns

inView : boolean

[source]

function IsAboveMiniMap(x, y)

Parameters

x : number
y : number

Returns

isAbove : boolean

[source]

function IsCheatingEnabled()

Returns

enabled : boolean

[source]

function IsDevLuaEnabled()

Returns

enabled : boolean

[source]

function IsEditDefsEnabled()

Returns

enabled : boolean

[source]

function IsGameOver()

Returns

isGameOver : boolean

[source]

function IsGodModeEnabled()

Returns

enabled : boolean

[source]

function IsGUIHidden()

Returns

: boolean

[source]

function IsNoCostEnabled()

Returns

enabled : boolean

[source]

function IsPosInAirLos(posX, posY, posZ, allyTeamID)

Parameters

posX : number
posY : number
posZ : number
allyTeamID : integer?

Returns

: boolean

[source]

function IsPosInLos(posX, posY, posZ, allyTeamID)

Parameters

posX : number
posY : number
posZ : number
allyTeamID : integer?

Returns

: boolean

[source]

function IsPosInMap(x, z)

Parameters

x : number
z : number

Returns

inPlayArea : boolean - whether the position is in the active play area
inMap : boolean - whether the position is in the full map area (currently this is the same as above)

[source]

function IsPosInRadar(posX, posY, posZ, allyTeamID)

Parameters

posX : number
posY : number
posZ : number
allyTeamID : integer?

Returns

: boolean

[source]

function IsReplay()

Returns

isReplay : boolean?

[source]

function IsSphereInView(posX, posY, posZ, radius)

Parameters

posX : number
posY : number
posZ : number
radius : number? - (Default: `0`)

Returns

inView : boolean

[source]

function IsUnitAllied(unitID)

Parameters

unitID : integer

Returns

isAllied : boolean? - nil with unitID cannot be parsed

[source]

function IsUnitIcon(unitID)

Parameters

unitID : integer

Returns

isUnitIcon : boolean? - nil when unitID cannot be parsed

[source]

function IsUnitInAirLos(unitID, allyTeamID)

Parameters

unitID : integer
allyTeamID : integer

Returns

inAirLos : boolean

[source]

function IsUnitInJammer(unitID, allyTeamID)

Parameters

unitID : integer
allyTeamID : integer

Returns

inJammer : boolean

[source]

function IsUnitInLos(unitID, allyTeamID)

Parameters

unitID : integer
allyTeamID : integer

Returns

inLos : boolean

[source]

function IsUnitInRadar(unitID, allyTeamID)

Parameters

unitID : integer
allyTeamID : integer

Returns

inRadar : boolean

[source]

function IsUnitInView(unitID)

Parameters

unitID : integer

Returns

inView : boolean? - nil when unitID cannot be parsed

[source]

function IsUnitSelected(unitID)

Parameters

unitID : integer

Returns

isSelected : boolean? - nil when unitID cannot be parsed

[source]

function IsUnitVisible(unitID, radius, checkIcon)

Parameters

unitID : integer
radius : number? - unitRadius when not specified
checkIcon : boolean

Returns

isVisible : boolean? - nil when unitID cannot be parsed

[source]

function IsUserWriting()

Returns

: boolean

[source]

function KillTeam(teamID)

Parameters

teamID : integer

Returns

: nil

Will declare a team to be dead (no further orders can be assigned to such teams units).

[source]

Gaia team cannot be killed.

function LevelHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Set the height of a point in the world.

[source]

function LevelHeightMap(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number?

Returns

: nil

Set the height of a rectangle area in the world.

[source]

function LevelOriginalHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Set the height of a point in the original map height cache.

[source]

function LevelOriginalHeightMap(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number

Set the height of a rectangle area in the original map height cache.

[source]

function LevelSmoothMesh(x, z, height)

Parameters

x : number
z : number
height : number

[source]

function LevelSmoothMesh(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number

[source]

function LoadCmdColorsConfig(config)

Parameters

config : string

Returns

: nil

[source]

function LoadCtrlPanelConfig(config)

Parameters

config : string

Returns

: nil

[source]

function LoadModelTextures(modelName)

Parameters

modelName : string

Returns

success : boolean?

[source]

function LoadSoundDef(soundfile)

Parameters

soundfile : string

Returns

success : boolean

Loads a SoundDefs file, the format is the same as in gamedata/sounds.lua.

[source]

function Log(section, logLevel, ...)

Parameters

section : string - Sets an arbitrary section. Level filtering can be applied per-section
logLevel : (LogLevel|LOG)? - (Default: `"notice"`)
... : string - messages

Logs a message to the logfile/console.

[source]

function MarkerAddLine(x1, y1, z1, x2, y2, z2, localOnly, playerId)

Parameters

x1 : number
y1 : number
z1 : number
x2 : number
y2 : number
z2 : number
localOnly : boolean? - (Default: `false`)
playerId : number?

Returns

: nil

[source]

function MarkerAddPoint(x, y, z, text, localOnly)

Parameters

x : number
y : number
z : number
text : string? - (Default: `""`)
localOnly : boolean?

Returns

: nil

[source]

function MarkerErasePosition(x, y, z, unused, localOnly, playerId, alwaysErase)

Parameters

x : number
y : number
z : number
unused : nil - This argument is ignored.
localOnly : boolean? - (Default: `false`) do not issue a network message, erase only for the current player
playerId : number? - when not specified it uses the issuer playerId
alwaysErase : boolean? - (Default: `false`) erase any marker when `localOnly` and current player is spectating. Allows spectators to erase players markers locally

Returns

: nil

[source]

Issue an erase command for markers on the map.

property MoveCtrl MoveCtrl

[source]

function PauseDollyCamera(fraction)

Parameters

fraction : number - Fraction of the total runtime to pause at, 0 to 1 inclusive. A null value pauses at current percent

Returns

: nil

Pause Dolly Camera

[source]

function PauseSoundStream()

Returns

: nil

Pause any SoundStream currently running.

[source]

function Ping(pingTag)

Parameters

pingTag : number

Returns

: nil

Send a ping request to the server

[source]

function PlaySoundFile(soundfile, volume, posx, posy, posz, speedx, speedy, speedz, channel)

Parameters

soundfile : string
volume : number? - (Default: 1.0)
posx : number?
posy : number?
posz : number?
speedx : number?
speedy : number?
speedz : number?
channel : SoundChannel? - (Default: `0|"general"`)

Returns

playSound : boolean

[source]

function PlaySoundStream(oggfile, volume, enqueue)

Parameters

oggfile : string
volume : number? - (Default: 1.0)
enqueue : boolean?

Returns

success : boolean

Allows to play an Ogg Vorbis (.OGG) and mp3 compressed sound file.

[source]

Multiple sound streams may be played at once.

function Pos2BuildPos(unitDefID, posX, posY, posZ, buildFacing)

Parameters

unitDefID : integer
posX : number
posY : number
posZ : number
buildFacing : number? - (Default: `0`) one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3

Returns

buildPosX : number
buildPosY : number
buildPosZ : number

Snaps a position to the building grid

[source]

function PreloadFeatureDefModel(featureDefID)

Parameters

featureDefID : integer

Returns

: nil

[source]

function PreloadSoundItem(name)

Parameters

name : string

Returns

: nil

[source]

function PreloadUnitDefModel(unitDefID)

Parameters

unitDefID : integer

Returns

: nil

[source]

Allow the engine to load the unit’s model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

function Quit()

Returns

: nil

Closes the application

[source]

function RebuildSmoothMesh()

Returns

: nil

[source]

Heightmap changes normally take up to 25s to propagate to the smooth mesh. Use to force a mapwide update immediately.

function Reload(startScript)

Parameters

startScript : string - the CONTENT of the script.txt spring should use to start.

Returns

: nil

[source]

function RemoveGrass(x, z)

Parameters

x : number
z : number

Returns

: nil

[source]

function RemoveObjectDecal(unitID)

Parameters

unitID : integer

Returns

: nil

[source]

function RemoveUnitCmdDesc(unitID, cmdDescID)

Parameters

unitID : integer
cmdDescID : integer?

[source]

function ReplaceMouseCursor(oldFileName, newFileName, hotSpotTopLeft)

Parameters

oldFileName : string
newFileName : string
hotSpotTopLeft : boolean? - (Default: `false`)

Returns

assigned : boolean?

Mass replace all occurrences of the cursor in all CursorCmds.

[source]

function Restart(commandline_args, startScript)

Parameters

commandline_args : string - commandline arguments passed to spring executable.
startScript : string

Returns

: nil

[source]

If this call returns, something went wrong

function ResumeDollyCamera()

Returns

: nil

Resume Dolly Camera

[source]

function RevertHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Restore map height at a point in the world.

[source]

function RevertHeightMap(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number?

Returns

: nil

Restore map height of a rectangle area in the world.

[source]

function RevertOriginalHeightMap(x, z, height)

Parameters

x : number
z : number
height : number

Restore original map height at a point in the world.

[source]

function RevertOriginalHeightMap(x1, z1, x2, z2, height)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
height : number?

Returns

: nil

Restore original map height over a rectangle in the world.

[source]

function RevertSmoothMesh(x, z, origFactor)

Parameters

x : number
z : number
origFactor : number

[source]

function RevertSmoothMesh(x1, z1, x2, z2, origFactor)

Parameters

x1 : number
z1 : number
x2 : number
z2 : number
origFactor : number

[source]

function RunDollyCamera(runtime)

Parameters

runtime : number - Runtime in milliseconds.

Returns

: nil

Runs Dolly Camera

[source]

function SDLSetTextInputRect(x, y, width, height)

Parameters

x : number
y : number
width : number
height : number

Returns

: nil

[source]

function SDLStartTextInput()

Returns

: nil

[source]

function SDLStopTextInput()

Returns

: nil

[source]

function SelectUnit(unitID, append)

Parameters

unitID : integer?
append : boolean? - (Default: `false`) Append to current selection.

Returns

: nil

Selects a single unit

[source]

function SelectUnitArray(unitIDs, append)

Parameters

unitIDs : integer[] - Table with unit IDs as values.
append : boolean? - (Default: `false`) append to current selection

Returns

: nil

Selects multiple units, or appends to selection. Accepts a table with unitIDs as values

[source]

function SelectUnitMap(unitMap, append)

Parameters

unitMap : table<integer,any> - Table with unit IDs as keys.
append : boolean? - (Default: `false`) append to current selection

Returns

: nil

Selects multiple units, or appends to selection. Accepts a table with unitIDs as keys

[source]

function SendAllyChat(message)

Parameters

message : string

Returns

: nil

Sends a chat message to the sender’s ally team (if a spectator, to other spectators).

[source]

function SendCommands(commands)

Parameters

commands : string[]

[source]

function SendCommands(command, ...)

Parameters

command : string
... : string - additional commands

Returns

: nil

[source]

function SendLuaGaiaMsg(message)

Parameters

message : string

Returns

: nil

[source]

function SendLuaMenuMsg(msg)

Parameters

msg : string

[source]

function SendLuaRulesMsg(message)

Parameters

message : string

Returns

: nil

[source]

function SendLuaUIMsg(message, mode)

Parameters

message : string
mode : string - "s"/"specs" | "a"/"allies"

Returns

: nil

[source]

function SendMessage(message)

Parameters

message : string

Returns

: nil

[source]

function SendMessageToAllyTeam(allyID, message)

Parameters

allyID : integer
message : string

Returns

: nil

[source]

function SendMessageToPlayer(playerID, message)

Parameters

playerID : integer
message : string

Returns

: nil

[source]

function SendMessageToSpectators(message)

Parameters

message : string - ``"`<PLAYER#>`"`` where `#` is a player ID. This will be replaced with the player's name. e.g. ```lua Spring.SendMessage("`<PLAYER1>` did something") -- "ProRusher did something" ```

Returns

: nil

[source]

function SendMessageToTeam(teamID, message)

Parameters

teamID : integer
message : string

Returns

: nil

[source]

function SendPrivateChat(message, playerID)

Parameters

message : string
playerID : integer

Returns

: nil

Sends a private chat message to a specific player ID.

[source]

function SendPublicChat(message)

Parameters

message : string

Returns

: nil

Sends a chat message to everyone (players and spectators).

[source]

function SendSkirmishAIMessage(aiTeam, message)

Parameters

aiTeam : number
message : string

Returns

ai_processed : boolean?

[source]

function SendSpectatorChat(message)

Parameters

message : string

Returns

: nil

Sends a chat message to spectators. Works even if you’re a player.

[source]

function SetActiveCommand(action, actionExtra)

Parameters

action : string
actionExtra : string?

Returns

commandSet : boolean?

[source]

function SetActiveCommand(cmdIndex, button, leftClick, rightClick, alt, ctrl, meta, shift)

Parameters

cmdIndex : number
button : number? - (Default: `1`)
leftClick : boolean?
rightClick : boolean?
alt : boolean?
ctrl : boolean?
meta : boolean?
shift : boolean?

Returns

commandSet : boolean?

[source]

function SetAlly(firstAllyTeamID, secondAllyTeamID, ally)

Parameters

firstAllyTeamID : integer
secondAllyTeamID : integer
ally : boolean

Returns

: nil

Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.

[source]

function SetAllyTeamStartBox(allyTeamID, xMin, zMin, xMax, zMax)

Parameters

allyTeamID : integer
xMin : number - left start box boundary (elmos)
zMin : number - top start box boundary (elmos)
xMax : number - right start box boundary (elmos)
zMax : number - bottom start box boundary (elmos)

Returns

: nil

Changes the start box position of an allyTeam.

[source]

function SetAtmosphere(params)

Parameters

params : AtmosphereParams

Set atmosphere parameters

[source]

function SetAutoShowMetal(autoShow)

Parameters

autoShow : boolean

Returns

: nil

[source]

function SetBoxSelectionByEngine(state)

Parameters

state : boolean

Returns

: nil

[source]

function SetBuildFacing(facing)

Parameters

facing : FacingInteger

Returns

: nil

[source]

function SetBuildSpacing(spacing)

Parameters

spacing : number

Returns

: nil

[source]

function SetCameraOffset(posX, posY, posZ, tiltX, tiltY, tiltZ)

Parameters

posX : number? - (Default: `0`)
posY : number? - (Default: `0`)
posZ : number? - (Default: `0`)
tiltX : number? - (Default: `0`)
tiltY : number? - (Default: `0`)
tiltZ : number? - (Default: `0`)

Returns

: nil

[source]

function SetCameraState(cameraState, transitionTime, transitionTimeFactor, transitionTimeExponent)

Parameters

cameraState : CameraState - The fields must be consistent with the name/mode and current/new camera mode.
transitionTime : number? - (Default: `0`) in nanoseconds
transitionTimeFactor : number?
transitionTimeExponent : number?

Returns

set : boolean - `true` when applied without errors, otherwise `false`.

Set camera state.

[source]

function SetCameraTarget(x, y, z, transTime)

Parameters

x : number
y : number
z : number
transTime : number?

Returns

: nil

For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

[source]

function SetClipboard(text)

Parameters

text : string

Returns

: nil

[source]

function SetConfigFloat(name, value, useOverlay)

Parameters

name : string
value : number
useOverlay : boolean? - (Default: `false`) If `true`, the value will only be set in memory, and not be restored for the next game.

Returns

: nil

[source]

function SetConfigInt(name, value, useOverlay)

Parameters

name : string
value : integer
useOverlay : boolean? - (Default: `false`) If `true`, the value will only be set in memory, and not be restored for the next game.

Returns

: nil

[source]

function SetConfigString(name, value, useOverlay)

Parameters

name : string
value : string
useOverlay : boolean? - (Default: `false`) If `true`, the value will only be set in memory, and not be restored for the next game.

Returns

: nil

[source]

function SetCustomCommandDrawData(cmdID, cmdReference, color, showArea)

Parameters

cmdID : integer
cmdReference : (string|integer)? - The name or ID of an icon for command. Pass `nil` to clear draw data for command.
color : rgba? - (Default: white)
showArea : boolean? - (Default: `false`)

Returns

: nil

Register your custom cmd so it gets visible in the unit’s cmd queue

[source]

function SetDollyCameraCurve(degree, cpoints, knots)

Parameters

degree : number
cpoints : ControlPoint[] - NURBS control point positions.
knots : table

Returns

: nil

Sets Dolly Camera movement Curve

[source]

function SetDollyCameraLookCurve(degree, cpoints, knots)

Parameters

degree : number
cpoints : ControlPoint[] - NURBS control point positions.
knots : table

Returns

: nil

Sets Dolly Camera Look Curve

[source]

function SetDollyCameraLookPosition(x, y, z)

Parameters

x : number
y : number
z : number

Returns

: nil

Sets Dolly Camera Look Position

[source]

function SetDollyCameraLookUnit(unitID)

Parameters

unitID : integer - The unit to look at.

Returns

: nil

Sets target unit for Dolly Camera to look towards

[source]

function SetDollyCameraMode(mode)

Parameters

mode : (1|2) - `1` static position, `2` nurbs curve

Returns

: nil

Sets Dolly Camera movement mode

[source]

function SetDollyCameraPosition(x, y, z)

Parameters

x : number
y : number
z : number

Returns

: nil

Sets Dolly Camera Position

[source]

function SetDollyCameraRelativeMode(relativeMode)

Parameters

relativeMode : number - `1` world, `2` look target

Returns

: nil

Sets Dolly Camera movement curve to world relative or look target relative

[source]

function SetDrawGround(drawGround)

Parameters

drawGround : boolean

Returns

: nil

[source]

function SetDrawGroundDeferred(drawGroundDeferred, drawGroundForward)

Parameters

drawGroundDeferred : boolean
drawGroundForward : boolean? - allows disabling of the forward pass

Returns

: nil

[source]

function SetDrawModelsDeferred(drawUnitsDeferred, drawFeaturesDeferred, drawUnitsForward, drawFeaturesForward)

Parameters

drawUnitsDeferred : boolean
drawFeaturesDeferred : boolean
drawUnitsForward : boolean? - allows disabling of the respective forward passes
drawFeaturesForward : boolean? - allows disabling of the respective forward passes

Returns

: nil

[source]

function SetDrawSelectionInfo(enable)

Parameters

enable : boolean

Returns

: nil

Disables the “Selected Units x” box in the GUI.

[source]

function SetDrawSky(drawSky)

Parameters

drawSky : boolean

Returns

: nil

[source]

function SetDrawWater(drawWater)

Parameters

drawWater : boolean

Returns

: nil

[source]

function SetExperienceGrade(expGrade, ExpPowerScale, ExpHealthScale, ExpReloadScale)

Parameters

expGrade : number
ExpPowerScale : number?
ExpHealthScale : number?
ExpReloadScale : number?

Returns

: nil

Defines how often Callins.UnitExperience will be called.

[source]

function SetFactoryBuggerOff(unitID, buggerOff, offset, radius, relHeading, spherical, forced)

Parameters

unitID : integer
buggerOff : boolean?
offset : number?
radius : number?
relHeading : Heading?
spherical : boolean?
forced : boolean?

Returns

buggerOff : number?

[source]

function SetFeatureAlwaysUpdateMatrix(featureID, alwaysUpdateMat)

Parameters

featureID : integer
alwaysUpdateMat : number

Returns

: nil

[source]

function SetFeatureAlwaysVisible(featureID, enable)

Parameters

featureID : integer
enable : boolean

Returns

: nil

[source]

function SetFeatureBlocking(featureID, isBlocking, isSolidObjectCollidable, isProjectileCollidable, isRaySegmentCollidable, crushable, blockEnemyPushing, blockHeightChanges)

Parameters

featureID : integer
isBlocking : boolean? - If `true` add this feature to the `GroundBlockingMap`, but only if it collides with solid objects (or is being set to collide with the `isSolidObjectCollidable` argument). If `false`, remove this feature from the `GroundBlockingMap`. No change if `nil`.
isSolidObjectCollidable : boolean? - Enable or disable collision with solid objects, or no change if `nil`.
isProjectileCollidable : boolean? - Enable or disable collision with projectiles, or no change if `nil`.
isRaySegmentCollidable : boolean? - Enable or disable collision with ray segments, or no change if `nil`.
crushable : boolean? - Enable or disable crushable, or no change if `nil`.
blockEnemyPushing : boolean? - Enable or disable blocking enemy pushing, or no change if `nil`.
blockHeightChanges : boolean? - Enable or disable blocking height changes, or no change if `nil`.

Returns

isBlocking : boolean

[source]

function SetFeatureCollisionVolumeData(featureID, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, vType, tType, Axis)

Parameters

featureID : integer
scaleX : number
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
vType : number
tType : number
Axis : number

Returns

: nil

[source]

Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.

function SetFeatureDirection(featureID, frontx, fronty, frontz)

Parameters

featureID : integer
frontx : number
fronty : number
frontz : number

Returns

: nil

DEPRECATED: It's strongly that you use the overload that accepts a right direction as `frontDir` alone doesn't define object orientation.

[source]

Set feature front direction vector. The vector is normalized in the engine.

function SetFeatureDirection(featureID, frontx, fronty, frontz, rightx, righty, rightz)

Parameters

featureID : integer
frontx : number
fronty : number
frontz : number
rightx : number
righty : number
rightz : number

Returns

: nil

[source]

Set feature front and right direction vectors.

Both vectors will be normalized in the engine.

function SetFeatureEngineDrawMask(featureID, engineDrawMask)

Parameters

featureID : integer
engineDrawMask : number

Returns

: nil

[source]

function SetFeatureFade(featureID, allow)

Parameters

featureID : integer
allow : boolean

Returns

: nil

Control whether a feature will fade or not when zoomed out.

[source]

function SetFeatureFireTime(featureID, fireTime)

Parameters

featureID : integer
fireTime : number - in seconds

Set the fire timer for a feature.

[source]

Starts or resets an internal feature fire timer, when reaching zero the feature will be destroyed.

function SetFeatureHeadingAndUpDir(featureID, heading, upx, upy, upz)

Parameters

featureID : integer
heading : Heading
upx : number
upy : number
upz : number

Returns

: nil

[source]

Use this call to set up feature direction in a robust way. If feature was completely upright, new {upx, upy, upz} direction will be used as new “up” vector, the rotation set by “heading” will remain preserved.

function SetFeatureHealth(featureID, health, checkDestruction)

Parameters

featureID : integer
health : number
checkDestruction : boolean? - (Default: `false`) Whether to destroy feature if feature goes below 0 health.

Returns

: nil

[source]

function SetFeatureMass(featureID, mass)

Parameters

featureID : integer
mass : number

Returns

: nil

[source]

function SetFeatureMaxHealth(featureID, maxHealth)

Parameters

featureID : integer
maxHealth : number - minimum 0.1

Returns

: nil

[source]

function SetFeatureMidAndAimPos(featureID, mpX, mpY, mpZ, apX, apY, apZ, relative)

Parameters

featureID : integer
mpX : number
mpY : number
mpZ : number
apX : number
apY : number
apZ : number
relative : boolean?

Returns

success : boolean

[source]

Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.

function SetFeatureMoveCtrl(featureID, enabled, initialVelocityX, initialVelocityY, initialVelocityZ, accelerationX, accelerationY, accelerationZ)

Parameters

featureID : integer
enabled : true - Enable feature movement.
initialVelocityX : number? - Initial velocity on X axis, or `nil` for no change.
initialVelocityY : number? - Initial velocity on Y axis, or `nil` for no change.
initialVelocityZ : number? - Initial velocity on Z axis, or `nil` for no change.
accelerationX : number? - Acceleration per frame on X axis, or `nil` for no change.
accelerationY : number? - Acceleration per frame on Y axis, or `nil` for no change.
accelerationZ : number? - Acceleration per frame on Z axis, or `nil` for no change.

Enable feature movement control.

[source]

function SetFeatureMoveCtrl(featureID, enabled, velocityMaskX, velocityMaskY, velocityMaskZ, impulseMaskX, impulseMaskY, impulseMaskZ, movementMaskX, movementMaskY, movementMaskZ)

Parameters

featureID : integer
enabled : false - Disable feature movement.
velocityMaskX : number? - Lock velocity change in X dimension when not using `MoveCtrl`. `0` to lock, non-zero to allow, or `nil` to for no change.
velocityMaskY : number? - Lock velocity change in Y dimension when not using `MoveCtrl`. `0` to lock, non-zero to allow, or `nil` to for no change.
velocityMaskZ : number? - Lock velocity change in Z dimension when not using `MoveCtrl`. `0` to lock, non-zero to allow, or `nil` to for no change.
impulseMaskX : number? - Lock impulse in X dimension when not using `MoveCtrl`. `0` to lock, non-zero to allow, or `nil` to for no change.
impulseMaskY : number? - Lock impulse in Y dimension when not using `MoveCtrl`. `0` to lock, non-zero to allow, or `nil` to for no change.
impulseMaskZ : number? - Lock impulse in Z dimension when not using `MoveCtrl`. `0` to lock, non-zero to allow, or `nil` to for no change.
movementMaskX : number? - Lock move in X dimension when not using `MoveCtrl`. `0` to lock the axis, non-zero to allow, or `nil` for no change.
movementMaskY : number? - Lock move in Y dimension when not using `MoveCtrl`. `0` to lock the axis, non-zero to allow, or `nil` for no change.
movementMaskZ : number? - Lock move in Z dimension when not using `MoveCtrl`. `0` to lock the axis, non-zero to allow, or `nil` for no change.

Disable feature movement control.

Optional parameter allow physics vectors to build when not using MoveCtrl.

It is necessary to unlock feature movement on x, z axis before changing feature physics.

For example:

-- Unlock all movement before setting velocity.
Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)

-- Set velocity.
Spring.SetFeatureVelocity(featureID,10,0,10)

[source]

function SetFeatureNoDraw(featureID, noDraw)

Parameters

featureID : integer
noDraw : boolean

Returns

: nil

[source]

function SetFeatureNoSelect(featureID, noSelect)

Parameters

featureID : integer
noSelect : boolean

Returns

: nil

[source]

function SetFeaturePhysics(featureID, posX, posY, posZ, velX, velY, velZ, rotX, rotY, rotZ, dragX, dragY, dragZ)

Parameters

featureID : integer
posX : number
posY : number
posZ : number
velX : number
velY : number
velZ : number
rotX : number
rotY : number
rotZ : number
dragX : number
dragY : number
dragZ : number

Returns

: nil

[source]

function SetFeaturePieceCollisionVolumeData(featureID, pieceIndex, enable, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, Axis, volumeType, primaryAxis)

Parameters

featureID : integer
pieceIndex : number
enable : boolean
scaleX : number
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
Axis : number
volumeType : number
primaryAxis : number?

Returns

: nil

[source]

function SetFeaturePieceVisible(featureID, pieceIndex, visible)

Parameters

featureID : integer
pieceIndex : number
visible : boolean

Returns

: nil

[source]

function SetFeaturePosition(featureID, x, y, z, snapToGround)

Parameters

featureID : integer
x : number
y : number
z : number
snapToGround : boolean?

Returns

: nil

[source]

function SetFeatureRadiusAndHeight(featureID, radius, height)

Parameters

featureID : integer
radius : number
height : number

Returns

success : boolean

[source]

function SetFeatureReclaim(featureID, reclaimLeft)

Parameters

featureID : integer
reclaimLeft : number

Returns

: nil

[source]

function SetFeatureResources(featureID, metal, energy, reclaimTime, reclaimLeft, featureDefMetal, featureDefEnergy)

Parameters

featureID : integer
metal : number
energy : number
reclaimTime : number?
reclaimLeft : number?
featureDefMetal : number?
featureDefEnergy : number?

Returns

: nil

[source]

function SetFeatureResurrect(featureID, unitDef, facing, progress)

Parameters

featureID : integer
unitDef : (string|integer) - Can be a number id or a string name, this allows cancelling resurrection by passing `-1`.
facing : Facing? - (Default: `"south"`)
progress : number? - Set the level of progress.

Returns

: nil

[source]

function SetFeatureRotation(featureID, pitch, yaw, roll)

Parameters

featureID : integer
pitch : number - Rotation in X axis
yaw : number - Rotation in Y axis
roll : number - Rotation in Z axis

Returns

: nil

[source]

Note: PYR order

function SetFeatureRulesParam(featureID, paramName, paramValue, losAccess)

Parameters

featureID : integer
paramName : string
paramValue : (number|string)? - numeric paramValues in quotes will be converted to number.
losAccess : losAccess?

Returns

: nil

[source]

function SetFeatureSelectionVolumeData(featureID, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, vType, tType, Axis)

Parameters

featureID : integer
scaleX : number
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
vType : number
tType : number
Axis : number

Returns

: nil

[source]

function SetFeatureSmokeTime(featureID, smokeTime)

Parameters

featureID : integer
smokeTime : number - in seconds

Set the smoke timer for a feature.

[source]

If different than zero, starts emitting smoke until the timer counts down to zero.

Setting to zero will stop smoke emission by the feature.

The smoke timer affects both the duration and size of the smoke particles.

function SetFeatureUseAirLos(featureID, useAirLos)

Parameters

featureID : integer
useAirLos : boolean

Returns

: nil

[source]

function SetFeatureVelocity(featureID, velX, velY, velZ)

Parameters

featureID : integer
velX : number - in elmos/frame
velY : number - in elmos/frame
velZ : number - in elmos/frame

Set the velocity of a Feature

[source]

(See: )

function SetGameRulesParam(paramName, paramValue, losAccess)

Parameters

paramName : string
paramValue : (number|string)? - numeric paramValues in quotes will be converted to number.
losAccess : losAccess?

Returns

: nil

[source]

function SetGlobalLos(allyTeamID, globallos)

Parameters

allyTeamID : integer
globallos : boolean

Returns

: nil

Changes access to global line of sight for a team and its allies.

[source]

function SetGroundDecalAlpha(decalID, alpha, alphaFalloff)

Parameters

decalID : integer
alpha : number? - (Default: currAlpha) Between 0 and 1
alphaFalloff : number? - (Default: currAlphaFalloff) Between 0 and 1, per second

Returns

decalSet : boolean

[source]

function SetGroundDecalCreationFrame(decalID, creationFrameMin, creationFrameMax)

Parameters

decalID : integer
creationFrameMin : number? - (Default: currCreationFrameMin)
creationFrameMax : number? - (Default: currCreationFrameMax)

Returns

decalSet : boolean

[source]

Use separate min and max for “gradient” style decals such as tank tracks

function SetGroundDecalMisc(decalID, dotElimExp, refHeight, minHeight, maxHeight, forceHeightMode)

Parameters

decalID : integer
dotElimExp : number? - (Default: curValue) pow(max(dot(decalProjVector, SurfaceNormal), 0.0), dotElimExp), used to reduce decal artifacts on surfaces non-collinear with the projection vector
refHeight : number? - (Default: curValue)
minHeight : number? - (Default: curValue)
maxHeight : number? - (Default: curValue)
forceHeightMode : number? - (Default: curValue) in case forceHeightMode==1.0 ==> force relative height: midPoint.y = refHeight + clamp(midPoint.y - refHeight, minHeight); forceHeightMode==2.0 ==> force absolute height: midPoint.y = midPoint.y, clamp(midPoint.y, minHeight, maxHeight); other forceHeightMode values do not enforce the height of the center position

Returns

decalSet : boolean

[source]

Sets varios secondary parameters of a decal

function SetGroundDecalNormal(decalID, normalX, normalY, normalZ)

Parameters

decalID : integer
normalX : number? - (Default: `0`)
normalY : number? - (Default: `0`)
normalZ : number? - (Default: `0`)

Returns

decalSet : boolean

[source]

Sets projection cube normal to orient in 3D space. In case the normal (0,0,0) then normal is picked from the terrain

function SetGroundDecalPosAndDims(decalID, midPosX, midPosZ, sizeX, sizeZ, projCubeHeight)

Parameters

decalID : integer
midPosX : number? - (Default: currMidPosX)
midPosZ : number? - (Default: currMidPosZ)
sizeX : number? - (Default: currSizeX)
sizeZ : number? - (Default: currSizeZ)
projCubeHeight : number? - (Default: calculateProjCubeHeight)

Returns

decalSet : boolean

[source]

function SetGroundDecalQuadPosAndHeight(decalID, posTL, posTR, posBR, posBL, projCubeHeight)

Parameters

decalID : integer
posTL : xz? - (Default: currPosTL)
posTR : xz? - (Default: currPosTR)
posBR : xz? - (Default: currPosBR)
posBL : xz? - (Default: currPosBL)
projCubeHeight : number? - (Default: calculateProjCubeHeight)

Returns

decalSet : boolean

[source]

Use for non-rectangular decals

function SetGroundDecalRotation(decalID, rot)

Parameters

decalID : integer
rot : number? - (Default: random) in radians

Returns

decalSet : boolean

[source]

function SetGroundDecalTexture(decalID, textureName, isMainTex)

Parameters

decalID : integer
textureName : string - The texture has to be on the atlas which seems to mean it's defined as an explosion, unit tracks, or building plate decal on some unit already (no arbitrary textures)
isMainTex : boolean? - (Default: `true`) If false, it sets the normals/glow map

Returns

decalSet : boolean?

[source]

function SetGroundDecalTextureParams(decalID, texWrapDistance, texTraveledDistance)

Parameters

decalID : integer
texWrapDistance : number? - (Default: currTexWrapDistance) if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos
texTraveledDistance : number? - (Default: currTexTraveledDistance) shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments.

Returns

decalSet : boolean?

[source]

function SetGroundDecalTextureParams(decalID)

Parameters

decalID : integer

Returns

texWrapDistance : number? - If non-zero, sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos.
texTraveledDistance : number - Shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments.

[source]

function SetGroundDecalTint(decalID, tintColR, tintColG, tintColB, tintColA)

Parameters

decalID : integer
tintColR : number? - (Default: curTintColR)
tintColG : number? - (Default: curTintColG)
tintColB : number? - (Default: curTintColB)
tintColA : number? - (Default: curTintColA)

Returns

decalSet : boolean

[source]

Sets the tint of the ground decal. Color = 2 * textureColor * tintColor Respectively a color of (0.5, 0.5, 0.5, 0.5) is effectively no tint

function SetHeightMap(x, z, height, terraform)

Parameters

x : number
z : number
height : number
terraform : number? - (Default: `1`) Scaling factor.

Returns

absHeightDiff : integer? - If `0`, nothing will be changed (the terraform starts), if `1` the terraform will be finished.

[source]

Can only be called in Spring.SetHeightMapFunc.

function SetHeightMapFunc(luaFunction, arg, ...)

Parameters

luaFunction : function
arg : number
... : number

Returns

absTotalHeightMapAmountChanged : integer?

[source]

Example code:

function Spring.SetHeightMapFunc(function()
  for z=0,Game.mapSizeZ, Game.squareSize do
    for x=0,Game.mapSizeX, Game.squareSize do
      Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
    end
  end
end)

function SetLastMessagePosition(x, y, z)

Parameters

x : number
y : number
z : number

Returns

: nil

[source]

function SetLogSectionFilterLevel(sectionName, logLevel)

Parameters

sectionName : string
logLevel : (string|number)?

Returns

: nil

[source]

function SetLosViewColors(always, LOS, radar, jam, radar2)

Parameters

always : rgb
LOS : rgb
radar : rgb
jam : rgb
radar2 : rgb

Returns

: nil

[source]

function SetMapLightTrackingState(lightHandle, unitOrProjectileID, enableTracking, unitOrProjectile)

Parameters

lightHandle : number
unitOrProjectileID : integer
enableTracking : boolean
unitOrProjectile : boolean

Returns

success : boolean

Set a map-illuminating light to start/stop tracking the position of a moving object (unit or projectile)

[source]

function SetMapRenderingParams(params)

Parameters

params : MapRenderingParams

Returns

: nil

Allows to change map rendering params at runtime.

[source]

function SetMapShader(standardShaderID, deferredShaderID)

Parameters

standardShaderID : integer
deferredShaderID : integer

Returns

: nil

[source]

The ID’s must refer to valid programs returned by gl.CreateShader. Passing in a value of 0 will cause the respective shader to revert back to its engine default. Custom map shaders that declare a uniform ivec2 named “texSquare” can sample from the default diffuse texture(s), which are always bound to TU 0.

function SetMapShadingTexture(texType, texName)

Parameters

texType : string
texName : string

Returns

success : boolean

[source]

function SetMapSquareTerrainType(x, z, newType)

Parameters

x : number
z : number
newType : number

Returns

oldType : integer?

[source]

function SetMapSquareTexture(texSqrX, texSqrY, luaTexName)

Parameters

texSqrX : number
texSqrY : number
luaTexName : string

Returns

success : boolean

[source]

function SetMetalAmount(x, z, metalAmount)

Parameters

x : integer - X coordinate in worldspace / `Game.metalMapSquareSize`.
z : integer - Z coordinate in worldspace / `Game.metalMapSquareSize`.
metalAmount : number - must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).

Returns

: nil

Sets the amount of metal on a single square.

[source]

function SetMiniMapRotation(rotation)

Parameters

rotation : number - amount in radians

Returns

: nil

[source]

function SetModelLightTrackingState(lightHandle, unitOrProjectileID, enableTracking, unitOrProjectile)

Parameters

lightHandle : number
unitOrProjectileID : integer
enableTracking : boolean
unitOrProjectile : boolean

Returns

success : boolean

Set a model-illuminating light to start/stop tracking the position of a moving object (unit or projectile)

[source]

function SetMouseCursor(cursorName, cursorScale)

Parameters

cursorName : string
cursorScale : number? - (Default: `1.0`)

Returns

: nil

[source]

function SetNanoProjectileParams(rotVal, rotVel, rotAcc, rotValRng, rotVelRng, rotAccRng)

Parameters

rotVal : number? - (Default: `0`) in degrees
rotVel : number? - (Default: `0`) in degrees
rotAcc : number? - (Default: `0`) in degrees
rotValRng : number? - (Default: `0`) in degrees
rotVelRng : number? - (Default: `0`) in degrees
rotAccRng : number? - (Default: `0`) in degrees

Returns

: nil

[source]

function SetNoPause(noPause)

Parameters

noPause : boolean

Returns

: nil

[source]

function SetOriginalHeightMap(x, y, height, factor)

Parameters

x : number
y : number
height : number
factor : number?

Returns

: nil

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

function SetOriginalHeightMapFunc(heightMapFunc)

Parameters

heightMapFunc : function

Returns

: nil

[source]

Cannot recurse on itself

function SetPieceProjectileParams(projectileID, explosionFlags, spinAngle, spinSpeed, spinVectorX, spinVectorY, spinVectorZ)

Parameters

projectileID : integer
explosionFlags : number?
spinAngle : number?
spinSpeed : number?
spinVectorX : number?
spinVectorY : number?
spinVectorZ : number?

Set piece projectile params

Non passed or nil args don’t set params.

[source]

function SetPlayerRulesParam(playerID, paramName, paramValue, losAccess)

Parameters

playerID : integer
paramName : string
paramValue : (number|string)? - numeric paramValues in quotes will be converted to number.
losAccess : losAccess?

Returns

: nil

[source]

function SetProjectileAlwaysVisible(projectileID, alwaysVisible)

Parameters

projectileID : integer
alwaysVisible : boolean

Returns

: nil

[source]

function SetProjectileCEG(projectileID, ceg_name)

Parameters

projectileID : integer
ceg_name : string

Returns

: nil

[source]

function SetProjectileCollision(projectileID)

Parameters

projectileID : integer

[source]

function SetProjectileDamages(unitID, weaponNum, key, value)

Parameters

unitID : integer
weaponNum : integer
key : string
value : number

[source]

function SetProjectileGravity(projectileID, grav)

Parameters

projectileID : integer
grav : number? - (Default: `0`)

Returns

: nil

[source]

function SetProjectileIgnoreTrackingError(projectileID, ignore)

Parameters

projectileID : integer
ignore : boolean

[source]

function SetProjectileIsIntercepted(projectileID)

Parameters

projectileID : integer

[source]

function SetProjectileMoveControl(projectileID, enable)

Parameters

projectileID : integer
enable : boolean

Set whether engine should process position and speed for a projectile

Contrary to Spring.SetFeatureMoveCtrl, speed and position for projectiles can be set regardless of whether this method has been called or not.

Passing true merely skips engine updating velocity and position.

[source]

function SetProjectilePosition(projectileID, posX, posY, posZ)

Parameters

projectileID : integer
posX : number? - (Default: `0`)
posY : number? - (Default: `0`)
posZ : number? - (Default: `0`)

Set the position of a projectile

[source]

function SetProjectileTarget(projectileID, targetID, targetType)

Parameters

projectileID : integer
targetID : number
targetType : ProjectileTargetType

Returns

validTarget : boolean?

Set projectile target (object)

[source]

function SetProjectileTarget(projectileID, posX, posY, posZ)

Parameters

projectileID : integer
posX : number
posY : number
posZ : number

Returns

validTarget : boolean?

Set projectile target (position)

[source]

function SetProjectileTimeToLive(projectileID, ttl)

Parameters

projectileID : integer
ttl : number - Remaining time to live in frames

Set Time To Live for a projectile

[source]

function SetProjectileUseAirLos(projectileID, useAirLos)

Parameters

projectileID : integer
useAirLos : boolean

Returns

: nil

[source]

function SetProjectileVelocity(projectileID, velX, velY, velZ)

Parameters

projectileID : integer
velX : number - in elmos/frame
velY : number - in elmos/frame
velZ : number - in elmos/frame

Set the velocity of a projectile

Note

Differently from features, Spring.SetProjectileMoveControl is not required to have been called to make use of this method, but often used in conjunction.

[source]

(See: )

function SetRadarErrorParams(allyTeamID, allyteamErrorSize, baseErrorSize, baseErrorMult)

Parameters

allyTeamID : integer
allyteamErrorSize : number
baseErrorSize : number?
baseErrorMult : number?

Returns

: nil

[source]

function SetShareLevel(resource, shareLevel)

Parameters

resource : string - metal | energy
shareLevel : number

Returns

: nil

[source]

function SetSkyBoxTexture(texName)

Parameters

texName : string

Returns

: nil

[source]

function SetSmoothMesh(x, z, height, terraform)

Parameters

x : number
z : number
height : number
terraform : number? - (Default: `1`)

Returns

The : number? - absolute height difference, or `nil` if coordinates are invalid.

Can only be called in Spring.SetSmoothMeshFunc.

[source]

function SetSmoothMeshFunc(luaFunction, arg, ...)

Parameters

luaFunction : function
arg : any
... : any

Returns

absTotalHeightMapAmountChanged : number?

[source]

function SetSoundEffectParams()

[source]

function SetSoundStreamVolume(volume)

Parameters

volume : number

Returns

: nil

Set volume for SoundStream

[source]

function SetSquareBuildingMask(x, z, mask)

Parameters

x : number
z : number
mask : number

Returns

See : nil - also buildingMask unitdef tag.

[source]

function SetSunDirection(dirX, dirY, dirZ, intensity)

Parameters

dirX : number
dirY : number
dirZ : number
intensity : number? - (Default: `1.0`)

Returns

: nil

[source]

function SetSunLighting(params)

Parameters

params : { groundAmbientColor: rgb, groundDiffuseColor: rgb }

Modify sun lighting parameters.

Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })

[source]

function SetTeamColor(teamID, r, g, b)

Parameters

teamID : integer
r : number
g : number
b : number

Returns

: nil

[source]

function SetTeamResource(teamID, resource, amount)

Parameters

teamID : integer
resource : (ResourceName|StorageName)
amount : number

Returns

: nil

[source]

function SetTeamRulesParam(teamID, paramName, paramValue, losAccess)

Parameters

teamID : integer
paramName : string
paramValue : (number|string)? - numeric paramValues in quotes will be converted to number.
losAccess : losAccess?

Returns

: nil

[source]

function SetTeamShareLevel(teamID, type, amount)

Parameters

teamID : integer
type : ResourceName
amount : number

Returns

: nil

Changes the resource amount for a team beyond which resources aren’t stored but transferred to other allied teams if possible.

[source]

function SetTerrainTypeData(typeIndex, speedTanks, speedKBOts, speedHovers, speedShips)

Parameters

typeIndex : number
speedTanks : number? - (Default: nil)
speedKBOts : number? - (Default: nil)
speedHovers : number? - (Default: nil)
speedShips : number? - (Default: nil)

Returns

: boolean? - true

[source]

function SetTidal(strength)

Parameters

strength : number

Returns

: nil

Set tidal strength

[source]

function SetUnitAlwaysUpdateMatrix(unitID, alwaysUpdateMatrix)

Parameters

unitID : integer
alwaysUpdateMatrix : boolean

Returns

: nil

[source]

function SetUnitAlwaysVisible(unitID, alwaysVisible)

Parameters

unitID : integer
alwaysVisible : boolean

Returns

: nil

[source]

function SetUnitArmored(unitID, armored, armorMultiple)

Parameters

unitID : integer
armored : boolean?
armorMultiple : number?

Returns

: nil

[source]

function SetUnitBlocking(unitID, isBlocking, isSolidObjectCollidable, isProjectileCollidable, isRaySegmentCollidable, crushable, blockEnemyPushing, blockHeightChanges)

Parameters

unitID : integer
isBlocking : boolean? - If `true` add this unit to the `GroundBlockingMap`, but only if it collides with solid objects (or is being set to collide with the `isSolidObjectCollidable` argument). If `false`, remove this unit from the `GroundBlockingMap`. No change if `nil`.
isSolidObjectCollidable : boolean? - Enable or disable collision with solid objects, or no change if `nil`.
isProjectileCollidable : boolean? - Enable or disable collision with projectiles, or no change if `nil`.
isRaySegmentCollidable : boolean? - Enable or disable collision with ray segments, or no change if `nil`.
crushable : boolean? - Enable or disable crushable, or no change if `nil`.
blockEnemyPushing : boolean? - Enable or disable blocking enemy pushing, or no change if `nil`.
blockHeightChanges : boolean? - Enable or disable blocking height changes, or no change if `nil`.

Returns

isBlocking : boolean

[source]

function SetUnitBuildeeRadius(unitID, build)

Parameters

unitID : integer
build : number - radius for when targeted by build, repair, reclaim-type commands.

Returns

: nil

[source]

Sets the unit’s radius for when targeted by build, repair, reclaim-type commands.

function SetUnitBuildParams(unitID, paramName, value)

Parameters

unitID : integer
paramName : string - one of `buildRange`|`buildDistance`|`buildRange3D`
value : (number|boolean) - boolean when `paramName` is `buildRange3D`, otherwise number.

Returns

: nil

[source]

function SetUnitBuildSpeed(builderID, buildSpeed, repairSpeed, reclaimSpeed, captureSpeed, terraformSpeed)

Parameters

builderID : integer
buildSpeed : number
repairSpeed : number?
reclaimSpeed : number?
captureSpeed : number?
terraformSpeed : number?

Returns

: nil

[source]

function SetUnitCloak(unitID, cloak, cloakArg)

Parameters

unitID : integer
cloak : (boolean|number)
cloakArg : (boolean|number)

Returns

: nil

[source]

If the 2nd argument is a number, the value works like this: 1:=normal cloak 2:=for free cloak (cost no E) 3:=for free + no decloaking (except the unit is stunned) 4:=ultimate cloak (no ecost, no decloaking, no stunned decloak)

The decloak distance is only changed:

  • if the 3th argument is a number or a boolean.
  • if the boolean is false it takes the default decloak distance for that unitdef,
  • if the boolean is true it takes the absolute value of it.

function SetUnitCollisionVolumeData(unitID, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, vType, tType, Axis)

Parameters

unitID : integer
scaleX : number
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
vType : number
tType : number
Axis : number

Returns

enum : nil - COLVOL_TYPES { COLVOL_TYPE_DISABLED = -1, COLVOL_TYPE_ELLIPSOID = 0, COLVOL_TYPE_CYLINDER, COLVOL_TYPE_BOX, COLVOL_TYPE_SPHERE, COLVOL_NUM_TYPES // number of non-disabled collision volume types }; enum COLVOL_TESTS { COLVOL_TEST_DISC = 0, COLVOL_TEST_CONT = 1, COLVOL_NUM_TESTS = 2 // number of tests }; enum COLVOL_AXES { COLVOL_AXIS_X = 0, COLVOL_AXIS_Y = 1, COLVOL_AXIS_Z = 2, COLVOL_NUM_AXES = 3 // number of collision volume axes };

[source]

function SetUnitCosts(unitID, where)

Parameters

unitID : integer
where : table<number,number> - keys and values are, respectively and in this order: buildTime=amount, metalCost=amount, energyCost=amount

Returns

: nil

[source]

function SetUnitCrashing(unitID, crashing)

Parameters

unitID : integer
crashing : boolean

Returns

success : boolean

[source]

function SetUnitDefIcon(unitDefID, iconName)

Parameters

unitDefID : integer
iconName : string

Returns

: nil

[source]

function SetUnitDefImage(unitDefID, image)

Parameters

unitDefID : integer
image : string - luaTexture|texFile

Returns

: nil

[source]

function SetUnitDirection(unitID, frontx, fronty, frontz)

Parameters

unitID : integer
frontx : number
fronty : number
frontz : number

Returns

: nil

DEPRECATED: It's strongly that you use the overload that accepts a right direction as `frontDir` alone doesn't define object orientation.

[source]

Set unit front direction vector. The vector is normalized in the engine.

function SetUnitDirection(unitID, frontx, fronty, frontz, rightx, righty, rightz)

Parameters

unitID : integer
frontx : number
fronty : number
frontz : number
rightx : number
righty : number
rightz : number

Returns

: nil

[source]

Set unit front and right direction vectors.

Both vectors will be normalized in the engine.

function SetUnitEngineDrawMask(unitID, drawMask)

Parameters

unitID : integer
drawMask : number

Returns

: nil

[source]

function SetUnitExperience(unitID, experience)

Parameters

unitID : integer
experience : number

Returns

: nil

[source]

(See: )

function SetUnitFlanking(unitID, type, arg1, y, z)

Parameters

unitID : integer
type : string - "dir"|"minDamage"|"maxDamage"|"moveFactor"|"mode"
arg1 : number - x|minDamage|maxDamage|moveFactor|mode
y : number? - only when type is "dir"
z : number? - only when type is "dir"

Returns

: nil

[source]

function SetUnitGroup(unitID, groupID)

Parameters

unitID : integer
groupID : integer - the group number to be assigned, or -1 for deassignment

Returns

: nil

[source]

function SetUnitHarvestStorage(unitID, metal)

Parameters

unitID : integer
metal : number

Returns

: nil

See also harvestStorage UnitDef tag.

[source]

function SetUnitHeadingAndUpDir(unitID, heading, upx, upy, upz)

Parameters

unitID : integer
heading : Heading
upx : number
upy : number
upz : number

Returns

: nil

[source]

Use this call to set up unit direction in a robust way. If unit was completely upright, new {upx, upy, upz} direction will be used as new “up” vector, the rotation set by “heading” will remain preserved.

function SetUnitHealth(unitID, health)

Parameters

unitID : integer
health : (number|SetUnitHealthAmounts) - If a number, sets the units health to that value. Pass a table to update health, capture progress, paralyze damage, and build progress.

Returns

: nil

[source]

Note, if your game’s custom shading framework doesn’t support reverting into nanoframes then reverting into nanoframes via the “build” tag will fail to render properly.

(See: )

function SetUnitIconDraw(unitID, drawIcon)

Parameters

unitID : integer
drawIcon : boolean

Returns

: nil

[source]

function SetUnitLandGoal(unitID, goalX, goalY, goalZ, goalRadius)

Parameters

unitID : integer
goalX : number
goalY : number
goalZ : number
goalRadius : number?

Returns

: nil

Used in conjunction with Spring.UnitAttach et al. to re-implement old airbase & fuel system in Lua.

[source]

function SetUnitLeavesGhost(leavesGhost, leaveDeadGhost)

Parameters

leavesGhost : boolean
leaveDeadGhost : boolean? - (Default: `false`) leave a dead ghost behind if disabling and the unit had a live static ghost.

Set whether unit leaves static radar ghosts.

[source]

function SetUnitLeaveTracks(unitID, unitLeaveTracks)

Parameters

unitID : integer
unitLeaveTracks : boolean - whether unit leaves tracks on movement

Returns

: nil

[source]

function SetUnitLoadingTransport(passengerID, transportID)

Parameters

passengerID : integer
transportID : integer

Returns

: nil

Disables collisions between the two units to allow colvol intersection during the approach.

[source]

function SetUnitLosMask(unitID, allyTeam, losTypes)

Parameters

unitID : integer
allyTeam : number
losTypes : (LosTable|LosMask|integer) - A bitmask of `LosMask` bits or a table. True bits disable engine updates to visibility.

Set visibility status mask for a unit and team

Use this to allow or disallow a unit from having its visibility status against a certain team updated by the engine.

[source]

(See: )

function SetUnitLosState(unitID, allyTeam, losTypes)

Parameters

unitID : integer
allyTeam : number
losTypes : (LosTable|LosMask|integer) - A bitmask of `LosMask` bits or a table

Set current visibility status for a unit and team

Note this state will not be persisted if the visibility state is not masked.

Use it to change visibility state, once you set the unit to not receive engine visibility updates.

A few notes on certain bits:

  • contradar: True when the unit entered los at some point, remains set until radar is lost. Useful for tracking the unit type in radar, if you lost los you still know what unit type that radar dot refers to.
  • prevlos: True when the unit has entered los at least once, useful for tracking building locations (controls whether a ghost appears or not in the location)

[source]

(See: )

function SetUnitMass(unitID, mass)

Parameters

unitID : integer
mass : number

Returns

: nil

[source]

function SetUnitMaxHealth(unitID, maxHealth)

Parameters

unitID : integer
maxHealth : number

Returns

: nil

[source]

function SetUnitMaxRange(unitID, maxRange)

Parameters

unitID : integer
maxRange : number

Returns

: nil

[source]

function SetUnitMetalExtraction(unitID, depth, range)

Parameters

unitID : integer
depth : number - corresponds to metal extraction rate
range : number? - similar to "extractsMetal" in unitDefs.

Returns

: nil

[source]

function SetUnitMidAndAimPos(unitID, mpX, mpY, mpZ, apX, apY, apZ, relative)

Parameters

unitID : integer
mpX : number - new middle positionX of unit
mpY : number - new middle positionY of unit
mpZ : number - new middle positionZ of unit
apX : number - new positionX that enemies aim at on this unit
apY : number - new positionY that enemies aim at on this unit
apZ : number - new positionZ that enemies aim at on this unit
relative : boolean? - (Default: `false`) are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!

Returns

success : boolean

[source]

function SetUnitMoveGoal(unitID, goalX, goalY, goalZ, goalRadius, moveSpeed, moveRaw)

Parameters

unitID : integer
goalX : number
goalY : number
goalZ : number
goalRadius : number?
moveSpeed : number?
moveRaw : boolean?

Returns

: nil

Used by default commands to get in build-, attackrange etc.

[source]

function SetUnitNanoPieces(builderID, pieces)

Parameters

builderID : integer
pieces : table

Returns

: nil

[source]

This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!

function SetUnitNeutral(unitID, neutral)

Parameters

unitID : integer
neutral : boolean

Returns

setNeutral : boolean?

[source]

function SetUnitNoDraw(unitID, noDraw)

Parameters

unitID : integer
noDraw : boolean

Returns

: nil

[source]

function SetUnitNoGroup(unitID, unitNoGroup)

Parameters

unitID : integer
unitNoGroup : boolean - Whether unit can be added to selection groups

[source]

function SetUnitNoMinimap(unitID, unitNoMinimap)

Parameters

unitID : integer
unitNoMinimap : boolean

Returns

: nil

[source]

function SetUnitNoSelect(unitID, unitNoSelect)

Parameters

unitID : integer
unitNoSelect : boolean - whether unit can be selected or not

Returns

: nil

[source]

function SetUnitPhysicalStateBit(unitID, Physical)

Parameters

unitID : integer
Physical :

Returns

: nil

[source]

function SetUnitPhysics(unitID, posX, posY, posZ, velX, velY, velZ, rotX, rotY, rotZ, dragX, dragY, dragZ)

Parameters

unitID : integer
posX : number
posY : number
posZ : number
velX : number
velY : number
velZ : number
rotX : number
rotY : number
rotZ : number
dragX : number
dragY : number
dragZ : number

Returns

: nil

[source]

function SetUnitPieceCollisionVolumeData(unitID, pieceIndex, enable, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, volumeType, primaryAxis)

Parameters

unitID : integer
pieceIndex : number
enable : boolean
scaleX : number
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
volumeType : number?
primaryAxis : number?

Returns

: nil

[source]

function SetUnitPieceMatrix(unitID, pieceNum, matrix)

Parameters

unitID : integer
pieceNum : number
matrix : number[] - an array of 16 floats

Returns

: nil

Sets the local (i.e. parent-relative) matrix of the given piece.

[source]

If any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed.

function SetUnitPieceParent(unitID, AlteredPiece, ParentPiece)

Parameters

unitID : integer
AlteredPiece : number
ParentPiece : number

Returns

: nil

Changes the pieces hierarchy of a unit by attaching a piece to a new parent.

[source]

function SetUnitPieceVisible(unitID, pieceIndex, visible)

Parameters

unitID : integer
pieceIndex : number
visible : boolean

Returns

: nil

[source]

function SetUnitPosErrorParams(unitID, posErrorVectorX, posErrorVectorY, posErrorVectorZ, posErrorDeltaX, posErrorDeltaY, posErrorDeltaZ, nextPosErrorUpdate)

Parameters

unitID : integer
posErrorVectorX : number
posErrorVectorY : number
posErrorVectorZ : number
posErrorDeltaX : number
posErrorDeltaY : number
posErrorDeltaZ : number
nextPosErrorUpdate : number?

Returns

: nil

Sets a unit’s radar wobble

Controls how much a unit’s radar dot will wobble. Note that setting this above the allyTeam’s default wobble may result in the edgemost dot positions failing to register in ray traces, i.e. things like native “is under cursor” checks and some Lua interfaces.

[source]

function SetUnitPosition(unitID, x, z, floating)

Parameters

unitID : integer
x : number
z : number
floating : boolean? - (Default: `false`) If true, over water the position is on surface. If false, on seafloor.

Returns

: nil

Set unit position (2D)

[source]

Sets a unit’s position in 2D, at terrain height.

function SetUnitPosition(unitID, x, y, z)

Parameters

unitID : integer
x : number
y : number
z : number

Returns

: nil

Set unit position (3D)

[source]

Sets a unit’s position in 3D, at an arbitrary height.

function SetUnitRadiusAndHeight(unitID, radius, height)

Parameters

unitID : integer
radius : number
height : number

Returns

success : boolean

[source]

function SetUnitResourcing(unitID, res, amount)

Parameters

unitID : integer
res : string
amount : number

Returns

: nil

[source]

function SetUnitResourcing(unitID, res)

Parameters

unitID : integer
res : table<string,number> - keys are: "[u|c][u|m][m|e]" unconditional | conditional, use | make, metal | energy. Values are amounts

Returns

: nil

[source]

function SetUnitRotation(unitID, pitch, yaw, roll)

Parameters

unitID : integer
pitch : number - Rotation in X axis
yaw : number - Rotation in Y axis
roll : number - Rotation in Z axis

Returns

: nil

[source]

Note: PYR order

function SetUnitRulesParam(unitID, paramName, paramValue, losAccess)

Parameters

unitID : integer
paramName : string
paramValue : (number|string)? - numeric paramValues in quotes will be converted to number.
losAccess : losAccess?

Returns

: nil

[source]

function SetUnitSeismicSignature(unitID, seismicSignature)

Parameters

unitID : integer
seismicSignature : number

Returns

: nil

[source]

function SetUnitSelectionVolumeData(unitID, featureID, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, vType, tType, Axis)

Parameters

unitID : integer
featureID : integer
scaleX : number
scaleY : number
scaleZ : number
offsetX : number
offsetY : number
offsetZ : number
vType : number
tType : number
Axis : number

Returns

: nil

[source]

function SetUnitSensorRadius(unitID, type, radius)

Parameters

unitID : integer
type : (“los”|“airLos”|“radar”|“sonar”|“seismic”|“radarJammer”…)
radius : number

Returns

New : number? - radius, or `nil` if unit is invalid.

[source]

function SetUnitShieldRechargeDelay(unitID, weaponID, rechargeTime)

Parameters

unitID : integer
weaponID : integer? - (optional if the unit only has one shield)
rechargeTime : number? - (in seconds; emulates a regular hit if nil)

Returns

: nil

[source]

function SetUnitShieldState(unitID, weaponID, enabled, power)

Parameters

unitID : integer
weaponID : integer? - (Default: `-1`)
enabled : boolean?
power : number?

Returns

: nil

[source]

function SetUnitSonarStealth(unitID, sonarStealth)

Parameters

unitID : integer
sonarStealth : boolean

Returns

: nil

[source]

function SetUnitStealth(unitID, stealth)

Parameters

unitID : integer
stealth : boolean

Returns

: nil

[source]

function SetUnitStockpile(unitID, stockpile, buildPercent)

Parameters

unitID : integer
stockpile : number?
buildPercent : number?

Returns

: nil

[source]

function SetUnitStorage(unitID, res, amount)

Parameters

unitID : integer
res : string
amount : number

[source]

function SetUnitStorage(unitID, res)

Parameters

unitID : integer
res : ResourceUsage - keys are: "[m|e]" metal | energy. Values are amounts

[source]

function SetUnitTarget(unitID, enemyUnitID, dgun, userTarget, weaponNum)

Parameters

unitID : integer
enemyUnitID : integer? - when nil drops the units current target.
dgun : boolean? - (Default: `false`)
userTarget : boolean? - (Default: `false`)
weaponNum : number? - (Default: `-1`)

Returns

success : boolean

Defines a unit’s target.

[source]

function SetUnitTarget(unitID, x, y, z, dgun, userTarget, weaponNum)

Parameters

unitID : integer
x : number? - when nil or not passed it will drop target and ignore other parameters
y : number?
z : number?
dgun : boolean? - (Default: `false`)
userTarget : boolean? - (Default: `false`)
weaponNum : number? - (Default: `-1`)

Returns

success : boolean

[source]

function SetUnitTooltip(unitID, tooltip)

Parameters

unitID : integer
tooltip : string

Returns

: nil

[source]

function SetUnitUseAirLos(unitID, useAirLos)

Parameters

unitID : integer
useAirLos : boolean

Returns

: nil

[source]

function SetUnitUseWeapons(unitID, forceUseWeapons, allowUseWeapons)

Parameters

unitID : integer
forceUseWeapons : number?
allowUseWeapons : number?

Returns

: nil

[source]

function SetUnitVelocity(unitID, velX, velY, velZ)

Parameters

unitID : integer
velX : number - in elmos/frame
velY : number - in elmos/frame
velZ : number - in elmos/frame

Set the velocity of a Unit

[source]

(See: )

function SetUnitWeaponDamages(unitID, weaponNum, damages)

Parameters

unitID : integer
weaponNum : (number|“selfDestruct”|“explode”)
damages : WeaponDamages

Returns

: nil

[source]

function SetUnitWeaponDamages(unitID, weaponNum, key, value)

Parameters

unitID : integer
weaponNum : (number|“selfDestruct”|“explode”)
key : string
value : number

Returns

: nil

[source]

function SetUnitWeaponState(unitID, weaponNum, states)

Parameters

unitID : integer
weaponNum : number
states : WeaponState

Returns

: nil

[source]

function SetUnitWeaponState(unitID, weaponNum, key, value)

Parameters

unitID : integer
weaponNum : number
key : string
value : number

Returns

: nil

[source]

function SetVideoCapturingMode(allowCaptureMode)

Parameters

allowCaptureMode : boolean

Returns

: nil

This doesn’t actually record the game in any way, it just regulates the framerate and interpolations.

[source]

function SetVideoCapturingTimeOffset(timeOffset)

Parameters

timeOffset : boolean

Returns

: nil

[source]

function SetWaterParams(waterParams)

Parameters

waterParams : WaterParams

Returns

: nil

Does not need cheating enabled.

Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your springrc to 1, then you don’t even need to restart BumpWater via /water 4.

[source]

function SetWind(minStrength, maxStrength)

Parameters

minStrength : number
maxStrength : number

Returns

: nil

Set wind strength

[source]

function SetWindowGeometry(displayIndex, winRelPosX, winRelPosY, winSizeX, winSizeY, fullScreen, borderless)

Parameters

displayIndex : number
winRelPosX : number
winRelPosY : number
winSizeX : number
winSizeY : number
fullScreen : boolean
borderless : boolean

Returns

: nil

[source]

function SetWindowMaximized()

Returns

maximized : boolean

[source]

function SetWindowMinimized()

Returns

minimized : boolean

[source]

function SetWMCaption(title, titleShort)

Parameters

title : string - (Default: `"Spring <version>"`)
titleShort : string? - (Default: `"Spring <version>"`) displayed in the OS task-bar . > [!NOTE] > shortTitle is only ever possibly used under X11 (Linux & OS X), but not > with QT (KDE) and never under Windows.

Returns

: nil

Set the window title for the process

[source]

function SetWMIcon(iconFileName)

Parameters

iconFileName : string

Returns

: nil

Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo).

[source]

Note: has to be 24bit or 32bit. Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) Note: *.bmp images have to be in BGR format (default for m$ ones). Note: *.ico images are not supported.

function ShareResources(teamID, units)

Parameters

teamID : integer
units : string

Returns

: nil

[source]

function ShareResources(teamID, resource, amount)

Parameters

teamID : integer
resource : string - metal | energy
amount : number

Returns

: nil

[source]

function ShareTeamResource(teamID_src, teamID_recv, type, amount)

Parameters

teamID_src : integer
teamID_recv : integer
type : ResourceName
amount : number

Returns

: nil

Transfers resources between two teams.

[source]

function SolveNURBSCurve(groupID)

Parameters

groupID : integer

Returns

unitIDs : number[]?

[source]

function SpawnCEG(cegname, posX, posY, posZ, dirX, dirY, dirZ, radius, damage)

Parameters

cegname : string
posX : number? - (Default: `0`)
posY : number? - (Default: `0`)
posZ : number? - (Default: `0`)
dirX : number? - (Default: `0`)
dirY : number? - (Default: `0`)
dirZ : number? - (Default: `0`)
radius : number? - (Default: `0`)
damage : number? - (Default: `0`)

Returns

success : boolean?
cegID : integer

[source]

function SpawnExplosion(posX, posY, posZ, dirX, dirY, dirZ, explosionParams)

Parameters

posX : number? - (Default: `0`)
posY : number? - (Default: `0`)
posZ : number? - (Default: `0`)
dirX : number? - (Default: `0`)
dirY : number? - (Default: `0`)
dirZ : number? - (Default: `0`)
explosionParams : ExplosionParams

Returns

: nil

[source]

function SpawnProjectile(weaponDefID, projectileParams)

Parameters

weaponDefID : integer
projectileParams : ProjectileParams

Returns

projectileID : integer?

[source]

function SpawnSFX(unitID, sfxID, posX, posY, posZ, dirX, dirY, dirZ, radius, damage, absolute)

Parameters

unitID : integer? - (Default: `0`)
sfxID : integer? - (Default: `0`)
posX : number? - (Default: `0`)
posY : number? - (Default: `0`)
posZ : number? - (Default: `0`)
dirX : number? - (Default: `0`)
dirY : number? - (Default: `0`)
dirZ : number? - (Default: `0`)
radius : number? - (Default: `0`)
damage : number? - (Default: `0`)
absolute : boolean?

Returns

success : boolean?

Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

[source]

function Start(commandline_args, startScript)

Parameters

commandline_args : string - commandline arguments passed to spring executable.
startScript : string - the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args.

Returns

: nil

Launches a new Spring instance without terminating the existing one.

[source]

If this call returns, something went wrong

function StopSoundStream()

Returns

: nil

Terminates any SoundStream currently running.

[source]

function TestBuildOrder(unitDefID, x, y, z, facing)

Parameters

unitDefID : integer
x : number
y : number
z : number
facing : Facing

Returns

blocking : BuildOrderBlockedStatus
featureID : integer? - A reclaimable feature in the way.

[source]

function TestMoveOrder(unitDefID, posX, posY, posZ, dirX, dirY, dirZ, testTerrain, testObjects, centerOnly)

Parameters

unitDefID : integer
posX : number
posY : number
posZ : number
dirX : number? - (Default: `0.0`)
dirY : number? - (Default: `0.0`)
dirZ : number? - (Default: `0.0`)
testTerrain : boolean? - (Default: `true`)
testObjects : boolean? - (Default: `true`)
centerOnly : boolean? - (Default: `false`)

Returns

: boolean

[source]

function TraceRayGroundBetweenPositions(startX, startY, startZ, endX, endY, endZ, testWater)

Parameters

startX : number
startY : number
startZ : number
endX : number
endY : number
endZ : number
testWater : boolean? - (Default: `true`)

Returns

rayLength : number
posX : number
posY : number
posZ : number

Checks for a ground collision between two positions

[source]

Checks if there is surface (ground, optionally water) between two positions and returns the distance to the closest hit and its position, if any.

function TraceRayGroundInDirection(posX, posY, posZ, dirX, dirY, dirZ, testWater)

Parameters

posX : number
posY : number
posZ : number
dirX : number
dirY : number
dirZ : number
testWater : boolean? - (Default: `true`)

Returns

rayLength : number
posX : number
posY : number
posZ : number

Checks for a ground collision in given direction

[source]

Checks if there is surface (ground, optionally water) towards a vector and returns the distance to the closest hit and its position, if any.

function TraceScreenRay(screenX, screenY, onlyCoords, useMinimap, includeSky, ignoreWater, heightOffset)

Parameters

screenX : number - position on x axis in mouse coordinates (origin on left border of view)
screenY : number - position on y axis in mouse coordinates (origin on top border of view)
onlyCoords : boolean? - (Default: `false`) return only description (1st return value) and coordinates (2nd return value)
useMinimap : boolean? - (Default: `false`) if position arguments are contained by minimap, use the minimap corresponding world position
includeSky : boolean? - (Default: `false`)
ignoreWater : boolean? - (Default: `false`)
heightOffset : number? - (Default: `0`)

Returns

description : string? - of traced position
unitID : (number|string|xyz)? - or feature, position triple when onlyCoords=true
featureID : (number|string)? - or ground
coords : xyz?

Get information about a ray traced from screen to world position

[source]

Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown).

Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true).

This will only work for units & objects with the default collision sphere. Per Piece collision and custom collision objects are not supported.

The unit must be selectable, to appear to a screen trace ray.

function TransferFeature(featureID, teamID)

Parameters

featureID : integer
teamID : integer

Returns

: nil

Feature Control

[source]

function TransferUnit(unitID, newTeamID, given)

Parameters

unitID : integer
newTeamID : integer
given : boolean? - (Default: `true`) if false, the unit is captured.

Returns

: nil

[source]

function UnitAttach(transporterID, passengerID, pieceNum)

Parameters

transporterID : integer
passengerID : integer
pieceNum : number

Returns

: nil

[source]

function UnitDetach(passengerID)

Parameters

passengerID : integer

Returns

: nil

[source]

function UnitDetachFromAir(passengerID)

Parameters

passengerID : integer

Returns

: nil

[source]

function UnitFinishCommand(unitID)

Parameters

unitID : integer

[source]

function UnitIconGetDraw(unitID)

Parameters

unitID : integer

Returns

drawIcon : boolean?

[source]

function UnitIconSetDraw(unitID, drawIcon)

Parameters

unitID : integer
drawIcon : boolean

Returns

: nil

DEPRECATED:

[source]

Use Spring.SetUnitIconDraw instead.

function UnitWeaponFire(unitID, weaponID)

Parameters

unitID : integer
weaponID : integer

Returns

: nil

[source]

function UnitWeaponHoldFire(unitID, weaponID)

Parameters

unitID : integer
weaponID : integer

Returns

: nil

[source]

function UpdateMapLight(lightHandle, lightParams)

Parameters

lightHandle : number
lightParams : LightParams

Returns

success : boolean

[source]

function UpdateModelLight(lightHandle, lightParams)

Parameters

lightHandle : number
lightParams : LightParams

Returns

success : boolean

[source]

function UseTeamResource(teamID, type, amount)

Parameters

teamID : integer
type : ResourceName - Resource type.
amount : number - Amount of resource to use.

Returns

hadEnough : boolean

Consumes metal or energy resources of the specified team.

[source]

function UseTeamResource(teamID, amount)

Parameters

teamID : integer
amount : ResourceUsage

Returns

hadEnough : boolean

Consumes metal and/or energy resources of the specified team.

[source]

function UseUnitResource(unitID, resource, amount)

Parameters

unitID : integer
resource : ResourceName
amount : number

Returns

okay : boolean?

[source]

function UseUnitResource(unitID, resources)

Parameters

unitID : integer
resources : ResourceUsage

Returns

okay : boolean?

[source]

function ValidFeatureID(featureID)

Parameters

featureID : integer

Returns

: boolean

[source]

function ValidUnitID(unitID)

Parameters

unitID : integer

Returns

: boolean

Get whether a unitID is valid

Dead units are not valid.

[source]

function WarpMouse(x, y)

Parameters

x : number
y : number

Returns

: nil

[source]

function WorldToScreenCoords(x, y, z)

Parameters

x : number
y : number
z : number

Returns

viewPortX : number
viewPortY : number
viewPortZ : number

[source]

function Yield()

Returns

when : boolean - true caller should continue calling `Spring.Yield` during the widgets/gadgets load, when false it shouldn't call it any longer.

Relinquish control of the game loading thread and OpenGL context back to the UI (LuaIntro).

[source]

Should be called after each widget/unsynced gadget is loaded in widget/gadget handler. Use it to draw screen updates and process windows events.

property SYNCED table<string,any>

Proxy table for reading synced global state in unsynced code.

Generally not recommended. Instead, listen to the same events as synced and build the table in parallel

Unsynced code can read from the synced global table (_G) using the SYNCED proxy table. e.g. _G.foo can be access from unsynced via SYNCED.foo.

This table makes a copy of the object on the other side, and only copies numbers, strings, bools and tables (recursively but with the type restriction), in particular this does not allow access to functions.

Note that this makes a copy on each access, so is very slow and will not reflect changes. Cache it, but remember to refresh.

[source]

table tracy

function LuaTracyPlot(plotName, plotValue)

Parameters

plotName : string - Which LuaPlot should be updated
plotValue : number - the number to show on the Tracy plot

Update a Tracy plot with a value

[source]

function LuaTracyPlotConfig(plotName, plotFormatType, stepwise, fill, color)

Parameters

plotName : string - name of the plot to customize
plotFormatType : (“Number”|“Percentage”|“Memory”)? - (Default: `"Number"`)
stepwise : boolean? - (Default: `true`) stepwise chart
fill : boolean? - (Default: `false`) whether to fill color
color : integer? - (Default: `0xFFFFFF`) uint32 number as BGR color

Configure custom appearance for a Tracy plot for use in debugging or profiling

[source]

function Message(text)

Parameters

text : string

function ZoneBegin(name)

Parameters

name : string

function ZoneBeginN(name)

Parameters

name : string

function ZoneBeginNS(name)

Parameters

name : string

function ZoneBeginS(name)

Parameters

name : string

function ZoneEnd()

function ZoneName(name)

Parameters

name : string

function ZoneText(text)

Parameters

text : string

table VFS

Unified IO for archive and filesystem

The Virtual File System is a unified layer to access (read-only) the different archives used at runtime. So you can access map, game & config files via the same interface.

Overview

Although Spring can access the filesystem directly (via os module) it is more common that you would want to access files included with your game or Spring. Trouble is, most of these files are compressed into archives (.sdz/.sd7) so random access would generally be a difficult procedure. Fortunately, the Spring Lua system automatically provides access to mod and base files via the VFS module.

As an additional caveat, synced Lua cannot use the os and io modules, so using VFS is mandatory there to have any file access at all.

The VFS module doesn’t simply open archives though. What it does is map your game files, game dependencies and Spring content onto a virtual file tree. All archives start from the ‘roots’ of the tree and share the same virtual space, meaning that if two or more archives contain the same resource file name the resources overlap and only one of the files will be retrieved. Overlapping directories on the other hand are merged so the resulting virtual directory contains the contents of both. Here is an example of how this works:

Archive 1 (games/mygame.sd7)

textures
└── texture1.png
models
└── model1.mdl

Archive 2 (base/springcontent.sdz)

textures
├── texture1.png
├── texture2.png
└── texture3.png

VFS

textures
├── texture1.png
├── texture2.png
└── texture3.png
models
└── model1.mdl

This raises the question: If both archives have a texture1.png then which texture1.png is retreived via the VFS? The answer depends on the order the archives are loaded and the VFS mode (more on modes below). Generally however, each archive loaded overrides any archives loaded before it. The standard order of loading (from first to last) is:

  1. The automatic dependencies springcontent.sdz and maphelper.sdz.
  2. Dependencies listed in your modinfo.lua (or modinfo.tdf), in the order listed. Note that they are loaded fully and recursively, i.e. all the deeper dependencies of the 1st base-level dependency are loaded before the 2nd base-level dependency. This breaks the usual “loaded later overrides loaded earlier” priority if a dependency comes from multiple places, since only the first time an archive is loaded counts.
  3. Your mod archive.

Loose files (not within any archive) in the engine dir are also visible as if under the VFS root if loading under the VFS.RAW mode, though you can also use full FS path (i.e. C:/.../Spring/foo/bar.txt is visible both as that and as just foo/bar.txt). Note that VFS.RAW is only accessible to unsynced Lua, all synced states are limited to loaded archives.

Paths

Spring’s VFS is lowercase only. Also it is strongly recommended to use linux style path separators, e.g. "foo/bar.txt" and not "foo\bar.txt".

Engine read files

The engine access a few files directly, most of them are lua files which access other files themselves. Here the list of files that must exist in the VFS (some of them don’t have to be in the game/map archive cause there are fallback solutions in springcontent.sdz & maphelper.sdz):

  • ./
  • anims/
  • cursornormal.bmp/png
  • gamedata/
  • defs.lua
  • explosions.lua
  • explosion_alias.lua
  • icontypes.lua
  • messages.lua
  • modrules.lua
  • resources.lua
  • resources_map.lua
  • sidedata.lua
  • sounds.lua
  • luagaia/
  • main.lua
  • draw.lua
  • luarules/
  • main.lua
  • draw.lua
  • luaui/
  • main.lua
  • shaders/
  • ?
  • luaai.lua
  • mapinfo.lua
  • mapoptions.lua
  • modinfo.lua
  • modoptions.lua
  • validmaps.lua

[source]

property BASE string: "b"

[source]

function CalculateHash(input, hashType)

Parameters

input : string
hashType : HashType - Hash type.

Returns

hash : string?

Calculates hash of a given string.

  • MD5 gets base64 encoded.
  • SHA512 gets hex encoded.

[source]

function CompressFolder(folderPath, archiveType, compressedFilePath, includeFolder, mode)

Parameters

folderPath : string
archiveType : string? - (Default: `"zip"`)The compression type (can currently be only `"zip"`).
compressedFilePath : string? - (Default: `folderPath .. ".sdz"`)
includeFolder : boolean? - (Default: `false`) Whether the archive should have the specified folder as root.
mode : string?

Compresses the specified folder.

[source]

function DirList(directory, pattern, mode, recursive)

Parameters

directory : string
pattern : string? - (Default: `"*"`)
mode : string?
recursive : boolean? - (Default: `false`)

Returns

filenames : string[]

List files in a directory.

[source]

Example usage:

local luaFiles = VFS.DirList('units/', '*.lua', nil, true)

function FileExists(filename, mode)

Parameters

filename : string
mode : string?

Returns

exists : boolean - `true` if the file exists, otherwise `false`.

Check if file exists in VFS.

[source]

Example usage:

if VFS.FileExists("mapconfig/custom_lava_config.lua", VFS.MAP) then
  # ...
end

property GAME string: "M"

[source]

function GetAllArchives()

Returns

archiveNames : string[]

[source]

function GetArchiveChecksum(archiveName)

Parameters

archiveName : string

Returns

singleArchiveChecksum : string
completeArchiveChecksum : string

[source]

function GetArchiveContainingFile(filename, mode)

Parameters

filename : string
mode : string?

Returns

archiveName : string?

[source]

function GetArchiveDependencies(archiveName)

Parameters

archiveName : string

Returns

archiveNames : string[]

[source]

function GetArchiveInfo(archiveName)

Parameters

archiveName : string

Returns

archiveInfo : ArchiveInfo?

[source]

function GetArchivePath(archiveName)

Parameters

archiveName : string

Returns

archivePath : string?

[source]

function GetArchiveReplaces(archiveName)

Parameters

archiveName : string

Returns

archiveNames : string[]

[source]

function GetAvailableAIs(gameArchiveName, mapArichiveName)

Parameters

gameArchiveName : string?
mapArichiveName : string?

Returns

ais : AIInfo[]

Get a list of all Spring AIs.

The optional gameName and mapName parameters can be used to include game/map specific LuaAIs in the list.

[source]

function GetFileAbsolutePath(filename, mode)

Parameters

filename : string
mode : string?

Returns

absolutePath : string?

[source]

function GetGames()

Returns

gameNames : string[]

[source]

function GetLoadedArchives()

Returns

archiveNames : string[]

[source]

function GetMaps()

Returns

mapNames : string[]

[source]

function GetNameFromRapidTag(rapidTag)

Parameters

rapidTag : string

Returns

archiveName : string

[source]

function HasArchive()

Returns

hasArchive : boolean

[source]

function Include(filename, environment, mode)

Parameters

filename : string
environment : table? - (Default: the current function environment) The environment arg sets the global environment (see generic lua refs). In almost all cases, this should be left `nil` to preserve the current env. If the provided, any non-local variables and functions defined in `filename.lua` are then accessable via env. Vise-versa, any variables defined in env prior to passing to `VFS.Include` are available to code in the included file. Code running in `filename.lua` will see the contents of env in place of the normal global environment.
mode : string?

Returns

module : any - The return value of the included file.

Loads and runs lua code from a file in the VFS.

[source]

The path is relative to the main Spring directory, e.g.

VFS.Include('LuaUI/includes/filename.lua', nil, vfsmode)

function LoadFile(filename, mode)

Parameters

filename : string
mode : string?

Returns

data : string? - The contents of the file.

Load raw text data from the VFS.

[source]

Returns file contents as a string. Unlike VFS.Include the file will not be executed. This lets you pre-process the code. Use loadstring afterwards.

property MAP string: "m"

[source]

property MENU string: "e"

[source]

property MOD string: "M"

DEPRECATED:

[source]

function PackS16(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert signed 16-bit integer(s) to binary string.

[source]

function PackS16(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert signed 16-bit integer(s) to binary string.

[source]

function PackS32(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert signed 32-bit integer(s) to binary string.

[source]

function PackS32(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert signed 32-bit integer(s) to binary string.

[source]

function PackS32(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert signed 32-bit float(s) to binary string.

[source]

function PackS32(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert signed 32-bit float(s) to binary string.

[source]

function PackS8(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert signed 8-bit integer(s) to binary string.

[source]

function PackS8(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert signed 8-bit integer(s) to binary string.

[source]

function PackU16(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert unsigned 16-bit integer(s) to binary string.

[source]

function PackU16(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert unsigned 16-bit integer(s) to binary string.

[source]

function PackU32(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert unsigned 32-bit integer(s) to binary string.

[source]

function PackU32(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert unsigned 32-bit integer(s) to binary string.

[source]

function PackU8(...)

Parameters

... : integer - Numbers to pack.

Returns

: string

Convert unsigned 8-bit integer(s) to binary string.

[source]

function PackU8(numbers)

Parameters

numbers : integer[] - Numbers to pack.

Returns

: string

Convert unsigned 8-bit integer(s) to binary string.

[source]

property RAW string: "r"

[source] Only select uncompressed files.

property RAW_FIRST string: "rMmeb"

[source] Try uncompressed files first, then compressed.

property RAW_ONLY string: "r"

DEPRECATED:

[source]

function SubDirs(directory, pattern, mode, recursive)

Parameters

directory : string
pattern : string? - (Default: `"*"`)
mode : string?
recursive : boolean? - (Default: `false`)

Returns

dirnames : string[]

List sub-directories in a directory.

[source]

Example usage:

local files = VFS.SubDirs('sounds/voice/' .. language, '*')
for _, file in ipairs(files) do
    # ...
end

function UnpackF32(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to a signed 32-bit float.

[source]

function UnpackS16(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to a signed 16-bit integer.

[source]

function UnpackS32(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to a signed 32-bit integer.

[source]

function UnpackS8(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to a signed 8-bit integer.

[source]

function UnpackU16(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to an unsigned 16-bit integer.

[source]

function UnpackU32(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to an unsigned 32-bit integer.

[source]

function UnpackU8(str, pos)

Parameters

str : string - Binary string.
pos : integer? - Byte offset.

Returns

: integer

Convert a binary string to an unsigned 8-bit integer.

[source]

function UseArchive(archiveName, fun)

Parameters

archiveName : string
fun : unknown

Returns

Results : any … - of the given function

Temporarily load an archive from the VFS and run the given function, which can make usage of the files in the archive.

[source]

property ZIP string: "Mmeb"

[source] Only select compressed files (.sdz, .sd7).

property ZIP_FIRST string: "Mmebr"

[source] Try compressed files first, then uncompressed.

property ZIP_ONLY string: "Mmeb"

DEPRECATED:

[source]

function ZlibCompress(uncompressed)

Parameters

uncompressed : string - Data to compress.

Returns

compressed : string? - Compressed data, or `nil` on error.

[source]

function ZlibDecompress(compressed)

Parameters

compressed : string - Data to decompress.

Returns

uncompressed : string? - Uncompressed data, or `nil` on error.

[source]

Types

class ActiveUniform

[source]

property length integer

The character length of name.

property location GL

property name string

property size integer

property type string

String name of GL_* constant.

class AIInfo

[source]

property shortName string

property version string

class ArchiveInfo

[source]

property description string

property game string

property mapfile string

property modtype ModType

property mutator string

property name string

property shortgame string

property shortname string

property version string

class AtmosphereParams

[source]

property cloudColor rgba

property fogEnd number

property fogStart number

property skyAxisAngle xyzw

rotation axis and angle in radians of skybox orientation

property skyColor rgba

property sunColor rgba

alias Attachment is (“depth”|“stencil”|“color0”|“color1”|“color2”|“color3”|“color4”|“color5”…)

[source]

alias BuildOrderBlockedStatus is (0|1|2|3)

[source]

class CallAsTeamOptions

[source]

property ctrl integer

Ctrl team ID.

property read integer

Read team ID.

property select integer

Select team ID.

class Callins

[source]

function ActiveCommandChanged(cmdId, cmdType)

Parameters

cmdId : integer?
cmdType : integer?

Called when a command is issued.

[source]

function AddConsoleLine(msg, priority)

Parameters

msg : string
priority : integer

Called when text is entered into the console (e.g. Spring.Echo).

[source]

function CameraPositionChanged(posX, posY, posZ)

Parameters

posX : number - Camera position x in world coordinates
posY : number - Camera position y in world coordinates
posZ : number - Camera position z in world coordinates

Called whenever the camera position changes

[source]

function CameraRotationChanged(rotX, rotY, rotZ)

Parameters

rotX : number - Camera rotation around the x axis in radians.
rotY : number - Camera rotation around the y axis in radians.
rotZ : number - Camera rotation around the z axis in radians.

Called whenever the camera rotation changes

[source]

function CommandNotify(cmdID, cmdParams, options)

Parameters

cmdID : integer
cmdParams : table
options : CommandOptions

Returns

Returning : boolean - true deletes the command and does not send it through the network.

Called when a command is issued.

[source]

function DefaultCommand(type, id)

Parameters

type : (“unit”|“feature”) - The type of the object pointed at.
id : integer - The `unitID` or `featureID`.

Used to set the default command when a unit is selected.

[source]

function DownloadFailed(id, errorID)

Parameters

id : integer
errorID : integer

Called when a Pr-downloader download fails to complete.

[source]

function DownloadFinished(id)

Parameters

id : integer

Called when a Pr-downloader download finishes successfully.

[source]

function DownloadProgress(id, downloaded, total)

Parameters

id : integer
downloaded : integer
total : integer

Called incrementally during a Pr-downloader download.

[source]

function DownloadQueued(id, name, type)

Parameters

id : integer
name : string
type : string

Called when a Pr-downloader download is queued

[source]

function DownloadStarted(id)

Parameters

id : integer

Called when a Pr-downloader download is started via VFS.DownloadArchive.

[source]

function DrawFeaturesPostDeferred()

Runs at the end of the feature deferred pass to inform Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

[source]

function DrawGenesis()

Use this callin to update textures, shaders, etc.

[source]

Doesn’t render to screen! Also available to LuaMenu.

function DrawGroundDeferred()

[source]

function DrawGroundPostDeferred()

This runs at the end of its respective deferred pass.

[source]

Allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and DrawWorldPreUnit) via gl.CopyToTexture.

function DrawGroundPostForward()

[source]

function DrawGroundPreDeferred()

Runs at the start of the deferred pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

[source]

function DrawGroundPreForward()

Runs at the start of the forward pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

[source]

function DrawInMiniMap(sx, sy)

Parameters

sx : number - relative to the minimap's position and scale.
sy : number - relative to the minimap's position and scale.

[source]

function DrawInMiniMapBackground(sx, sy)

Parameters

sx : number - relative to the minimap's position and scale.
sy : number - relative to the minimap's position and scale.

[source]

function DrawPreDecals()

Called before decals are drawn

[source]

function DrawScreen(viewSizeX, viewSizeY)

Parameters

viewSizeX : number
viewSizeY : number

Also available to LuaMenu.

[source]

function DrawScreenEffects(viewSizeX, viewSizeY)

Parameters

viewSizeX : number
viewSizeY : number

[source]

function DrawScreenPost(viewSizeX, viewSizeY)

Parameters

viewSizeX : number
viewSizeY : number

Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).

[source]

Note: This callin is invoked after the software rendered cursor (configuration variable HardwareCursor=0) is drawn.

function DrawShadowFeaturesLua()

[source]

function DrawShadowPassTransparent()

Invoked after semi-transparent shadows pass is about to conclude

[source]

This callin has depth and color buffer of shadowmap bound via FBO as well as the FFP state to do “semi-transparent” shadows pass (traditionally only used to draw shadows of shadow casting semi-transparent particles). Can be used to draw nice colored shadows.

function DrawShadowUnitsLua()

[source]

function DrawUnitsPostDeferred()

Runs at the end of the unit deferred pass.

[source]

Informs Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

function DrawWaterPost()

[source]

function DrawWorld()

Spring draws command queues, ‘map stuff’, and map marks.

[source]

function DrawWorldPreParticles(drawAboveWater, drawBelowWater, drawReflection, drawRefraction)

Parameters

drawAboveWater : boolean
drawBelowWater : boolean
drawReflection : boolean
drawRefraction : boolean

DrawWorldPreParticles is called multiples times per draw frame. Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction.

[source]

function DrawWorldPreUnit()

Spring draws units, features, some water types, cloaked units, and the sun.

[source]

function DrawWorldReflection()

[source]

function DrawWorldRefraction()

[source]

function DrawWorldShadow()

[source]

function Explosion(weaponDefID, px, py, pz, attackerID, projectileID)

Parameters

weaponDefID : integer
px : number
py : number
pz : number
attackerID : integer
projectileID : integer

Returns

noGfx : boolean - if then no graphical effects are drawn by the engine for this explosion.

Called when an explosion occurs.

[source]

Only called for weaponDefIDs registered via Script.SetWatchExplosion or Script.SetWatchWeapon.

(See: )

function FeatureCreated(featureID, allyTeamID)

Parameters

featureID : integer
allyTeamID : integer

Called when a feature is created.

[source]

function FeatureDamaged(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Parameters

featureID : integer
featureDefID : integer
featureTeam : number
damage : number
weaponDefID : integer
projectileID : integer
attackerID : integer
attackerDefID : integer
attackerTeam : number

Called when a feature is damaged.

[source]

function FeatureDestroyed(featureID, allyTeamID)

Parameters

featureID : integer
allyTeamID : integer

Called when a feature is destroyed.

[source]

function FontsChanged()

Called whenever fonts are updated. Signals the game display lists and other caches should be discarded.

Gets called before other Update and Draw callins.

[source]

function GameFrame(frame)

Parameters

frame : number - Starts at frame 1

Called for every game simulation frame (30 per second).

[source]

function GameFramePost(frame)

Parameters

frame : number - Starts at frame 1

Called at the end of every game simulation frame

[source]

function GameID(gameID)

Parameters

gameID : string - encoded in hex.

Called once to deliver the gameID

[source]

function GameOver(winningAllyTeams)

Parameters

winningAllyTeams : number[] - list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

Called when the game ends

[source]

function GamePaused(playerID, paused)

Parameters

playerID : integer
paused : boolean

Called when the game is paused.

[source]

function GamePreload()

Called before the 0 gameframe.

Is not called when a saved game is loaded.

[source]

function GameProgress(serverFrameNum)

Parameters

serverFrameNum : integer

Called every 60 frames, calculating delta between GameFrame and GameProgress.

Can give an ETA about catching up with simulation for mid-game join players.

[source]

function GameSetup(state, ready, playerStates)

Parameters

state : READY_MESSAGE - the current message the engine would display to the player
ready : boolean - whether the player is currently ready or not
playerStates : table<number,READY_STATE> - indexed by playerID

Returns

gameHandled : boolean? - disables the engine ui when true
newReady : boolean? - whether the player is ready (ignored unless `gameHandled = true`)

Fired when the pregame stage is reached

Pregame is the stage where player readiness is managed before a game starts. Game only starts once all players are ready.

[source]

function GameStart()

Called upon the start of the game.

[source]

Is not called when a saved game is loaded.

function GetTooltip(x, y)

Parameters

x : number
y : number

Returns

tooltip : string

Called when Spring.IsAbove returns true.

[source]

function GotChatMsg(msg, playerID)

Parameters

msg : string
playerID : integer

Called when a player issues a UI command e.g. types /foo or /luarules foo.

[source]

function GroupChanged(groupID)

Parameters

groupID : integer

Called when a unit is added to or removed from a control group.

[source]

function Initialize()

Called when the addon is (re)loaded.

[source]

function IsAbove(x, y)

Parameters

x : number
y : number

Returns

isAbove : boolean

Called every Update.

[source]

Must return true for Mouse* events and Spring.GetToolTip to be called.

function KeyMapChanged()

Called when the keymap changes

[source]

Can be caused due to a change in language or keyboard

function KeyPress(keyCode, mods, isRepeat, label, utf32char, scanCode, actionList)

Parameters

keyCode : number
mods : KeyModifiers
isRepeat : boolean - If you want an action to occur only once check for isRepeat == false.
label : boolean - the name of the key
utf32char : number - (deprecated) always 0
scanCode : number
actionList : table - the list of actions for this keypress

Returns

halt : boolean - whether to halt the chain for consumers of the keypress

Called repeatedly when a key is pressed down.

[source]

Return true if you don’t want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki.

function KeyRelease(keyCode, mods, label, utf32char, scanCode, actionList)

Parameters

keyCode : number
mods : KeyModifiers
label : boolean - the name of the key
utf32char : number - (deprecated) always 0
scanCode : number
actionList : table - the list of actions for this keyrelease

Returns

: boolean

Called when the key is released.

[source]

function Load(zipReader)

Parameters

zipReader : table

Called after GamePreload and before GameStart. See Lua_SaveLoad.

[source]

function LoadCode()

Called when the game is (re)loaded.

[source]

function MapDrawCmd(playerID, type, posX, posY, posZ, label)

Parameters

playerID : integer
type : “point”
posX : number
posY : number
posZ : number
label : string

[source]

function MapDrawCmd(playerID, type, pos1X, pos1Y, pos1Z, pos2X, pos2Y, pos2Z)

Parameters

playerID : integer
type : “line”
pos1X : number
pos1Y : number
pos1Z : number
pos2X : number
pos2Y : number
pos2Z : number

[source]

function MapDrawCmd(playerID, type, posX, posY, posZ, radius)

Parameters

playerID : integer
type : “erase”
posX : number
posY : number
posZ : number
radius : number

[source]

function MouseMove(x, y, dx, dy, button)

Parameters

x : number - final x position
y : number - final y position
dx : number - distance travelled in x
dy : number - distance travelled in y
button : number

Called when the mouse is moved.

[source]

function MousePress(x, y, button)

Parameters

x : number
y : number
button : number

Returns

becomeMouseOwner : boolean

Called when a mouse button is pressed.

The button parameter supports up to 7 buttons. Must return true for MouseRelease and other functions to be called.

[source]

function MouseRelease(x, y, button)

Parameters

x : number
y : number
button : number

Returns

becomeMouseOwner : boolean

Called when a mouse button is released.

[source]

Please note that in order to have Spring call Spring.MouseRelease, you need to have a Spring.MousePress call-in in the same addon that returns true.

function MouseWheel(up, value)

Parameters

up : boolean - the direction
value : number - the amount travelled

Called when the mouse wheel is moved.

[source]

function PlayerAdded(playerID)

Parameters

playerID : integer

Called whenever a new player joins the game.

[source]

function PlayerChanged(playerID)

Parameters

playerID : integer

Called whenever a player’s status changes e.g. becoming a spectator.

[source]

function PlayerRemoved(playerID, reason)

Parameters

playerID : integer
reason : string

Called whenever a player is removed from the game.

[source]

function ProjectileCreated(proID, proOwnerID, weaponDefID)

Parameters

proID : integer
proOwnerID : integer
weaponDefID : integer

Called when the projectile is created.

[source]

Note that weaponDefID is missing if the projectile is spawned as part of a burst, but Spring.GetProjectileDefID and Spring.GetProjectileName still work in callin scope using proID.

(See: )

function ProjectileDestroyed(proID, ownerID, proWeaponDefID)

Parameters

proID : integer
ownerID : integer
proWeaponDefID : integer

Called when the projectile is destroyed.

[source]

(See: )

function RecvLuaMsg(msg, playerID)

Parameters

msg : string
playerID : integer

Receives messages from unsynced sent via Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.

[source]

function RecvSkirmishAIMessage(aiTeam, dataStr)

Parameters

aiTeam : integer
dataStr : string

[source]

function RenderUnitDestroyed(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called just before a unit is invalid, after it finishes its death animation.

[source]

function Save(zip)

Parameters

zip : table - a userdatum representing the savegame zip file. See Lua_SaveLoad.

Called when a chat command ‘/save’ or ‘/savegame’ is received.

[source]

function Shutdown()

Returns

: nil

Called when the addon or the game is shutdown.

[source]

function StockpileChanged(unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
weaponNum : integer
oldCount : integer
newCount : integer

Called when a units stockpile of weapons increases or decreases.

[source]

function SunChanged()

[source]

function TeamChanged(teamID)

Parameters

teamID : integer

[source]

function TeamDied(teamID)

Parameters

teamID : integer

Called when a team dies (see Spring.KillTeam).

[source]

function TextEditing(utf8, start, length)

Parameters

utf8 : string
start : number
length : number

[source]

function TextInput(utf8char)

Parameters

utf8char : string

Called whenever a key press results in text input.

[source]

function UnitArrivedAtGoal(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitCloaked(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called when a unit cloaks.

[source]

function UnitCmdDone(unitID, unitDefID, unitTeam, cmdID, cmdParams, options, cmdTag)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
cmdID : integer
cmdParams : table
options : CommandOptions
cmdTag : number

Called when a unit completes a command.

[source]

function UnitCommand(unitID, unitDefID, unitTeam, cmdID, cmdParams, options, cmdTag)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
cmdID : integer
cmdParams : table
options : CommandOptions
cmdTag : number

Called after when a unit accepts a command, after AllowCommand returns true.

[source]

function UnitConstructionDecayed(unitID, unitDefID, unitTeam, timeSinceLastBuild, iterationPeriod, part)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
timeSinceLastBuild : number
iterationPeriod : number
part : number

Called when a unit being built starts decaying.

[source]

function UnitCreated(unitID, unitDefID, unitTeam, builderID)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
builderID : integer?

Called at the moment the unit is created.

[source]

function UnitDamaged(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
damage : number
paralyzer : number
weaponDefID : integer
projectileID : integer
attackerID : integer
attackerDefID : integer
attackerTeam : number

Called when a unit is damaged (after UnitPreDamaged).

[source]

function UnitDecloaked(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called when a unit decloaks.

[source]

function UnitDestroyed(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam, weaponDefID)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
attackerID : integer
attackerDefID : integer
attackerTeam : number
weaponDefID : integer

Called when a unit is destroyed.

[source]

function UnitEnteredAir(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitEnteredLos(unitID, unitTeam, allyTeam, unitDefID)

Parameters

unitID : integer
unitTeam : integer
allyTeam : integer - who's LOS the unit entered.
unitDefID : integer

Called when a unit enters LOS of an allyteam.

Its called after the unit is in LOS, so you can query that unit.

[source]

function UnitEnteredRadar(unitID, unitTeam, allyTeam, unitDefID)

Parameters

unitID : integer
unitTeam : integer
allyTeam : integer
unitDefID : integer

Called when a unit enters radar of an allyteam.

Also called when a unit enters LOS without any radar coverage.

[source]

function UnitEnteredUnderwater(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitEnteredWater(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitExperience(unitID, unitDefID, unitTeam, experience, oldExperience)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
experience : number
oldExperience : number

Called when a unit gains experience greater or equal to the minimum limit set by calling Spring.SetExperienceGrade.

Should be called more reliably with small values of experience grade.

[source]

function UnitFeatureCollision(colliderID, collideeID)

Parameters

colliderID : integer
collideeID : integer

Called when a unit collides with a feature.

[source]

The unit must be registered with Script.SetWatchUnit and the feature registered with Script.SetWatchFeature.

function UnitFinished(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called at the moment the unit is completed.

[source]

function UnitFromFactory(unitID, unitDefID, unitTeam, factID, factDefID, userOrders)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
factID : integer
factDefID : integer
userOrders : boolean

Called when a factory finishes construction of a unit.

[source]

function UnitGiven(unitID, unitDefID, newTeam, oldTeam)

Parameters

unitID : integer
unitDefID : integer
newTeam : number
oldTeam : number

Called when a unit is transferred between teams. This is called after UnitTaken and in that moment unit is assigned to the newTeam.

[source]

function UnitHarvestStorageFull(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called when a unit’s harvestStorage is full (according to its unitDef’s entry).

[source]

function UnitIdle(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called when a unit is idle (empty command queue).

[source]

function UnitLeftAir(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitLeftLos(unitID, unitTeam, allyTeam, unitDefID)

Parameters

unitID : integer
unitTeam : integer
allyTeam : integer
unitDefID : integer

Called when a unit leaves LOS of an allyteam.

For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.

[source]

function UnitLeftRadar(unitID, unitTeam, allyTeam, unitDefID)

Parameters

unitID : integer
unitTeam : integer
allyTeam : integer
unitDefID : integer

Called when a unit leaves radar of an allyteam.

Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.

[source]

function UnitLeftUnderwater(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitLeftWater(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitLoaded(unitID, unitDefID, unitTeam, transportID, transportTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
transportID : integer
transportTeam : integer

Called when a unit is loaded by a transport.

[source]

function UnitMoveFailed(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

[source]

function UnitReverseBuilt(unitID, unitDefID, unitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer

Called when a living unit becomes a nanoframe again.

[source]

function UnitSeismicPing(x, y, z, strength, allyTeam, unitID, unitDefID)

Parameters

x : number
y : number
z : number
strength : number
allyTeam : integer
unitID : integer
unitDefID : integer

Called when a unit emits a seismic ping.

[source]

See seismicSignature.

function UnitStunned(unitID, unitDefID, unitTeam, stunned)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
stunned : boolean

Called when a unit changes its stun status.

[source]

function UnitTaken(unitID, unitDefID, oldTeam, newTeam)

Parameters

unitID : integer
unitDefID : integer
oldTeam : number
newTeam : number

Called when a unit is transferred between teams. This is called before UnitGiven and in that moment unit is still assigned to the oldTeam.

[source]

function UnitUnitCollision(colliderID, collideeID)

Parameters

colliderID : integer
collideeID : integer

Called when two units collide.

Both units must be registered with Script.SetWatchUnit.

[source]

function UnitUnloaded(unitID, unitDefID, unitTeam, transportID, transportTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
transportID : integer
transportTeam : integer

Called when a unit is unloaded by a transport.

[source]

function UnsyncedHeightMapUpdate()

Returns

x1 : number
z1 : number
x2 : number
z2 : number

Called when the unsynced copy of the height-map is altered.

[source]

function Update(dt)

Parameters

dt : number - the time since the last update.

Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.

[source]

function ViewResize(viewSizeX, viewSizeY)

Parameters

viewSizeX : number
viewSizeY : number

Called whenever the window is resized.

[source]

function WorldTooltip(type, unitId)

Parameters

type : “unit”
unitId : integer

Returns

tooltip : string

[source]

function WorldTooltip(type, featureId)

Parameters

type : “feature”
featureId : integer

Returns

tooltip : string

[source]

function WorldTooltip(type, posX, posY, posZ)

Parameters

type : “ground”
posX : number
posY : number
posZ : number

Returns

tooltip : string

[source]

function WorldTooltip(type)

Parameters

type : “selection”

Returns

tooltip : string

[source]

alias CameraMode is (0|1|2|3|4|5|6)

alias CameraName is (“ta”|“spring”|“rot”|“ov”|“free”|“fps”|“dummy”)

class CameraState

Parameters for camera state.

Highly dependent on the type of the current camera controller.

property angle number?

Camera rotation angle on X axis (aka tilt/pitch). (ta)

property dist number?

Camera distance from the ground. (spring)

property dx number?

Camera direction vector X.

property dy number?

Camera direction vector Y.

property dz number?

Camera direction vector Z.

property flipped number?

-1 for when south is down, 1 for when north is down. (ta)

property fov number?

property height number?

Camera distance from the ground. (ta)

property mode CameraMode

The camera mode.

property name CameraName

The camera name.

property oldHeight number?

Camera distance from the ground, cannot be changed. (rot)

property px number?

Position X of the ground point in screen center.

property py number?

Position Y of the ground point in screen center.

property pz number?

Position Z of the ground point in screen center.

property rx number?

Camera rotation angle on X axis. (spring)

property ry number?

Camera rotation angle on Y axis. (spring)

property rz number?

Camera rotation angle on Z axis. (spring)

class CameraVectors

[source]

property botFrustumPlane xyz

property forward xyz

property lftFrustumPlane xyz

property rgtFrustumPlane xyz

property right xyz

property topFrustumPlane xyz

property up xyz

enum CMD is (-1|25|75|50|90|32…)

Command constants.

Table defining Command related constants.

  • Contains a mix of special constants like command options or move states, and the list of engine command IDs.
  • Also supports integer keys, and those perform reverse mapping of command IDs.

[source]

property AREA_ATTACK integer: 21

[source]

property ATTACK integer: 20

Attack command. Gives an order to attack some target(s).

The command has different modes of operation, depending on the number of parameters and options used.

Modes of operation

Attack single target

  • params {unitID}: Attack a unit

The command will end once the target is dead or not valid any more.

Area attack

Will create a number of single target actions by finding targets in a circle.

Note: this is different than CMD.AREA_ATTACK, since this initially finds the targets but then doesn’t consider the area any more.

  • params {x,y,z,r} when radius is greater than 0.
  • r: radius
  • x,y,z: map position

Ground attack

  • params {x,y,z,0} or {x,y,z}
  • x,y,z: map position

Command Options

  • alt Also target stunned targets. Without this stunned targets will be skipped.
  • meta Override manualFire, and noAutoTarget weapon behaviours.

Other modifiers

  • modInfo.targetableTransportedUnits: Controls whether transported units are targetable.

Callins

  • UnitCmdDone: Run when the command is finished.

Examples

Attack unit with id targetID.

Spring.GiveOrderToUnit(unitID, CMD.ATTACK, targetID)

Area attack of radius 50 at map position 1000,1000 with height 100:

Spring.GiveOrderToUnit(unitID, CMD.ATTACK, {1000,100,1000,50})

Ground attack at map position 1000,1000 with height 100:

Spring.GiveOrderToUnit(unitID, CMD.ATTACK, {1000,100,1000})

[source]

property AUTOREPAIRLEVEL integer: 135

[source]

property CAPTURE integer: 130

[source]

property CLOAK integer: 95

[source]

property DEATHWAIT integer: 7

Makes the unit suspend processing its commmand queue until the death of a given unit or units in an area.

Modes of operation

Wait for death of specific unit

  • params {unitID} unitID of the unit to wait for.

Wait for death of units in an area

  • params {x1, y1, z1, x2, y2, z2}: Wait for death of units in square {x1, z1, x2, z2}.

[source]

property DGUN integer: 105

[source]

property FIGHT integer: 16

[source]

property FIRE_STATE integer: 45

[source]

property FIRESTATE_FIREATNEUTRAL integer: 3

[source]

property FIRESTATE_FIREATWILL integer: 2

[source]

property FIRESTATE_HOLDFIRE integer: 0

[source]

property FIRESTATE_NONE integer: -1

[source]

property FIRESTATE_RETURNFIRE integer: 1

[source]

property GATHERWAIT integer: 9

Makes the unit wait for all other selected units to reach the command.

Useful to make units wait until all other units have reached a waypoint.

Will only be given to movable (unitDef.canMove == true) non-factory units.

Accepts no parameters.

[source]

property GROUPADD integer: 36

[source]

property GROUPCLEAR integer: 37

[source]

property GROUPSELECT integer: 35

[source]

property GUARD integer: 25

[source]

property IDLEMODE integer: 145

[source]

property INSERT integer: 1

[source]

property INTERNAL integer: 60

[source]

property LOAD_ONTO integer: 76

[source]

property LOAD_UNITS integer: 75

[source]

property LOOPBACKATTACK integer: 20

[source]

property MANUALFIRE integer: 105

[source]

property MOVE integer: 10

[source]

property MOVE_STATE integer: 50

[source]

property MOVESTATE_HOLDPOS integer: 0

[source]

property MOVESTATE_MANEUVER integer: 1

[source]

property MOVESTATE_NONE integer: -1

[source]

property MOVESTATE_ROAM integer: 2

[source]

property ONOFF integer: 85

[source]

property OPT_ALT integer: 128

[source]

property OPT_CTRL integer: 64

[source]

property OPT_INTERNAL integer: 8

[source]

property OPT_META integer: 4

[source]

property OPT_RIGHT integer: 16

[source]

property OPT_SHIFT integer: 32

[source]

property PATROL integer: 15

[source]

property RECLAIM integer: 90

[source]

property REMOVE integer: 2

Remove all commands from a unit’s queue matching specific cmdIDs or tags.

Modes of operation

Filter by tag

Removes any command with a tag matching those included in params.

  • params {tag1, tag2 …} an array of tags to look for.

This is the default mode of operation.

Filter by id

Removes any command with a command id matching those included in params.

  • params {id1, id2 …} or {tag1, tag2, …} an array of ids tags to look for.

To use this mode you need to pass the alt option.

Command Options

  • alt Tag/Id switch
  • ctrl Alternative queue selection.
  • For factories alternative queue is the factory command queue, default queue is the rally queue.
  • For other units no effect.

Examples

Delete all attack orders from unit, or factory rally queue if factory:

Spring.GiveOrderToUnit(unitID, CMD.REMOVE, CMD.ATTACK)

Delete all attack and fight orders from unit, or factory rally queue if factory:

Spring.GiveOrderToUnit(unitID, CMD.REMOVE, {CMD.ATTACK, CMD.FIGHT}, CMD.OPT_ALT)

Delete commands with specific tags:

Spring.GiveOrderToUnit(unitID, CMD.REMOVE, {tag1, tag2, tag3})

Delete all commands to build units with UnitDef ids unitDefId1 and unitDefId2 from factory queue:

Spring.GiveOrderToUnit(unitID, CMD.REMOVE, {-unitDefId1, -unitDefId2}, CMD.OPT_ALT + CMD.OPT_CTRL)

[source]

property REPAIR integer: 40

[source]

property REPEAT integer: 115

[source]

property RESTORE integer: 110

[source]

property RESURRECT integer: 125

[source]

property SELFD integer: 65

[source]

property SETBASE integer: 55

[source]

property SQUADWAIT integer: 8

Makes selected units, or units coming out of a factory wait until squadSize peers are found to go with them.

If given to non factory units and the squadSize is smaller than the selected number of units the command will have no effect.

Each unit will find squadSize other units and resume wait, those remaining without peers will wait. For example if there are 30 selected units and a squadSize of 12 is sent, 6 units will stay waiting, as 30 - 12*2 = 6.

If given at a waypoint for a factory queue for new units, units coming out of the factory will wait at the waypoint until squadSize units are available, and then they will proceed together.

Can also be given to a group of factories, and units from those factories will gather together.

  • params {squadSize} Squad size.

[source]

property STOCKPILE integer: 100

[source]

property STOP integer: 0

Stop the current action and clear the unit’s command queue.

For factories, this will cancel the new unit orders queue. For units, this will cancel the current command and queue.

Accepts no parameters.

It won’t do anything if used with CMD.INSERT, or the shift option.

[source]

property TIMEWAIT integer: 6

Makes the unit suspend processing its command queue for a given duration.

  • params {duration} Time to wait in seconds.

[source]

property TRAJECTORY integer: 120

[source]

property UNLOAD_UNIT integer: 81

[source]

property UNLOAD_UNITS integer: 80

[source]

property WAIT integer: 5

Makes the unit suspend processing its command queue until wait is removed.

Accepts no parameters.

[source]

property WAITCODE_DEATH integer: 2

[source]

property WAITCODE_GATHER integer: 4

[source]

property WAITCODE_SQUAD integer: 3

[source]

property WAITCODE_TIME integer: 1

[source]

enum CMDTYPE is integer

Command type constants

Note, the CMDTYPE[] table is bidirectional. That means: CMDTYPE[CMDTYPE.ICON] := "CMDTYPE_ICON"

[source]

property CUSTOM integer

Expect with CMD_INTERNAL.

[source]

property ICON integer

Expect 0 parameters in return.

[source]

property ICON_AREA integer

Expect 4 parameters in return (mappos+radius).

[source]

property ICON_BUILDING integer

Expect 3 parameters in return (mappos).

[source]

property ICON_FRONT integer

Expect 3 or 6 parameters in return (middle and right side of front if a front was defined).

[source]

property ICON_MAP integer

Expect 3 parameters in return (mappos).

[source]

property ICON_MODE integer

Expect 1 parameter in return (number selected mode).

[source]

property ICON_UNIT integer

Expect 1 parameters in return (unitid).

[source]

property ICON_UNIT_FEATURE_OR_AREA integer

Expect 1 parameter in return (unitid or Game.maxUnits+featureid) or 4 parameters in return (mappos+radius).

[source]

property ICON_UNIT_OR_AREA integer

Expect 1 parameter in return (unitid) or 4 parameters in return (mappos+radius).

[source]

property ICON_UNIT_OR_MAP integer

Expect 1 parameters in return (unitid) or 3 parameters in return (mappos).

[source]

property ICON_UNIT_OR_RECTANGLE integer

Expect 1 parameter in return (unitid) or 3 parameters in return (mappos) or 6 parameters in return (startpos+endpos).

[source]

property NEXT integer

Expect command page used with CMD_INTERNAL.

[source]

property NUMBER integer

Expect 1 parameter in return (number).

[source]

property PREV integer

Expect command page used with CMD_INTERNAL.

[source]

enum COB is integer

COB constants

[source]

property ABS integer

[source]

property ACTIVATION integer

[source]

property AIR_LOS_RADIUS integer

[source]

property ARMORED integer

[source]

property ATAN integer

[source]

property BUGGER_OFF integer

[source]

property BUILD_PERCENT_LEFT integer

[source]

property BUSY integer

[source]

property CEG_DAMAGE integer

[source]

property CHANGE_TARGET integer

[source]

property CLOAKED integer

[source]

property COB_ID integer

[source]

property CRASHING integer

[source]

property CURRENT_FUEL integer

[source]

property CURRENT_SPEED integer

[source]

property DO_SEISMIC_PING integer

[source]

property FLANK_B_DIR integer

[source]

property FLANK_B_MAX_DAMAGE integer

[source]

property FLANK_B_MIN_DAMAGE integer

[source]

property FLANK_B_MOBILITY_ADD integer

[source]

property FLANK_B_MODE integer

[source]

property GAME_FRAME integer

[source]

property GROUND_HEIGHT integer

[source]

property GROUND_WATER_HEIGHT integer

[source]

property HEADING integer

[source]

property HEALTH integer

[source]

property HYPOT integer

[source]

property IN_WATER integer

[source]

property INBUILDSTANCE integer

[source]

property JAMMER_RADIUS integer

[source]

property KILL_UNIT integer

[source]

property LAST_ATTACKER_ID integer

[source]

property LOS_RADIUS integer

[source]

property MAX integer

[source]

property MAX_ID integer

[source]

property MAX_SPEED integer

[source]

property MIN integer

[source]

property MY_ID integer

[source]

property ON_ROAD integer

[source]

property PIECE_XZ integer

[source]

property PIECE_Y integer

[source]

property PLAY_SOUND integer

[source]

property POW integer

[source]

property PRINT integer

[source]

property RADAR_RADIUS integer

[source]

property REVERSING integer

[source]

property SEISMIC_RADIUS integer

[source]

property SET_WEAPON_GROUND_TARGET integer

[source]

property SET_WEAPON_UNIT_TARGET integer

[source]

property SHIELD_POWER integer

[source]

property SONAR_JAM_RADIUS integer

[source]

property SONAR_RADIUS integer

[source]

property SONAR_STEALTH integer

[source]

property STANDINGFIREORDERS integer

[source]

property STANDINGMOVEORDERS integer

[source]

property STEALTH integer

[source]

property TARGET_ID integer

[source]

property TRANSPORT_ID integer

[source]

property UNIT_ALLIED integer

[source]

property UNIT_BUILD_PERCENT_LEFT integer

[source]

property UNIT_HEIGHT integer

[source]

property UNIT_TEAM integer

[source]

property UNIT_XZ integer

[source]

property UNIT_Y integer

[source]

property UPRIGHT integer

[source]

property VETERAN_LEVEL integer

[source]

property WANT_CLOAK integer

[source]

property WEAPON_ACCURACY integer

[source]

property WEAPON_PROJECTILE_SPEED integer

[source]

property WEAPON_RANGE integer

[source]

property WEAPON_RELOADSTATE integer

[source]

property WEAPON_RELOADTIME integer

[source]

property WEAPON_SPRAY integer

[source]

property XZ_ATAN integer

[source]

property XZ_HYPOT integer

[source]

property YARD_OPEN integer

[source]

class CollisionVolumeData

Parameters related to a collision volume.

[source]

property boundingRadius number

property defaultToFootPrint boolean

property defaultToPieceTree boolean

property defaultToSphere boolean

property offsetX number

property offsetY number

property offsetZ number

property scaleX number

property scaleY number

property scaleZ number

property type (“ellipsoid”|“cylinder”|“box”|“sphere”)

type

class Command

[source]

property id integer

property options CommandOptions?

property params number[]?

class CommandDescription

Contains data about a command.

[source]

property action string?

property cursor string?

property disabled boolean?

property hidden boolean?

property id (CMD|integer)?

property name string?

property onlyTexture boolean?

property params string[]?

property queueing boolean?

property showUnique boolean?

property texture string?

property tooltip string?

property type CMDTYPE?

alias CommandOptionBit is (4|8|16|32|64|128)

[source]

alias CommandOptionName is (“right”|“alt”|“ctrl”|“shift”|“meta”)

[source]

class CommandOptions

Full command options object for reading from a Command.

Note that this has extra fields internal and coded that are not supported when creating a command from Lua.

[source]

property alt boolean

Alt key pressed.

property coded (CommandOptionBit|integer)

Bitmask of command options.

property ctrl boolean

Ctrl key pressed.

property internal boolean

property meta boolean

Meta key (space) pressed.

property right boolean

Right mouse key pressed.

property shift boolean

Shift key pressed.

class Configuration

Contains data about a configuration, only name and type are guaranteed

[source]

property declarationFile string

property declarationLine string

property defaultValue string

property description string

property maximumValue string

property minimumValue string

property name string

property readOnly boolean

property safemodeValue string

property type string

class ControlPoint

NURBS control point.

[source]

class CreateCommand

Used when assigning multiple commands at once.

[source]

alias CreateCommandOptions is (CommandOptionName[]|table<CommandOptionName,boolean>|CommandOptionBit|integer)

[source]

alias CreateCommandParams is (number[]|number)

[source]

class CreateRBOData

[source]

property format GL

property samples number?

any number here will result in creation of multisampled RBO

property target GL

alias DrawFlag is (0|1|2|4|8|16|32|128)

Drawing Flags

[source]

alias DrawMask is integer

class ExplosionParams

Parameters for explosion.

Please note the explosion defaults to 1 damage regardless of what it’s defined in the weaponDef. The weapondefID is only used for visuals and for passing into callins like UnitDamaged.

[source]

property craterAreaOfEffect number

property damageAreaOfEffect number

property damageGround boolean

property edgeEffectiveness number

property explosionSpeed number

property gfxMod number

property hitFeature number

property hitUnit number

property ignoreOwner boolean

property impactOnly boolean

property owner number

property weaponDef number

alias Facing is (0|1|2|3|“s”|“e”|“n”|“w”…)

alias FacingInteger is (0|1|2|3)

class FBO

User Data FBO

[source]

class FBODescription

[source]

property color0 string?

property color1 string?

property color10 string?

property color11 string?

property color12 string?

property color13 string?

property color14 string?

property color15 string?

property color2 string?

property color3 string?

property color4 string?

property color5 string?

property color6 string?

property color7 string?

property color8 string?

property color9 string?

property depth string?

property drawbuffers (integer|GL)[]?

e.g. { GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}

property readbuffer (integer|GL)?

e.g. GL_COLOR_ATTACHMENT0_EXT

property stencil string?

class FeatureSupport

[source]

property groupAddDoesntSelect boolean

Whether ‘group add’ also selects the group (does both if false)

property gunshipCruiseAltitudeMultiplier number

For gunships, the cruiseAltitude from the unit def is multiplied by this much

property hasExitOnlyYardmaps boolean

Whether yardmaps accept ’e’ (exit only) and ‘u’ (unbuildable, walkable)

property maxPiecesPerModel integer

How many pieces supported for 3d models?

property NegativeGetUnitCurrentCommand boolean

Whether Spring.GetUnitCurrentCommand allows negative indices to look from the end

property noAutoShowMetal boolean

Whether the engine switches to the metal view when selecting a “build metal extractor” command (yes if false)

property noHandicapForReclaim boolean

Whether handicap is applied to income from reclaim

property noOffsetForFeatureID boolean

Whether featureID from various interfaces (targetID for Reclaim commands, ownerID from SpringGetGroundDecalOwner, etc) needs to be offset by Game.maxUnits

property noRefundForConstructionDecay boolean

Whether there is no refund for construction decay (100% metal back if false)

property noRefundForFactoryCancel boolean

Whether there is no refund for factory cancel (100% metal back if false)

property rmlUiApiVersion integer

Version of Recoil’s rmlUI API

alias float2 is xy

alias float3 is xyz

alias float4 is xyzw

class GenericMoveType

[source]

property maneuverLeash number?

property maxSpeed number?

property maxWantedSpeed number?

property useWantedSpeed[0] boolean?

Use wanted speed for individual orders.

property useWantedSpeed[1] boolean?

Use wanted speed for formation orders.

property waterline number?

alias GenericMoveTypeBooleanKey is (“useWantedSpeed[0]"|“useWantedSpeed[1]”)

[source]

alias GenericMoveTypeNumberKey is (“maxSpeed”|“maxWantedSpeed”|“maneuverLeash”|“waterline”)

[source]

enum GL is integer

Constants for OpenGL API

For callouts related to OpenGL usage in Recoil, see gl.

[source]

property ACCUM_BUFFER_BIT integer

[source]

property ALL_ATTRIB_BITS integer

[source]

property ALL_BARRIER_BITS integer

[source]

property ALWAYS integer

[source]

property AMBIENT integer

[source]

property AND integer

[source]

property AND_INVERTED integer

[source]

property AND_REVERSE integer

[source]

property ARRAY_BUFFER integer

[source]

property ATOMIC_COUNTER_BARRIER_BIT integer

[source]

property BACK integer

[source]

property BLEND integer

[source]

property BUFFER integer

[source]

property BUFFER_UPDATE_BARRIER_BIT integer

[source]

property BYTE integer

[source]

property CLAMP integer

[source]

property CLAMP_TO_BORDER integer

[source]

property CLAMP_TO_EDGE integer

[source]

property CLEAR integer

[source]

property COLOR_ATTACHMENT0 integer

[source]

property COLOR_ATTACHMENT0_EXT integer

[source]

property COLOR_ATTACHMENT1 integer

[source]

property COLOR_ATTACHMENT1_EXT integer

[source]

property COLOR_ATTACHMENT10 integer

[source]

property COLOR_ATTACHMENT10_EXT integer

[source]

property COLOR_ATTACHMENT11 integer

[source]

property COLOR_ATTACHMENT11_EXT integer

[source]

property COLOR_ATTACHMENT12 integer

[source]

property COLOR_ATTACHMENT12_EXT integer

[source]

property COLOR_ATTACHMENT13 integer

[source]

property COLOR_ATTACHMENT13_EXT integer

[source]

property COLOR_ATTACHMENT14 integer

[source]

property COLOR_ATTACHMENT14_EXT integer

[source]

property COLOR_ATTACHMENT15 integer

[source]

property COLOR_ATTACHMENT15_EXT integer

[source]

property COLOR_ATTACHMENT2 integer

[source]

property COLOR_ATTACHMENT2_EXT integer

[source]

property COLOR_ATTACHMENT3 integer

[source]

property COLOR_ATTACHMENT3_EXT integer

[source]

property COLOR_ATTACHMENT4 integer

[source]

property COLOR_ATTACHMENT4_EXT integer

[source]

property COLOR_ATTACHMENT5 integer

[source]

property COLOR_ATTACHMENT5_EXT integer

[source]

property COLOR_ATTACHMENT6 integer

[source]

property COLOR_ATTACHMENT6_EXT integer

[source]

property COLOR_ATTACHMENT7 integer

[source]

property COLOR_ATTACHMENT7_EXT integer

[source]

property COLOR_ATTACHMENT8 integer

[source]

property COLOR_ATTACHMENT8_EXT integer

[source]

property COLOR_ATTACHMENT9 integer

[source]

property COLOR_ATTACHMENT9_EXT integer

[source]

property COLOR_BUFFER_BIT integer

[source]

property COMMAND_BARRIER_BIT integer

[source]

property CONSTANT_ATTENUATION integer

[source]

property COPY integer

[source]

property COPY_INVERTED integer

[source]

property CURRENT_BIT integer

[source]

property DECAL integer

[source]

property DEPTH_ATTACHMENT integer

[source]

property DEPTH_ATTACHMENT_EXT integer

[source]

property DEPTH_BUFFER_BIT integer

[source]

property DEPTH_COMPONENT16 integer

[source]

property DEPTH_COMPONENT24 integer

[source]

property DEPTH_COMPONENT32 integer

[source]

property DEPTH_COMPONENT32F integer

[source]

property DIFFUSE integer

[source]

property DONT_CARE integer

[source]

property DST_ALPHA integer

[source]

property DST_COLOR integer

[source]

property ELEMENT_ARRAY_BARRIER_BIT integer

[source]

property ELEMENT_ARRAY_BUFFER integer

[source]

property ENABLE_BIT integer

[source]

property EQUAL integer

[source]

property EQUIV integer

[source]

property EVAL_BIT integer

[source]

property EYE_LINEAR integer

[source]

property EYE_PLANE integer

[source]

property FASTEST integer

[source]

property FILL integer

[source]

property FLAT integer

[source]

property FLOAT integer

[source]

property FLOAT_MAT4 integer

[source]

property FLOAT_VEC4 integer

[source]

property FOG_BIT integer

[source]

property FOG_HINT integer

[source]

property FRAGMENT_SHADER integer

[source]

property FRAMEBUFFER integer

[source]

property FRAMEBUFFER_BARRIER_BIT integer

[source]

property FRONT integer

[source]

property FRONT_AND_BACK integer

[source]

property FUNC_ADD integer

[source]

property FUNC_REVERSE_SUBTRACT integer

[source]

property FUNC_SUBTRACT integer

[source]

property GEOMETRY_INPUT_TYPE_EXT integer

[source]

property GEOMETRY_OUTPUT_TYPE_EXT integer

[source]

property GEOMETRY_SHADER_EXT integer

[source]

property GEOMETRY_VERTICES_OUT_EXT integer

[source]

property GEQUAL integer

[source]

property GREATER integer

[source]

property HINT_BIT integer

[source]

property INT integer

[source]

property INT_VEC4 integer

[source]

property INVERT integer

[source]

property LEQUAL integer

[source]

property LESS integer

[source]

property LIGHTING_BIT integer

[source]

property LINE integer

[source]

property LINE_BIT integer

[source]

property LINE_LOOP integer

[source]

property LINE_STRIP integer

[source]

property LINE_STRIP_ADJACENCY integer

[source]

property LINEAR integer

[source]

property LINEAR_ATTENUATION integer

[source]

property LINEAR_MIPMAP_LINEAR integer

[source]

property LINEAR_MIPMAP_NEAREST integer

[source]

property LINES integer

[source]

property LINES_ADJACENCY integer

[source]

property LIST_BIT integer

[source]

property MAX integer

[source]

property MIN integer

[source]

property MIRRORED_REPEAT integer

[source]

property MODELVIEW integer

[source]

property MODULATE integer

[source]

property NAND integer

[source]

property NEAREST integer

[source]

property NEAREST_MIPMAP_LINEAR integer

[source]

property NEAREST_MIPMAP_NEAREST integer

[source]

property NEVER integer

[source]

property NICEST integer

[source]

property NOOP integer

[source]

property NOR integer

[source]

property NORMAL_MAP integer

[source]

property NOTEQUAL integer

[source]

property OBJECT_LINEAR integer

[source]

property OBJECT_PLANE integer

[source]

property ONE integer

[source]

property ONE_MINUS_DST_ALPHA integer

[source]

property ONE_MINUS_DST_COLOR integer

[source]

property ONE_MINUS_SRC_ALPHA integer

[source]

property ONE_MINUS_SRC_COLOR integer

[source]

property OR integer

[source]

property OR_INVERTED integer

[source]

property OR_REVERSE integer

[source]

property PATCH_DEFAULT_INNER_LEVEL integer

[source]

property PATCH_DEFAULT_OUTER_LEVEL integer

[source]

property PATCH_VERTICES integer

[source]

property PATCHES integer

[source]

property PERSPECTIVE_CORRECTION_HINT integer

[source]

property PIXEL_BUFFER_BARRIER_BIT integer

[source]

property PIXEL_MODE_BIT integer

[source]

property POINT integer

[source]

property POINT_BIT integer

[source]

property POINTS integer

[source]

property POLYGON integer

[source]

property POLYGON_BIT integer

[source]

property POLYGON_STIPPLE_BIT integer

[source]

property POSITION integer

[source]

property PROGRAM integer

[source]

property PROGRAM_PIPELINE integer

[source]

property PROJECTION integer

[source]

property Q integer

[source]

property QUAD_STRIP integer

[source]

property QUADRATIC_ATTENUATION integer

[source]

property QUADS integer

[source]

property QUERY integer

[source]

property R integer

[source]

property R11F_G11F_B10F integer

[source]

property R16 integer

[source]

property R16_SNORM integer

[source]

property R16F integer

[source]

property R16I integer

[source]

property R16UI integer

[source]

property R32F integer

[source]

property R32I integer

[source]

property R32UI integer

[source]

property R8 integer

[source]

property R8_SNORM integer

[source]

property R8I integer

[source]

property R8UI integer

[source]

property READ_ONLY integer

[source]

property READ_WRITE integer

[source]

property REFLECTION_MAP integer

[source]

property RENDERBUFFER integer

[source]

property REPEAT integer

[source]

property REPLACE integer

[source]

property RG16 integer

[source]

property RG16_SNORM integer

[source]

property RG16F integer

[source]

property RG16I integer

[source]

property RG16UI integer

[source]

property RG32F integer

[source]

property RG32I integer

[source]

property RG32UI integer

[source]

property RG8 integer

[source]

property RG8_SNORM integer

[source]

property RG8I integer

[source]

property RG8UI integer

[source]

property RGB10_A2 integer

[source]

property RGB10_A2UI integer

[source]

property RGBA16 integer

[source]

property RGBA16_SNORM integer

[source]

property RGBA16F integer

[source]

property RGBA16I integer

[source]

property RGBA16UI integer

[source]

property RGBA32F integer

[source]

property RGBA32I integer

[source]

property RGBA32UI integer

[source]

property RGBA8 integer

[source]

property RGBA8_SNORM integer

[source]

property RGBA8I integer

[source]

property RGBA8UI integer

[source]

property S integer

[source]

property SCISSOR_BIT integer

[source]

property SET integer

[source]

property SHADER integer

[source]

property SHADER_IMAGE_ACCESS_BARRIER_BIT integer

[source]

property SHADER_STORAGE_BARRIER_BIT integer

[source]

property SHADER_STORAGE_BUFFER integer

[source]

property SHORT integer

[source]

property SMOOTH integer

[source]

property SPECULAR integer

[source]

property SPHERE_MAP integer

[source]

property SPOT_CUTOFF integer

[source]

property SPOT_DIRECTION integer

[source]

property SPOT_EXPONENT integer

[source]

property SRC_ALPHA integer

[source]

property SRC_ALPHA_SATURATE integer

[source]

property SRC_COLOR integer

[source]

property STENCIL_ATTACHMENT integer

[source]

property STENCIL_ATTACHMENT_EXT integer

[source]

property STENCIL_BUFFER_BIT integer

[source]

property T integer

[source]

property TESS_CONTROL_SHADER integer

[source]

property TESS_EVALUATION_SHADER integer

[source]

property TEXTURE integer

[source]

property TEXTURE_1D integer

[source]

property TEXTURE_2D integer

[source]

property TEXTURE_2D_ARRAY integer

[source]

property TEXTURE_2D_MULTISAMPLE integer

[source]

property TEXTURE_3D integer

[source]

property TEXTURE_BIT integer

[source]

property TEXTURE_CUBE_MAP integer

[source]

property TEXTURE_ENV integer

[source]

property TEXTURE_ENV_COLOR integer

[source]

property TEXTURE_ENV_MODE integer

[source]

property TEXTURE_FETCH_BARRIER_BIT integer

[source]

property TEXTURE_FILTER_CONTROL integer

[source]

property TEXTURE_GEN_MODE integer

[source]

property TEXTURE_LOD_BIAS integer

[source]

property TEXTURE_UPDATE_BARRIER_BIT integer

[source]

property TRANSFORM_BIT integer

[source]

property TRANSFORM_FEEDBACK integer

[source]

property TRANSFORM_FEEDBACK_BARRIER_BIT integer

[source]

property TRIANGLE_FAN integer

[source]

property TRIANGLE_STRIP integer

[source]

property TRIANGLE_STRIP_ADJACENCY integer

[source]

property TRIANGLES integer

[source]

property TRIANGLES_ADJACENCY integer

[source]

property UNIFORM_BARRIER_BIT integer

[source]

property UNIFORM_BUFFER integer

[source]

property UNSIGNED_BYTE integer

[source]

property UNSIGNED_INT integer

[source]

property UNSIGNED_INT_VEC4 integer

[source]

property UNSIGNED_SHORT integer

[source]

property VERTEX_ARRAY integer

[source]

property VERTEX_ATTRIB_ARRAY_BARRIER_BIT integer

[source]

property VERTEX_SHADER integer

[source]

property VIEWPORT_BIT integer

[source]

property WRITE_ONLY integer

[source]

property XOR integer

[source]

property ZERO integer

[source]

class GroundMoveType inherits from GenericMoveType

[source]

property accRate number?

property atEndOfPath boolean?

property atGoal boolean?

property decRate number?

property maxReverseDist number?

property maxReverseSpeed number?

property minReverseAngle number?

property minScriptChangeHeading integer?

property myGravity number?

property pushResistant boolean?

property sqSkidSpeedMult number?

property turnAccel number?

property turnRate number?

alias HashType is (0|1)

[source]

alias Heading is integer

Integer in range [-32768, 32767] that represents a 2D (xz plane) unit orientation.

                  F(N=2) = H(-32768 / 32767)

                         ^
                         |
                         |
 F(W=3) = H(-16384)  <---o--->  F(E=1) = H(16384)
                         |
                         |
                         v

                  F(S=0) = H(0)

[source]

class HoverAirMoveType inherits from GenericMoveType

[source]

property accRate number?

property airStrafe boolean?

property altitudeRate number?

property bankingAllowed boolean?

property collide boolean?

property currentBank number?

property currentPitch number?

property decRate number?

property dontLand boolean?

property maxDrift number?

property turnRate number?

property useSmoothMesh boolean?

property wantedHeight number?

class Intro inherits from Callins

[source]

function DrawLoadScreen()

Draws custom load screens.

[source]

function LoadProgress(message, replaceLastLine)

Parameters

message : string
replaceLastLine : boolean

[source]

class KeyBinding

Contains data about a keybinding

[source]

property boundWith string

property command string

property extra string

class KeyModifiers

Key Modifier Params

[source]

property alt boolean

Alt key pressed

property ctrl boolean

Ctrl key pressed

property right boolean

Right mouse key pressed

property shift boolean

Shift key pressed

class LightParams

Parameters for lighting

[source]

property ambientColor { blue: number, green: number, red: number }

property ambientDecayRate { ambientBlueDecay: number, ambientGreenDecay: number, ambientRedDecay: number }

Per-frame decay of ambientColor (spread over TTL frames)

property decayFunctionType { ambientDecayType: number, diffuseDecayType: number, specularDecayType: number }

If value is 0.0 then the *DecayRate values will be interpreted as linear, otherwise exponential.

property diffuseColor { blue: number, green: number, red: number }

property diffuseDecayRate { diffuseBlueDecay: number, diffuseGreenDecay: number, diffuseRedDecay: number }

Per-frame decay of diffuseColor (spread over TTL frames)

property direction { dx: number, dy: number, dz: number }

property fov number

property ignoreLOS boolean

property intensityWeight { ambientWeight: number, diffuseWeight: number, specularWeight: number }

property position { px: number, py: number, pz: number }

property priority number

property radius number

property specularColor { blue: number, green: number, red: number }

property specularDecayRate { specularBlueDecay: number, specularGreenDecay: number, specularRedDecay: number }

Per-frame decay of specularColor (spread over TTL frames)

property ttl number

enum LOG is (40|35|50|37|20|30…)

[source]

property DEBUG integer: 20

property DEPRECATED integer: 37

property ERROR integer: 50

property FATAL integer: 60

property INFO integer: 30

property NOTICE integer: 35

Engine default.

property WARNING integer: 40

alias LogLevel is (integer|“debug”|“info”|“notice”|“warning”|“deprecated”|“error”|“fatal”)

[source]

class losAccess

Parameters for los access

If one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with inradar=true even if the param has inlos=false) All GameRulesParam are public, TeamRulesParams can just be private,allied and/or public You can read RulesParams from any Lua environments! With those losAccess policies you can limit their access.

All GameRulesParam are public, TeamRulesParams can just be private,allied and/or public You can read RulesParams from any Lua environments! With those losAccess policies you can limit their access.

[source]

property allied boolean?

readable by ally + ingame allied

property inlos boolean?

readable if the unit is in LOS

property inradar boolean?

readable if the unit is in AirLOS

property private boolean?

only readable by the ally (default)

property public boolean?

readable by all

enum LosMask is (2|4|8|1)

[source]

property CONTRADAR integer: 8

the unit has continuously been in radar since it was last inlos by the allyteam

property INLOS integer: 1

the unit is currently in the los of the allyteam

property INRADAR integer: 2

the unit is currently in radar from the allyteam

property PREVLOS integer: 4

the unit has previously been in los from the allyteam

alias LosTable is table<(“los”|“radar”|“prevLos”|“contRadar”),boolean>

[source]

class LuaFont

Lua opengl font object.

[source]

function Begin(userDefinedBlending)

Parameters

userDefinedBlending : boolean? - When `true` doesn't set the gl.BlendFunc automatically. Defaults to `false`.

Begin a block of font commands.

[source]

Fonts can be printed without using Start/End, but when doing several operations it’s more optimal if done inside a block.

Also allows disabling automatic setting of the blend mode. Otherwise the font will always print with BlendFunc(GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA).

(See: )

function SubmitBuffered(noBillboarding, userDefinedBlending)

Parameters

noBillboarding : boolean? - When `false` sets 3d billboard mode. Defaults to `true`.
userDefinedBlending : boolean? - When `true` doesn't set the gl.BlendFunc automatically. Defaults to `false`.

Draws text printed with the buffered option.

[source]

(See: )

class MapRenderingParams

Map rendering params

[source]

property splatDetailNormalDiffuseAlpha boolean

property splatTexMults rgba

property splatTexScales rgba

property voidGround boolean

property voidWater boolean

class Material

[source]

property ambidiff (rgb|rgba)

property ambient (rgb|rgba)

property diffuse (rgb|rgba)

property emission (rgb|rgba)

property shininess number

property specular (rgb|rgba)

class Matrix4x4

[source]

alias MatrixName is (“view”|“projection”|“viewprojection”|“viewinverse”|“projectioninverse”|“viewprojectioninverse”|“billboard”|“shadow”…)

[source]

class Menu inherits from Callins

[source]

function ActivateGame()

Called whenever LuaMenu is on with a game loaded.

[source]

function ActivateMenu()

Called whenever LuaMenu is on with no game loaded.

[source]

function AllowDraw()

Returns

allowDraw : boolean

Enables Draw{Genesis,Screen,ScreenPost} callins if true is returned, otherwise they are called once every 30 seconds. Only active when a game isn’t running.

[source]

alias ModType is (0|1|3|4)

[source]

class MoveCtrl

function Disable(unitID)

Parameters

unitID : integer

[source]

function Enable(unitID)

Parameters

unitID : integer

[source]

function GetTag(tag)

Parameters

tag : integer?

[source]

function IsEnabled(unitID)

Parameters

unitID : integer

Returns

isEnabled : boolean?

[source]

function SetAirMoveTypeData(unitID, moveType)

Parameters

unitID : integer
moveType : StrafeAirMoveType

Returns

numAssignedValues : number

[source]

function SetAirMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (GenericMoveTypeBooleanKey|“collide”|“useSmoothMesh”|“loopbackAttack”)
value : boolean

Returns

numAssignedValues : number

[source]

function SetAirMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (GenericMoveTypeNumberKey|“wantedHeight”|“turnRadius”|“accRate”|“decRate”|“maxAcc”|“maxDec”|“maxBank”…)
value : number

Returns

numAssignedValues : number

[source]

function SetAirMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (“maneuverBlockTime”)
value : integer

Returns

numAssignedValues : number

[source]

function SetCollideStop(unitID, collideStop)

Parameters

unitID : integer
collideStop : boolean

[source]

function SetDrag(unitID, drag)

Parameters

unitID : integer
drag : number

[source]

function SetExtrapolate(unitID, extrapolate)

Parameters

unitID : integer
extrapolate : boolean

[source]

function SetGravity(unitID, gravityFactor)

Parameters

unitID : integer
gravityFactor : number

[source]

function SetGroundMoveTypeData(unitID, moveType)

Parameters

unitID : integer
moveType : GroundMoveType

Returns

numAssignedValues : number

[source]

function SetGroundMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (GenericMoveTypeBooleanKey|“atGoal”|“atEndOfPath”|“pushResistant”)
value : boolean

Returns

numAssignedValues : number

[source]

function SetGroundMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (GenericMoveTypeNumberKey|“turnRate”|“turnAccel”|“accRate”|“decRate”|“myGravity”|“maxReverseDist”|“minReverseAngle”…)
value : number

Returns

numAssignedValues : number

[source]

function SetGroundMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (“minScriptChangeHeading”)
value : integer

Returns

numAssignedValues : number

[source]

function SetGroundOffset(unitID, groundOffset)

Parameters

unitID : integer
groundOffset : number

[source]

function SetGunshipMoveTypeData(unitID, moveType)

Parameters

unitID : integer
moveType : HoverAirMoveType

Returns

numAssignedValues : number

[source]

function SetGunshipMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (GenericMoveTypeBooleanKey|“collide”|“dontLand”|“airStrafe”|“useSmoothMesh”|“bankingAllowed”)
value : boolean

Returns

numAssignedValues : number

[source]

function SetGunshipMoveTypeData(unitID, key, value)

Parameters

unitID : integer
key : (GenericMoveTypeNumberKey|“wantedHeight”|“accRate”|“decRate”|“turnRate”|“altitudeRate”|“currentBank”|“currentPitch”…)
value : number

Returns

numAssignedValues : number

[source]

function SetHeading(unitID, heading)

Parameters

unitID : integer
heading : Heading

[source]

function SetLimits(unitID, minX, minY, minZ, maxX, maxY, maxZ)

Parameters

unitID : integer
minX : number - Minimum position X component.
minY : number - Minimum position Y component.
minZ : number - Minimum position Z component.
maxX : number - Maximum position X component.
maxY : number - Maximum position Y component.
maxZ : number - Maximum position Z component.

[source]

function SetLimitsStop(unitID, limitsStop)

Parameters

unitID : integer
limitsStop : boolean

[source]

function SetMoveDef(unitID, moveDef)

Parameters

unitID : integer
moveDef : (integer|string) - Name or path type of the MoveDef.

Returns

success : boolean - `true` if the `MoveDef` was set, `false` if `unitID` or `moveDef` were invalid, or if the unit does not support a `MoveDef`.

[source]

function SetNoBlocking(unitID, noBlocking)

Parameters

unitID : integer
noBlocking : boolean

[source]

function SetPhysics(unitID, posX, posY, posZ, velX, velY, velZ, rotX, rotY, rotZ)

Parameters

unitID : integer
posX : number - Position X component.
posY : number - Position Y component.
posZ : number - Position Z component.
velX : number - Velocity X component.
velY : number - Velocity Y component.
velZ : number - Velocity Z component.
rotX : number - Rotation X component.
rotY : number - Rotation Y component.
rotZ : number - Rotation Z component.

[source]

function SetPosition(unitID, posX, posY, posZ)

Parameters

unitID : integer
posX : number - Position X component.
posY : number - Position Y component.
posZ : number - Position Z component.

[source]

function SetProgressState(unitID, state)

Parameters

unitID : integer
state : (0|1|2|“done”|“active”|“failed”)

[source]

function SetRelativeVelocity(unitID, relVelX, relVelY, relVelZ)

Parameters

unitID : integer
relVelX : number - Relative velocity X component.
relVelY : number - Relative velocity Y component.
relVelZ : number - Relative velocity Z component.

[source]

function SetRotation(unitID, rotX, rotY, rotZ)

Parameters

unitID : integer
rotX : number - Rotation X component.
rotY : number - Rotation Y component.
rotZ : number - Rotation Z component.

[source]

function SetRotationOffset()

DEPRECATED:

[source]

function SetRotationVelocity(unitID, rotVelX, rotVelY, rotVelZ)

Parameters

unitID : integer
rotVelX : number - Rotation velocity X component.
rotVelY : number - Rotation velocity Y component.
rotVelZ : number - Rotation velocity Z component.

[source]

function SetTag(unitID, tag)

Parameters

unitID : integer
tag : integer

[source]

function SetTrackGround(unitID, trackGround)

Parameters

unitID : integer
trackGround : boolean

[source]

function SetTrackLimits(unitID, trackLimits)

Parameters

unitID : integer
trackLimits : boolean

[source]

function SetTrackSlope(unitID, trackSlope)

Parameters

unitID : integer
trackSlope : boolean

[source]

function SetVelocity(unitID, velX, velY, velZ)

Parameters

unitID : integer
velX : number - Velocity X component.
velY : number - Velocity Y component.
velZ : number - Velocity Z component.

[source]

function SetWindFactor(unitID, windFactor)

Parameters

unitID : integer
windFactor : number

[source]

class PieceInfo

[source]

property children string[]

names

property empty boolean

property max (number,number,number)

(x,y,z)

property min (number,number,number)

(x,y,z)

property name string

property offset (number,number,number)

(x,y,z)

property parent string

class Plane

[source]

property d number

property normalVecX number

property normalVecY number

property normalVecZ number

class PlatformVideoMode

[source]

property bpp integer

[source]

property display integer

[source]

property displayName string

[source]

property h number

[source]

property hz number

[source]

property w number

[source]

class ProjectileParams

[source]

property cegTag string

property end xyz

property endAlpha number

property error xyz

property gravity number

property maxRange number

property model string

property owner integer

property pos xyz

property speed xyz

property spread xyz

property startAlpha number

property team integer

property tracking number

property ttl number

enum ProjectileTargetType is (102|112|117)

[source]

property feature integer: 102

ASCII number for the character f

property projectile integer: 112

ASCII number for the character p

property unit integer: 117

ASCII number for the character u

class RBO

User Data RBO

[source]

property format GL

property samples integer

will return globalRendering->msaaLevel for multisampled RBO or 0 otherwise

property target GL

property valid boolean

property xsize integer

property ysize integer

enum READY_MESSAGE is (“Choose start pos”|“Waiting for players, press key to force start"|“Starting in n”|“Waiting for players”)

[source]

property CHOOSE_POS string: "Choose start pos"

when current player is not ready and is not a spectator

property HOST_WAITING string: "Waiting for players, press key to force start"

when waiting and currently the host, key is the first key bound to the action forcestart

property STARTING string: "Starting in n"

where n is the number of seconds

property WAITING string: "Waiting for players"

enum READY_STATE is (“notready”|“missing”|“ready”)

[source]

property MISSING string: "missing"

when the player hasn’t joined yet (NETMSG_PLAYERNAME wasn’t received)

property NOT_READY string: "notready"

property READY string: "ready"

class ResourceCost

[source]

property energy number

property metal number

alias ResourceName is (“metal”|“energy”|“m”|“e”)

alias ResourceUsage is table<ResourceName,number>

class rgb

Color triple (RGB)

class rgba

Color quadruple (RGBA)

class RmlUi.Context

Holds documents and a data model.

The Context class has no constructor; it must be instantiated through the CreateContext() function. It has the following functions and properties:

[source]

function ActivateTheme(theme_name, activate)

Parameters

theme_name : string
activate : boolean

Activates a theme for the context.

[source]

function AddEventListener(event, script, element_context, in_capture_phase)

Parameters

event : string
script : RmlUi.Element
element_context : boolean
in_capture_phase : boolean

Adds the inline Lua script, script, as an event listener to the context. element_context is an optional Element; if it is not None, then the script will be executed as if it was bound to that element.

[source]

function CreateDocument(tag)

Parameters

tag : string

Returns

: RmlUi.Document

Creates a new document with the tag name of tag.

[source]

property dimensions [RmlUi.Vector](#type-RmlUi-Vector)2i

[source]

property documents RmlUi.Document[]

[source]

property dp_ratio number

[source]

function EnableMouseCursor(enable)

Parameters

enable : boolean

Enables or disables the mouse cursor for the context.

[source]

property focus_element RmlUi.Element

[source]

function GetDocument(name)

Parameters

name : string

[source]

function GetElementAtPoint(point, ignore)

Parameters

point : RmlUi.Vector2f
ignore : RmlUi.Element?

Returns

: RmlUi.Element

Returns the element at the point specified by point.

[source]

property hover_element RmlUi.Element

[source]

function IsMouseInteracting()

Returns

: boolean

Returns true if the mouse is currently interacting with the context, false if not.

[source]

function IsThemeActive(theme_name)

Parameters

theme_name : string

Returns

: boolean

Returns true if the theme is active, false if not.

[source]

function LoadDocument(document_path)

Parameters

document_path : string

Returns

: RmlUi.Document

Attempts to load a document from the RML file found at document_path. If successful, the document will be returned with a reference count of one.

[source]

property name string

[source]

function OpenDataModel <T>(name, model, widget)

Parameters

name : string
model : T
widget : table

Returns

: SolLuaDataModel

Create a new data model from a base table model and register to the context. The model table is copied. Note that widget does not actually have to be a widget; it can be any table. This table can be accessed in widgets like <button class="mode-button" onclick="widget:SetCamMode()">Set Dolly Mode</button>. Also note that your data model is inaccessible in onx properties.

[source]

function ProcessKeyDown(key, key_modifier_state)

Parameters

key : RmlUi.key_identifier
key_modifier_state : integer

Returns

: boolean

Processes a key down event.

[source]

function ProcessKeyUp(key, key_modifier_state)

Parameters

key : RmlUi.key_identifier
key_modifier_state : integer

Returns

: boolean

Processes a key up event.

[source]

function ProcessMouseButtonDown(button, key_modifier_state)

Parameters

button : RmlUi.MouseButton
key_modifier_state : integer

Returns

: boolean

Processes a mouse button down event.

[source]

function ProcessMouseButtonUp(button, key_modifier_state)

Parameters

button : RmlUi.MouseButton
key_modifier_state : integer

Returns

: boolean

Processes a mouse button up event.

[source]

function ProcessMouseLeave()

Returns

: boolean

Processes a mouse leave event.

[source]

function ProcessMouseMove(position)

Parameters

position : RmlUi.Vector2f

Returns

: boolean

Processes a mouse move event.

[source]

function ProcessMouseWheel(delta, key_modifier_state)

Parameters

delta : (RmlUi.Vector2f|number)
key_modifier_state : integer

Returns

: boolean

Processes a mouse wheel event.

[source]

function ProcessTextInput(text)

Parameters

text : string

Returns

: boolean

Processes a text input event.

[source]

function PullDocumentToFront(document)

Parameters

document : RmlUi.Document

Pulls the document to the front of the context.

[source]

function PushDocumentToBack(document)

Parameters

document : RmlUi.Document

Pushes the document to the back of the context.

[source]

function RemoveDataModel(name)

Parameters

name : string

Removes a data model from the context.

[source]

function Render()

Returns

: boolean

Renders the context.

[source]

property root_element RmlUi.Element

[source]

function UnloadAllDocuments()

Closes all documents currently loaded with the context.

[source]

function UnloadDocument(document)

Parameters

document : RmlUi.Document

Unloads a specific document within the context.

[source]

function Update()

Returns

: boolean

Updates the context.

[source]

enum RmlUi.default_action_phase is integer

[source]

property Auto integer

[source]

property Target integer

[source]

property TargetAndBubble integer

[source]

class RmlUi.Document inherits from RmlUi.Element

Document derives from Element.

Document has no constructor; it must be instantiated through a Context object instead, either by loading an external RML file or creating an empty document. It has the following functions and properties:

[source]

function AppendToStyleSheet(content)

Parameters

content : string

Append text to style sheet.

[source]

function Close()

Hides and closes the document, destroying its contents.

[source]

property context RmlUi.Context

[source]

function CreateElement(tag_name)

Parameters

tag_name : string

Returns

: RmlUi.ElementPtr

Instances an element with a tag of tag_name.

[source]

function CreateTextNode(text)

Parameters

text : string

Returns

: RmlUi.ElementPtr

Instances a text element containing the string text.

[source]

function Hide()

Hides the document.

[source]

function LoadExternalScript(source_path)

Parameters

source_path : string

Load an external script.

[source]

function LoadInlineScript(content, source, source_line)

Parameters

content : string
source : string?
source_line : integer?

Load scripts as if it were in the script tag.

[source]

property modal boolean

[source] Is it modal?

function PullToFront()

Pulls the document in front of other documents within its context with a similar z-index.

[source]

function PushToBack()

Pushes the document behind other documents within its context with a similar z-index.

[source]

function ReloadStyleSheet(load)

Parameters

load : boolean?

Reload the active style sheet.

[source]

function Show(modal, focus)

Parameters

modal : RmlUi.RmlModalFlag? - Defaults to Focus
focus : RmlUi.RmlFocusFlag?

Shows the document.

[source]

property title string

[source]

function UpdateDocument()

Update the Document.

[source]

property url string

[source]

property widget table

[source] A table of data that can be accessed in onevent attributes. It doesn’t have to be a widget.

class RmlUi.Element

Represents an element in the RmlUi document tree. This class cannot be constructed directly; use a Document object to instantiate elements. This is the foundational piece of the DOM.

[source]

property absolute_left integer

[source] Read-only. The absolute left position of the element relative to the document.

property absolute_top integer

[source] Read-only. The absolute top position of the element relative to the document.

function AddEventListener(event, listener, in_capture_phase)

Parameters

event : string
listener : (function|string)
in_capture_phase : boolean

Adds an event listener to the element.

[source]

property address string

[source] Read-only. The address of the element in the document tree.

function AppendChild(element)

Parameters

element : RmlUi.ElementPtr

Returns

: RmlUi.ElementPtr

Appends element as a child to this element.

[source]

function ArePseudoCLassesSet(class_names)

Parameters

class_names : string[]

Returns

: boolean

[source]

property attributes RmlUi.ElementAttributesProxy

[source] Read-only. Proxy for accessing element attributes.

property baseline integer

[source] Read-only. The baseline position of the element.

function Blur()

Removes input focus from this element.

[source]

property child_nodes RmlUi.ElementChildNodesProxy

[source] Read-only. Proxy for accessing child nodes of the element.

property class_name string

[source] Name of the class.

function Click()

Fakes a click on this element.

[source]

property client_height integer

[source] Read-only. The inner height of the element in pixels, including padding but not the horizontal scrollbar height, border, or margin.

property client_left integer

[source] Read-only. The width of the left border of the element in pixels.

property client_top integer

[source] Read-only. The width of the top border of the element in pixels.

property client_width integer

[source] Read-only. The inner width of the element in pixels, including padding but not the vertical scrollbar width, border, or margin.

function Clone()

Returns

: RmlUi.ElementPtr

[source]

function Closest()

Returns

: RmlUi.Element?

[source]

function DispatchEvent(event, parameters, interruptible)

Parameters

event : string
parameters : table
interruptible : string

Returns

: boolean

Dispatches an event to this element.

[source]

property first_child RmlUi.Element?

[source] Read-only. The first child element, or nil if there are no children.

function Focus()

Gives input focus to this element.

[source]

function GetActivePseudoCLasses()

Returns

: string[]

[source]

function GetAttribute(name)

Parameters

name : string

Returns

: any

Returns the value of the attribute named name. If no such attribute exists, the empty string will be returned.

[source]

function GetChild(index)

Parameters

index : integer

Returns

: RmlUi.Element?

[source]

function GetElementById(id)

Parameters

id : string

Returns

: RmlUi.Element

Returns the descendant element with an id of id.

[source]

function GetElementsByClassName(class_name)

Parameters

class_name : string

Returns

: RmlUi.Element[]

[source]

function GetElementsByTagName(tag_name)

Parameters

tag_name : string

Returns

: RmlUi.ElementPtr[]

Returns a list of all descendant elements with the tag of tag_name.

[source]

function GetValue()

Returns

value : (number|string|"") - Returns number if it has the tag "input", a string if it has the tag "textarea", else an empty string.

Get the value of this element.

[source]

function HasAttribute(name)

Parameters

name : string

Returns

: boolean

Returns True if the element has a value for the attribute named name, False if not.

[source]

function HasChildNodes()

Returns

: boolean

Returns True if the element has at least one child node, false if not.

[source]

property id string

[source] ID of this element, in the context of <span id="foo">.

property inner_rml string

[source] Gets or sets the inner RML (markup) content of the element.

function InsertBefore(element, adjacent_element)

Parameters

element : RmlUi.ElementPtr
adjacent_element : RmlUi.Element

Returns

: RmlUi.Element?

Inserts the element element as a child of this element, directly before adjacent_element in the list of children.

[source]

function IsClassSet(name)

Parameters

name : string

Returns

: boolean

Returns true if the class name is set on the element, false if not.

[source]

function IsPointWithinElement(point)

Parameters

point : [RmlUi.Vector](#type-RmlUi-Vector)2i

Returns

: boolean

Is a screen-space point within this element?

[source]

function IsPseudoClassSet(class_name)

Parameters

class_name : string

Returns

: boolean

[source]

property last_child RmlUi.Element?

[source] Read-only. The last child element, or nil if there are no children.

property line_height integer

[source] Read-only. The computed line height of the element.

property next_sibling RmlUi.Element?

[source] Read-only. The next sibling element, or nil if there is none.

property offset_height integer

[source] Read-only. The height of the element including vertical padding and borders, in pixels.

property offset_left integer

[source] Read-only. The distance from the inner left edge of the offset parent, in pixels.

property offset_parent RmlUi.Element

[source] Read-only. The closest positioned ancestor element.

property offset_top integer

[source] Read-only. The distance from the inner top edge of the offset parent, in pixels.

property offset_width integer

[source] Read-only. The width of the element including horizontal padding and borders, in pixels.

property owner_document RmlUi.Document

[source] Read-only. The document that owns this element.

property parent_node RmlUi.Element?

[source] Read-only. The parent node of this element, or nil if there is none.

property previous_sibling RmlUi.Element?

[source] Read-only. The previous sibling element, or nil if there is none.

function ProcessDefaultAction(event)

Parameters

event : RmlUi.Event

[source]

function QuerySelector(query)

Parameters

query : string

Returns

: RmlUi.ElementPtr

Unsure what this does, but seems powerful?

[source]

function QuerySelectorAll(selectors)

Parameters

selectors : string

Unsure what this does, but seems powerful?

[source]

function RemoveAttribute(name)

Parameters

name : string

Removes the attribute named name from the element.

[source]

function RemoveChild(element)

Parameters

element : RmlUi.Element

Returns

: boolean

Removes the child element element from this element.

[source]

function ReplaceChild(inserted_element, replaced_element)

Parameters

inserted_element : RmlUi.ElementPtr
replaced_element : RmlUi.Element

Returns

: boolean

Replaces the child element replaced_element with inserted_element in this element’s list of children. If replaced_element is not a child of this element, inserted_element will be appended onto the list instead.

[source]

property scroll_height integer

[source] Read-only. The total height of the element’s content, including content not visible on the screen due to overflow.

property scroll_left integer

[source] Gets or sets the number of pixels that the content of the element is scrolled from the left.

property scroll_top integer

[source] Gets or sets the number of pixels that the content of the element is scrolled from the top.

property scroll_width integer

[source] Read-only. The total width of the element’s content, including content not visible on the screen due to overflow.

function ScrollIntoView(align_with_top)

Parameters

align_with_top : boolean

Scrolls this element into view if its ancestors have hidden overflow.

[source]

function SetAttribute(name, value)

Parameters

name : string
value : string

Sets the value of the attribute named name to value.

[source]

function SetClass(name, value)

Parameters

name : string
value : boolean

Sets (if value is true) or clears (if value is false) the class name on the element.

[source]

function SetPseudoClass(class_name)

Parameters

class_name : string

[source]

property style RmlUi.ElementStyleProxy

[source] Read-only. Proxy for accessing and modifying the element’s style properties.

property tag_name string

[source] Read-only. The tag name of the element.

property visible boolean

[source] Read-only. True if the element is visible, false otherwise.

property z_index integer

[source] Read-only. The computed z-index of the element.

alias RmlUi.ElementAttributesProxy is { [string]: (string|number|boolean) }

Contains all the attributes of an element: The stuff in the opening tag i.e. <span class="my-class">

[source]

alias RmlUi.ElementChildNodesProxy is RmlUi.Element[]

Contains a list of all child elements.

[source]

class RmlUi.ElementForm inherits from RmlUi.Element

[source]

function Submit(name, value)

Parameters

name : string?
value : string?

[source]

class RmlUi.ElementFormControl inherits from RmlUi.Element

[source]

property disabled boolean

[source]

property name string

[source]

property submitted boolean

[source]

property value string

[source]

class RmlUi.ElementFormControlInput inherits from RmlUi.ElementRmlUi.ElementFormControl

[source]

property checked boolean

[source]

property max integer

[source]

property maxlength integer

[source]

property min integer

[source]

property size integer

[source]

property step integer

[source]

class RmlUi.ElementFormControlSelect inherits from RmlUi.ElementRmlUi.ElementFormControl

[source]

function Add(element, before)

Parameters

element : RmlUi.Element
before : integer?

[source]

function Remove(index)

Parameters

index : integer

[source]

function RemoveAll()

[source]

class RmlUi.ElementFormControlTextArea inherits from RmlUi.ElementRmlUi.ElementFormControl

[source]

property cols integer

[source]

property maxlength integer

[source]

property rows integer

[source]

property wordwrap boolean

[source]

class RmlUi.ElementProgress inherits from RmlUi.Element

[source]

property max number

[source]

property value number

[source]

class RmlUi.ElementPtr

Represents an owned element.

This type is mainly used to modify the DOM tree by passing the object into other elements. For example RmlUi.Element:AppendChild(). A current limitation in the Lua plugin is that Element member properties and functions cannot be used directly on this type.

[source]

alias RmlUi.ElementStyleProxy is { [string]: string }

Gets the rcss styles associated with an element. As far as I can tell, the values will always be a string.

[source]

class RmlUi.ElementTabSet inherits from RmlUi.Element

[source]

property active_tab integer

[source]

property num_tabs integer

[source]

function RemoveTab(index)

Parameters

index : integer

[source]

function SetPanel(index, rml)

Parameters

index : integer
rml : string

Sets the contents of a panel to the RML content rml. If index is out-of-bounds, a new panel will be added at the end.

[source]

function SetTab(index, rml)

Parameters

index : integer
rml : string

Sets the contents of a tab to the RML content rml. If index is out-of-bounds, a new tab will be added at the end.

[source]

class RmlUi.ElementText inherits from RmlUi.Element

[source]

property text string

[source]

class RmlUi.Event

An event that happens to an element.

[source]

property current_element RmlUi.Element

[source]

property event_phase RmlUi.RmlEventPhase

[source]

property immediate_propagating boolean

[source]

property interruptible boolean

[source]

property parameters RmlUi.EventParametersProxy

[source]

property propagating boolean

[source]

property target_element RmlUi.Element

[source] What element it happened to

property type string

[source]

alias RmlUi.EventID is (0|1|2|3|4|5|6|7…)

[source]

class RmlUi.EventListener

Event listener interface

[source]

function OnAttach(element)

Parameters

element : RmlUi.Element

[source]

function OnDetach(element)

Parameters

element : RmlUi.Element

[source]

function ProcessEvent(event)

Parameters

event : RmlUi.Event

[source]

class RmlUi.EventParametersProxy

Keyboard and mouse input data associated with an event.

[source]

property alt_key RmlUi.EventParametersProxy.TrueFalse

property button RmlUi.EventParametersProxy.MouseButton

property caps_lock_key RmlUi.EventParametersProxy.TrueFalse

property ctrl_key RmlUi.EventParametersProxy.TrueFalse

property meta_key RmlUi.EventParametersProxy.TrueFalse

property mouse_x integer

property mouse_y integer

property scroll_lock_key RmlUi.EventParametersProxy.TrueFalse

property shift_key RmlUi.EventParametersProxy.TrueFalse

alias RmlUi.EventParametersProxy.MouseButton is (0|1|2)

[source]

alias RmlUi.EventParametersProxy.TrueFalse is (0|1)

RmlUi uses 0 and 1 to represent boolean values here.

[source]

enum RmlUi.font_weight is integer

[source]

property Auto integer

[source]

property Bold integer

[source]

property Normal integer

[source]

enum RmlUi.key_identifier is integer

[source]

property 0 integer

property A integer

[source]

property ACCEPT integer

[source]

property ADD integer

[source]

property APPS integer

[source]

property ATTN integer

[source]

property B integer

[source]

property BACK integer

[source]

property BROWSER_BACK integer

[source]

property BROWSER_FAVORITES integer

[source]

property BROWSER_FORWARD integer

[source]

property BROWSER_HOME integer

[source]

property BROWSER_REFRESH integer

[source]

property BROWSER_SEARCH integer

[source]

property BROWSER_STOP integer

[source]

property C integer

[source]

property CAPITAL integer

[source]

property CLEAR integer

[source]

property CONVERT integer

[source]

property CRSEL integer

[source]

property D integer

[source]

property DECIMAL integer

[source]

property DELETE integer

[source]

property DIVIDE integer

[source]

property DOWN integer

[source]

property E integer

[source]

property END integer

[source]

property EREOF integer

[source]

property ESCAPE integer

[source]

property EXECUTE integer

[source]

property EXSEL integer

[source]

property F integer

[source]

property F1 integer

[source]

property F10 integer

[source]

property F11 integer

[source]

property F12 integer

[source]

property F13 integer

[source]

property F14 integer

[source]

property F15 integer

[source]

property F16 integer

[source]

property F17 integer

[source]

property F18 integer

[source]

property F19 integer

[source]

property F2 integer

[source]

property F20 integer

[source]

property F21 integer

[source]

property F22 integer

[source]

property F23 integer

[source]

property F24 integer

[source]

property F3 integer

[source]

property F4 integer

[source]

property F5 integer

[source]

property F6 integer

[source]

property F7 integer

[source]

property F8 integer

[source]

property F9 integer

[source]

property FINAL integer

[source]

property G integer

[source]

property H integer

[source]

property HANGUL integer

[source]

property HANJA integer

[source]

property HELP integer

[source]

property HOME integer

[source]

property I integer

[source]

property ICO_00 integer

[source]

property ICO_CLEAR integer

[source]

property ICO_HELP integer

[source]

property INSERT integer

[source]

property J integer

[source]

property JUNJA integer

[source]

property K integer

[source]

property KANA integer

[source]

property KANJI integer

[source]

property L integer

[source]

property LAUNCH_APP1 integer

[source]

property LAUNCH_APP2 integer

[source]

property LAUNCH_MAIL integer

[source]

property LAUNCH_MEDIA_SELECT integer

[source]

property LCONTROL integer

[source]

property LEFT integer

[source]

property LMENU integer

[source]

property LSHIFT integer

[source]

property LWIN integer

[source]

property M integer

[source]

property MEDIA_NEXT_TRACK integer

[source]

property MEDIA_PLAY_PAUSE integer

[source]

property MEDIA_PREV_TRACK integer

[source]

property MEDIA_STOP integer

[source]

property MODECHANGE integer

[source]

property MULTIPLY integer

[source]

property N integer

[source]

property NEXT integer

[source]

property NONCONVERT integer

[source]

property NUMLOCK integer

[source]

property NUMPAD0 integer

[source]

property NUMPAD1 integer

[source]

property NUMPAD2 integer

[source]

property NUMPAD3 integer

[source]

property NUMPAD4 integer

[source]

property NUMPAD5 integer

[source]

property NUMPAD6 integer

[source]

property NUMPAD7 integer

[source]

property NUMPAD8 integer

[source]

property NUMPAD9 integer

[source]

property NUMPADENTER integer

[source]

property O integer

[source]

property OEM_1 integer

[source]

property OEM_102 integer

[source]

property OEM_2 integer

[source]

property OEM_3 integer

[source]

property OEM_4 integer

[source]

property OEM_5 integer

[source]

property OEM_6 integer

[source]

property OEM_7 integer

[source]

property OEM_8 integer

[source]

property OEM_AX integer

[source]

property OEM_CLEAR integer

[source]

property OEM_COMMA integer

[source]

property OEM_FJ_JISHO integer

[source]

property OEM_FJ_LOYA integer

[source]

property OEM_FJ_MASSHOU integer

[source]

property OEM_FJ_ROYA integer

[source]

property OEM_FJ_TOUROKU integer

[source]

property OEM_MINUS integer

[source]

property OEM_NEC_EQUAL integer

[source]

property OEM_PERIOD integer

[source]

property OEM_PLUS integer

[source]

property P integer

[source]

property PA1 integer

[source]

property PAUSE integer

[source]

property PLAY integer

[source]

property POWER integer

[source]

property PRINT integer

[source]

property PRIOR integer

[source]

property PROCESSKEY integer

[source]

property Q integer

[source]

property R integer

[source]

property RCONTROL integer

[source]

property RETURN integer

[source]

property RIGHT integer

[source]

property RMENU integer

[source]

property RSHIFT integer

[source]

property RWIN integer

[source]

property S integer

[source]

property SCROLL integer

[source]

property SELECT integer

[source]

property SEPARATOR integer

[source]

property SLEEP integer

[source]

property SNAPSHOT integer

[source]

property SPACE integer

[source]

property SUBTRACT integer

[source]

property T integer

[source]

property TAB integer

[source]

property U integer

[source]

property UNKNOWN integer

[source]

property UP integer

[source]

property V integer

[source]

property VOLUME_DOWN integer

[source]

property VOLUME_MUTE integer

[source]

property VOLUME_UP integer

[source]

property W integer

[source]

property WAKE integer

[source]

property X integer

[source]

property Y integer

[source]

property Z integer

[source]

property ZOOM integer

[source]

property 1 integer

property 2 integer

property 3 integer

property 4 integer

property 5 integer

property 6 integer

property 7 integer

property 8 integer

property 9 integer

enum RmlUi.key_modifier is integer

[source]

property ALT integer

[source]

property CAPSLOCK integer

[source]

property CTRL integer

[source]

property META integer

[source]

property NUMLOCK integer

[source]

property SCROLLLOCK integer

[source]

property SHIFT integer

[source]

alias RmlUi.MouseButton is (0|1|2)

[source]

enum RmlUi.RmlEventPhase is integer

[source]

property Bubble integer

[source]

property Capture integer

[source]

property None integer

[source]

property Target integer

[source]

enum RmlUi.RmlFocusFlag is integer

[source]

property Auto integer

[source]

property Document integer

[source]

property Keep integer

[source]

property None integer

[source]

enum RmlUi.RmlModalFlag is integer

[source]

property Keep integer

[source]

property Modal integer

[source]

property None integer

[source]

alias RmlUi.SelectOptionsProxy is RmlUi.SelectOptionsProxyNode[]

[source]

alias RmlUi.SelectOptionsProxyNode is { element: RmlUi.Element, value: string }

[source]

class RmlUi.SolLuaDataModel

Handle for a data model.

It is a wrapper around the model table, marked as type T. You can access fields by using normal indexing, but for the moment, the only keys that work are strings. Any index done this way will automatically trigger a rerender. If you need to index any tables or subtables by anything not a string, you will need to use the underlying table, gotten with __GetTable. This will not trigger a rerender. To trigger a rerender manually, use _SetDirty, passing in the name of the top-level entry in your model table that you edited.

[source]

function __SetDirty(property)

Parameters

property : string

Set a table property dirty to trigger a rerender

[source]

alias RmlUi.StyleProxy is { [string]: string }

[source]

class RmlUi.Vector2f

property magnitude number

[source]

function new(x, y)

Parameters

x : number
y : number

Returns

: RmlUi.Vector2f

[source]

property x number

[source]

property y number

[source]

class RmlUi.Vector2i

Two-dimensional integral vector.

[source]

property magnitude number

[source]

function new(x, y)

Parameters

x : integer
y : integer

Returns

: [RmlUi.Vector](#type-RmlUi-Vector)2i

[source]

property x integer

[source]

property y integer

[source]

class Roster

Contains data about a player

[source]

property allyTeamID integer

property cpuUsage number

in order to find the progress, use: cpuUsage&0x1 if it’s PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage»8)*1000 for the progress

property name string

property pingTime number

if -1, the player is pathfinding

property playerID integer

property spectator boolean

property teamID integer

class RulesParams inherits from table<string,integer>

[source]

class RulesSyncedCallins inherits from CallinsUnsyncedCallinsSyncedCallins

Callins that are sent to the synced lua file: LuaRules/main.lua

class RulesUnsyncedCallins inherits from CallinsUnsyncedCallins

Callins that are sent to the unsynced lua file: LuaRules/draw.lua

class SaveImageOptions

[source]

property alpha boolean

(Default: false)

property grayscale16bit boolean

(Default: false)

property readbuffer GL

(Default: current read buffer)

property yflip boolean

(Default: true)

class SetUnitHealthAmounts

[source]

property build number?

Set the unit’s build progress.

property capture number?

Set the unit’s capture progress.

property health number?

Set the unit’s health.

property paralyze number?

Set the unit’s paralyze damage.

enum SFX is integer

[source]

property BLACK_SMOKE integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property BUBBLE integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property CEG integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property DETONATE_WEAPON integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property EXPLODE integer

Piece flag for Spring.UnitScript.Explode.

[source]

property EXPLODE_ON_HIT integer

Piece flag for Spring.UnitScript.Explode.

[source]

property FALL integer

Piece flag for Spring.UnitScript.Explode.

[source]

property FIRE integer

Piece flag for Spring.UnitScript.Explode.

[source]

property FIRE_WEAPON integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property GLOBAL integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property NO_CEG_TRAIL integer

Piece flag for Spring.UnitScript.Explode.

[source]

property NO_HEATCLOUD integer

Piece flag for Spring.UnitScript.Explode.

[source]

property NONE integer

Piece flag for Spring.UnitScript.Explode.

[source]

property RECURSIVE integer

Piece flag for Spring.UnitScript.Explode.

[source]

property REVERSE_WAKE integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property SHATTER integer

Piece flag for Spring.UnitScript.Explode.

[source]

property SMOKE integer

Piece flag for Spring.UnitScript.Explode.

[source]

property VTOL integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property WAKE integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

property WHITE_SMOKE integer

Piece flag for Spring.UnitScript.EmitSfx.

[source]

class ShaderParams

[source]

property definitions string?

string of shader #defines"

property fragment string?

The “Fragment” or Fragment-shader (sometimes called pixel-Shader) is post processing the already rendered picture (for example drawing stars on the sky).

Remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed.

property geoInputType integer?

inType

property geometry string?

The “Geometry” or Geometry-shader can create new vertices and vertice-stripes from points.

property geoOutputType integer?

outType

property geoOutputVerts integer?

maxVerts

property tcs string?

The “TCS” or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage.

property tes string?

The “TES” or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader.

property uniform UniformParam?

property uniformFloat UniformParam?

property uniformInt UniformParam?

property uniformMatrix UniformParam?

property vertex string?

The “Vertex” or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc.

class SideSpec

Side spec

[source]

property caseName string

Original case side name.

property sideName string

Returned when getting arrays of side specifications.

Lowercase side name.

property startUnit string

alias SoundChannel is (“general”|“battle”|“sfx”|“unitreply”|“voice”|“userinterface”|“ui”|0…)

[source]

class SoundDeviceSpec

Contains data about a sound device.

[source]

property name string

alias StorageName is (“metalStorage”|“energyStorage”|“ms”|“es”)

class StrafeAirMoveType inherits from GenericMoveType

[source]

property accRate number?

property attackSafetyDistance number?

property collide boolean?

property decRate number?

property loopbackAttack boolean?

property maneuverBlockTime integer?

property maxAcc number?

Synonym for accRate.

property maxAileron number?

property maxBank number?

property maxDec number?

Synonym for decRate.

property maxElevator number?

property maxPitch number?

property maxRudder number?

property myGravity number?

property turnRadius number?

property useSmoothMesh boolean?

property wantedHeight number?

class SyncedCallins

[source]

Functions called by the Engine (Synced).

function AllowBuilderHoldFire(unitID, unitDefID, action)

Parameters

unitID : integer
unitDefID : integer
action : unknown

Returns

actionAllowed : boolean

Called when a construction unit wants to “use his nano beams”.

[source]

function AllowCommand(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced, fromLua)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
cmdID : integer
cmdParams : number[]
cmdOptions : CommandOptions
cmdTag : number
synced : boolean
fromLua : boolean

Returns

whether : boolean - it should be let into the queue.

Called when the command is given, before the unit’s queue is altered.

[source]

The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.

function AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
playerID : integer

Returns

allow : boolean

Determines if this unit can be controlled directly in FPS view.

[source]

function AllowFeatureBuildStep(builderID, builderTeam, featureID, featureDefID, part)

Parameters

builderID : integer
builderTeam : integer
featureID : integer
featureDefID : integer
part : number

Returns

whether : boolean - or not the change is permitted

Called just before a feature changes its build percentage.

[source]

Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and resurrect they are positive. Part is the percentage the feature be built or reclaimed per frame. Eg. for a 30 workertime builder, that’s a build power of 1 per frame. For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically.

function AllowFeatureCreation(featureDefID, teamID, x, y, z)

Parameters

featureDefID : integer
teamID : integer
x : number
y : number
z : number

Returns

whether : boolean - or not the creation is permitted

Called just before feature is created.

[source]

function AllowResourceLevel(teamID, res, level)

Parameters

teamID : integer
res : string
level : number

Returns

whether : boolean - or not the sharing level is permitted

Called when a team sets the sharing level of a resource.

[source]

function AllowResourceTransfer(oldTeamID, newTeamID, res, amount)

Parameters

oldTeamID : integer
newTeamID : integer
res : string
amount : number

Returns

whether : boolean - or not the transfer is permitted.

Called just before resources are transferred between players.

[source]

function AllowStartPosition(playerID, teamID, readyState, clampedX, clampedY, clampedZ, rawX, rawY, rawZ)

Parameters

playerID : integer
teamID : integer
readyState : number
clampedX : number
clampedY : number
clampedZ : number
rawX : number
rawY : number
rawZ : number

Returns

allow : boolean

Whether a start position should be allowed

[source]

clamped{X,Y,Z} are the coordinates clamped into start-boxes, raw is where player tried to place their marker.

The readyState can be any one of:

0 - player picked a position, 1 - player clicked ready, 2 - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or 3 - the player failed to load. The default ‘failed to choose’ start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.

function AllowUnitBuildStep(builderID, builderTeam, unitID, unitDefID, part)

Parameters

builderID : integer
builderTeam : integer
unitID : integer
unitDefID : integer
part : number

Returns

whether : boolean - or not the build makes progress.

Called just before a unit progresses its build percentage.

[source]

function AllowUnitCaptureStep(builderID, builderTeam, unitID, unitDefID, part)

Parameters

builderID : integer
builderTeam : integer
unitID : integer
unitDefID : integer
part : number

Returns

whether : boolean - or not the capture makes progress.

[source]

function AllowUnitCloak(unitID, enemyID)

Parameters

unitID : integer
enemyID : integer?

Returns

whether : boolean - unit is allowed to cloak

[source]

function AllowUnitCloak(unitID, objectID, weaponNum)

Parameters

unitID : integer
objectID : integer?
weaponNum : number?

Returns

whether : boolean - unit is allowed to decloak

[source]

function AllowUnitCreation(unitDefID, builderID, builderTeam, x, y, z, facing)

Parameters

unitDefID : integer
builderID : integer
builderTeam : integer
x : number
y : number
z : number
facing : FacingInteger

Returns

allow : boolean
dropOrder : boolean

Called just before unit is created.

[source]

function AllowUnitKamikaze(unitID, targetID)

Parameters

unitID : integer
targetID : integer

Returns

whether : boolean - unit is allowed to selfd

[source]

function AllowUnitTransfer(unitID, unitDefID, oldTeam, newTeam, capture)

Parameters

unitID : integer
unitDefID : integer
oldTeam : integer
newTeam : integer
capture : boolean

Returns

whether : boolean - or not the transfer is permitted.

Called just before a unit is transferred to a different team.

[source]

function AllowUnitTransport(transporterID, transporterUnitDefID, transporterTeam, transporteeID, transporteeUnitDefID, transporteeTeam)

Parameters

transporterID : integer
transporterUnitDefID : integer
transporterTeam : integer
transporteeID : integer
transporteeUnitDefID : integer
transporteeTeam : integer

Returns

whether : boolean - or not the transport is allowed

[source]

function AllowUnitTransportLoad(transporterID, transporterUnitDefID, transporterTeam, transporteeID, transporteeUnitDefID, transporteeTeam, x, y, z)

Parameters

transporterID : integer
transporterUnitDefID : integer
transporterTeam : integer
transporteeID : integer
transporteeUnitDefID : integer
transporteeTeam : integer
x : number
y : number
z : number

Returns

whether : boolean - or not the transport load is allowed

[source]

function AllowUnitTransportUnload(transporterID, transporterUnitDefID, transporterTeam, transporteeID, transporteeUnitDefID, transporteeTeam, x, y, z)

Parameters

transporterID : integer
transporterUnitDefID : integer
transporterTeam : integer
transporteeID : integer
transporteeUnitDefID : integer
transporteeTeam : integer
x : number
y : number
z : number

Returns

whether : boolean - or not the transport unload is allowed

[source]

function AllowWeaponInterceptTarget(interceptorUnitID, interceptorWeaponID, targetProjectileID)

Parameters

interceptorUnitID : integer
interceptorWeaponID : integer
targetProjectileID : integer

Returns

allowed : boolean

Controls blocking of a specific intercept target from being considered during an interceptor weapon’s periodic auto-targeting sweep.

[source]

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

(See: )

function AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)

Parameters

attackerID : integer
targetID : integer
attackerWeaponNum : integer
attackerWeaponDefID : integer
defPriority : number

Returns

allowed : boolean
the : number - new priority for this target (if you don't want to change it, return defPriority). Lower priority targets are targeted first.

Controls blocking of a specific target from being considered during a weapon’s periodic auto-targeting sweep.

[source]

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

(See: )

function AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)

Parameters

attackerID : integer
attackerWeaponNum : integer
attackerWeaponDefID : integer

Returns

allowCheck : boolean
ignoreCheck : boolean

Determines if this weapon can automatically generate targets itself. See also commandFire weaponDef tag.

[source]

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

(See: )

function CommandFallback(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
cmdID : integer
cmdParams : number[]
cmdOptions : CommandOptions
cmdTag : number

Returns

whether : boolean - to remove the command from the queue

Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine).

[source]

function FeaturePreDamaged(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Parameters

featureID : integer
featureDefID : integer
featureTeam : integer
damage : number
weaponDefID : integer
projectileID : integer
attackerID : integer
attackerDefID : integer
attackerTeam : integer

Returns

newDamage : number
impulseMult : number

Called before damage is applied to the feature.

[source]

Allows fine control over how much damage and impulse is applied.

function MoveCtrlNotify(unitID, unitDefID, unitTeam, data)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
data : number - was supposed to indicate the type of notification but currently never has a value other than 1 ("unit hit the ground").

Returns

whether : boolean - or not the unit should remain script-controlled (false) or return to engine controlled movement (true).

Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.

[source]

function SendToUnsynced(...)

Parameters

... : (boolean|number|string|table)? - Arguments. Typically the first argument is the name of a function to call. Argument tables will be recursively copied and stripped of unsupported types and metatables.

Invoke UnsyncedCallins:RecvFromSynced callin with the given arguments.

[source]

(See: )

function ShieldPreDamaged(projectileID, projectileOwnerID, shieldWeaponNum, shieldCarrierID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ)

Parameters

projectileID : integer
projectileOwnerID : integer
shieldWeaponNum : integer
shieldCarrierID : integer
bounceProjectile : boolean
beamEmitterWeaponNum : integer
beamEmitterUnitID : integer
startX : number
startY : number
startZ : number
hitX : number
hitY : number
hitZ : number

Returns

if : boolean - true the gadget handles the collision event and the engine does not remove the projectile

Called before any engine shield-vs-projectile logic executes.

[source]

If the weapon is a hitscan type (BeamLaser or LightningCanon) then proID is nil and beamEmitterWeaponNum and beamEmitterUnitID are populated instead.

function TerraformComplete(unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
buildUnitID : integer
buildUnitDefID : integer
buildUnitTeam : integer

Returns

if : boolean - true the current build order is terminated

Called when pre-building terrain levelling terraforms are completed (c.f. levelGround)

[source]

function UnitPreDamaged(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Parameters

unitID : integer
unitDefID : integer
unitTeam : integer
damage : number
paralyzer : boolean
weaponDefID : integer? - Synced Only
projectileID : integer? - Synced Only
attackerID : integer? - Synced Only
attackerDefID : integer? - Synced Only
attackerTeam : integer? - Synced Only

Returns

newDamage : number
impulseMult : number

Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.

[source]

Called after every damage modification (even HitByWeaponId) but before the damage is applied

expects two numbers returned by lua code: 1st is stored under *newDamage if newDamage != NULL 2nd is stored under *impulseMult if impulseMult != NULL

alias TargetType is (0|1|2|3)

[source]

class TeamStats

[source]

property damageDealt number

property damageReceived number

property energyExcess number

property energyProduced number

property energyReceived number

property energySent number

property energyUsed number

property frame number

property metalExcess number

property metalProduced number

property metalReceived number

property metalSent number

property metalUsed number

property time number

property unitsCaptured integer

property unitsDied integer

property unitsOutCaptured integer

property unitsProduced integer

property unitsReceived integer

property unitsSent integer

class TextColorCode

Indicator bytes representing color code operations during font rendering

property Color string

Indicates that the following bytes contain color code information

property ColorAndOutline string

Indicates that the following bytes contain color code and outline information

property Reset string

Indicates reset of the current color

class Texture

[source]

property aniso number?

property compareFunc number?

property format integer?

property lodBias number?

property mag_filter GL?

property min_filter GL?

property target GL?

property wrap_r GL?

property wrap_s GL?

property wrap_t GL?

class TextureInfo

[source]

property id integer

property target GL

property xsize integer

property ysize integer

property zsize integer

class UI inherits from Callins

[source]

function ConfigureLayout()

[source]

alias UniformArrayType is (1|2|3)

[source]

class UniformParam inherits from { [string]: (T|T[]) }

A table of uniform name to value.

The Uniforms are the values you send along with the shader-program. To use them in the shader-program declare them like this: uniform float frame;

Specify a Lua array to initialize GLSL arrays.

The engine will automatically fill in an appropriately named uniform for team colour if it is declared;

uniform vec4 teamColor;

[source]

class UnitDefDimensions

[source]

property height number

property maxx number

property maxy number

property maxz number

property midx number

property midy number

property midz number

property minx number

property miny number

property minz number

property radius number

class UnitState

[source]

property active boolean

property autoland boolean?

property autorepairlevel number?

property cloak boolean

property firestate number

property loopbackattack boolean?

property movestate number

property repeat boolean

property trajectory boolean

class UnsyncedCallins

[source]

Functions called by the Engine (Unsynced).

function DrawFeature(featureID, drawMode)

Parameters

featureID : integer
drawMode : number

Returns

suppressEngineDraw : boolean

DEPRECATED:

For custom rendering of features

[source]

function DrawMaterial(uuid, drawMode)

Parameters

uuid : integer
drawMode : number

Returns

suppressEngineDraw : boolean

DEPRECATED:

[source]

function DrawProjectile(projectileID, drawMode)

Parameters

projectileID : integer
drawMode : number

Returns

suppressEngineDraw : boolean

DEPRECATED:

For custom rendering of weapon (& other) projectiles

[source]

function DrawShield(featureID, weaponID, drawMode)

Parameters

featureID : integer
weaponID : integer
drawMode : number

Returns

suppressEngineDraw : boolean

DEPRECATED:

For custom rendering of shields.

[source]

function DrawUnit(unitID, drawMode)

Parameters

unitID : integer
drawMode : number

Returns

suppressEngineDraw : boolean

DEPRECATED:

For custom rendering of units

[source]

function RecvFromSynced(...)

Parameters

... : any

Receives data sent via SendToUnsynced callout.

[source]

class VAO

Vertex Array Object

[source]

function AddFeatureDefsToSubmission(featureDefIDs)

Parameters

featureDefIDs : (number|number[])

Returns

submittedCount : number

[source]

function AddFeaturesToSubmission(featureIDs)

Parameters

featureIDs : (number|number[])

Returns

submittedCount : number

[source]

function AddUnitDefsToSubmission(unitDefIDs)

Parameters

unitDefIDs : (number|number[])

Returns

submittedCount : number

[source]

function AddUnitsToSubmission(unitIDs)

Parameters

unitIDs : (number|number[])

Returns

submittedCount : number

[source]

function AttachIndexBuffer(vbo)

Parameters

vbo : VBO

Returns

: nil

Attaches a VBO to be used as an index buffer

[source]

function AttachInstanceBuffer(vbo)

Parameters

vbo : VBO

Returns

: nil

Attaches a VBO to be used as an instance buffer

[source]

function AttachVertexBuffer(vbo)

Parameters

vbo : VBO

Returns

: nil

Attaches a VBO to be used as a vertex buffer

[source]

function Delete()

Returns

: nil

[source]

function DrawArrays(glEnum, vertexCount, vertexFirst, instanceCount, instanceFirst)

Parameters

glEnum : number - primitivesMode
vertexCount : number?
vertexFirst : number?
instanceCount : number?
instanceFirst : number?

Returns

: nil

[source]

function DrawElements(glEnum, drawCount, baseIndex, instanceCount, baseVertex, baseInstance)

Parameters

glEnum : number - primitivesMode
drawCount : number?
baseIndex : number?
instanceCount : number?
baseVertex : number?
baseInstance : number?

Returns

: nil

[source]

function RemoveFromSubmission(index)

Parameters

index : number

Returns

: nil

[source]

function Submit()

Returns

: nil

[source]

class VBO

Vertex Buffer Object

[source]

function BindBufferRange(index, elementOffset, elementCount, target)

Parameters

index : integer - should be in the range between `5 < index < GL_MAX_UNIFORM_BUFFER_BINDINGS` value (usually 31)
elementOffset : integer?
elementCount : number?
target : number? - glEnum

Returns

bindingIndex : integer - when successful, -1 otherwise

Bind a range within a buffer object to an indexed buffer target

[source]

Generally mimics https://registry.khronos.org/OpenGL-Refpages/gl4/html/glBindBufferRange.xhtml except offset and size are specified in number of elements / element indices.

function CopyTo(destVBO, copySizeInBytes)

Parameters

destVBO : VBO
copySizeInBytes : integer

Returns

success : boolean

Copy the contents of the VBO to another VBO.

[source]

Destination VBO is expected to have sufficient allocation size, otherwise the copying will gracefully fail.

function Define(size, attribs)

Parameters

size : number - The maximum number of elements this VBO can have.
attribs : (number|VBOAttributeDef[])

Returns

: nil

Specify the kind of VBO you will be using.

terrainVertexVBO:Define(numPoints, {{ id = 0, name = "pos", size = 2 }})

It is usually an array of vertex/color/uv data, but can also be an array of instance uniforms.

If you want to specify multiple instances of something to render, you will need to create another VBO, which also specifies the number of instances you wish to render, and the size of the data passed to each instance.

If you want say 5 elements, and each element is defined in the layout:

{id = 0, name = "first", size = 1},{id = 1, name = "second", size = 2}}

Then the total size of your VBO will be 5 * (1 + 2).

They will be laid out consecutively: [1,2],[1,2],[1,2],[1,2],[1,2].

This is important for when you call VBO:Upload, you need to make sure you enter your data into the Lua array correctly.

[source]

(See: )

function Delete()

Returns

: nil

[source]

function Download(attributeIndex, elementOffset, elementCount, forceGPURead)

Parameters

attributeIndex : integer? - (Default: `-1`) when supplied with non-default value: only data from specified attribute will be downloaded - otherwise all attributes are downloaded
elementOffset : integer? - (Default: `0`) download data starting from this element
elementCount : number? - number of elements to download
forceGPURead : boolean? - (Default: `false`) force downloading the data from GPU buffer as opposed to using shadow RAM buffer

Returns

: unknown

[source]

function DumpDefinition()

Returns

: nil

Logs the definition of the VBO to the console

[source]

function GetBufferSize()

Returns

elementsCount : number
bufferSizeInBytes : number
size : number

[source]

function GetID()

Returns

bufferID : integer

Gets the OpenGL Buffer ID

[source]

function InstanceDataFromFeatureDefIDs(featureDefIDs, attrID, teamIdOpt, elementOffset)

Parameters

featureDefIDs : (number|number[])
attrID : integer
teamIdOpt : integer?
elementOffset : integer?

Returns

instanceData : (number,number,number,number)
elementOffset : integer
attrID : integer

Fills in attribute data for each specified featureDefID

[source]

The instance data in that attribute will contain the offset to bind position matrix in global matrices SSBO and offset to uniform buffer structure in global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as well as some auxiliary data ushc as draw flags and team index.

Data Layout

SInstanceData:
   , traOffset{ matOffset_ }            // updated during the following draw frames
   , uniOffset{ uniOffset_ }            // updated during the following draw frames
   , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames
   , aux1 { 0u }

function InstanceDataFromFeatureIDs(featureIDs, attrID, teamIdOpt, elementOffset)

Parameters

featureIDs : (number|number[])
attrID : integer
teamIdOpt : integer?
elementOffset : integer?

Returns

instanceData : (number,number,number,number)
elementOffset : integer
attrID : integer

Fills in attribute data for each specified featureID

[source]

The instance data in that attribute will contain the offset to bind position matrix in global matrices SSBO and offset to uniform buffer structure in global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as well as some auxiliary data ushc as draw flags and team index.

function InstanceDataFromUnitDefIDs(unitDefIDs, attrID, teamIdOpt, elementOffset)

Parameters

unitDefIDs : (number|number[])
attrID : integer
teamIdOpt : integer?
elementOffset : integer?

Returns

instanceData : (number,number,number,number)
elementOffset : integer
attrID : integer

Fills in attribute data for each specified unitDefID

[source]

The instance data in that attribute will contain the offset to bind position matrix in global matrices SSBO and offset to uniform buffer structure in global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as well as some auxiliary data ushc as draw flags and team index.

Data Layout:

SInstanceData:
   , traOffset{ matOffset_ }            // updated during the following draw frames
   , uniOffset{ uniOffset_ }            // updated during the following draw frames
   , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames
   , aux1 { 0u }

function InstanceDataFromUnitIDs(unitIDs, attrID, teamIdOpt, elementOffset)

Parameters

unitIDs : (number|number[])
attrID : integer
teamIdOpt : integer?
elementOffset : integer?

Returns

instanceData : (number,number,number,number)
elementOffset : integer
attrID : integer

Fills in attribute data for each specified unitID

[source]

The instance data in that attribute will contain the offset to bind position matrix in global matrices SSBO and offset to uniform buffer structure in global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as well as some auxiliary data ushc as draw flags and team index.

Data Layout

SInstanceData:
   , traOffset{ matOffset_ }            // updated during the following draw frames
   , uniOffset{ uniOffset_ }            // updated during the following draw frames
   , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames
   , aux1 { 0u }

function MatrixDataFromProjectileIDs(projectileIDs, attrID, teamIdOpt, elementOffset)

Parameters

projectileIDs : (integer|integer[])
attrID : integer
teamIdOpt : integer?
elementOffset : integer?

Returns

matDataVec : number[] - 4x4 matrix
elemOffset : integer
attrID : (integer|(integer,integer…))

[source]

function ModelsVBO()

Returns

buffer : number? - size in bytes

Binds engine side vertex or index VBO containing models (units, features) data.

[source]

Also fills in VBO definition data as they’re set for engine models (no need to do VBO:Define()).

function UnbindBufferRange(index, elementOffset, elementCount, target)

Parameters

index : integer
elementOffset : integer?
elementCount : number?
target : number? - glEnum

Returns

bindingIndex : number - when successful, -1 otherwise

[source]

function Upload(vboData, attributeIndex, elemOffset, luaStartIndex, luaFinishIndex)

Parameters

vboData : number[] - Array of values to upload into the VBO.
attributeIndex : integer? - (Default: `-1`) If supplied with non-default value then the data from `vboData` will only be used to upload the data to this particular attribute. The whole `vboData` is expected to contain only attributeIndex data. Otherwise all attributes get updated sequentially across attributes and elements.
elemOffset : integer? - (Default: `0`) The index in destination VBO (on GPU) at which storing begins.
luaStartIndex : integer? - (Default: `1`) The index of `vboData` at which copying begins.
luaFinishIndex : integer? - (Default: `#vboData`) The index of `vboData` at which copying ends.

Returns

indexData : number[]
elemOffset : integer
attrID : (integer|(integer,integer…))

Uploads data into the VBO.

[source]

(See: )

class VBOAttributeDef

[source]

property id integer?

property name string?

The location in the vertex shader layout e.g.: layout (location = 0) in vec2 aPos. optional attrib, specifies location in the vertex shader. If not specified the implementation will increment the counter starting from 0. There can be maximum 16 attributes (so id of 15 is max).

(Default: attr# where # is id)

The name for this VBO, only used for debugging.

property normalized boolean?

(Defaults: false)

It’s possible to submit normals without normalizing them first, normalized will make sure data is normalized.

property size integer?

property type GL?

Defaults to to 4 for VBO. The number of floats that constitute 1 element in this buffer. e.g. for the previous layout (location = 0) in vec2 aPos, it would be size = 2.

(Default: GL.FLOAT) The datatype of this element.

Accepts the following:

  • GL.BYTE
  • GL.UNSIGNED_BYTE
  • GL.SHORT
  • GL.UNSIGNED_SHORT
  • GL.INT
  • GL.UNSIGNED_INT
  • GL.FLOAT

class VertexData

[source]

property c float4?

Short for color.

property color float4?

property n float3?

Short for norm.

property norm float3?

property t float2?

Short for texcoord.

property texcoord float2?

property v xyz?

Short for vert.

property vert xyz?

class WaterParams

Water params

[source]

property absorb rgb

property ambientFactor number

property baseColor rgb

property blurBase number

property blurExponent number

property causticsResolution number

property causticsStrength number

property damage number

property diffuseColor rgb

property diffuseFactor number

property foamTexture string

file

property forceRendering boolean

property fresnelMax number

property fresnelMin number

property fresnelPower number

property hasWaterPlane boolean

property minColor rgb

property normalTexture string

file

property numTiles integer

property perlinAmplitude number

property perlinLacunarity number

property perlinStartFreq number

property planeColor rgb

property reflectionDistortion number

property repeatX number

property repeatY number

property shoreWaves boolean

property specularColor rgb

property specularFactor number

property specularPower number

property surfaceAlpha number

property surfaceColor rgb

property texture string

file

property waveFoamDistortion number

property waveFoamIntensity number

property waveLength number

property waveOffsetFactor number

property windSpeed number

class WeaponDamages

Parameters for damage

[source]

property craterAreaOfEffect number

property craterBoost number

property craterMult number

property damageAreaOfEffect number

property dynDamageExp number

property dynDamageInverted number

Set to true if a non-zero value is passed, false is zero is passed.

property dynDamageMin number

property dynDamageRange number

property edgeEffectiveness number

property explosionSpeed number

property impulseBoost number

property impulseFactor number

property paralyzeDamageTime integer

class WeaponState

Parameter for weapon states

[source]

property accuracy number?

property aimReady number?

Set to true if a non-zero value is passed, false is zero is passed.

property avoidFlags integer?

property burst integer?

property burstRate number?

property collisionFlags integer?

property forceAim integer?

property nextSalvo integer?

property projectiles integer?

property projectileSpeed number?

property range number?

If you change the range of a weapon with dynamic damage make sure you use SetUnitWeaponDamages to change dynDamageRange as well.

property reaimTime integer?

property reloadFrame integer?

Alias for reloadState.

property reloadState integer?

property reloadTime number?

property salvoLeft integer?

property sprayAngle number?

property ttl number?

How many seconds the projectile should live

class xy

Cartesian double (XY)

class xyz

Cartesian triple (XYZ)

class xyzw

Cartesian quadruple (XYZW)

class xz

[source]

property x number

property y number