Lua API

Overview

We list here all globals available among all different lua environments within Recoil. Some types listed here exist only as helpers for aliasing parameters and returns.

The documentation pages are still a work in progress.

Spring (table)

Members

Spring.Ping (function) view source

Send a ping request to the server
Spring.Ping(integer?) -> nil
Parameters
integer?pingTag
Returns
nil

Spring.SendCommands (function) view source 

Spring.SendCommands(string[]) -> nil
Parameters
string[]commands

Spring.SendCommands (function overload 1) view source 

Spring.SendCommands(string, [string, ]*) -> nil
Parameters
stringcommand
string...
additional commands
Returns
nil

Spring.SendPublicChat (function) view source

Sends a chat message to everyone (players and spectators).
Spring.SendPublicChat(string) -> nil
Parameters
stringmessage
Returns
nil

Spring.SendAllyChat (function) view source

Sends a chat message to the sender’s ally team (if a spectator, to other spectators).
Spring.SendAllyChat(string) -> nil
Parameters
stringmessage
Returns
nil

Spring.SendSpectatorChat (function) view source

Sends a chat message to spectators. Works even if you’re a player.
Spring.SendSpectatorChat(string) -> nil
Parameters
stringmessage
Returns
nil

Spring.SendPrivateChat (function) view source

Sends a private chat message to a specific player ID.
Spring.SendPrivateChat(string, PlayerID) -> nil
Parameters
stringmessage
PlayerIDplayerID
Returns
nil

Spring.SendMessage (function) view source 

Spring.SendMessage(string) -> nil
Parameters
stringmessage
Returns
nil

Spring.SendMessageToSpectators (function) view source

Send a message to spectators.

If message contains "<PLAYER#>" (where # is a player ID) it will be replaced with the player’s name. e.g.

lua Spring.SendMessageToSpectators(" did something") – “ProRusher did something” 

Spring.SendMessageToSpectators(string) -> nil
Parameters
stringmessage
Message to send.
Returns
nil

Spring.SendMessageToPlayer (function) view source 

Spring.SendMessageToPlayer(PlayerID, string) -> nil
Parameters
PlayerIDplayerID
stringmessage
Returns
nil

Spring.SendMessageToTeam (function) view source 

Spring.SendMessageToTeam(TeamID, string) -> nil
Parameters
TeamIDteamID
stringmessage
Returns
nil

Spring.SendMessageToAllyTeam (function) view source 

Spring.SendMessageToAllyTeam(AllyTeamID, string) -> nil
Parameters
AllyTeamIDallyID
stringmessage
Returns
nil

Spring.RequestStartPosition (function) view source

Requests a startpoint, as if clicking the spot with the native GUI.
Spring.RequestStartPosition(number, number, number, boolean?) -> nil
Parameters
numberx
numbery
numberz
boolean?ready

Spring.LoadSoundDef (function) view source

Loads a SoundDefs file, the format is the same as in gamedata/sounds.lua.
Spring.LoadSoundDef(string) -> boolean
Parameters
stringsoundfile
Returns
booleansuccess

Spring.PlaySoundFile (function) view source 

Spring.PlaySoundFile(string, number?, number?, number?, number?, number?, number?, number?, SoundChannel?) -> boolean
Parameters
stringsoundfile
number?volume
(Default: 1.0) optional; all following arguments are optional
number?posx
world position X (use with posy and posz, or omit all three)
number?posy
number?posz
number?speedx
velocity X (use with speedy and speedz after position, or omit all three)
number?speedy
number?speedz
SoundChannel?channel
(Default: 0|“general”) optional; parsed from the last argument index after position and speed triples
Returns
booleanplaySound

Spring.PlaySoundStream (function) view source

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

Multiple sound streams may be played at once.

Spring.PlaySoundStream(string, number?, boolean?) -> boolean
Parameters
stringoggfile
number?volume
(Default: 1.0)
boolean?enqueue
Returns
booleansuccess

Spring.StopSoundStream (function) view source

Terminates any SoundStream currently running.
Spring.StopSoundStream() -> nil
Returns
nil

Spring.PauseSoundStream (function) view source

Pause any SoundStream currently running.
Spring.PauseSoundStream() -> nil
Returns
nil

Spring.SetSoundStreamVolume (function) view source

Set volume for SoundStream
Spring.SetSoundStreamVolume(number) -> nil
Parameters
numbervolume
Returns
nil

Spring.SetSoundEffectParams (function) view source 

Spring.SetSoundEffectParams() -> nil

Spring.AddWorldIcon (function) view source 

Spring.AddWorldIcon(integer, number, number, number) -> nil
Parameters
integercmdID
numberposX
numberposY
numberposZ
Returns
nil

Spring.AddWorldText (function) view source 

Spring.AddWorldText(string, number, number, number) -> nil
Parameters
stringtext
numberposX
numberposY
numberposZ
Returns
nil

Spring.AddWorldUnit (function) view source 

Spring.AddWorldUnit(UnitDefID, number, number, number, TeamID, FacingInteger) -> nil
Parameters
UnitDefIDunitDefID
numberposX
numberposY
numberposZ
TeamIDteamID
FacingIntegerfacing
Returns
nil

Spring.DrawUnitCommands (function) view source 

Spring.DrawUnitCommands(UnitID) -> nil
Parameters
UnitIDunitID

Spring.DrawUnitCommands (function overload 1) view source 

Spring.DrawUnitCommands(UnitID[], false?) -> nil
Parameters
UnitID[]unitIDs
Unit ids.
false?tableOrArray
Set to true if the unit IDs should be read from the keys of unitIDs.

Spring.DrawUnitCommands (function overload 2) view source 

Spring.DrawUnitCommands(table<UnitID,any>, true) -> nil
Parameters
table<UnitID,any>unitIDs
Table with unit IDs as keys.
truetableOrArray
Set to false if the unit IDs should be read from the values of unitIDs.
Returns
nil

Spring.SetCameraTarget (function) view source

For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
Spring.SetCameraTarget(number, number, number, number?, number?, number?, number?) -> nil
Parameters
numberx
numbery
numberz
number?transTime
(Default: 0.5) transition duration; values below zero are clamped to zero
number?dirX
(Default: current camera direction X)
number?dirY
(Default: current camera direction Y)
number?dirZ
(Default: current camera direction Z)
Returns
nil

Spring.SetCameraOffset (function) view source 

Spring.SetCameraOffset(number?, number?, number?, number?, number?, number?) -> nil
Parameters
number?posX
(Default: 0)
number?posY
(Default: 0)
number?posZ
(Default: 0)
number?tiltX
(Default: 0)
number?tiltY
(Default: 0)
number?tiltZ
(Default: 0)
Returns
nil

Spring.SetCameraState (function) view source

Set camera state.

transitionTimeFactor defaults to “CamTimeFactor” springsetting unless set previously.

transitionTimeExponent defaults to “CamTimeExponent” springsetting unless set previously.

Spring.SetCameraState(CameraState, number?, number?, number?) -> boolean
Parameters
CameraStatecameraState
The fields must be consistent with the name/mode and current/new camera mode.
number?transitionTime
(Default: 0) in nanoseconds
number?transitionTimeFactor
Multiplicative factor applied to this and all subsequent transition times for this camera mode.
number?transitionTimeExponent
Tween factor applied to this and all subsequent transitions for this camera mode.
Returns
booleanset
true when applied without errors, otherwise false.

Spring.RunDollyCamera (function) view source

Runs Dolly Camera
Spring.RunDollyCamera(number) -> nil
Parameters
numberruntime
Runtime in milliseconds.
Returns
nil

Spring.PauseDollyCamera (function) view source

Pause Dolly Camera
Spring.PauseDollyCamera(number?) -> nil
Parameters
number?fraction
Fraction of the total runtime to pause at, 0 to 1 inclusive. A null value pauses at current percent
Returns
nil

Spring.ResumeDollyCamera (function) view source

Resume Dolly Camera
Spring.ResumeDollyCamera() -> nil
Returns
nil

Spring.SetDollyCameraPosition (function) view source

Sets Dolly Camera Position
Spring.SetDollyCameraPosition(number, number, number) -> nil
Parameters
numberx
numbery
numberz
Returns
nil

Spring.SetDollyCameraCurve (function) view source

Sets Dolly Camera movement Curve
Spring.SetDollyCameraCurve(integer, ControlPoint[], table) -> nil
Parameters
integerdegree
ControlPoint[]cpoints
NURBS control point positions.
tableknots
Returns
nil

Spring.SetDollyCameraMode (function) view source

Sets Dolly Camera movement mode
Spring.SetDollyCameraMode((1|2)) -> nil
Parameters
(1|2)mode
1 static position, 2 nurbs curve
Returns
nil

Spring.SetDollyCameraRelativeMode (function) view source

Sets Dolly Camera movement curve to world relative or look target relative
Spring.SetDollyCameraRelativeMode(integer) -> nil
Parameters
integerrelativeMode
1 world, 2 look target
Returns
nil

Spring.SetDollyCameraLookCurve (function) view source

Sets Dolly Camera Look Curve
Spring.SetDollyCameraLookCurve(integer, ControlPoint[], table) -> nil
Parameters
integerdegree
ControlPoint[]cpoints
NURBS control point positions.
tableknots
Returns
nil

Spring.SetDollyCameraLookPosition (function) view source

Sets Dolly Camera Look Position
Spring.SetDollyCameraLookPosition(number, number, number) -> nil
Parameters
numberx
numbery
numberz
Returns
nil

Spring.SetDollyCameraLookUnit (function) view source

Sets target unit for Dolly Camera to look towards
Spring.SetDollyCameraLookUnit(UnitID) -> nil
Parameters
UnitIDunitID
The unit to look at.
Returns
nil

Spring.SelectUnit (function) view source

Selects a single unit
Spring.SelectUnit(UnitID?, boolean?) -> nil
Parameters
UnitID?unitID
boolean?append
(Default: false) Append to current selection.
Returns
nil

Spring.DeselectUnit (function) view source 

Spring.DeselectUnit(UnitID) -> nil
Parameters
UnitIDunitID
Returns
nil

Spring.DeselectUnitArray (function) view source

Deselects multiple units.
Spring.DeselectUnitArray(UnitID[]) -> nil
Parameters
UnitID[]unitIDs
Table with unit IDs as values.
Returns
nil

Spring.DeselectUnitMap (function) view source

Deselects multiple units.
Spring.DeselectUnitMap(table<UnitID,any>) -> nil
Parameters
table<UnitID,any>unitMap
Table with unit IDs as keys.
Returns
nil

Spring.SelectUnitArray (function) view source

Selects multiple units, or appends to selection. Accepts a table with unitIDs as values
Spring.SelectUnitArray(UnitID[], boolean?) -> nil
Parameters
UnitID[]unitIDs
Table with unit IDs as values.
boolean?append
(Default: false) append to current selection
Returns
nil

Spring.SelectUnitMap (function) view source

Selects multiple units, or appends to selection. Accepts a table with unitIDs as keys
Spring.SelectUnitMap(table<UnitID,any>, boolean?) -> nil
Parameters
table<UnitID,any>unitMap
Table with unit IDs as keys.
boolean?append
(Default: false) append to current selection
Returns
nil

Spring.AddMapLight (function) view source

requires MaxDynamicMapLights > 0
Spring.AddMapLight(LightParams) -> integer
Parameters
LightParamslightParams
Returns
integerlightHandle

Spring.AddModelLight (function) view source

requires MaxDynamicMapLights > 0
Spring.AddModelLight(LightParams) -> integer
Parameters
LightParamslightParams
Returns
integerlightHandle

Spring.UpdateMapLight (function) view source 

Spring.UpdateMapLight(integer, LightParams) -> boolean
Parameters
integerlightHandle
LightParamslightParams
Returns
booleansuccess

Spring.UpdateModelLight (function) view source 

Spring.UpdateModelLight(integer, LightParams) -> boolean
Parameters
integerlightHandle
LightParamslightParams
Returns
booleansuccess

Spring.AddLightTrackingTarget (function) view source 

Spring.AddLightTrackingTarget() -> nil

Spring.SetMapLightTrackingState (function) view source

Set a map-illuminating light to start/stop tracking the position of a moving object (unit or projectile)
Spring.SetMapLightTrackingState(integer, (UnitID|ProjectileID), boolean?, boolean?) -> boolean
Parameters
integerlightHandle
(UnitID|ProjectileID)unitOrProjectileID
boolean?enableTracking
boolean?unitOrProjectile
Returns
booleansuccess

Spring.SetModelLightTrackingState (function) view source

Set a model-illuminating light to start/stop tracking the position of a moving object (unit or projectile)
Spring.SetModelLightTrackingState(integer, (UnitID|ProjectileID), boolean?, boolean?) -> boolean
Parameters
integerlightHandle
(UnitID|ProjectileID)unitOrProjectileID
boolean?enableTracking
boolean?unitOrProjectile
Returns
booleansuccess

Spring.SetMapShader (function) view 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.
Spring.SetMapShader(integer, integer, boolean?) -> nil
Parameters
integerstandardShaderID
integerdeferredShaderID
boolean?combinedShader
(Default: false) Declares that the deferred program also writes the lit forward color to fragment output 5, with non-zero alpha where ground is opaque (the composite skips zero-alpha pixels). With AllowCombinedMapRendering the ground is then rasterized only once (no forward pass, DrawGroundPreForward is not called, and on void maps the alpha test reads output 0’s alpha); otherwise the flag is ignored and both programs run as before.
Returns
nil

Spring.SetMapSquareTexture (function) view source 

Spring.SetMapSquareTexture(integer, integer, string) -> boolean
Parameters
integertexSqrX
integertexSqrY
stringluaTexName
Returns
booleansuccess

Spring.SetMapShadingTexture (function) view source 

Spring.SetMapShadingTexture(string, string) -> boolean
Parameters
stringtexType
stringtexName
Returns
booleansuccess

Spring.SetSkyBoxTexture (function) view source 

Spring.SetSkyBoxTexture(string) -> nil
Parameters
stringtexName
Returns
nil

Spring.SetUnitNoDraw (function) view source 

Spring.SetUnitNoDraw(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleannoDraw
Returns
nil

Spring.SetUnitEngineDrawMask (function) view source 

Spring.SetUnitEngineDrawMask(UnitID, number) -> nil
Parameters
UnitIDunitID
numberdrawMask
Returns
nil

Spring.SetUnitAlwaysUpdateMatrix (function) view source 

Spring.SetUnitAlwaysUpdateMatrix(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanalwaysUpdateMatrix
Returns
nil

Spring.SetUnitNoMinimap (function) view source 

Spring.SetUnitNoMinimap(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanunitNoMinimap
Returns
nil

Spring.SetMiniMapRotation (function) view source 

Spring.SetMiniMapRotation(number) -> nil
Parameters
numberrotation
amount in radians
Returns
nil

Spring.SetUnitNoGroup (function) view source 

Spring.SetUnitNoGroup(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanunitNoGroup
Whether unit can be added to selection groups

Spring.SetUnitNoSelect (function) view source 

Spring.SetUnitNoSelect(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanunitNoSelect
whether unit can be selected or not
Returns
nil

Spring.SetUnitLeaveTracks (function) view source 

Spring.SetUnitLeaveTracks(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanunitLeaveTracks
whether unit leaves tracks on movement
Returns
nil

Spring.SetUnitSelectionVolumeData (function) view source 

Spring.SetUnitSelectionVolumeData(UnitID, number, number, number, number, number, number, integer, integer, integer) -> nil
Parameters
UnitIDunitID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integervType
integertType
integerAxis
Returns
nil

Spring.SetFeatureNoDraw (function) view source 

Spring.SetFeatureNoDraw(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleannoDraw
Returns
nil

Spring.SetFeatureEngineDrawMask (function) view source 

Spring.SetFeatureEngineDrawMask(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numberengineDrawMask
Returns
nil

Spring.SetFeatureAlwaysUpdateMatrix (function) view source 

Spring.SetFeatureAlwaysUpdateMatrix(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numberalwaysUpdateMat
Returns
nil

Spring.SetFeatureFade (function) view source

Control whether a feature will fade or not when zoomed out.
Spring.SetFeatureFade(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleanallow
Returns
nil

Spring.SetFeatureSelectionVolumeData (function) view source 

Spring.SetFeatureSelectionVolumeData(FeatureID, number, number, number, number, number, number, integer, integer, integer) -> nil
Parameters
FeatureIDfeatureID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integervType
integertType
integerAxis
Returns
nil

Spring.AddUnitIcon (function) view source 

Spring.AddUnitIcon(string, string, number?, number?, number?, number?, number?, number?, number?, number?) -> boolean
Parameters
stringiconName
stringtexFile
number?size
number?dist
number?radAdjust
number?u0
number?v0
number?u1
number?v1
number?drawOrder
(Default: 0) Sort priority for icon drawing; icons with higher values are drawn on top of lower ones.
Returns
booleanadded

Spring.FreeUnitIcon (function) view source 

Spring.FreeUnitIcon(string) -> boolean?
Parameters
stringiconName
Returns
boolean?freed

Spring.UnitIconSetDraw (function) view source

Use Spring.SetUnitIconDraw instead.

Deprecated

Spring.UnitIconSetDraw(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleandrawIcon
Returns
nil

Spring.SetUnitIconDraw (function) view source 

Spring.SetUnitIconDraw(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleandrawIcon
Returns
nil

Spring.SetUnitIcon (function) view source 

Spring.SetUnitIcon(UnitID, string?) -> nil
Parameters
UnitIDunitID
string?iconName
supply nil to reset to the default
Returns
nil

Spring.SetUnitDefIcon (function) view source 

Spring.SetUnitDefIcon(UnitDefID, string) -> nil
Parameters
UnitDefIDunitDefID
stringiconName
Returns
nil

Spring.SetUnitDefImage (function) view source 

Spring.SetUnitDefImage(UnitDefID, string?) -> nil
Parameters
UnitDefIDunitDefID
string?image
luaTexture|texFile
Returns
nil

Spring.ExtractModArchiveFile (function) view source 

Spring.ExtractModArchiveFile(string) -> boolean
Parameters
stringmodfile
Returns
booleanextracted

Spring.CreateDir (function) view source 

Spring.CreateDir(string) -> boolean?
Parameters
stringpath
Returns
boolean?dirCreated

Spring.SetActiveCommand (function) view source 

Spring.SetActiveCommand(string, string?) -> boolean?
Parameters
stringaction
string?actionExtra
Returns
boolean?commandSet

Spring.SetActiveCommand (function overload 1) view source 

Spring.SetActiveCommand(integer, integer?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?) -> boolean?
Parameters
integercmdIndex
integer?button
(Default: 1)
boolean?leftClick
boolean?rightClick
boolean?alt
boolean?ctrl
boolean?meta
boolean?shift
Returns
boolean?commandSet

Spring.LoadCmdColorsConfig (function) view source 

Spring.LoadCmdColorsConfig(string) -> nil
Parameters
stringconfig
Returns
nil

Spring.LoadCtrlPanelConfig (function) view source 

Spring.LoadCtrlPanelConfig(string) -> nil
Parameters
stringconfig
Returns
nil

Spring.ForceLayoutUpdate (function) view source 

Spring.ForceLayoutUpdate() -> nil
Returns
nil

Spring.SetDrawSelectionInfo (function) view source

Disables the “Selected Units x” box in the GUI.
Spring.SetDrawSelectionInfo(boolean) -> nil
Parameters
booleanenable
Returns
nil

Spring.SetBoxSelectionByEngine (function) view source 

Spring.SetBoxSelectionByEngine(boolean) -> nil
Parameters
booleanstate
Returns
nil

Spring.SetTeamColor (function) view source 

Spring.SetTeamColor(TeamID, number, number, number, number?) -> nil
Parameters
TeamIDteamID
numberr
numberg
numberb
number?alpha
Returns
nil

Spring.SetCustomPaletteColor (function) view source 

Spring.SetCustomPaletteColor(integer, number, number, number) -> nil
Parameters
integerindex
0-based index into custom palette (0..1791, maps to palette slots 256..2047)
numberr
numberg
numberb
Returns
nil

Spring.SetUnitPaletteIndex (function) view source

Sets a custom color for a unit from the palette. Custom assignments are permanent until explicitly reset by passing nil, and are NOT affected by team changes.
Spring.SetUnitPaletteIndex(UnitID, integer?) -> nil
Parameters
UnitIDunitID
integer?customIndex
[0..MAX_CUSTOM_COLORS) index into custom palette, or nil to reset to team color
Returns
nil

Spring.SetFeaturePaletteIndex (function) view source

Sets a custom color for a feature from the palette. Custom assignments are permanent until explicitly reset by passing nil, and are NOT affected by team changes.
Spring.SetFeaturePaletteIndex(FeatureID, integer?) -> nil
Parameters
FeatureIDfeatureID
integer?customIndex
[0..MAX_CUSTOM_COLORS) index into custom palette, or nil to reset to team color
Returns
nil

Spring.AssignMouseCursor (function) view source

Changes/creates the cursor of a single CursorCmd.

iconFileName is not the full filename, instead it is like this:

Wanted filename: Anims/cursorattack_0.bmp
  => iconFileName: cursorattack
  
Spring.AssignMouseCursor(string, string, boolean?, boolean?) -> boolean?
Parameters
stringcmdName
stringiconFileName
The cursor name, without path, frame number or extension.
boolean?overwrite
(Default: true)
boolean?hotSpotTopLeft
(Default: false)
Returns
boolean?assigned

Spring.ReplaceMouseCursor (function) view source

Mass replace all occurrences of the cursor in all CursorCmds.
Spring.ReplaceMouseCursor(string, string, boolean?) -> boolean?
Parameters
stringoldFileName
stringnewFileName
boolean?hotSpotTopLeft
(Default: false)
Returns
boolean?assigned

Spring.SetCustomCommandDrawData (function) view source

Register your custom cmd so it gets visible in the unit’s cmd queue
Spring.SetCustomCommandDrawData(integer, (string|integer)?, rgba?, boolean?) -> nil
Parameters
integercmdID
(string|integer)?cmdReference
The name or ID of an icon for command. Pass nil to clear draw data for command.
rgba?color
(Default: white)
boolean?showArea
(Default: false)
Returns
nil

Spring.WarpMouse (function) view source 

Spring.WarpMouse(integer, integer) -> nil
Parameters
integerx
integery
Returns
nil

Spring.SetMouseCursor (function) view source 

Spring.SetMouseCursor(string, number?) -> nil
Parameters
stringcursorName
number?cursorScale
(Default: 1.0)
Returns
nil

Spring.SetLosViewColors (function) view source 

Spring.SetLosViewColors(rgb, rgb, rgb, rgb, rgb) -> nil
Parameters
rgbalways
rgbLOS
rgbradar
rgbjam
rgbradar2
Returns
nil

Spring.SetNanoProjectileParams (function) view source 

Spring.SetNanoProjectileParams(number?, number?, number?, number?, number?, number?) -> nil
Parameters
number?rotVal
(Default: 0) in degrees
number?rotVel
(Default: 0) in degrees
number?rotAcc
(Default: 0) in degrees
number?rotValRng
(Default: 0) in degrees
number?rotVelRng
(Default: 0) in degrees
number?rotAccRng
(Default: 0) in degrees
Returns
nil

Spring.UnbindAll (function) view source

Completely unbinds all key bindings without setting fallback bootstrap keys.
Spring.UnbindAll() -> nil
Returns
nil

Spring.SetConfigInt (function) view source 

Spring.SetConfigInt(string, integer, boolean?) -> nil
Parameters
stringname
integervalue
boolean?useOverlay
(Default: false) If true, the value will only be set in memory, and not be restored for the next game.
Returns
nil

Spring.SetConfigFloat (function) view source 

Spring.SetConfigFloat(string, number, boolean?) -> nil
Parameters
stringname
numbervalue
boolean?useOverlay
(Default: false) If true, the value will only be set in memory, and not be restored for the next game.
Returns
nil

Spring.SetConfigString (function) view source 

Spring.SetConfigString(string, string, boolean?) -> nil
Parameters
stringname
stringvalue
boolean?useOverlay
(Default: false) If true, the value will only be set in memory, and not be restored for the next game.
Returns
nil

Spring.Quit (function) view source

Closes the application
Spring.Quit() -> nil
Returns
nil

Spring.SetUnitGroup (function) view source 

Spring.SetUnitGroup(UnitID, GroupID) -> nil
Parameters
UnitIDunitID
GroupIDgroupID
the group number to be assigned, or -1 for deassignment
Returns
nil

Spring.GiveOrder (function) view source

Give order to selected units.
Spring.GiveOrder((CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
(CMD|integer)cmdID
The command ID.
CreateCommandParams?params
Parameters for the given command.
CreateCommandOptions?options
integer?timeout
Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.
Returns
boolean

Spring.GiveOrderToUnit (function) view source

Give order to specific unit.
Spring.GiveOrderToUnit(UnitID, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
UnitIDunitID
(CMD|integer)cmdID
The command ID.
CreateCommandParams?params
Parameters for the given command.
CreateCommandOptions?options
integer?timeout
Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.
Returns
boolean

Spring.GiveOrderToUnit (function overload 1) view source 

Spring.GiveOrderToUnit(UnitID, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
UnitIDunitID
(CMD|integer)cmdID
The command ID.
CreateCommandParams?params
Parameters for the given command.
CreateCommandOptions?options
integer?timeout
Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.
Returns
booleanunitOrdered

Spring.GiveOrderToUnitMap (function) view source

Give order to multiple units, specified by table keys.
Spring.GiveOrderToUnitMap(table<UnitID,any>, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
table<UnitID,any>unitMap
A table with unit IDs as keys.
(CMD|integer)cmdID
The command ID.
CreateCommandParams?params
Parameters for the given command.
CreateCommandOptions?options
integer?timeout
Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.
Returns
booleanorderGiven

Spring.GiveOrderToUnitMap (function overload 1) view source

Give order to multiple units, specified by table keys.
Spring.GiveOrderToUnitMap(table<UnitID,any>, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> integer
Parameters
table<UnitID,any>unitMap
A table with unit IDs as keys.
(CMD|integer)cmdID
The command ID.
CreateCommandParams?params
Parameters for the given command.
CreateCommandOptions?options
integer?timeout
Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.
Returns
integerunitsOrdered
The number of units ordered.

Spring.GiveOrderToUnitArray (function) view source

Give order to an array of units.
Spring.GiveOrderToUnitArray(UnitID[], (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
UnitID[]unitIDs
Array of unit IDs.
(CMD|integer)cmdID
The command ID.
CreateCommandParams?params
Parameters for the given command.
CreateCommandOptions?options
integer?timeout
Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.
Returns
booleanordersGiven
true if any orders were sent, otherwise false.

Spring.GiveOrderToUnitArray (function overload 1) view source 

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

Spring.GiveOrderArrayToUnit (function) view source 

Spring.GiveOrderArrayToUnit(UnitID, CreateCommand[]) -> boolean
Parameters
UnitIDunitID
Unit ID.
CreateCommand[]commands
Returns
booleanordersGiven
true if any orders were sent, otherwise false.

Spring.GiveOrderArrayToUnit (function overload 1) view source 

Spring.GiveOrderArrayToUnit(UnitID, CreateCommand[]) -> boolean
Parameters
UnitIDunitID
CreateCommand[]commands
Returns
booleanordersGiven

Spring.GiveOrderArrayToUnitMap (function) view source 

Spring.GiveOrderArrayToUnitMap(table<UnitID,any>, CreateCommand[]) -> boolean
Parameters
table<UnitID,any>unitMap
A table with unit IDs as keys.
CreateCommand[]commands
Returns
booleanordersGiven
true if any orders were sent, otherwise false.

Spring.GiveOrderArrayToUnitMap (function overload 1) view source 

Spring.GiveOrderArrayToUnitMap(table<UnitID,any>, CreateCommand[]) -> integer
Parameters
table<UnitID,any>unitMap
A table with unit IDs as keys.
CreateCommand[]commands
Returns
integerunitsOrdered
The number of units ordered.

Spring.GiveOrderArrayToUnitArray (function) view source

When pairwise is 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.

Spring.GiveOrderArrayToUnitArray(UnitID[], CreateCommand[], boolean?) -> boolean
Parameters
UnitID[]unitIDs
Array of unit IDs.
CreateCommand[]commands
boolean?pairwise
(Default: false) When true, assign commands to units by index.
Returns
booleanordersGiven
true if any orders were sent, otherwise false.

Spring.GiveOrderArrayToUnitArray (function overload 1) view source

When pairwise is 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.

Spring.GiveOrderArrayToUnitArray(UnitID[], CreateCommand[], boolean?) -> integer
Parameters
UnitID[]unitIDs
Array of unit IDs.
CreateCommand[]commands
boolean?pairwise
(Default: false) When true, assign commands to units by index.
Returns
integerunitsOrdered
The number of units ordered.

Spring.SetBuildSpacing (function) view source 

Spring.SetBuildSpacing(integer) -> nil
Parameters
integerspacing
Returns
nil

Spring.SetBuildFacing (function) view source 

Spring.SetBuildFacing(FacingInteger) -> nil
Parameters
FacingIntegerfacing
Returns
nil

Spring.SendLuaUIMsg (function) view source 

Spring.SendLuaUIMsg(string, string?) -> nil
Parameters
stringmessage
string?mode
“s”/“specs” | “a”/“allies”
Returns
nil

Spring.SendLuaGaiaMsg (function) view source 

Spring.SendLuaGaiaMsg(string) -> nil
Parameters
stringmessage
Returns
nil

Spring.SendLuaRulesMsg (function) view source 

Spring.SendLuaRulesMsg(string) -> nil
Parameters
stringmessage
Returns
nil

Spring.SendLuaMenuMsg (function) view source 

Spring.SendLuaMenuMsg(string) -> nil
Parameters
stringmsg

Spring.SetShareLevel (function) view source 

Spring.SetShareLevel(string, number) -> nil
Parameters
stringresource
metal | energy
numbershareLevel
Returns
nil

Spring.ShareResources (function) view source 

Spring.ShareResources(TeamID, string) -> nil
Parameters
TeamIDteamID
stringunits
Returns
nil

Spring.ShareResources (function overload 1) view source 

Spring.ShareResources(TeamID, string, number) -> nil
Parameters
TeamIDteamID
stringresource
metal | energy
numberamount
Returns
nil

Spring.SetLastMessagePosition (function) view source 

Spring.SetLastMessagePosition(number, number, number) -> nil
Parameters
numberx
numbery
numberz
Returns
nil

Spring.MarkerAddPoint (function) view source 

Spring.MarkerAddPoint(number, number, number, string?, boolean?, PlayerID?) -> nil
Parameters
numberx
numbery
numberz
string?text
(Default: "")
boolean?localOnly
PlayerID?playerID
Local labels pretend they are from this player
Returns
nil

Spring.MarkerAddLine (function) view source 

Spring.MarkerAddLine(number, number, number, number, number, number, boolean?, PlayerID?) -> nil
Parameters
numberx1
numbery1
numberz1
numberx2
numbery2
numberz2
boolean?localOnly
(Default: false)
PlayerID?playerId
Returns
nil

Spring.MarkerErasePosition (function) view source

Issue an erase command for markers on the map.
Spring.MarkerErasePosition(number, number, number, nil, boolean?, PlayerID?, boolean?) -> nil
Parameters
numberx
numbery
numberz
nilunused
This argument is ignored.
boolean?localOnly
(Default: false) do not issue a network message, erase only for the current player
PlayerID?playerId
when not specified it uses the issuer playerId
boolean?alwaysErase
(Default: false) erase any marker when localOnly and current player is spectating. Allows spectators to erase players markers locally
Returns
nil

Spring.SetAtmosphere (function) view source

Set atmosphere parameters
Spring.SetAtmosphere(AtmosphereParams) -> nil
Parameters
AtmosphereParamsparams

Spring.SetSunDirection (function) view source 

Spring.SetSunDirection(number, number, number, number?) -> nil
Parameters
numberdirX
numberdirY
numberdirZ
number?intensity
(Default: 1.0)
Returns
nil

Spring.SetSunLighting (function) view source

Modify sun lighting parameters.

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

Spring.SetSunLighting(SunLightingParams) -> nil
Parameters
SunLightingParamsparams

Spring.SetMapRenderingParams (function) view source

Allows to change map rendering params at runtime.
Spring.SetMapRenderingParams(MapRenderingParams) -> nil
Parameters
MapRenderingParamsparams
Returns
nil

Spring.ForceTesselationUpdate (function) view source 

Spring.ForceTesselationUpdate(boolean?, boolean?) -> boolean
Parameters
boolean?normal
(Default: true)
boolean?shadow
(Default: false)
Returns
booleanupdated

Spring.SendSkirmishAIMessage (function) view source 

Spring.SendSkirmishAIMessage(TeamID, string) -> boolean?
Parameters
TeamIDaiTeam
stringmessage
Returns
boolean?ai_processed

Spring.SetLogSectionFilterLevel (function) view source 

Spring.SetLogSectionFilterLevel(string, (string|number)?) -> nil
Parameters
stringsectionName
(string|number)?logLevel
Returns
nil

Spring.GarbageCollectCtrl (function) view source 

Spring.GarbageCollectCtrl(integer?, integer?, integer?, integer?, number?, number?, number?, number?) -> nil
Parameters
integer?itersPerBatch
integer?numStepsPerIter
integer?minStepsPerIter
integer?maxStepsPerIter
number?minLoopRunTime
number?maxLoopRunTime
number?baseRunTimeMult
number?baseMemLoadMult
Returns
nil

Spring.SetAutoShowMetal (function) view source 

Spring.SetAutoShowMetal(boolean) -> nil
Parameters
booleanautoShow
Returns
nil

Spring.SetDrawSky (function) view source 

Spring.SetDrawSky(boolean) -> nil
Parameters
booleandrawSky
Returns
nil

Spring.SetDrawWater (function) view source 

Spring.SetDrawWater(boolean) -> nil
Parameters
booleandrawWater
Returns
nil

Spring.SetDrawGround (function) view source 

Spring.SetDrawGround(boolean) -> nil
Parameters
booleandrawGround
Returns
nil

Spring.SetDrawGroundDeferred (function) view source 

Spring.SetDrawGroundDeferred(boolean, boolean?) -> nil
Parameters
booleandrawGroundDeferred
boolean?drawGroundForward
allows disabling of the forward pass
Returns
nil

Spring.SetDrawModelsDeferred (function) view source 

Spring.SetDrawModelsDeferred(boolean, boolean, boolean?, boolean?) -> nil
Parameters
booleandrawUnitsDeferred
booleandrawFeaturesDeferred
boolean?drawUnitsForward
allows disabling of the respective forward passes
boolean?drawFeaturesForward
allows disabling of the respective forward passes
Returns
nil

Spring.SetEngineBuildSquareRendering (function) view source 

Spring.SetEngineBuildSquareRendering(boolean) -> nil
Parameters
booleanenabled
Returns
nil

Spring.SetVideoCapturingMode (function) view source

This doesn’t actually record the game in any way, it just regulates the framerate and interpolations.
Spring.SetVideoCapturingMode(boolean) -> nil
Parameters
booleanallowCaptureMode
Returns
nil

Spring.SetVideoCapturingTimeOffset (function) view source 

Spring.SetVideoCapturingTimeOffset(boolean) -> nil
Parameters
booleantimeOffset
Returns
nil

Spring.SetWaterParams (function) view source

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.

Spring.SetWaterParams(WaterParams) -> nil
Parameters
WaterParamswaterParams
Returns
nil

Spring.PreloadUnitDefModel (function) view 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.
Spring.PreloadUnitDefModel(UnitDefID) -> nil
Parameters
UnitDefIDunitDefID
Returns
nil

Spring.PreloadFeatureDefModel (function) view source 

Spring.PreloadFeatureDefModel(FeatureDefID) -> nil
Parameters
FeatureDefIDfeatureDefID
Returns
nil

Spring.PreloadSoundItem (function) view source 

Spring.PreloadSoundItem(string) -> nil
Parameters
stringname
Returns
nil

Spring.LoadModelTextures (function) view source 

Spring.LoadModelTextures(string?) -> boolean?
Parameters
string?modelName
Returns
boolean?success

Spring.CreateGroundDecal (function) view source 

Spring.CreateGroundDecal() -> DecalID?
Returns
DecalID?decalID

Spring.DestroyGroundDecal (function) view source 

Spring.DestroyGroundDecal(DecalID) -> boolean
Parameters
DecalIDdecalID
Returns
booleandelSuccess

Spring.SetGroundDecalPosAndDims (function) view source 

Spring.SetGroundDecalPosAndDims(DecalID, number?, number?, number?, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?midPosX
(Default: currMidPosX)
number?midPosZ
(Default: currMidPosZ)
number?sizeX
(Default: currSizeX)
number?sizeZ
(Default: currSizeZ)
number?projCubeHeight
(Default: calculateProjCubeHeight)
Returns
booleandecalSet

Spring.SetGroundDecalQuadPosAndHeight (function) view source

Use for non-rectangular decals
Spring.SetGroundDecalQuadPosAndHeight(DecalID, xz?, xz?, xz?, xz?, number?) -> boolean
Parameters
DecalIDdecalID
xz?posTL
(Default: currPosTL)
xz?posTR
(Default: currPosTR)
xz?posBR
(Default: currPosBR)
xz?posBL
(Default: currPosBL)
number?projCubeHeight
(Default: calculateProjCubeHeight)
Returns
booleandecalSet

Spring.SetGroundDecalRotation (function) view source 

Spring.SetGroundDecalRotation(DecalID, number?) -> boolean
Parameters
DecalIDdecalID
number?rot
(Default: random) in radians
Returns
booleandecalSet

Spring.SetGroundDecalTexture (function) view source 

Spring.SetGroundDecalTexture(DecalID, string, boolean?) -> boolean?
Parameters
DecalIDdecalID
stringtextureName
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)
boolean?isMainTex
(Default: true) If false, it sets the normals/glow map
Returns
boolean?decalSet

Spring.SetGroundDecalTextureParams (function) view source 

Spring.SetGroundDecalTextureParams(DecalID, number?, number?) -> boolean?
Parameters
DecalIDdecalID
number?texWrapDistance
(Default: currTexWrapDistance) if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos
number?texTraveledDistance
(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
boolean?decalSet

Spring.SetGroundDecalAlpha (function) view source 

Spring.SetGroundDecalAlpha(DecalID, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?alpha
(Default: currAlpha) Between 0 and 1
number?alphaFalloff
(Default: currAlphaFalloff) Between 0 and 1, per second
Returns
booleandecalSet

Spring.SetGroundDecalNormal (function) view source

Sets projection cube normal to orient in 3D space. In case the normal (0,0,0) then normal is picked from the terrain
Spring.SetGroundDecalNormal(DecalID, number?, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?normalX
(Default: 0)
number?normalY
(Default: 0)
number?normalZ
(Default: 0)
Returns
booleandecalSet

Spring.SetGroundDecalTint (function) view 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
Spring.SetGroundDecalTint(DecalID, number?, number?, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?tintColR
(Default: curTintColR)
number?tintColG
(Default: curTintColG)
number?tintColB
(Default: curTintColB)
number?tintColA
(Default: curTintColA)
Returns
booleandecalSet

Spring.SetGroundDecalMisc (function) view source

Sets varios secondary parameters of a decal
Spring.SetGroundDecalMisc(DecalID, number?, number?, number?, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?dotElimExp
(Default: curValue) pow(max(dot(decalProjVector, SurfaceNormal), 0.0), dotElimExp), used to reduce decal artifacts on surfaces non-collinear with the projection vector
number?refHeight
(Default: curValue)
number?minHeight
(Default: curValue)
number?maxHeight
(Default: curValue)
number?forceHeightMode
(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
booleandecalSet

Spring.SetGroundDecalCreationFrame (function) view source

Use separate min and max for “gradient” style decals such as tank tracks
Spring.SetGroundDecalCreationFrame(DecalID, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?creationFrameMin
(Default: currCreationFrameMin)
number?creationFrameMax
(Default: currCreationFrameMax)
Returns
booleandecalSet

Spring.SetGroundDecalGlowParams (function) view source

Set decal glow parameters
Spring.SetGroundDecalGlowParams(DecalID, number?, number?) -> boolean
Parameters
DecalIDdecalID
number?glow
Between 0 and 1 (Default: currGlow)
number?glowFalloff
Between 0 and 1, per second (Default: currGlowFallOff)
Returns
booleandecalSet

Spring.SetGroundDecalUserData (function) view source

Set decal user data. Useful in conjunction with custom decal shaders
Spring.SetGroundDecalUserData(DecalID, integer, number?, number?, number?, number?) -> boolean
Parameters
DecalIDdecalID
integerudQuad
vec4 index, must be within [0;1] for now
number?x
Any valid Lua float number (Default: current data)
number?y
Any valid Lua float number (Default: current data)
number?z
Any valid Lua float number (Default: current data)
number?w
Any valid Lua float number (Default: current data)
Returns
booleandecalSet

Spring.SDLSetTextInputRect (function) view source 

Spring.SDLSetTextInputRect(integer, integer, integer, integer) -> nil
Parameters
integerx
integery
integerwidth
integerheight
Returns
nil

Spring.SDLStartTextInput (function) view source 

Spring.SDLStartTextInput() -> nil
Returns
nil

Spring.SDLStopTextInput (function) view source 

Spring.SDLStopTextInput() -> nil
Returns
nil

Spring.SetWindowGeometry (function) view source 

Spring.SetWindowGeometry(integer, integer, integer, integer, integer, boolean, boolean) -> nil
Parameters
integerdisplayIndex
integerwinRelPosX
integerwinRelPosY
integerwinSizeX
integerwinSizeY
booleanfullScreen
booleanborderless
Returns
nil

Spring.SetWindowMinimized (function) view source 

Spring.SetWindowMinimized() -> boolean
Returns
booleanminimized

Spring.SetWindowMaximized (function) view source 

Spring.SetWindowMaximized() -> boolean
Returns
booleanmaximized

Spring.Reload (function) view source 

Spring.Reload(string) -> nil
Parameters
stringstartScript
the CONTENT of the script.txt spring should use to start.
Returns
nil

Spring.Restart (function) view source

If this call returns, something went wrong
Spring.Restart(string, string) -> nil
Parameters
stringcommandline_args
commandline arguments passed to spring executable.
stringstartScript
Returns
nil

Spring.Start (function) view source

Launches a new Spring instance without terminating the existing one.

If this call returns, something went wrong

Spring.Start(string, string) -> nil
Parameters
stringcommandline_args
commandline arguments passed to spring executable.
stringstartScript
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

Spring.SetWMIcon (function) view source

Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo).

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.

Spring.SetWMIcon(string, boolean?) -> nil
Parameters
stringiconFileName
boolean?autoFree
Returns
nil

Spring.SetWMCaption (function) view source

Set the window title for the process

Note

shortTitle is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows.

Spring.SetWMCaption(string, string?) -> nil
Parameters
stringtitle
(Default: “Spring <version>")
string?titleShort
(Default: “Spring <version>") Displayed in the OS task-bar.
Returns
nil

Spring.ClearWatchDogTimer (function) view source 

Spring.ClearWatchDogTimer(string?) -> nil
Parameters
string?threadName
(Default: main)
Returns
nil

Spring.SetClipboard (function) view source 

Spring.SetClipboard(string) -> nil
Parameters
stringtext
Returns
nil

Spring.Yield (function) view source

Relinquish control of the game loading thread and OpenGL context back to the UI (LuaIntro).

Should be called after each widget/unsynced gadget is loaded in widget/gadget handler. Use it to draw screen updates and process windows events.

Spring.Yield() -> boolean
Returns
booleancontinueYielding
when true caller should continue calling Spring.Yield during the widgets/gadgets load, when false it shouldn’t call it any longer.

Spring.CallAsTeam (function) view source

Calls a function from given team’s PoV. In particular this makes callouts obey that team’s visibility rules.
Spring.CallAsTeam(TeamID, fun(...), [any, ]*) -> any ...
Parameters
TeamIDteamID
Team ID.
fun(...)func
The function to call.
any...
Arguments to pass to the function.
Returns
any ...The
return values of the function.

Spring.CallAsTeam (function overload 1) view source 

Spring.CallAsTeam(CallAsTeamOptions, fun(...), [any, ]*) -> any ...
Parameters
CallAsTeamOptionsoptions
Options.
fun(...)func
The function to call.
any...
Arguments to pass to the function.
Returns
any ...The
return values of the function.

Spring.Echo (function) view source

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

Hint: the default print() writes to STDOUT.

Spring.Echo(any, [any, ]*) -> nil
Parameters
anyarg
any...
Returns
nil

Spring.Log (function) view source

Logs a message to the logfile/console.
Spring.Log(string, (LogLevel|LOG)?, [string, ]*) -> nil
Parameters
stringsection
Sets an arbitrary section. Level filtering can be applied per-section
(LogLevel|LOG)?logLevel
(Default: “notice”)
string...
messages

Spring.SetAlly (function) view source

Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
Spring.SetAlly(AllyTeamID, AllyTeamID, boolean) -> nil
Parameters
AllyTeamIDfirstAllyTeamID
AllyTeamIDsecondAllyTeamID
booleanally
Returns
nil

Spring.SetAllyTeamStartBox (function) view source

Changes the start box position of an allyTeam.
Spring.SetAllyTeamStartBox(AllyTeamID, number, number, number, number) -> nil
Parameters
AllyTeamIDallyTeamID
numberxMin
left start box boundary (elmos)
numberzMin
top start box boundary (elmos)
numberxMax
right start box boundary (elmos)
numberzMax
bottom start box boundary (elmos)
Returns
nil

Spring.AssignPlayerToTeam (function) view source

Assigns a player to a team.
Spring.AssignPlayerToTeam(PlayerID, TeamID) -> nil
Parameters
PlayerIDplayerID
TeamIDteamID
Returns
nil

Spring.SetTeamStartPosition (function) view source

Set the starting position of a team.

If the position argument is outside the team’s startbox, the position is clamped.

Spring.SetTeamStartPosition(TeamID, number, number, number) -> boolean
Parameters
TeamIDteamID
numberx
left position (elmos)
numbery
vertical position (elmos)
numberz
top position (elmos)
Returns
booleansuccess
true if the position was set, false if the teamID is invalid

Spring.SetPlayerReadyState (function) view source

Set the ready state of a player.

Use to mark a player (un)ready in the pregame phase.

Spring.SetPlayerReadyState(PlayerID, boolean) -> boolean
Parameters
PlayerIDplayerID
booleanready
Returns
booleansuccess
true if the state was set, false if the playerID was invalid

Spring.SetGlobalLos (function) view source

Changes access to global line of sight for a team and its allies.
Spring.SetGlobalLos(AllyTeamID, boolean) -> nil
Parameters
AllyTeamIDallyTeamID
booleangloballos
Returns
nil

Spring.SetCheatingEnabled (function) view source

Changes whether activating cheats is allowed. Note that already activated cheats (e.g. god mode) stay active even if you disallow activating.
Spring.SetCheatingEnabled(boolean) -> nil
Parameters
booleancheatsEnabled
Returns
nil

Spring.SetGodMode (function) view source

Toggles ‘god mode’, i.e. whether control of teams other than one’s own is allowed. Affects all teams.
Spring.SetGodMode(boolean?, boolean?) -> nil
Parameters
boolean?controlAllies
boolean?controlEnemies
Returns
nil

Spring.KillTeam (function) view source

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

Gaia team cannot be killed.

Spring.KillTeam(TeamID) -> nil
Parameters
TeamIDteamID
Returns
nil

Spring.GameOver (function) view source

Declare game over.

Pass multiple winners to declare a draw. Pass no arguments if undecided (e.g. when dropped from the host).

Spring.GameOver(AllyTeamID[]) -> integer
Parameters
AllyTeamID[]winningAllyTeamIDs
List of winning ally team IDs.
Returns
integerteams
Number of accepted (valid) ally teams.

Spring.SetTidal (function) view source

Set tidal strength
Spring.SetTidal(number?) -> nil
Parameters
number?strength
Returns
nil

Spring.SetWind (function) view source

Set wind strength
Spring.SetWind(number?, number?) -> nil
Parameters
number?minStrength
number?maxStrength
Returns
nil

Spring.AddTeamResource (function) view source

Adds metal or energy resources to the specified team. Counts as production in post-game graph statistics.
Spring.AddTeamResource(TeamID, ResourceName, number) -> nil
Parameters
TeamIDteamID
ResourceNametype
numberamount
Returns
nil

Spring.UseTeamResource (function) view source

Consumes metal or energy resources of the specified team. Counts as usage in post-game graph statistics.
Spring.UseTeamResource(TeamID, ResourceName, number) -> boolean
Parameters
TeamIDteamID
ResourceNametype
Resource type.
numberamount
Amount of resource to use.
Returns
booleanhadEnough
True if enough of the resource type was available and was consumed, otherwise false.

Spring.UseTeamResource (function overload 1) view source

Consumes metal and/or energy resources of the specified team. Counts as usage in post-game graph statistics.
Spring.UseTeamResource(TeamID, ResourceUsage) -> boolean
Parameters
TeamIDteamID
ResourceUsageamount
Returns
booleanhadEnough
True if enough of the resource type(s) were available and was consumed, otherwise false.

Spring.SetTeamResource (function) view source 

Spring.SetTeamResource(TeamID, (ResourceName|StorageName), number) -> nil
Parameters
TeamIDteamID
(ResourceName|StorageName)resource
numberamount
Returns
nil

Spring.SetTeamShareLevel (function) view source

Changes the resource amount for a team beyond which resources aren’t stored but transferred to other allied teams if possible.
Spring.SetTeamShareLevel(TeamID, ResourceName, number) -> nil
Parameters
TeamIDteamID
ResourceNametype
numberamount
Returns
nil

Spring.AddTeamResourceExcessStats (function) view source

Records resource excess for a team without moving resources.

The engine normally tracks excess, but if you use gadget:ResourceExcess to handle it manually it’s now also up to you to track stats.

Spring.AddTeamResourceExcessStats(TeamID, ResourceName, number) -> nil
Parameters
TeamIDteamID
ResourceNametype
numberexcess
Amount wasted this tick.
Returns
nil

Spring.ShareTeamResource (function) view source

Transfers resources between two teams. Transfers directly, without involving AllowResourceTransfer callin. Approximately equivalent to doing Use and Add for the sender and receiver, the difference being that it counts to sent/received stats rather than used/produced in end-game statistics graphs.
Spring.ShareTeamResource(TeamID, TeamID, ResourceName, number) -> nil
Parameters
TeamIDteamID_src
TeamIDteamID_recv
ResourceNametype
numberamount
Returns
nil

Spring.SetGameRulesParam (function) view source 

Spring.SetGameRulesParam(string, (boolean|string|number)?, losAccess?) -> nil
Parameters
stringparamName
(boolean|string|number)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetTeamRulesParam (function) view source 

Spring.SetTeamRulesParam(TeamID, string, (boolean|string|number)?, losAccess?) -> nil
Parameters
TeamIDteamID
stringparamName
(boolean|string|number)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetPlayerRulesParam (function) view source 

Spring.SetPlayerRulesParam(PlayerID, string, (boolean|string|number)?, losAccess?) -> nil
Parameters
PlayerIDplayerID
stringparamName
(boolean|string|number)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetUnitRulesParam (function) view source 

Spring.SetUnitRulesParam(UnitID, string, (boolean|string|number)?, losAccess?) -> nil
Parameters
UnitIDunitID
stringparamName
(boolean|string|number)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetFeatureRulesParam (function) view source 

Spring.SetFeatureRulesParam(FeatureID, string, (boolean|string|number)?, losAccess?) -> nil
Parameters
FeatureIDfeatureID
stringparamName
(boolean|string|number)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.CallCOBScript (function) view source 

Spring.CallCOBScript(UnitID, (string|integer)?, integer, [any, ]*) -> integer ...
Parameters
UnitIDunitID
(string|integer)?funcName
Function ID or name.
integerretArgs
Number of values to return.
any...
Arguments
Returns
integer ...

Spring.GetCOBScriptID (function) view source 

Spring.GetCOBScriptID(UnitID, string) -> integer?
Parameters
UnitIDunitID
stringfuncName
Returns
integer?funcID

Spring.CreateUnit (function) view source

See Spring.DestroyUnit

Spring.CreateUnit((string|integer), number, number, number, Facing, TeamID?, boolean?, boolean?, UnitID?, UnitID?) -> UnitID?
Parameters
(string|integer)unitDef
UnitDef name or ID.
numberposX
numberposY
numberposZ
Facingfacing
TeamID?teamID
boolean?build
(Default: false) The unit is created in “being built” state with zero buildProgress.
boolean?flattenGround
(Default: true) The unit flattens ground, if it normally does so.
UnitID?unitID
Request a specific unitID.
UnitID?builderID
Returns
UnitID?unitID
The ID of the created unit, or nil if the unit could not be created.

Spring.DestroyUnit (function) view source

See Spring.CreateUnit

Spring.DestroyUnit(UnitID, boolean?, boolean?, UnitID?, boolean?) -> nil
Parameters
UnitIDunitID
boolean?selfd
(Default: false) makes the unit act like it self-destructed.
boolean?reclaimed
(Default: false) don’t show any DeathSequences, don’t leave a wreckage. This does not give back the resources to the team!
UnitID?attackerID
boolean?cleanupImmediately
(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

Spring.TransferUnit (function) view source 

Spring.TransferUnit(UnitID, TeamID, boolean?, boolean?) -> boolean
Parameters
UnitIDunitID
TeamIDnewTeamID
boolean?given
(Default: true) if false, the unit is captured.
boolean?adjustUnitLimit
(Default: false) if true, also transfer the limit slot
Returns
booleansuccessfulTransfer

Spring.TransferTeamMaxUnits (function) view source

Transfer capacity of units from one team to another

There are some conditions that must be satisfied for the operation to be successful:

  • transferAmnt must be lower or equal than the origin team current maxunits (can’t transfer limit team does not have available)
  • transferAmnt must be lower than origin team maxunits - currentunitscount (can’t transfer limit if origin team would be already over the limit after transfer)
Spring.TransferTeamMaxUnits(TeamID, TeamID, integer) -> boolean
Parameters
TeamIDfromTeamID
TeamIDnewTeamID
integertransferAmnt
Returns
booleansuccessfulTransfer
Whether the max unit limit was successfully transferred.

Spring.SetUnitCosts (function) view source 

Spring.SetUnitCosts(UnitID, table<number,number>) -> nil
Parameters
UnitIDunitID
table<number,number>where
keys and values are, respectively and in this order: buildTime=amount, metalCost=amount, energyCost=amount
Returns
nil

Spring.SetUnitResourcing (function) view source 

Spring.SetUnitResourcing(UnitID, string, number) -> nil
Parameters
UnitIDunitID
stringres
numberamount
Returns
nil

Spring.SetUnitResourcing (function overload 1) view source 

Spring.SetUnitResourcing(UnitID, table<string,number>) -> nil
Parameters
UnitIDunitID
table<string,number>res
keys are: “[u|c][u|m][m|e]” unconditional | conditional, use | make, metal | energy. Values are amounts
Returns
nil

Spring.SetUnitStorage (function) view source 

Spring.SetUnitStorage(UnitID, string, number) -> nil
Parameters
UnitIDunitID
stringres
numberamount

Spring.SetUnitStorage (function overload 1) view source 

Spring.SetUnitStorage(UnitID, ResourceUsage) -> nil
Parameters
UnitIDunitID
ResourceUsageres
keys are: “[m|e]” metal | energy. Values are amounts

Spring.SetUnitTooltip (function) view source 

Spring.SetUnitTooltip(UnitID, string) -> nil
Parameters
UnitIDunitID
stringtooltip
Returns
nil

Spring.SetUnitHealth (function) view 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 SetUnitHealthAmounts

Spring.SetUnitHealth(UnitID, (number|SetUnitHealthAmounts)) -> nil
Parameters
UnitIDunitID
(number|SetUnitHealthAmounts)health
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

Spring.SetUnitMaxHealth (function) view source 

Spring.SetUnitMaxHealth(UnitID, number) -> nil
Parameters
UnitIDunitID
numbermaxHealth
Returns
nil

Spring.SetUnitStockpile (function) view source 

Spring.SetUnitStockpile(UnitID, integer?, number?) -> nil
Parameters
UnitIDunitID
integer?stockpile
number?buildPercent
Returns
nil

Spring.SetUnitUseWeapons (function) view source 

Spring.SetUnitUseWeapons(UnitID, number?, number?) -> nil
Parameters
UnitIDunitID
number?forceUseWeapons
number?allowUseWeapons
Returns
nil

Spring.SetUnitWeaponState (function) view source 

Spring.SetUnitWeaponState(UnitID, integer, WeaponState) -> nil
Parameters
UnitIDunitID
integerweaponNum
WeaponStatestates
Returns
nil

Spring.SetUnitWeaponState (function overload 1) view source 

Spring.SetUnitWeaponState(UnitID, integer, string, number) -> nil
Parameters
UnitIDunitID
integerweaponNum
stringkey
numbervalue
Returns
nil

Spring.SetUnitWeaponDamages (function) view source 

Spring.SetUnitWeaponDamages(UnitID, (integer|"selfDestruct"|"explode"), WeaponDamages) -> nil
Parameters
UnitIDunitID
(integer|"selfDestruct"|"explode")weaponNum
WeaponDamagesdamages
Returns
nil

Spring.SetUnitWeaponDamages (function overload 1) view source 

Spring.SetUnitWeaponDamages(UnitID, (integer|"selfDestruct"|"explode"), string, number) -> nil
Parameters
UnitIDunitID
(integer|"selfDestruct"|"explode")weaponNum
stringkey
numbervalue
Returns
nil

Spring.SetUnitMaxRange (function) view source 

Spring.SetUnitMaxRange(UnitID, number) -> nil
Parameters
UnitIDunitID
numbermaxRange
Returns
nil

Spring.SetUnitExperience (function) view source

See Spring.AddUnitExperience, Spring.GetUnitExperience

Spring.SetUnitExperience(UnitID, number) -> nil
Parameters
UnitIDunitID
numberexperience
Returns
nil

Spring.AddUnitExperience (function) view source

See Spring.SetUnitExperience, Spring.GetUnitExperience

Spring.AddUnitExperience(UnitID, number) -> nil
Parameters
UnitIDunitID
numberdeltaExperience
Can be negative to subtract, but the unit will never have negative total afterwards
Returns
nil

Spring.SetUnitArmored (function) view source 

Spring.SetUnitArmored(UnitID, boolean?, number?) -> nil
Parameters
UnitIDunitID
boolean?armored
number?armorMultiple
Returns
nil

Spring.SetUnitLosMask (function) view source

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.

See Spring.SetUnitLosState

Spring.SetUnitLosMask(UnitID, AllyTeamID, (LosTable|LosMask|integer)) -> nil
Parameters
UnitIDunitID
AllyTeamIDallyTeam
(LosTable|LosMask|integer)losTypes
A bitmask of LosMask bits or a table. True bits disable engine updates to visibility.

Spring.SetUnitLosState (function) view source

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)

See Spring.SetUnitLosMask

Spring.SetUnitLosState(UnitID, AllyTeamID, (LosTable|LosMask|integer)) -> nil
Parameters
UnitIDunitID
AllyTeamIDallyTeam
(LosTable|LosMask|integer)losTypes
A bitmask of LosMask bits or a table.

Spring.SetUnitCloak (function) view 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.
Spring.SetUnitCloak(UnitID, (boolean|number)?, (boolean|number)?) -> nil
Parameters
UnitIDunitID
(boolean|number)?cloak
(boolean|number)?cloakArg
Returns
nil

Spring.SetUnitStealth (function) view source 

Spring.SetUnitStealth(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanstealth
Returns
nil

Spring.SetUnitSonarStealth (function) view source 

Spring.SetUnitSonarStealth(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleansonarStealth
Returns
nil

Spring.SetUnitSeismicSignature (function) view source 

Spring.SetUnitSeismicSignature(UnitID, number) -> nil
Parameters
UnitIDunitID
numberseismicSignature
Returns
nil

Spring.SetUnitLeavesGhost (function) view source

Set whether unit leaves static radar ghosts.
Spring.SetUnitLeavesGhost(boolean, boolean?) -> nil
Parameters
booleanleavesGhost
boolean?leaveDeadGhost
(Default: false) leave a dead ghost behind if disabling and the unit had a live static ghost.

Spring.SetUnitAlwaysVisible (function) view source 

Spring.SetUnitAlwaysVisible(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanalwaysVisible
Returns
nil

Spring.SetUnitUseAirLos (function) view source 

Spring.SetUnitUseAirLos(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanuseAirLos
Returns
nil

Spring.SetUnitMetalExtraction (function) view source 

Spring.SetUnitMetalExtraction(UnitID, number, number?) -> nil
Parameters
UnitIDunitID
numberdepth
corresponds to metal extraction rate
number?range
similar to “extractsMetal” in unitDefs.
Returns
nil

Spring.SetUnitHarvestStorage (function) view source

See also harvestStorage UnitDef tag.
Spring.SetUnitHarvestStorage(UnitID, number?) -> nil
Parameters
UnitIDunitID
number?metal
Returns
nil

Spring.SetUnitBuildParams (function) view source 

Spring.SetUnitBuildParams(UnitID, string, (boolean|number)?) -> nil
Parameters
UnitIDunitID
stringparamName
one of buildRange|buildDistance|buildRange3D
(boolean|number)?value
boolean when paramName is buildRange3D, otherwise number.
Returns
nil

Spring.SetUnitBuildSpeed (function) view source 

Spring.SetUnitBuildSpeed(UnitID, number, number?, number?, number?, number?) -> nil
Parameters
UnitIDbuilderID
numberbuildSpeed
number?repairSpeed
number?reclaimSpeed
number?captureSpeed
number?terraformSpeed
Returns
nil

Spring.SetUnitNanoPieces (function) view source

This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!
Spring.SetUnitNanoPieces(UnitID, table) -> nil
Parameters
UnitIDbuilderID
tablepieces
Returns
nil

Spring.SetUnitBlocking (function) view source 

Spring.SetUnitBlocking(UnitID, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?) -> boolean
Parameters
UnitIDunitID
boolean?isBlocking
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.
boolean?isSolidObjectCollidable
Enable or disable collision with solid objects, or no change if nil.
boolean?isProjectileCollidable
Enable or disable collision with projectiles, or no change if nil.
boolean?isRaySegmentCollidable
Enable or disable collision with ray segments, or no change if nil.
boolean?crushable
Enable or disable crushable, or no change if nil.
boolean?blockEnemyPushing
Enable or disable blocking enemy pushing, or no change if nil.
boolean?blockHeightChanges
Enable or disable blocking height changes, or no change if nil.
Returns
booleanisBlocking

Spring.SetUnitCrashing (function) view source 

Spring.SetUnitCrashing(UnitID, boolean?) -> boolean
Parameters
UnitIDunitID
boolean?crashing
Returns
booleansuccess

Spring.SetUnitShieldState (function) view source 

Spring.SetUnitShieldState(UnitID, integer?, boolean?, number?) -> nil
Parameters
UnitIDunitID
integer?weaponID
(Default: -1)
boolean?enabled
number?power
Returns
nil

Spring.SetUnitShieldRechargeDelay (function) view source 

Spring.SetUnitShieldRechargeDelay(UnitID, integer?, number?) -> nil
Parameters
UnitIDunitID
integer?weaponID
(optional if the unit only has one shield)
number?rechargeTime
(in seconds; emulates a regular hit if nil)
Returns
nil

Spring.SetUnitFlanking (function) view source 

Spring.SetUnitFlanking(UnitID, string, number, number?, number?) -> nil
Parameters
UnitIDunitID
stringtype
“dir”|“minDamage”|“maxDamage”|“moveFactor”|“mode”
numberarg1
x|minDamage|maxDamage|moveFactor|mode
number?y
only when type is “dir”
number?z
only when type is “dir”
Returns
nil

Spring.SetUnitPhysicalStateBit (function) view source 

Spring.SetUnitPhysicalStateBit(UnitID, number[bit]) -> nil
Parameters
UnitIDunitID
number[bit]Physical
state bit
Returns
nil

Spring.GetUnitPhysicalState (function) view source 

Spring.GetUnitPhysicalState(UnitID) -> integer
Parameters
UnitIDunitID
Returns
integerphysicalState
Unit’s PhysicalState bitmask

Spring.SetUnitNeutral (function) view source 

Spring.SetUnitNeutral(UnitID, boolean) -> boolean?
Parameters
UnitIDunitID
booleanneutral
Returns
boolean?setNeutral

Spring.SetUnitTarget (function) view source

Defines a unit’s target.
Spring.SetUnitTarget(UnitID, UnitID?, boolean?, boolean?, boolean?, integer?) -> boolean
Parameters
UnitIDunitID
UnitID?enemyUnitID
when nil drops the units current target.
boolean?dgun
(Default: false)
boolean?userTarget
(Default: false)
boolean?dontForceTarget
integer?weaponNum
(Default: -1)
Returns
booleansuccess

Spring.SetUnitTarget (function overload 1) view source 

Spring.SetUnitTarget(UnitID, number?, number?, number?, boolean?, boolean?, boolean?, integer?) -> boolean
Parameters
UnitIDunitID
number?x
when nil or not passed it will drop target and ignore other parameters
number?y
number?z
boolean?dgun
(Default: false)
boolean?userTarget
(Default: false)
boolean?dontForceTarget
integer?weaponNum
(Default: -1)
Returns
booleansuccess

Spring.SetUnitMidAndAimPos (function) view source 

Spring.SetUnitMidAndAimPos(UnitID, number, number, number, number, number, number, boolean?) -> boolean
Parameters
UnitIDunitID
numbermpX
new middle positionX of unit
numbermpY
new middle positionY of unit
numbermpZ
new middle positionZ of unit
numberapX
new positionX that enemies aim at on this unit
numberapY
new positionY that enemies aim at on this unit
numberapZ
new positionZ that enemies aim at on this unit
boolean?relative
(Default: false) are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!
Returns
booleansuccess

Spring.SetUnitRadiusAndHeight (function) view source 

Spring.SetUnitRadiusAndHeight(UnitID, number?, number?) -> boolean
Parameters
UnitIDunitID
number?radius
number?height
Returns
booleansuccess

Spring.SetUnitBuildeeRadius (function) view source

Sets the unit’s radius for when targeted by build, repair, reclaim-type commands.
Spring.SetUnitBuildeeRadius(UnitID, number) -> nil
Parameters
UnitIDunitID
numberbuild
radius for when targeted by build, repair, reclaim-type commands.
Returns
nil

Spring.SetUnitPieceParent (function) view source

Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
Spring.SetUnitPieceParent(UnitID, integer, integer) -> nil
Parameters
UnitIDunitID
integerAlteredPiece
integerParentPiece
Returns
nil

Spring.SetUnitPieceMatrix (function) view source

Sets the local (i.e. parent-relative) matrix of the given piece.

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.

Spring.SetUnitPieceMatrix(UnitID, integer, number[]) -> boolean?
Parameters
UnitIDunitID
integerpieceNum
number[]matrix
an array of 16 floats
Returns
boolean?valid
whether the matrix can be used for the purpose of defining the piece spatial transformation. Blocks the piece animation, if true.

Spring.SetUnitCollisionVolumeData (function) view source

cpp enum 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 }; 
Spring.SetUnitCollisionVolumeData(UnitID, number, number, number, number, number, number, integer, integer, integer) -> nil
Parameters
UnitIDunitID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integervType
integertType
integerAxis
Returns
nil

Spring.SetUnitPieceCollisionVolumeData (function) view source 

Spring.SetUnitPieceCollisionVolumeData(UnitID, integer, boolean, number, number, number, number, number, number, integer?, integer?) -> nil
Parameters
UnitIDunitID
integerpieceIndex
booleanenable
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integer?volumeType
integer?primaryAxis
Returns
nil

Spring.SetUnitPieceVisible (function) view source 

Spring.SetUnitPieceVisible(UnitID, integer, boolean) -> nil
Parameters
UnitIDunitID
integerpieceIndex
booleanvisible
Returns
nil

Spring.SetUnitSensorRadius (function) view source 

Spring.SetUnitSensorRadius(UnitID, ("los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"...), integer) -> integer?
Parameters
UnitIDunitID
("los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"...)type
integerradius
Returns
integer?newRadius
New radius, or nil if unit is invalid.

Spring.SetUnitPosErrorParams (function) view source

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.

Spring.SetUnitPosErrorParams(UnitID, number?, number?, number?, number?, number?, number?, integer?) -> nil
Parameters
UnitIDunitID
number?posErrorVectorX
number?posErrorVectorY
number?posErrorVectorZ
number?posErrorDeltaX
number?posErrorDeltaY
number?posErrorDeltaZ
integer?nextPosErrorUpdate
Returns
nil

Spring.SetUnitMoveGoal (function) view source

Used by default commands to get in build-, attackrange etc.
Spring.SetUnitMoveGoal(UnitID, number, number, number, number?, number?, boolean?) -> nil
Parameters
UnitIDunitID
numbergoalX
numbergoalY
numbergoalZ
number?goalRadius
number?moveSpeed
boolean?moveRaw
Returns
nil

Spring.SetUnitLandGoal (function) view source

Used in conjunction with Spring.UnitAttach et al. to re-implement old airbase & fuel system in Lua.
Spring.SetUnitLandGoal(UnitID, number, number, number, number?) -> nil
Parameters
UnitIDunitID
numbergoalX
numbergoalY
numbergoalZ
number?goalRadius
Returns
nil

Spring.ClearUnitGoal (function) view source 

Spring.ClearUnitGoal(UnitID, boolean?) -> nil
Parameters
UnitIDunitID
boolean?maneuver
Returns
nil

Spring.SetUnitPhysics (function) view source 

Spring.SetUnitPhysics(UnitID, number, number, number, number, number, number, number, number, number, number, number, number) -> nil
Parameters
UnitIDunitID
numberposX
numberposY
numberposZ
numbervelX
numbervelY
numbervelZ
numberrotX
numberrotY
numberrotZ
numberdragX
numberdragY
numberdragZ
Returns
nil

Spring.SetUnitMass (function) view source 

Spring.SetUnitMass(UnitID, number) -> nil
Parameters
UnitIDunitID
numbermass
Returns
nil

Spring.SetUnitPosition (function) view source

Set unit position (2D)

Sets a unit’s position in 2D, at terrain height.

Spring.SetUnitPosition(UnitID, number, number, boolean?) -> nil
Parameters
UnitIDunitID
numberx
numberz
boolean?floating
(Default: false) If true, over water the position is on surface. If false, on seafloor.
Returns
nil

Spring.SetUnitPosition (function overload 1) view source

Set unit position (3D)

Sets a unit’s position in 3D, at an arbitrary height.

Spring.SetUnitPosition(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberx
numbery
numberz
Returns
nil

Spring.SetUnitRotation (function) view source

Note: PYR order
Spring.SetUnitRotation(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberpitch
Rotation in X axis
numberyaw
Rotation in Y axis
numberroll
Rotation in Z axis
Returns
nil

Spring.SetUnitDirection (function) view source

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

Deprecated: It’s strongly that you use the overload that accepts

Spring.SetUnitDirection(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberfrontx
numberfronty
numberfrontz
Returns
nil

Spring.SetUnitDirection (function overload 1) view source

Set unit front and right direction vectors.

Both vectors will be normalized in the engine.

Spring.SetUnitDirection(UnitID, number, number, number, number, number, number) -> nil
Parameters
UnitIDunitID
numberfrontx
numberfronty
numberfrontz
numberrightx
numberrighty
numberrightz
Returns
nil

Spring.SetUnitHeadingAndUpDir (function) view 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.
Spring.SetUnitHeadingAndUpDir(UnitID, Heading, number, number, number) -> nil
Parameters
UnitIDunitID
Headingheading
numberupx
numberupy
numberupz
Returns
nil

Spring.SetUnitVelocity (function) view source

Set the velocity of a Unit

See Spring.SetUnitMoveCtrl for disabling/enabling this control

Spring.SetUnitVelocity(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numbervelX
Velocity x component in elmos/frame.
numbervelY
Velocity y component in elmos/frame.
numbervelZ
Velocity z component in elmos/frame.

Spring.SetFactoryBuggerOff (function) view source 

Spring.SetFactoryBuggerOff(UnitID, boolean?, number?, number?, Heading?, boolean?, boolean?) -> number?
Parameters
UnitIDunitID
boolean?buggerOff
number?offset
number?radius
Heading?relHeading
boolean?spherical
boolean?forced
Returns
number?buggerOff

Spring.BuggerOff (function) view source 

Spring.BuggerOff(number, number, number?, number, TeamID, boolean?, boolean?, UnitID?, UnitDefID[]?) -> nil
Parameters
numberx
numbery
number?z
uses ground height when unspecified
numberradius
TeamIDteamID
boolean?spherical
(Default: true)
boolean?forced
(Default: true)
UnitID?excludeUnitID
UnitDefID[]?excludeUnitDefIDs
Returns
nil

Spring.AddFeatureDamage (function) view source

Apply damage to feature

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 SyncedCallins:FeaturePreDamaged, SyncedCallins:FeatureDamaged

Spring.AddFeatureDamage(FeatureID, number, integer?, UnitID?, WeaponDefID?, number?, number?, number?) -> nil
Parameters
FeatureIDfeatureID
numberdamage
integer?paralyze
(Default: 0) equals to the paralyzetime in the WeaponDef.
UnitID?attackerID
(Default: -1)
WeaponDefID?weaponID
(Default: -1)
number?impulseX
number?impulseY
number?impulseZ

Spring.AddUnitDamage (function) view source 

Spring.AddUnitDamage(UnitID, number, integer?, UnitID?, WeaponDefID?, number?, number?, number?) -> nil
Parameters
UnitIDunitID
numberdamage
integer?paralyze
(Default: 0) equals to the paralyzetime in the WeaponDef.
UnitID?attackerID
(Default: -1)
WeaponDefID?weaponID
(Default: -1)
number?impulseX
number?impulseY
number?impulseZ
Returns
nil

Spring.AddUnitImpulse (function) view source 

Spring.AddUnitImpulse(UnitID, number, number, number, number?) -> nil
Parameters
UnitIDunitID
numberx
numbery
numberz
number?decayRate
Returns
nil

Spring.AddUnitSeismicPing (function) view source 

Spring.AddUnitSeismicPing(UnitID, number) -> nil
Parameters
UnitIDunitID
numberpindSize
Returns
nil

Spring.AddUnitResource (function) view source 

Spring.AddUnitResource(UnitID, string, number) -> nil
Parameters
UnitIDunitID
stringresource
“m” | “e”
numberamount
Returns
nil

Spring.UseUnitResource (function) view source 

Spring.UseUnitResource(UnitID, ResourceName, number) -> boolean?
Parameters
UnitIDunitID
ResourceNameresource
numberamount
Returns
boolean?okay

Spring.UseUnitResource (function overload 1) view source 

Spring.UseUnitResource(UnitID, ResourceUsage) -> boolean?
Parameters
UnitIDunitID
ResourceUsageresources
Returns
boolean?okay

Spring.AddObjectDecal (function) view source 

Spring.AddObjectDecal(UnitID) -> nil
Parameters
UnitIDunitID
Returns
nil

Spring.RemoveObjectDecal (function) view source 

Spring.RemoveObjectDecal(UnitID) -> nil
Parameters
UnitIDunitID
Returns
nil

Spring.AddGrass (function) view source 

Spring.AddGrass(number, number) -> nil
Parameters
numberx
numberz
Returns
nil

Spring.RemoveGrass (function) view source 

Spring.RemoveGrass(number, number) -> nil
Parameters
numberx
numberz
Returns
nil

Spring.CreateFeature (function) view source 

Spring.CreateFeature((string|integer), number, number, number, Heading?, TeamID?, FeatureID?) -> FeatureID?
Parameters
(string|integer)featureDef
name or id
numberx
numbery
numberz
Heading?heading
TeamID?teamID
FeatureID?featureID
Returns
FeatureID?featureID
returns nil if creation was unsuccessful

Spring.DestroyFeature (function) view source 

Spring.DestroyFeature(FeatureID) -> nil
Parameters
FeatureIDfeatureID
Returns
nil

Spring.TransferFeature (function) view source

Feature Control
Spring.TransferFeature(FeatureID, TeamID) -> nil
Parameters
FeatureIDfeatureID
TeamIDteamID
Returns
nil

Spring.SetFeatureAlwaysVisible (function) view source 

Spring.SetFeatureAlwaysVisible(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleanenable
Returns
nil

Spring.SetFeatureUseAirLos (function) view source 

Spring.SetFeatureUseAirLos(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleanuseAirLos
Returns
nil

Spring.SetFeatureHealth (function) view source 

Spring.SetFeatureHealth(FeatureID, number, boolean?) -> nil
Parameters
FeatureIDfeatureID
numberhealth
boolean?checkDestruction
(Default: false) Whether to destroy feature if feature goes below 0 health.
Returns
nil

Spring.SetFeatureMaxHealth (function) view source 

Spring.SetFeatureMaxHealth(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numbermaxHealth
minimum 0.1
Returns
nil

Spring.SetFeatureReclaim (function) view source 

Spring.SetFeatureReclaim(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numberreclaimLeft
Returns
nil

Spring.SetFeatureResources (function) view source 

Spring.SetFeatureResources(FeatureID, number, number, number?, number?, number?, number?) -> nil
Parameters
FeatureIDfeatureID
numbermetal
numberenergy
number?reclaimTime
number?reclaimLeft
number?featureDefMetal
number?featureDefEnergy
Returns
nil

Spring.SetFeatureResurrect (function) view source 

Spring.SetFeatureResurrect(FeatureID, (string|integer)?, Facing?, number?) -> nil
Parameters
FeatureIDfeatureID
(string|integer)?unitDef
Can be a number id or a string name, this allows cancelling resurrection by passing -1.
Facing?facing
(Default: “south”)
number?progress
Set the level of progress.
Returns
nil

Spring.SetFeatureMoveCtrl (function) view source

Enable feature movement control.
Spring.SetFeatureMoveCtrl(FeatureID, true, number?, number?, number?, number?, number?, number?) -> nil
Parameters
FeatureIDfeatureID
trueenabled
Enable feature movement.
number?initialVelocityX
Initial velocity on X axis, or nil for no change.
number?initialVelocityY
Initial velocity on Y axis, or nil for no change.
number?initialVelocityZ
Initial velocity on Z axis, or nil for no change.
number?accelerationX
Acceleration per frame on X axis, or nil for no change.
number?accelerationY
Acceleration per frame on Y axis, or nil for no change.
number?accelerationZ
Acceleration per frame on Z axis, or nil for no change.

Spring.SetFeatureMoveCtrl (function overload 1) view source

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:

lua – 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) 

Spring.SetFeatureMoveCtrl(FeatureID, false, number?, number?, number?, number?, number?, number?, number?, number?, number?) -> nil
Parameters
FeatureIDfeatureID
falseenabled
Disable feature movement.
number?velocityMaskX
Lock velocity change in X dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.
number?velocityMaskY
Lock velocity change in Y dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.
number?velocityMaskZ
Lock velocity change in Z dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.
number?impulseMaskX
Lock impulse in X dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.
number?impulseMaskY
Lock impulse in Y dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.
number?impulseMaskZ
Lock impulse in Z dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.
number?movementMaskX
Lock move in X dimension when not using MoveCtrl. 0 to lock the axis, non-zero to allow, or nil for no change.
number?movementMaskY
Lock move in Y dimension when not using MoveCtrl. 0 to lock the axis, non-zero to allow, or nil for no change.
number?movementMaskZ
Lock move in Z dimension when not using MoveCtrl. 0 to lock the axis, non-zero to allow, or nil for no change.

Spring.SetFeaturePhysics (function) view source 

Spring.SetFeaturePhysics(FeatureID, number, number, number, number, number, number, number, number, number, number, number, number) -> nil
Parameters
FeatureIDfeatureID
numberposX
numberposY
numberposZ
numbervelX
numbervelY
numbervelZ
numberrotX
numberrotY
numberrotZ
numberdragX
numberdragY
numberdragZ
Returns
nil

Spring.SetFeatureMass (function) view source 

Spring.SetFeatureMass(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numbermass
Returns
nil

Spring.SetFeaturePosition (function) view source 

Spring.SetFeaturePosition(FeatureID, number, number, number, boolean?) -> nil
Parameters
FeatureIDfeatureID
numberx
numbery
numberz
boolean?snapToGround
Returns
nil

Spring.SetFeatureRotation (function) view source

Note: PYR order
Spring.SetFeatureRotation(FeatureID, number, number, number) -> nil
Parameters
FeatureIDfeatureID
numberpitch
Rotation in X axis
numberyaw
Rotation in Y axis
numberroll
Rotation in Z axis
Returns
nil

Spring.SetFeatureDirection (function) view source

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

Deprecated: It’s strongly that you use the overload that accepts

Spring.SetFeatureDirection(FeatureID, number, number, number) -> nil
Parameters
FeatureIDfeatureID
numberfrontx
numberfronty
numberfrontz
Returns
nil

Spring.SetFeatureDirection (function overload 1) view source

Set feature front and right direction vectors.

Both vectors will be normalized in the engine.

Spring.SetFeatureDirection(FeatureID, number, number, number, number, number, number) -> nil
Parameters
FeatureIDfeatureID
numberfrontx
numberfronty
numberfrontz
numberrightx
numberrighty
numberrightz
Returns
nil

Spring.SetFeatureHeadingAndUpDir (function) view 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.
Spring.SetFeatureHeadingAndUpDir(FeatureID, Heading, number, number, number) -> nil
Parameters
FeatureIDfeatureID
Headingheading
numberupx
numberupy
numberupz
Returns
nil

Spring.SetFeatureVelocity (function) view source

Set the velocity of a Feature

See Spring.SetFeatureMoveCtrl for disabling/enabling this control

Spring.SetFeatureVelocity(FeatureID, number, number, number) -> nil
Parameters
FeatureIDfeatureID
numbervelX
Velocity x component in elmos/frame.
numbervelY
Velocity y component in elmos/frame.
numbervelZ
Velocity z component in elmos/frame.

Spring.SetFeatureBlocking (function) view source 

Spring.SetFeatureBlocking(FeatureID, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?) -> boolean
Parameters
FeatureIDfeatureID
boolean?isBlocking
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.
boolean?isSolidObjectCollidable
Enable or disable collision with solid objects, or no change if nil.
boolean?isProjectileCollidable
Enable or disable collision with projectiles, or no change if nil.
boolean?isRaySegmentCollidable
Enable or disable collision with ray segments, or no change if nil.
boolean?crushable
Enable or disable crushable, or no change if nil.
boolean?blockEnemyPushing
Enable or disable blocking enemy pushing, or no change if nil.
boolean?blockHeightChanges
Enable or disable blocking height changes, or no change if nil.
Returns
booleanisBlocking

Spring.SetFeatureNoSelect (function) view source 

Spring.SetFeatureNoSelect(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleannoSelect
Returns
nil

Spring.SetFeatureMidAndAimPos (function) view source

Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.
Spring.SetFeatureMidAndAimPos(FeatureID, number, number, number, number, number, number, boolean?) -> boolean
Parameters
FeatureIDfeatureID
numbermpX
numbermpY
numbermpZ
numberapX
numberapY
numberapZ
boolean?relative
Returns
booleansuccess

Spring.SetFeatureRadiusAndHeight (function) view source 

Spring.SetFeatureRadiusAndHeight(FeatureID, number?, number?) -> boolean
Parameters
FeatureIDfeatureID
number?radius
number?height
Returns
booleansuccess

Spring.SetFeatureCollisionVolumeData (function) view source

Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.
Spring.SetFeatureCollisionVolumeData(FeatureID, number, number, number, number, number, number, integer, integer, integer) -> nil
Parameters
FeatureIDfeatureID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integervType
integertType
integerAxis
Returns
nil

Spring.SetFeaturePieceCollisionVolumeData (function) view source 

Spring.SetFeaturePieceCollisionVolumeData(FeatureID, integer, boolean, number, number, number, number, number, number, number, number, number?) -> nil
Parameters
FeatureIDfeatureID
integerpieceIndex
booleanenable
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numberAxis
numbervolumeType
number?primaryAxis
Returns
nil

Spring.SetFeaturePieceVisible (function) view source 

Spring.SetFeaturePieceVisible(FeatureID, integer, boolean) -> nil
Parameters
FeatureIDfeatureID
integerpieceIndex
booleanvisible
Returns
nil

Spring.SetFeaturePieceMatrix (function) view source

Sets the local (i.e. parent-relative) matrix of the given piece, for a feature.
Spring.SetFeaturePieceMatrix(FeatureID, integer, number[]) -> boolean?
Parameters
FeatureIDfeatureID
integerpieceIndex
number[]matrix
an array of 16 floats
Returns
boolean?valid
whether the matrix can be used for the purpose of defining the piece spatial transformation

Spring.SetFeatureFireTime (function) view source

Set the fire timer for a feature.

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

Spring.SetFeatureFireTime(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numberfireTime
Fire timer duration in seconds.

Spring.SetFeatureSmokeTime (function) view source

Set the smoke timer for a feature.

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.

Spring.SetFeatureSmokeTime(FeatureID, number) -> nil
Parameters
FeatureIDfeatureID
numbersmokeTime
Smoke timer duration in seconds.

Spring.CreateUnitWreck (function) view source

Create a wreck from a unit
Spring.CreateUnitWreck(UnitID, integer?, boolean?) -> FeatureID?
Parameters
UnitIDunitID
integer?wreckLevel
(Default: 1) Wreck index to use.
boolean?doSmoke
(Default: true) Wreck emits smoke when true.
Returns
FeatureID?featureID
The wreck featureID, or nil if it couldn’t be created or unit doesn’t exist.

Spring.CreateFeatureWreck (function) view source

Create a wreck from a feature
Spring.CreateFeatureWreck(FeatureID, integer?, boolean?) -> FeatureID?
Parameters
FeatureIDfeatureID
integer?wreckLevel
(Default: 1) Wreck index to use.
boolean?doSmoke
(Default: false) Wreck emits smoke when true.
Returns
FeatureID?featureID
The wreck featureID, or nil if it couldn’t be created or unit doesn’t exist.

Spring.SetProjectileAlwaysVisible (function) view source 

Spring.SetProjectileAlwaysVisible(ProjectileID, boolean) -> nil
Parameters
ProjectileIDprojectileID
booleanalwaysVisible
Returns
nil

Spring.SetProjectileUseAirLos (function) view source 

Spring.SetProjectileUseAirLos(ProjectileID, boolean) -> nil
Parameters
ProjectileIDprojectileID
booleanuseAirLos
Returns
nil

Spring.SetProjectileMoveControl (function) view source

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.

Spring.SetProjectileMoveControl(ProjectileID, boolean?) -> nil
Parameters
ProjectileIDprojectileID
boolean?enable

Spring.SetProjectilePosition (function) view source

Set the position of a projectile
Spring.SetProjectilePosition(ProjectileID, number?, number?, number?) -> nil
Parameters
ProjectileIDprojectileID
number?posX
(Default: 0)
number?posY
(Default: 0)
number?posZ
(Default: 0)

Spring.SetProjectileVelocity (function) view source

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.

See Spring.SetProjectileMoveControl

Spring.SetProjectileVelocity(ProjectileID, number, number, number) -> nil
Parameters
ProjectileIDprojectileID
numbervelX
Velocity x component in elmos/frame.
numbervelY
Velocity y component in elmos/frame.
numbervelZ
Velocity z component in elmos/frame.

Spring.SetProjectileCollision (function) view source 

Spring.SetProjectileCollision(ProjectileID) -> nil
Parameters
ProjectileIDprojectileID

Spring.SetProjectileTarget (function) view source

Set projectile target (object)
Spring.SetProjectileTarget(ProjectileID, (UnitID|FeatureID|ProjectileID), ProjectileTargetType) -> boolean?
Parameters
ProjectileIDprojectileID
(UnitID|FeatureID|ProjectileID)targetID
ProjectileTargetTypetargetType
Returns
boolean?validTarget

Spring.SetProjectileTarget (function overload 1) view source

Set projectile target (position)
Spring.SetProjectileTarget(ProjectileID, number, number, number) -> boolean?
Parameters
ProjectileIDprojectileID
numberposX
numberposY
numberposZ
Returns
boolean?validTarget

Spring.SetProjectileTimeToLive (function) view source

Set Time To Live for a projectile
Spring.SetProjectileTimeToLive(ProjectileID, integer) -> nil
Parameters
ProjectileIDprojectileID
integerttl
Remaining time to live in frames

Spring.SetProjectileIsIntercepted (function) view source 

Spring.SetProjectileIsIntercepted(ProjectileID) -> nil
Parameters
ProjectileIDprojectileID

Spring.SetProjectileDamages (function) view source 

Spring.SetProjectileDamages(ProjectileID, integer, string, number) -> nil
Parameters
ProjectileIDprojectileID
integerweaponNum
stringkey
numbervalue

Spring.SetProjectileIgnoreTrackingError (function) view source 

Spring.SetProjectileIgnoreTrackingError(ProjectileID, boolean) -> nil
Parameters
ProjectileIDprojectileID
booleanignore

Spring.SetProjectileGravity (function) view source 

Spring.SetProjectileGravity(ProjectileID, number?) -> nil
Parameters
ProjectileIDprojectileID
number?grav
(Default: 0)
Returns
nil

Spring.SetPieceProjectileParams (function) view source

Set piece projectile params

Non passed or nil args don’t set params.

Spring.SetPieceProjectileParams(ProjectileID, integer?, number?, number?, number?, number?, number?) -> nil
Parameters
ProjectileIDprojectileID
integer?explosionFlags
number?spinAngle
number?spinSpeed
number?spinVectorX
number?spinVectorY
number?spinVectorZ

Spring.SetProjectileCEG (function) view source 

Spring.SetProjectileCEG(ProjectileID, string) -> nil
Parameters
ProjectileIDprojectileID
stringceg_name
Returns
nil

Spring.UnitFinishCommand (function) view source 

Spring.UnitFinishCommand(UnitID) -> nil
Parameters
UnitIDunitID

Spring.LevelHeightMap (function) view source

Set the height of a point in the world.
Spring.LevelHeightMap(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.LevelHeightMap (function overload 1) view source

Set the height of a rectangle area in the world.
Spring.LevelHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.AdjustHeightMap (function) view source

Add height to a point in the world.
Spring.AdjustHeightMap(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.AdjustHeightMap (function overload 1) view source

Add height to a rectangle in the world.
Spring.AdjustHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.RevertHeightMap (function) view source

Restore map height at a point in the world.
Spring.RevertHeightMap(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.RevertHeightMap (function overload 1) view source

Restore map height of a rectangle area in the world.
Spring.RevertHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.AddHeightMap (function) view source

Can only be called in Spring.SetHeightMapFunc
Spring.AddHeightMap(number, number, number) -> integer?
Parameters
numberx
numberz
numberheight
Returns
integer?newHeight

Spring.SetHeightMap (function) view source

Can only be called in Spring.SetHeightMapFunc.
Spring.SetHeightMap(number, number, number, number?) -> integer?
Parameters
numberx
numberz
numberheight
number?terraform
(Default: 1) Scaling factor.
Returns
integer?absHeightDiff
If 0, nothing will be changed (the terraform starts), if 1 the terraform will be finished.

Spring.SetHeightMapFunc (function) view source

Example code:

lua 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) 

Spring.SetHeightMapFunc(function, [number, ]*) -> integer?
Parameters
functionluaFunction
number...
Returns
integer?absTotalHeightMapAmountChanged

Spring.LevelOriginalHeightMap (function) view source

Set the height of a point in the original map height cache.
Spring.LevelOriginalHeightMap(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.LevelOriginalHeightMap (function overload 1) view source

Set the height of a rectangle area in the original map height cache.
Spring.LevelOriginalHeightMap(number, number, number, number, number) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
numberheight

Spring.AdjustOriginalHeightMap (function) view source

Add height to a point in the original map height cache.
Spring.AdjustOriginalHeightMap(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.AdjustOriginalHeightMap (function overload 1) view source

Add height to a rectangle area in the original map height cache.
Spring.AdjustOriginalHeightMap(number, number, number, number, number) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
numberheight

Spring.RevertOriginalHeightMap (function) view source

Restore original map height at a point in the world.
Spring.RevertOriginalHeightMap(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.RevertOriginalHeightMap (function overload 1) view source

Restore original map height over a rectangle in the world.
Spring.RevertOriginalHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.AddOriginalHeightMap (function) view source

Can only be called in Spring.SetOriginalHeightMapFunc
Spring.AddOriginalHeightMap(number, number, number) -> nil
Parameters
numberx
numbery
numberheight
Returns
nil

Spring.SetOriginalHeightMap (function) view source

Can only be called in Spring.SetOriginalHeightMapFunc
Spring.SetOriginalHeightMap(number, number, number, number?) -> nil
Parameters
numberx
numbery
numberheight
number?factor
Returns
nil

Spring.SetOriginalHeightMapFunc (function) view source

Cannot recurse on itself
Spring.SetOriginalHeightMapFunc(function) -> nil
Parameters
functionheightMapFunc
Returns
nil

Spring.RebuildSmoothMesh (function) view source

Heightmap changes normally take up to 25s to propagate to the smooth mesh. Use to force a mapwide update immediately.
Spring.RebuildSmoothMesh() -> nil
Returns
nil

Spring.LevelSmoothMesh (function) view source 

Spring.LevelSmoothMesh(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.LevelSmoothMesh (function overload 1) view source 

Spring.LevelSmoothMesh(number, number, number, number, number) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
numberheight

Spring.AdjustSmoothMesh (function) view source 

Spring.AdjustSmoothMesh(number, number, number) -> nil
Parameters
numberx
numberz
numberheight

Spring.AdjustSmoothMesh (function overload 1) view source 

Spring.AdjustSmoothMesh(number, number, number, number, number) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
numberheight

Spring.RevertSmoothMesh (function) view source 

Spring.RevertSmoothMesh(number, number, number) -> nil
Parameters
numberx
numberz
numberorigFactor

Spring.RevertSmoothMesh (function overload 1) view source 

Spring.RevertSmoothMesh(number, number, number, number, number) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
numberorigFactor

Spring.AddSmoothMesh (function) view source

Can only be called in Spring.SetSmoothMeshFunc.
Spring.AddSmoothMesh(number, number, number) -> number?
Parameters
numberx
numberz
numberheight
Returns
number?height
The new height, or nil if coordinates are invalid.

Spring.SetSmoothMesh (function) view source

Can only be called in Spring.SetSmoothMeshFunc.
Spring.SetSmoothMesh(number, number, number, number?) -> number?
Parameters
numberx
numberz
numberheight
number?terraform
(Default: 1)
Returns
number?heightDifference
The absolute height difference, or nil if coordinates are invalid.

Spring.SetSmoothMeshFunc (function) view source 

Spring.SetSmoothMeshFunc(function, any, [any, ]*) -> number?
Parameters
functionluaFunction
anyarg
any...
Returns
number?absTotalHeightMapAmountChanged

Spring.SetMapSquareTerrainType (function) view source 

Spring.SetMapSquareTerrainType(number, number, integer) -> integer?
Parameters
numberx
numberz
integernewType
Returns
integer?oldType

Spring.SetTerrainTypeData (function) view source 

Spring.SetTerrainTypeData(integer, number?, number?, number?, number?) -> boolean?
Parameters
integertypeIndex
number?speedTanks
(Default: nil)
number?speedKBOts
(Default: nil)
number?speedHovers
(Default: nil)
number?speedShips
(Default: nil)
Returns
boolean?
true

Spring.SetSquareBuildingMask (function) view source

See also buildingMask unitdef tag.
Spring.SetSquareBuildingMask(integer, integer, integer) -> nil
Parameters
integerx
integerz
integermask
Returns
nil

Spring.UnitWeaponFire (function) view source 

Spring.UnitWeaponFire(UnitID, integer) -> nil
Parameters
UnitIDunitID
integerweaponID
Returns
nil

Spring.UnitWeaponHoldFire (function) view source 

Spring.UnitWeaponHoldFire(UnitID, integer) -> nil
Parameters
UnitIDunitID
integerweaponID
Returns
nil

Spring.ForceUnitCollisionUpdate (function) view source

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.

Spring.ForceUnitCollisionUpdate(UnitID) -> nil
Parameters
UnitIDunitID
Returns
nil

Spring.UnitAttach (function) view source 

Spring.UnitAttach(UnitID, UnitID, integer, boolean?) -> nil
Parameters
UnitIDtransporterID
UnitIDpassengerID
integerpieceNum
boolean?force
Returns
nil

Spring.UnitDetach (function) view source 

Spring.UnitDetach(UnitID) -> nil
Parameters
UnitIDpassengerID
Returns
nil

Spring.UnitDetachFromAir (function) view source 

Spring.UnitDetachFromAir(UnitID) -> nil
Parameters
UnitIDpassengerID
Returns
nil

Spring.SetUnitLoadingTransport (function) view source

Disables collisions between the two units to allow colvol intersection during the approach.
Spring.SetUnitLoadingTransport(UnitID, UnitID) -> nil
Parameters
UnitIDpassengerID
UnitIDtransportID
Returns
nil

Spring.SpawnProjectile (function) view source 

Spring.SpawnProjectile(WeaponDefID, ProjectileParams) -> ProjectileID?
Parameters
WeaponDefIDweaponDefID
ProjectileParamsprojectileParams
Returns
ProjectileID?projectileID

Spring.DeleteProjectile (function) view source

Silently removes projectiles (no explosion).
Spring.DeleteProjectile(ProjectileID) -> nil
Parameters
ProjectileIDprojectileID
Returns
nil

Spring.SpawnExplosion (function) view source 

Spring.SpawnExplosion(number?, number?, number?, number?, number?, number?, ExplosionParams?) -> nil
Parameters
number?posX
(Default: 0)
number?posY
(Default: 0)
number?posZ
(Default: 0)
number?dirX
(Default: 0)
number?dirY
(Default: 0)
number?dirZ
(Default: 0)
ExplosionParams?explosionParams
Returns
nil

Spring.SpawnCEG (function) view source 

Spring.SpawnCEG(string, number?, number?, number?, number?, number?, number?, number?, number?) -> boolean?, integer
Parameters
stringcegname
number?posX
(Default: 0)
number?posY
(Default: 0)
number?posZ
(Default: 0)
number?dirX
(Default: 0)
number?dirY
(Default: 0)
number?dirZ
(Default: 0)
number?radius
(Default: 0)
number?damage
(Default: 0)
Returns
boolean?success
integercegID

Spring.SpawnSFX (function) view source

Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.
Spring.SpawnSFX(UnitID?, integer?, number?, number?, number?, number?, number?, number?, number?, number?, boolean?) -> boolean?
Parameters
UnitID?unitID
(Default: 0)
integer?sfxID
(Default: 0)
number?posX
(Default: 0)
number?posY
(Default: 0)
number?posZ
(Default: 0)
number?dirX
(Default: 0)
number?dirY
(Default: 0)
number?dirZ
(Default: 0)
number?radius
(Default: 0)
number?damage
(Default: 0)
boolean?absolute
Returns
boolean?success

Spring.SetNoPause (function) view source 

Spring.SetNoPause(boolean) -> nil
Parameters
booleannoPause
Returns
nil

Spring.SetExperienceGrade (function) view source

Defines how often Callins.UnitExperience will be called.
Spring.SetExperienceGrade(number, number?, number?, number?) -> nil
Parameters
numberexpGrade
number?ExpPowerScale
number?ExpHealthScale
number?ExpReloadScale
Returns
nil

Spring.SetRadarErrorParams (function) view source 

Spring.SetRadarErrorParams(AllyTeamID, number, number?, number?) -> nil
Parameters
AllyTeamIDallyTeamID
numberallyteamErrorSize
number?baseErrorSize
number?baseErrorMult
Returns
nil

Spring.EditUnitCmdDesc (function) view source 

Spring.EditUnitCmdDesc(UnitID, integer, CommandDescription) -> nil
Parameters
UnitIDunitID
integercmdDescID
CommandDescriptioncmdArray

Spring.InsertUnitCmdDesc (function) view source

Insert a command description at a specific index.
Spring.InsertUnitCmdDesc(UnitID, integer, CommandDescription) -> nil
Parameters
UnitIDunitID
integerindex
CommandDescriptioncmdDesc

Spring.InsertUnitCmdDesc (function overload 1) view source

Insert a command description at the last position.
Spring.InsertUnitCmdDesc(UnitID, CommandDescription) -> nil
Parameters
UnitIDunitID
CommandDescriptioncmdDesc

Spring.RemoveUnitCmdDesc (function) view source 

Spring.RemoveUnitCmdDesc(UnitID, integer?) -> nil
Parameters
UnitIDunitID
integer?cmdDescID

Spring.SetShockFrontFactors (function) view source 

Spring.SetShockFrontFactors(number?, number?, number?) -> nil
Parameters
number?minArea
number?minPower
number?distAdj

Spring.RequestPath (function) view source 

Spring.RequestPath((string|integer), number, number, number, number, number, number, number?) -> userdata?
Parameters
(string|integer)moveID
numberstartX
numberstartY
numberstartZ
numberendX
numberendY
numberendZ
number?radius
Returns
userdata?path

Spring.InitPathNodeCostsArray (function) view source 

Spring.InitPathNodeCostsArray(integer, integer, integer) -> boolean
Parameters
integeroverlayIndex
integersizeX
integersizeZ
Returns
booleansuccess

Spring.FreePathNodeCostsArray (function) view source 

Spring.FreePathNodeCostsArray(integer) -> boolean
Parameters
integeroverlayIndex
Returns
booleansuccess

Spring.SetPathNodeCosts (function) view source 

Spring.SetPathNodeCosts(integer) -> boolean
Parameters
integeroverlayIndex
Returns
booleansuccess

Spring.GetPathNodeCosts (function) view source 

Spring.GetPathNodeCosts(integer) -> (table|boolean)
Parameters
integeroverlayIndex
Returns
(table|boolean)costs

Spring.SetPathNodeCost (function) view source 

Spring.SetPathNodeCost(integer, integer, number) -> boolean
Parameters
integeroverlayIndex
integercostIndex
0-based index in the overlay
numbercost
Returns
booleansuccess

Spring.GetPathNodeCost (function) view source 

Spring.GetPathNodeCost(integer, integer) -> number
Parameters
integernodeX
Heightmap node X coordinate
integernodeZ
Heightmap node Z coordinate
Returns
numbercost

Spring.IsReplay (function) view source 

Spring.IsReplay() -> boolean
Returns
booleanisReplay

Spring.GetReplayLength (function) view source 

Spring.GetReplayLength() -> number?
Returns
number?timeInSeconds

Spring.GetGameName (function) view source 

Spring.GetGameName() -> string
Returns
stringname

Spring.GetReplayFilePath (function) view source

If a replay is currently being watched, returns its file path.
Spring.GetReplayFilePath() -> string
Returns
stringfilePath

Spring.GetReplayRecordingFilePath (function) view source

If a replay is being recorded, returns its projected file path. Note that replay contents are only written there at game exit. Note also that watching a replay also records a meta-replay if the DemoFromDemo springsetting is set.
Spring.GetReplayRecordingFilePath() -> string
Returns
stringfilePath

Spring.GetMenuName (function) view source 

Spring.GetMenuName() -> string
Returns
stringname
name .. version from Modinfo.lua. E.g. “Spring: 1944 test-5640-ac2d15b”.

Spring.GetProfilerTimeRecord (function) view source 

Spring.GetProfilerTimeRecord(string, boolean?) -> number, number, number, number, number, table<integer,number>?
Parameters
stringprofilerName
boolean?frameData
(Default: false)
Returns
numbertotal
in ms
numbercurrent
in ms
numbermax_dt
numbertime_pct
numberpeak_pct
table<integer,number>?frameData
Table where key is the frame index and value is duration.

Spring.GetProfilerRecordNames (function) view source 

Spring.GetProfilerRecordNames() -> string[]
Returns
string[]profilerNames

Spring.GetLuaMemUsage (function) view source 

Spring.GetLuaMemUsage() -> number, number, number, number, number, number, number, number
Returns
numberluaHandleAllocedMem
in kilobytes
numberluaHandleNumAllocs
divided by 1000
numberluaGlobalAllocedMem
in kilobytes
numberluaGlobalNumAllocs
divided by 1000
numberluaUnsyncedGlobalAllocedMem
in kilobytes
numberluaUnsyncedGlobalNumAllocs
divided by 1000
numberluaSyncedGlobalAllocedMem
in kilobytes
numberluaSyncedGlobalNumAllocs
divided by 1000

Spring.GetVidMemUsage (function) view source 

Spring.GetVidMemUsage() -> number, number
Returns
numberusedMem
in MB
numberavailableMem
in MB

Spring.GetTimer (function) view source

Get a timer with millisecond resolution
Spring.GetTimer() -> integer
Returns
integer

Spring.GetTimerMicros (function) view source

Get a timer with microsecond resolution
Spring.GetTimerMicros() -> integer
Returns
integer

Spring.GetFrameTimer (function) view source

Get a timer for the start of the frame

This should give better results for camera interpolations

Spring.GetFrameTimer(boolean?) -> integer
Parameters
boolean?lastFrameTime
(Default: false) whether to use last frame time instead of last frame start
Returns
integer

Spring.DiffTimers (function) view source 

Spring.DiffTimers(integer, integer, boolean?, boolean?) -> number
Parameters
integerendTimer
integerstartTimer
boolean?returnMs
(Default: false) whether to return timeAmount in milliseconds as opposed to seconds
boolean?fromMicroSecs
(Default: false) whether timers are in microseconds instead of milliseconds
Returns
numbertimeAmount

Spring.GetNumDisplays (function) view source 

Spring.GetNumDisplays() -> integer
Returns
integernumDisplays
as returned by SDL_GetNumVideoDisplays

Spring.GetViewGeometry (function) view source

Get main view geometry (map and game rendering)
Spring.GetViewGeometry() -> integer, integer, integer, integer
Returns
integerviewSizeX
in px
integerviewSizeY
in px
integerviewPosX
offset from leftmost screen left border in px
integerviewPosY
offset from bottommost screen bottom border in px

Spring.GetDualViewGeometry (function) view source

Get dual view geometry (minimap when enabled)
Spring.GetDualViewGeometry() -> integer, integer, integer, integer
Returns
integerdualViewSizeX
in px
integerdualViewSizeY
in px
integerdualViewPosX
offset from leftmost screen left border in px
integerdualViewPosY
offset from bottommost screen bottom border in px

Spring.GetWindowGeometry (function) view source

Get main window geometry
Spring.GetWindowGeometry() -> integer, integer, integer, integer, integer, integer, integer, integer
Returns
integerwinSizeX
in px
integerwinSizeY
in px
integerwinPosX
in px
integerwinPosY
in px
integerwindowBorderTop
in px
integerwindowBorderLeft
in px
integerwindowBorderBottom
in px
integerwindowBorderRight
in px

Spring.GetWindowDisplayMode (function) view source

Get main window display mode
Spring.GetWindowDisplayMode() -> integer, integer, integer, integer
Returns
integerwidth
in px
integerheight
in px
integerbits
per pixel
integerrefresh
rate in Hz

Spring.GetScreenGeometry (function) view source

Get screen geometry
Spring.GetScreenGeometry(integer?, boolean?) -> integer, integer, integer, integer, integer, integer, integer, integer, integer?, integer?, integer?, integer?
Parameters
integer?displayIndex
(Default: -1)
boolean?queryUsable
(Default: false)
Returns
integerscreenSizeX
in px
integerscreenSizeY
in px
integerscreenPosX
in px
integerscreenPosY
in px
integerwindowBorderTop
in px
integerwindowBorderLeft
in px
integerwindowBorderBottom
in px
integerwindowBorderRight
in px
integer?screenUsableSizeX
in px
integer?screenUsableSizeY
in px
integer?screenUsablePosX
in px
integer?screenUsablePosY
in px

Spring.GetMiniMapGeometry (function) view source

Get minimap geometry
Spring.GetMiniMapGeometry() -> integer, integer, integer, integer, boolean, boolean
Returns
integerminimapPosX
in px
integerminimapPosY
in px
integerminimapSizeX
in px
integerminimapSizeY
in px
booleanminimized
booleanmaximized

Spring.GetMiniMapRotation (function) view source

Get minimap rotation
Spring.GetMiniMapRotation() -> number
Returns
numberrotation
in radians

Spring.GetMiniMapDualScreen (function) view source 

Spring.GetMiniMapDualScreen() -> ("left"|"right"|false)
Returns
("left"|"right"|false)position
“left” or “right” when dual screen is enabled, otherwise false.

Spring.GetSelectionBox (function) view source

Get vertices from currently active selection box

Returns nil when selection box is inactive

See Spring.GetUnitsInScreenRectangle

Spring.GetSelectionBox() -> number?, number?, number?, number?
Returns
number?left
number?top
number?right
number?bottom

Spring.GetDrawSelectionInfo (function) view source 

Spring.GetDrawSelectionInfo() -> boolean
Returns
boolean

Spring.IsAboveMiniMap (function) view source 

Spring.IsAboveMiniMap(integer, integer) -> boolean
Parameters
integerx
integery
Returns
booleanisAbove

Spring.GetDrawFrame (function) view source 

Spring.GetDrawFrame() -> integer, integer
Returns
integerlow_16bit
integerhigh_16bit

Spring.GetFrameTimeOffset (function) view 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.

Spring.GetFrameTimeOffset() -> number?
Returns
number?offset
of the current draw frame from the last sim frame, expressed in fractions of a frame

Spring.GetGameSecondsInterpolated (function) view source

Gets game time for drawing purposes

Returns the game time, taking the interpolated draw frame into account.

Spring.GetGameSecondsInterpolated() -> number
Returns
numbertime
in seconds

Spring.GetLastUpdateSeconds (function) view source 

Spring.GetLastUpdateSeconds() -> number?
Returns
number?lastUpdateSeconds

Spring.GetVideoCapturingMode (function) view source 

Spring.GetVideoCapturingMode() -> boolean
Returns
booleanallowRecord

Spring.GetPrevFrameSyncChecksum (function) view source

Returns the engine’s sync checksum for the previous simframe, useful for testing. The returned string is NOT convertible to a number within Lua.

Returns a dummy value if Platform.hasSyncChecksums is false, or if no frames were processed yet.

Spring.GetPrevFrameSyncChecksum() -> string
Returns
stringchecksum

Spring.IsUnitAllied (function) view source 

Spring.IsUnitAllied(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?isAllied
nil with unitID cannot be parsed

Spring.IsUnitSelected (function) view source 

Spring.IsUnitSelected(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?isSelected
nil when unitID cannot be parsed

Spring.GetUnitLuaDraw (function) view source 

Spring.GetUnitLuaDraw(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?draw
nil when unitID cannot be parsed

Spring.GetUnitNoDraw (function) view source 

Spring.GetUnitNoDraw(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?noDraw
nil when unitID cannot be parsed

Spring.GetUnitEngineDrawMask (function) view source 

Spring.GetUnitEngineDrawMask(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?drawMask
nil when unitID cannot be parsed

Spring.GetUnitAlwaysUpdateMatrix (function) view source 

Spring.GetUnitAlwaysUpdateMatrix(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?alwaysUpdateMatrix
nil when unitID cannot be parsed

Spring.GetUnitDrawFlag (function) view source 

Spring.GetUnitDrawFlag(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?drawFlag
nil when unitID cannot be parsed

Spring.GetUnitNoMinimap (function) view source 

Spring.GetUnitNoMinimap(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?noMinimap
nil when unitID cannot be parsed

Spring.GetUnitNoGroup (function) view source

Check if a unit is not allowed to be added to a group by a player.
Spring.GetUnitNoGroup(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?noGroup
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.

Spring.GetUnitNoSelect (function) view source 

Spring.GetUnitNoSelect(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?noSelect
nil when unitID cannot be parsed.

Spring.UnitIconGetDraw (function) view source 

Spring.UnitIconGetDraw(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?drawIcon
true if icon is being drawn, nil when unitID is invalid, otherwise false.

Spring.GetUnitIconData (function) view source

Get unit icon data

See Spring.GetIconData

Spring.GetUnitIconData(UnitID, boolean?) -> IconData?
Parameters
UnitIDunitID
boolean?fullData
(Default: false) Whether additional information about the icon is returned, otherwise only name and atlasTexCoords are returned
Returns
IconData?
nil if unit is not found or unit currentIconIndex is invalid

Spring.GetUnitIcon (function) view source

Get unit icon name
Spring.GetUnitIcon(UnitID) -> string
Parameters
UnitIDunitID
Returns
stringiconName

Spring.GetIconData (function) view source

Get icon data

See Spring.GetUnitIconData

Spring.GetIconData(string, boolean?) -> IconData?
Parameters
stringiconName
boolean?fullData
(Default: false) Whether additional information about the icon is returned, otherwise only name and atlasTexCoords are returned
Returns
IconData?
nil if iconName lookup fails

Spring.GetAllIconDataArray (function) view source

Get icon data

See Spring.GetUnitIconData, Spring.GetIconData

Spring.GetAllIconDataArray(boolean?) -> IconData[]
Parameters
boolean?fullData
(Default: false) Whether additional information about each icon is returned, otherwise only name and atlasTexCoords are returned
Returns
IconData[]iconDataList

Spring.GetUnitSelectionVolumeData (function) view source 

Spring.GetUnitSelectionVolumeData(UnitID) -> number?, number, number, number, number, number, integer, integer, integer, boolean
Parameters
UnitIDunitID
Returns
number?scaleX
nil when unitID cannot be parsed
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integervolumeType
integeruseContHitTest
integergetPrimaryAxis
booleanignoreHits

Spring.GetFeatureLuaDraw (function) view source 

Spring.GetFeatureLuaDraw(FeatureID) -> boolean?
Parameters
FeatureIDfeatureID
Returns
boolean?luaDraw
nil when featureID cannot be parsed

Spring.GetFeatureNoDraw (function) view source 

Spring.GetFeatureNoDraw(FeatureID) -> boolean?
Parameters
FeatureIDfeatureID
Returns
boolean?noDraw
nil when featureID cannot be parsed

Spring.GetFeatureEngineDrawMask (function) view source 

Spring.GetFeatureEngineDrawMask(FeatureID) -> boolean?
Parameters
FeatureIDfeatureID
Returns
boolean?drawMask
nil when featureID cannot be parsed

Spring.GetFeatureAlwaysUpdateMatrix (function) view source 

Spring.GetFeatureAlwaysUpdateMatrix(FeatureID) -> boolean?
Parameters
FeatureIDfeatureID
Returns
boolean?alwaysUpdateMatrix
nil when featureID cannot be parsed

Spring.GetFeatureDrawFlag (function) view source 

Spring.GetFeatureDrawFlag(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?drawFlag
nil when featureID cannot be parsed

Spring.GetFeatureSelectionVolumeData (function) view source 

Spring.GetFeatureSelectionVolumeData(FeatureID) -> number?, number, number, number, number, number, integer, integer, integer, boolean
Parameters
FeatureIDfeatureID
Returns
number?scaleX
nil when featureID cannot be parsed
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
integervolumeType
integeruseContHitTest
integergetPrimaryAxis
booleanignoreHits

Spring.GetUnitTransformMatrix (function) view source 

Spring.GetUnitTransformMatrix(UnitID) -> nil
Parameters
UnitIDunitID
Returns
nil
when unitID cannot be parsed

Spring.GetUnitTransformMatrix (function overload 1) view source 

Spring.GetUnitTransformMatrix(UnitID) -> number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
UnitIDunitID
Returns
numberm11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.GetFeatureTransformMatrix (function) view source 

Spring.GetFeatureTransformMatrix(FeatureID) -> nil
Parameters
FeatureIDfeatureID
Returns
nil
when featureID cannot be parsed

Spring.GetFeatureTransformMatrix (function overload 1) view source 

Spring.GetFeatureTransformMatrix(FeatureID) -> number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
FeatureIDfeatureID
Returns
numberm11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.IsUnitInView (function) view source 

Spring.IsUnitInView(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?inView
nil when unitID cannot be parsed

Spring.IsUnitVisible (function) view source 

Spring.IsUnitVisible(UnitID, number?, boolean) -> boolean?
Parameters
UnitIDunitID
number?radius
unitRadius when not specified
booleancheckIcon
Returns
boolean?isVisible
nil when unitID cannot be parsed

Spring.IsUnitIcon (function) view source 

Spring.IsUnitIcon(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?isUnitIcon
nil when unitID cannot be parsed

Spring.IsAABBInView (function) view source 

Spring.IsAABBInView(number, number, number, number, number, number) -> boolean
Parameters
numberminX
numberminY
numberminZ
numbermaxX
numbermaxY
numbermaxZ
Returns
booleaninView

Spring.IsSphereInView (function) view source 

Spring.IsSphereInView(number, number, number, number?) -> boolean
Parameters
numberposX
numberposY
numberposZ
number?radius
(Default: 0)
Returns
booleaninView

Spring.GetUnitViewPosition (function) view source 

Spring.GetUnitViewPosition(UnitID, boolean?) -> number?, number, number
Parameters
UnitIDunitID
boolean?midPos
(Default: false)
Returns
number?x
nil when unitID cannot be parsed
numbery
numberz

Spring.GetVisibleUnits (function) view source 

Spring.GetVisibleUnits(TeamID?, number?, boolean?) -> UnitID[]?
Parameters
TeamID?teamID
(Default: -1)
number?radius
(Default: 30)
boolean?icons
(Default: true)
Returns
UnitID[]?unitIDs

Spring.GetVisibleFeatures (function) view source 

Spring.GetVisibleFeatures(TeamID?, number?, boolean?, boolean?) -> FeatureID[]?
Parameters
TeamID?teamID
(Default: -1)
number?radius
(Default: 30)
boolean?icons
(Default: true)
boolean?geos
(Default: true)
Returns
FeatureID[]?featureIDs

Spring.GetVisibleProjectiles (function) view source 

Spring.GetVisibleProjectiles(AllyTeamID?, boolean?, boolean?, boolean?) -> ProjectileID[]?
Parameters
AllyTeamID?allyTeamID
(Default: -1)
boolean?addSyncedProjectiles
(Default: true)
boolean?addWeaponProjectiles
(Default: true)
boolean?addPieceProjectiles
(Default: true)
Returns
ProjectileID[]?projectileIDs

Spring.GetRenderUnits (function) view source 

Spring.GetRenderUnits(DrawMask, true) -> UnitID[], DrawFlag[]
Parameters
DrawMaskdrawMask
(Default: 0) Filter objects by their draw flags.
truesendMask
Whether to send objects draw flags as second return
Returns
UnitID[]unitIDs
DrawFlag[]drawFlags

Spring.GetRenderUnits (function overload 1) view source 

Spring.GetRenderUnits(DrawMask, false?) -> UnitID[]
Parameters
DrawMaskdrawMask
(Default: 0) Filter objects by their draw flags.
false?sendMask
Whether to send objects draw flags as second return
Returns
UnitID[]unitIDs

Spring.GetRenderUnitsDrawFlagChanged (function) view source

Gets a list of IDs of units that have had their draw flags changed, and the corresponding flags.
Spring.GetRenderUnitsDrawFlagChanged(true) -> UnitID[], DrawFlag[]
Parameters
truesendMask
Whether to send objects draw flags as second return.
Returns
UnitID[]ids
DrawFlag[]unitDrawFlags

Spring.GetRenderUnitsDrawFlagChanged (function overload 1) view source

Gets a list of IDs of units that have had their draw flags changed, and the corresponding flags.
Spring.GetRenderUnitsDrawFlagChanged(false?) -> UnitID[]
Parameters
false?sendMask
Whether to send objects draw flags as second return.
Returns
UnitID[]ids

Spring.GetRenderFeatures (function) view source 

Spring.GetRenderFeatures(DrawMask, true) -> FeatureID[], DrawFlag[]
Parameters
DrawMaskdrawMask
(Default: 0) Filter objects by their draw flags.
truesendMask
Whether to send objects draw flags as second return
Returns
FeatureID[]featureIDs
DrawFlag[]drawFlags

Spring.GetRenderFeatures (function overload 1) view source 

Spring.GetRenderFeatures(DrawMask, false?) -> FeatureID[]
Parameters
DrawMaskdrawMask
(Default: 0) Filter objects by their draw flags.
false?sendMask
Whether to send objects draw flags as second return
Returns
FeatureID[]featureIDs

Spring.GetRenderFeaturesDrawFlagChanged (function) view source

Gets a list of IDs of features that have had their draw flags changed, and the corresponding flags.
Spring.GetRenderFeaturesDrawFlagChanged(true) -> FeatureID[], DrawFlag[]
Parameters
truesendMask
Whether to send objects draw flags as second return.
Returns
FeatureID[]ids
DrawFlag[]featureDrawFlags

Spring.GetRenderFeaturesDrawFlagChanged (function overload 1) view source

Gets a list of IDs of features that have had their draw flags changed, and the corresponding flags.
Spring.GetRenderFeaturesDrawFlagChanged(false?) -> FeatureID[]
Parameters
false?sendMask
Whether to send objects draw flags as second return.
Returns
FeatureID[]ids

Spring.ClearUnitsPreviousDrawFlag (function) view source 

Spring.ClearUnitsPreviousDrawFlag() -> nil

Spring.ClearFeaturesPreviousDrawFlag (function) view source 

Spring.ClearFeaturesPreviousDrawFlag() -> nil

Spring.GetUnitsInScreenRectangle (function) view source

Get units inside a rectangle area on the map
Spring.GetUnitsInScreenRectangle(number, number, number, number, integer?) -> UnitID[]?
Parameters
numberleft
numbertop
numberright
numberbottom
integer?allegiance
(Default: -1) teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4
Returns
UnitID[]?unitIDs

Spring.GetFeaturesInScreenRectangle (function) view source

Get features inside a rectangle area on the map
Spring.GetFeaturesInScreenRectangle(number, number, number, number) -> FeatureID[]?
Parameters
numberleft
numbertop
numberright
numberbottom
Returns
FeatureID[]?featureIDs

Spring.GetLocalPlayerID (function) view source 

Spring.GetLocalPlayerID() -> PlayerID
Returns
PlayerIDplayerID

Spring.GetMyPlayerID (function) view source

Alias of GetLocalPlayerID
Spring.GetMyPlayerID() -> PlayerID
Returns
PlayerIDplayerID

Spring.GetLocalTeamID (function) view source 

Spring.GetLocalTeamID() -> TeamID
Returns
TeamIDteamID

Spring.GetMyTeamID (function) view source

Alias of GetLocalTeamID
Spring.GetMyTeamID() -> TeamID
Returns
TeamIDteamID

Spring.GetLocalAllyTeamID (function) view source 

Spring.GetLocalAllyTeamID() -> AllyTeamID
Returns
AllyTeamIDallyTeamID

Spring.GetMyAllyTeamID (function) view source

Alias of GetLocalAllyTeamID
Spring.GetMyAllyTeamID() -> AllyTeamID
Returns
AllyTeamIDallyTeamID

Spring.GetSpectatingState (function) view source 

Spring.GetSpectatingState() -> boolean, boolean, boolean
Returns
booleanspectating
booleanspectatingFullView
booleanspectatingFullSelect

Spring.GetSelectedUnits (function) view source 

Spring.GetSelectedUnits() -> UnitID[]
Returns
UnitID[]unitIDs

Spring.GetSelectedUnitsSorted (function) view source

Get selected units aggregated by unitDefID
Spring.GetSelectedUnitsSorted() -> table<UnitDefID,UnitID[]>, integer
Returns
table<UnitDefID,UnitID[]>unitsIDs
integercountDefs
the number of unitDefIDs

Spring.GetSelectedUnitsCounts (function) view source

Get an aggregate count of selected units per unitDefID
Spring.GetSelectedUnitsCounts() -> table<UnitDefID,integer>, integer
Returns
table<UnitDefID,integer>unitsCounts
integercountDefs
the number of unitDefIDs

Spring.GetSelectedUnitsCount (function) view source

Returns the amount of selected units
Spring.GetSelectedUnitsCount() -> integer
Returns
integerselectedUnitsCount

Spring.GetBoxSelectionByEngine (function) view source

Get if selection box is handled by engine.

See Spring.GetSelectionBox, Spring.SetBoxSelectionByEngine

Spring.GetBoxSelectionByEngine() -> boolean
Returns
booleanisHandledByEngine
true if the engine will select units inside selection box on release, otherwise false.

Spring.IsGUIHidden (function) view source 

Spring.IsGUIHidden() -> boolean
Returns
boolean

Spring.HaveShadows (function) view source 

Spring.HaveShadows() -> boolean
Returns
booleanshadowsLoaded

Spring.HaveAdvShading (function) view source 

Spring.HaveAdvShading() -> boolean, boolean
Returns
booleanuseAdvShading
booleangroundUseAdvShading

Spring.GetWaterMode (function) view source

See rts/Rendering/Env/IWater.h

Spring.GetWaterMode() -> integer, string
Returns
integerwaterRendererID
stringwaterRendererName

Spring.GetMapDrawMode (function) view source 

Spring.GetMapDrawMode() -> ("normal"|"height"|"metal"|"pathTraversability"|"los")
Returns
("normal"|"height"|"metal"|"pathTraversability"|"los")

Spring.GetMapSquareTexture (function) view source 

Spring.GetMapSquareTexture(integer, integer, integer, string, integer?) -> boolean?
Parameters
integertexSquareX
integertexSquareY
integerlodMin
stringluaTexName
integer?lodMax
(Default: lodMin)
Returns
boolean?success

Spring.GetLosViewColors (function) view source 

Spring.GetLosViewColors() -> rgb, rgb, rgb, rgb, rgb
Returns
rgbalways
rgbLOS
rgbradar
rgbjam
rgbradar2

Spring.GetNanoProjectileParams (function) view source 

Spring.GetNanoProjectileParams() -> number, number, number, number, number, number
Returns
numberrotVal
in degrees
numberrotVel
in degrees
numberrotAcc
in degrees
numberrotValRng
in degrees
numberrotVelRng
in degrees
numberrotAccRng
in degrees

Spring.GetCameraNames (function) view source

Get available cameras.
Spring.GetCameraNames() -> table<string,integer>
Returns
table<string,integer>indexByName
Table where where keys are names and values are indices.

Spring.GetCameraState (function) view source 

Spring.GetCameraState(false) -> CameraName, any ...
Parameters
falseuseTable
Returns
CameraNamename
any ...depends
on the current controller mode.

Spring.GetCameraState (function overload 1) view source 

Spring.GetCameraState(true?) -> CameraState
Parameters
true?useTable
(Default: true) Return a table instead of multiple values.
Returns
CameraStatecameraState

Spring.GetCameraPosition (function) view source 

Spring.GetCameraPosition() -> number, number, number
Returns
numberposX
numberposY
numberposZ

Spring.GetCameraDirection (function) view source 

Spring.GetCameraDirection() -> number, number, number
Returns
numberdirX
numberdirY
numberdirZ

Spring.GetCameraRotation (function) view source

Get camera rotation in radians.
Spring.GetCameraRotation() -> number, number, number
Returns
numberrotX
Rotation around X axis in radians.
numberrotY
Rotation around Y axis in radians.
numberrotZ
Rotation around Z axis in radians.

Spring.GetCameraFOV (function) view source 

Spring.GetCameraFOV() -> number, number
Returns
numbervFOV
numberhFOV

Spring.GetCameraVectors (function) view source 

Spring.GetCameraVectors() -> CameraVectors
Returns
CameraVectors

Spring.WorldToScreenCoords (function) view source 

Spring.WorldToScreenCoords(number, number, number) -> number, number, number
Parameters
numberx
numbery
numberz
Returns
numberviewPortX
numberviewPortY
numberviewPortZ

Spring.TraceScreenRay (function) view source

Get information about a ray traced from screen to world position

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.

Spring.TraceScreenRay(integer, integer, boolean?, boolean?, boolean?, boolean?, number?) -> string?, (UnitID|FeatureID|string|xyz)?, (FeatureID|string)?, xyz?
Parameters
integerscreenX
position on x axis in mouse coordinates (origin on left border of view)
integerscreenY
position on y axis in mouse coordinates (origin on top border of view)
boolean?onlyCoords
(Default: false) return only description (1st return value) and coordinates (2nd return value)
boolean?useMinimap
(Default: false) if position arguments are contained by minimap, use the minimap corresponding world position
boolean?includeSky
(Default: false)
boolean?ignoreWater
(Default: false)
number?heightOffset
(Default: 0)
Returns
string?description
of traced position
(UnitID|FeatureID|string|xyz)?unitID
or feature, position triple when onlyCoords=true
(FeatureID|string)?featureID
or ground
xyz?coords

Spring.GetPixelDir (function) view source 

Spring.GetPixelDir(integer, integer) -> number, number, number
Parameters
integerx
integery
Returns
numberdirX
numberdirY
numberdirZ

Spring.GetTeamColor (function) view source 

Spring.GetTeamColor(TeamID) -> number?, number?, number?, number?
Parameters
TeamIDteamID
Returns
number?r
factor from 0 to 1
number?g
factor from 0 to 1
number?b
factor from 0 to 1
number?a
factor from 0 to 1

Spring.GetTeamOrigColor (function) view source 

Spring.GetTeamOrigColor(TeamID) -> number?, number?, number?, number?
Parameters
TeamIDteamID
Returns
number?r
factor from 0 to 1
number?g
factor from 0 to 1
number?b
factor from 0 to 1
number?a
factor from 0 to 1

Spring.GetCustomPaletteColor (function) view source 

Spring.GetCustomPaletteColor(integer) -> number?, number?, number?
Parameters
integerindex
0-based index into custom palette
Returns
number?r
factor from 0 to 1
number?g
factor from 0 to 1
number?b
factor from 0 to 1

Spring.GetUnitPaletteIndex (function) view source

Returns the custom palette index for a unit, or nil if using team color.
Spring.GetUnitPaletteIndex(UnitID) -> integer?
Parameters
UnitIDunitID
Returns
integer?customIndex
[0..MAX_CUSTOM_COLORS) if unit uses a custom color, nil if using team color

Spring.GetFeaturePaletteIndex (function) view source

Returns the custom palette index for a feature, or nil if using team color.
Spring.GetFeaturePaletteIndex(FeatureID) -> integer?
Parameters
FeatureIDfeatureID
Returns
integer?customIndex
[0..MAX_CUSTOM_COLORS) if feature uses a custom color, nil if using team color

Spring.GetDrawSeconds (function) view source 

Spring.GetDrawSeconds() -> integer
Returns
integertime
Time in seconds.

Spring.GetSoundDevices (function) view source 

Spring.GetSoundDevices() -> SoundDeviceSpec[]
Returns
SoundDeviceSpec[]devices
Sound devices.

Spring.GetSoundStreamTime (function) view source 

Spring.GetSoundStreamTime() -> number, number
Returns
numberplayTime
numbertime

Spring.GetSoundEffectParams (function) view source 

Spring.GetSoundEffectParams() -> table?
Returns
table?soundEffectParams
nil on headless/no-sound builds or when EFX is unsupported.

Spring.GetFPS (function) view source 

Spring.GetFPS() -> integer
Returns
integerfps

Spring.GetGameSpeed (function) view source 

Spring.GetGameSpeed() -> number, number, boolean
Returns
numberwantedSpeedFactor
numberspeedFactor
booleanpaused

Spring.GetGameState (function) view source 

Spring.GetGameState(number?) -> boolean, boolean, boolean, boolean
Parameters
number?maxLatency
(Default: 500) used for isSimLagging return parameter
Returns
booleandoneLoading
booleanisSavedGame
booleanisClientPaused
booleanisSimLagging

Spring.GetActiveCommand (function) view source 

Spring.GetActiveCommand() -> integer?, integer?, integer?, string?
Returns
integer?cmdIndex
integer?cmdID
integer?cmdType
string?cmdName

Spring.GetDefaultCommand (function) view source 

Spring.GetDefaultCommand() -> integer?, integer?, integer?, string?
Returns
integer?cmdIndex
integer?cmdID
integer?cmdType
string?cmdName

Spring.GetActiveCmdDescs (function) view source 

Spring.GetActiveCmdDescs() -> CommandDescription[]
Returns
CommandDescription[]cmdDescs

Spring.GetActiveCmdDesc (function) view source 

Spring.GetActiveCmdDesc(integer) -> CommandDescription?
Parameters
integercmdIndex
Returns
CommandDescription?

Spring.GetCmdDescIndex (function) view source 

Spring.GetCmdDescIndex(integer) -> integer?
Parameters
integercmdID
Returns
integer?cmdDescIndex

Spring.GetBuildFacing (function) view source 

Spring.GetBuildFacing() -> FacingInteger
Returns
FacingIntegerbuildFacing

Spring.GetBuildSpacing (function) view source 

Spring.GetBuildSpacing() -> integer
Returns
integerbuildSpacing

Spring.GetGatherMode (function) view source 

Spring.GetGatherMode() -> integer
Returns
integergatherMode

Spring.GetActivePage (function) view source 

Spring.GetActivePage() -> integer, integer
Returns
integeractivePage
integermaxPage

Spring.GetMouseState (function) view source 

Spring.GetMouseState() -> integer, integer, boolean, boolean, boolean, boolean, boolean
Returns
integerx
integery
booleanlmbPressed
left mouse button pressed
booleanmmbPressed
middle mouse button pressed
booleanrmbPressed
right mouse button pressed
booleanoffscreen
booleanmmbScroll

Spring.GetMouseCursor (function) view source 

Spring.GetMouseCursor() -> string, number
Returns
stringcursorName
numbercursorScale

Spring.GetMouseStartPosition (function) view source 

Spring.GetMouseStartPosition(integer) -> integer, integer, number, number, number, number, number, number
Parameters
integerbutton
Returns
integerx
integery
numbercamPosX
numbercamPosY
numbercamPosZ
numberdirX
numberdirY
numberdirZ

Spring.GetMouseButtonsPressed (function) view source

Get pressed status for specific buttons.
Spring.GetMouseButtonsPressed(integer, [integer, ]*) -> boolean ...
Parameters
integerbutton1
Index of the first button.
integer...
Indices for more buttons.
Returns
boolean ...Pressed
status for the buttons.

Spring.GetClipboard (function) view source 

Spring.GetClipboard() -> string
Returns
stringtext

Spring.IsUserWriting (function) view source 

Spring.IsUserWriting() -> boolean
Returns
boolean

Spring.GetLastMessagePositions (function) view source 

Spring.GetLastMessagePositions() -> xyz[]
Returns
xyz[]message
positions

Spring.GetConsoleBuffer (function) view source 

Spring.GetConsoleBuffer(integer) -> { priority: integer, text: string }[]
Parameters
integermaxLines
Returns
{ priority: integer, text: string }[]buffer

Spring.GetCurrentTooltip (function) view source 

Spring.GetCurrentTooltip() -> string
Returns
stringtooltip

Spring.GetKeyFromScanSymbol (function) view source 

Spring.GetKeyFromScanSymbol(string?) -> string
Parameters
string?scanSymbol
Returns
stringkeyName

Spring.GetKeyState (function) view source 

Spring.GetKeyState(integer) -> boolean
Parameters
integerkeyCode
Returns
booleanpressed

Spring.GetModKeyState (function) view source 

Spring.GetModKeyState() -> boolean, boolean, boolean, boolean
Returns
booleanalt
booleanctrl
booleanmeta
booleanshift

Spring.GetPressedKeys (function) view source 

Spring.GetPressedKeys() -> table<(string|integer),true>
Returns
table<(string|integer),true>keys
where keys are keyCodes or key names

Spring.GetPressedScans (function) view source 

Spring.GetPressedScans() -> table<(string|integer),true>
Returns
table<(string|integer),true>scans
where keys are scanCodes or scan names

Spring.GetInvertQueueKey (function) view source 

Spring.GetInvertQueueKey() -> number?
Returns
number?queueKey

Spring.GetKeyCode (function) view source 

Spring.GetKeyCode(string) -> integer
Parameters
stringkeySym
Returns
integerkeyCode

Spring.GetKeySymbol (function) view source 

Spring.GetKeySymbol(integer) -> string, string
Parameters
integerkeyCode
Returns
stringkeyCodeName
stringkeyCodeDefaultName
name when there are not aliases

Spring.GetScanSymbol (function) view source 

Spring.GetScanSymbol(integer) -> string, string
Parameters
integerscanCode
Returns
stringscanCodeName
stringscanCodeDefaultName
name when there are not aliases

Spring.GetKeyBindings (function) view source 

Spring.GetKeyBindings(string?, string?) -> KeyBinding[]
Parameters
string?keySet1
filters keybindings bound to this keyset
string?keySet2
OR bound to this keyset
Returns
KeyBinding[]

Spring.GetActionHotKeys (function) view source 

Spring.GetActionHotKeys(string) -> string[]?
Parameters
stringactionName
Returns
string[]?hotkeys

Spring.GetGroupList (function) view source 

Spring.GetGroupList() -> table<GroupID,integer>?
Returns
table<GroupID,integer>?groupCounts

Spring.GetSelectedGroup (function) view source 

Spring.GetSelectedGroup() -> GroupID
Returns
GroupIDgroupID

Spring.GetUnitGroup (function) view source 

Spring.GetUnitGroup(UnitID) -> GroupID?
Parameters
UnitIDunitID
Returns
GroupID?groupID

Spring.GetGroupUnits (function) view source 

Spring.GetGroupUnits(GroupID) -> UnitID[]?
Parameters
GroupIDgroupID
Returns
UnitID[]?unitIDs

Spring.GetGroupUnitsSorted (function) view source 

Spring.GetGroupUnitsSorted(GroupID) -> table<UnitDefID,UnitID[]>?
Parameters
GroupIDgroupID
Returns
table<UnitDefID,UnitID[]>?unitsIDs

Spring.GetGroupUnitsCounts (function) view source 

Spring.GetGroupUnitsCounts(GroupID) -> table<UnitDefID,integer>?
Parameters
GroupIDgroupID
Returns
table<UnitDefID,integer>?unitsCounts

Spring.GetGroupUnitsCount (function) view source 

Spring.GetGroupUnitsCount(GroupID) -> integer?
Parameters
GroupIDgroupID
Returns
integer?groupSize

Spring.GetPlayerRoster (function) view source 

Spring.GetPlayerRoster(integer?, boolean?) -> Roster[]?
Parameters
integer?sortType
return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5
boolean?showPathingPlayers
(Default: false)
Returns
Roster[]?playerTable

Spring.GetPlayerTraffic (function) view source 

Spring.GetPlayerTraffic(PlayerID, integer?) -> integer
Parameters
PlayerIDplayerID
integer?packetID
Returns
integertraffic

Spring.GetPlayerStatistics (function) view source 

Spring.GetPlayerStatistics(PlayerID) -> integer?, integer, integer, integer, integer
Parameters
PlayerIDplayerID
Returns
integer?mousePixels
nil when invalid playerID
integermouseClicks
integerkeyPresses
integernumCommands
integerunitCommands

Spring.GetConfigParams (function) view source 

Spring.GetConfigParams() -> Configuration[]
Returns
Configuration[]

Spring.GetConfigInt (function) view source 

Spring.GetConfigInt(string, integer) -> integer
Parameters
stringname
integerdefault
Default value if name is not found
Returns
integer

Spring.GetConfigFloat (function) view source 

Spring.GetConfigFloat(string, number) -> number
Parameters
stringname
numberdefault
Default value if name is not found
Returns
number

Spring.GetConfigString (function) view source 

Spring.GetConfigString(string, string) -> string
Parameters
stringname
stringdefault
Default value if name is not found
Returns
string

Spring.GetLogSections (function) view source 

Spring.GetLogSections() -> table<string,integer>
Returns
table<string,integer>sections
where keys are names and loglevel are values. E.g. { “KeyBindings” = LOG.INFO, “Font” = LOG.INFO, “Sound” = LOG.WARNING, … }

Spring.GetAllGroundDecals (function) view source 

Spring.GetAllGroundDecals() -> DecalID[]
Returns
DecalID[]decalIDs

Spring.GetGroundDecalMiddlePos (function) view source 

Spring.GetGroundDecalMiddlePos(DecalID) -> number?, number
Parameters
DecalIDdecalID
Returns
number?posX
numberposZ

Spring.GetGroundDecalQuadPos (function) view source 

Spring.GetGroundDecalQuadPos(DecalID) -> number?, number, number, number, number, number, number, number
Parameters
DecalIDdecalID
Returns
number?posTL.x
numberposTL.z
numberposTR.x
numberposTR.z
numberposBR.x
numberposBR.z
numberposBL.x
numberposBL.z

Spring.GetGroundDecalSizeAndHeight (function) view source 

Spring.GetGroundDecalSizeAndHeight(DecalID) -> number?, number, number
Parameters
DecalIDdecalID
Returns
number?sizeX
numbersizeY
numberprojCubeHeight

Spring.GetGroundDecalRotation (function) view source 

Spring.GetGroundDecalRotation(DecalID) -> number?
Parameters
DecalIDdecalID
Returns
number?rotation
Rotation in radians.

Spring.GetGroundDecalTexture (function) view source 

Spring.GetGroundDecalTexture(DecalID, boolean?) -> string?
Parameters
DecalIDdecalID
boolean?isMainTex
(Default: true) If false, return the normal/glow map.
Returns
string?texture

Spring.GetGroundDecalTextures (function) view source

See Spring.GetGroundDecalTexture

Spring.GetGroundDecalTextures(boolean?, boolean?) -> string[]
Parameters
boolean?isMainTex
(Default: nil). If nil - no filtering is done, if false - return normal/glow textures, if true - return main color textures.
boolean?addFilenames
(Default: false). If true add the texture filenames in the second table
Returns
string[]textureNames
All textures on the atlas and available for use in SetGroundDecalTexture.

Spring.GetGroundDecalTextureParams (function) view source 

Spring.GetGroundDecalTextureParams(DecalID) -> number?, number
Parameters
DecalIDdecalID
Returns
number?texWrapDistance
If non-zero, sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos.
numbertexTraveledDistance
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.

Spring.GetGroundDecalAlpha (function) view source 

Spring.GetGroundDecalAlpha(DecalID) -> number?, number
Parameters
DecalIDdecalID
Returns
number?alpha
Between 0 and 1
numberalphaFalloff
Between 0 and 1, per second

Spring.GetGroundDecalNormal (function) view source

If all three equal 0, the decal follows the normals of ground at midpoint
Spring.GetGroundDecalNormal(DecalID) -> number?, number, number
Parameters
DecalIDdecalID
Returns
number?normal.x
numbernormal.y
numbernormal.z

Spring.GetGroundDecalTint (function) view source

Gets the tint of the ground decal. A color of (0.5, 0.5, 0.5, 0.5) is effectively no tint
Spring.GetGroundDecalTint(DecalID) -> number?, number, number, number
Parameters
DecalIDdecalID
Returns
number?tintR
numbertintG
numbertintB
numbertintA

Spring.GetGroundDecalMisc (function) view source

Returns less important parameters of a ground decal
Spring.GetGroundDecalMisc(DecalID) -> number?, number, number, number, number
Parameters
DecalIDdecalID
Returns
number?dotElimExp
numberrefHeight
numberminHeight
numbermaxHeight
numberforceHeightMode

Spring.GetGroundDecalCreationFrame (function) view source

Min can be not equal to max for “gradient” style decals, e.g. unit tracks
Spring.GetGroundDecalCreationFrame(DecalID) -> number?, number
Parameters
DecalIDdecalID
Returns
number?creationFrameMin
numbercreationFrameMax

Spring.GetGroundDecalOwner (function) view source 

Spring.GetGroundDecalOwner(DecalID) -> integer?
Parameters
DecalIDdecalID
Returns
integer?value
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.

Spring.GetGroundDecalGlowParams (function) view source

Gets the glow parameters of the ground decal.
Spring.GetGroundDecalGlowParams(DecalID) -> number?, number
Parameters
DecalIDdecalID
Returns
number?glow
Between 0 and 1
numberglowFalloff
Between 0 and 1, per second

Spring.GetGroundDecalUserData (function) view source

Gets the user defined decal data.
Spring.GetGroundDecalUserData(DecalID, integer) -> number?, number, number, number
Parameters
DecalIDdecalID
integerudQuad
vec4 index, must be within [0;1] for now
Returns
number?x
numbery
numberz
numberw

Spring.GetGroundDecalType (function) view source 

Spring.GetGroundDecalType(DecalID) -> ("explosion"|"plate"|"lua"|"track"|"unknown")?
Parameters
DecalIDdecalID
Returns
("explosion"|"plate"|"lua"|"track"|"unknown")?type

Spring.GetSyncedGCInfo (function) view source 

Spring.GetSyncedGCInfo(boolean?) -> integer?
Parameters
boolean?collectGC
(Default: false) collect before returning metric
Returns
integer?GC
values are expressed in Kbytes: #bytes/2^10

Spring.SolveNURBSCurve (function) view source 

Spring.SolveNURBSCurve(integer, number[], number[], integer) -> number[]
Parameters
integerdegree
Degree of the curve.
number[]controlPoints
Flat array of x, y, z, weight quadruples; its length must be a multiple of 4.
number[]knots
Knot vector.
integersegments
Number of segments to evaluate.
Returns
number[]points
Flat array of x, y, z triples along the curve.

Spring.IsCheatingEnabled (function) view source 

Spring.IsCheatingEnabled() -> boolean
Returns
booleanenabled

Spring.IsGodModeEnabled (function) view source 

Spring.IsGodModeEnabled() -> boolean
Returns
booleanenabled

Spring.IsDevLuaEnabled (function) view source 

Spring.IsDevLuaEnabled() -> boolean
Returns
booleanenabled

Spring.IsEditDefsEnabled (function) view source 

Spring.IsEditDefsEnabled() -> boolean
Returns
booleanenabled

Spring.IsNoCostEnabled (function) view source 

Spring.IsNoCostEnabled() -> boolean
Returns
booleanenabled

Spring.GetGlobalLos (function) view source 

Spring.GetGlobalLos(TeamID?) -> boolean
Parameters
TeamID?teamID
Returns
booleanenabled

Spring.AreHelperAIsEnabled (function) view source 

Spring.AreHelperAIsEnabled() -> boolean
Returns
booleanenabled

Spring.FixedAllies (function) view source 

Spring.FixedAllies() -> boolean?
Returns
boolean?enabled

Spring.IsGameOver (function) view source 

Spring.IsGameOver() -> boolean
Returns
booleanisGameOver

Spring.GetGameFrame (function) view source 

Spring.GetGameFrame() -> integer, integer
Returns
integert1
frameNum % dayFrames
integert2
frameNum / dayFrames

Spring.GetGameSeconds (function) view source 

Spring.GetGameSeconds() -> number
Returns
numberseconds

Spring.GetTidal (function) view source 

Spring.GetTidal() -> number
Returns
numbertidalStrength

Spring.GetWind (function) view source 

Spring.GetWind() -> number, number, number, number, number, number, number
Returns
numberwindSpeedX
numberwindSpeedY
(Always 0)
numberwindSpeedZ
numberwindStrength
(Length of windSpeed)
numberwindDirX
(Normalized windSpeed)
numberwindDirY
(Always 0)
numberwindDirZ

Spring.GetGameRulesParams (function) view source 

Spring.GetGameRulesParams() -> RulesParams
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetTeamRulesParams (function) view source 

Spring.GetTeamRulesParams(TeamID) -> RulesParams
Parameters
TeamIDteamID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetPlayerRulesParams (function) view source 

Spring.GetPlayerRulesParams(PlayerID) -> RulesParams
Parameters
PlayerIDplayerID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetUnitRulesParams (function) view source 

Spring.GetUnitRulesParams(UnitID) -> RulesParams
Parameters
UnitIDunitID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetFeatureRulesParams (function) view source 

Spring.GetFeatureRulesParams(FeatureID) -> RulesParams
Parameters
FeatureIDfeatureID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetGameRulesParam (function) view source 

Spring.GetGameRulesParam(string) -> (boolean|string|number)?
Parameters
stringname
rules-parameter key (only this argument is read)
Returns
(boolean|string|number)?value

Spring.GetTeamRulesParam (function) view source 

Spring.GetTeamRulesParam(TeamID, (string|number)) -> (string|number)?
Parameters
TeamIDteamID
(string|number)ruleRef
the rule index or name
Returns
(string|number)?value

Spring.GetPlayerRulesParam (function) view source 

Spring.GetPlayerRulesParam(PlayerID, (string|number)) -> (string|number)?
Parameters
PlayerIDplayerID
(string|number)ruleRef
the rule index or name
Returns
(string|number)?value

Spring.GetUnitRulesParam (function) view source 

Spring.GetUnitRulesParam(UnitID, (string|number)) -> (string|number)?
Parameters
UnitIDunitID
(string|number)ruleRef
the rule index or name
Returns
(string|number)?value

Spring.GetFeatureRulesParam (function) view source 

Spring.GetFeatureRulesParam(FeatureID, (string|number)) -> (string|number)?
Parameters
FeatureIDfeatureID
(string|number)ruleRef
the rule index or name
Returns
(string|number)?value

Spring.GetMapOption (function) view source 

Spring.GetMapOption(string) -> string
Parameters
stringmapOption
Returns
stringvalue
Value of modOption.

Spring.GetMapOptions (function) view source 

Spring.GetMapOptions() -> table<string,string>
Returns
table<string,string>mapOptions
Table with options names as keys and values as values.

Spring.GetModOption (function) view source 

Spring.GetModOption(string) -> string
Parameters
stringmodOption
Returns
stringvalue
Value of modOption.

Spring.GetModOptions (function) view source 

Spring.GetModOptions() -> table<string,string>
Returns
table<string,string>modOptions
Table with options names as keys and values as values.

Spring.GetHeadingFromVector (function) view source 

Spring.GetHeadingFromVector(number, number) -> integer
Parameters
numberx
numberz
Returns
integerheading

Spring.GetVectorFromHeading (function) view source 

Spring.GetVectorFromHeading(integer) -> number, number
Parameters
integerheading
Returns
numberx
numberz

Spring.GetFacingFromHeading (function) view source 

Spring.GetFacingFromHeading(integer) -> FacingInteger
Parameters
integerheading
Returns
FacingIntegerfacing

Spring.GetHeadingFromFacing (function) view source 

Spring.GetHeadingFromFacing(FacingInteger) -> integer
Parameters
FacingIntegerfacing
Returns
integerheading

Spring.GetSideData (function) view source 

Spring.GetSideData(string) -> string?, string?
Parameters
stringsideName
Case-insensitive side name.
Returns
string?startUnit
string?caseName
Original case side name.

Spring.GetSideData (function overload 1) view source 

Spring.GetSideData(integer) -> string?, string?, string?
Parameters
integersideID
Returns
string?sideName
Lowercase side name.
string?startUnit
string?caseName
Original case side name.

Spring.GetSideData (function overload 2) view source 

Spring.GetSideData() -> SideSpec[]
Returns
SideSpec[]sideArray

Spring.GetGaiaTeamID (function) view source 

Spring.GetGaiaTeamID() -> TeamID
Returns
TeamIDteamID

Spring.GetAllyTeamStartBox (function) view source 

Spring.GetAllyTeamStartBox(AllyTeamID) -> number?, number?, number?, number?
Parameters
AllyTeamIDallyID
Returns
number?xMin
number?zMin
number?xMax
number?zMax

Spring.GetTeamStartPosition (function) view source 

Spring.GetTeamStartPosition(TeamID) -> number?, number?, number?
Parameters
TeamIDteamID
Returns
number?x
number?y
number?x

Spring.GetMapStartPositions (function) view source 

Spring.GetMapStartPositions() -> float3[]
Returns
float3[]startPositions
array of positions indexed by teamID

Spring.GetAllyTeamList (function) view source 

Spring.GetAllyTeamList() -> AllyTeamID[]
Returns
AllyTeamID[]allyTeamIDs

Spring.GetTeamList (function) view source

Get all team IDs.
Spring.GetTeamList(-1?) -> TeamID[]
Parameters
-1?allyTeamID
(Default: -1)
Returns
TeamID[]teamIDs
List of team IDs.

Spring.GetTeamList (function overload 1) view source

Get team IDs in a specific ally team.
Spring.GetTeamList(AllyTeamID) -> TeamID[]?
Parameters
AllyTeamIDallyTeamID
The ally team ID to filter teams by. A value less than 0 will return all teams.
Returns
TeamID[]?teamIDs
List of team IDs or nil if allyTeamID is invalid.

Spring.GetPlayerList (function) view source 

Spring.GetPlayerList(TeamID?, boolean?) -> PlayerID[]?
Parameters
TeamID?teamID
(Default: -1) to filter by when >= 0
boolean?active
(Default: false) whether to filter only active teams
Returns
PlayerID[]?playerIDs
List of playerIDs.

Spring.GetTeamInfo (function) view source 

Spring.GetTeamInfo(TeamID, boolean?) -> TeamID?, PlayerID, number, number, string, AllyTeamID, number, table<string,string>
Parameters
TeamIDteamID
boolean?getTeamKeys
(Default: true) whether to return the customTeamKeys table
Returns
TeamID?teamID
PlayerIDleader
numberisDead
numberhasAI
stringside
AllyTeamIDallyTeam
numberincomeMultiplier
table<string,string>customTeamKeys
when getTeamKeys is true, otherwise nil

Spring.GetTeamAllyTeamID (function) view source 

Spring.GetTeamAllyTeamID(TeamID) -> AllyTeamID?
Parameters
TeamIDteamID
Returns
AllyTeamID?allyTeamID

Spring.GetTeamResources (function) view source 

Spring.GetTeamResources(TeamID, ResourceName) -> number?, number, number, number, number, number, number, number, number
Parameters
TeamIDteamID
ResourceNameresource
Returns
number?currentLevel
The current amount of the resource that the team has in storage at this moment
numberstorage
The maximum storage capacity for the resource.
numberpull
The total amount of the resource that is being requested/used by all units and buildings per second, regardless of whether the resource is actually available.
numberincome
The total amount of the resource being generated per second from all sources (e.g., mines, generators, reclaiming, etc.).
numberexpense
The total amount of the resource actually being spent per second. This is the real consumption, which may be less than pull if there isn’t enough resource available.
numbershare
The fraction (0.0 to 1.0) of the storage that the team is sharing with allied teams. A value of 0.0 means 100% of storage is shared, while 1.0 means only any excess is shared.
numbersent
The total amount of the resource that has actually been sent to allies (via sharing or manual transfer).
numberreceived
The total amount of the resource that has actually been received from allies (via sharing or manual transfer).
numberexcess
The amount of the resource that was lost due to storage overflow (wasted).

Spring.GetTeamUnitStats (function) view source 

Spring.GetTeamUnitStats(TeamID) -> integer?, integer, integer, integer, integer, integer
Parameters
TeamIDteamID
Returns
integer?killed
integerdied
integercapturedBy
integercapturedFrom
integerreceived
integersent

Spring.GetTeamResourceStats (function) view source 

Spring.GetTeamResourceStats(TeamID, ResourceName) -> number?, number, number, number, number
Parameters
TeamIDteamID
ResourceNameresource
Returns
number?used
numberproduced
numberexcessed
numberreceived
numbersent

Spring.GetTeamDamageStats (function) view source

Gets team damage dealt/received totals

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

Spring.GetTeamDamageStats(TeamID) -> number, number
Parameters
TeamIDteamID
Returns
numberdamageDealt
numberdamageReceived

Spring.GetTeamStatsHistory (function) view source

Get the number of history entries.
Spring.GetTeamStatsHistory(TeamID) -> integer?
Parameters
TeamIDteamID
Returns
integer?historyCount
The number of history entries, or nil if unable to resolve team.

Spring.GetTeamStatsHistory (function overload 1) view source

Get team stats history.
Spring.GetTeamStatsHistory(TeamID, integer, integer?) -> TeamStats[]
Parameters
TeamIDteamID
integerstartIndex
integer?endIndex
(Default: startIndex)
Returns
TeamStats[]teamStatsHistory
The team stats history, or nil if unable to resolve team.

Spring.GetTeamLuaAI (function) view source 

Spring.GetTeamLuaAI(TeamID) -> string
Parameters
TeamIDteamID
Returns
string

Spring.GetTeamMaxUnits (function) view source

Returns a team’s unit cap.

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

Spring.GetTeamMaxUnits(TeamID) -> integer, integer?
Parameters
TeamIDteamID
Returns
integermaxUnits
integer?currentUnits

Spring.GetPlayerInfo (function) view source 

Spring.GetPlayerInfo(PlayerID, boolean?) -> string, boolean, boolean, TeamID, AllyTeamID, number, number, string, integer, boolean, { [string]: string }, boolean
Parameters
PlayerIDplayerID
boolean?getPlayerOpts
(Default: true) whether to return custom player options
Returns
stringname
booleanactive
booleanspectator
TeamIDteamID
AllyTeamIDallyTeamID
numberpingTime
numbercpuUsage
stringcountry
integerrank
booleanhasSkirmishAIsInTeam
{ [string]: string }playerOpts
when playerOpts is true
booleandesynced

Spring.GetPlayerControlledUnit (function) view source

Returns unit controlled by player on FPS mode
Spring.GetPlayerControlledUnit(PlayerID) -> UnitID?
Parameters
PlayerIDplayerID
Returns
UnitID?

Spring.GetAIInfo (function) view source 

Spring.GetAIInfo(TeamID) -> integer, string, PlayerID, string, string, table<string,string>
Parameters
TeamIDteamID
Returns
integerskirmishAIID
stringname
PlayerIDhostingPlayerID
stringshortName
When synced “SYNCED_NOSHORTNAME”, otherwise the AI shortname or “UNKNOWN”.
stringversion
When synced “SYNCED_NOVERSION”, otherwise the AI version or “UNKNOWN”.
table<string,string>options

Spring.GetAllyTeamInfo (function) view source 

Spring.GetAllyTeamInfo(AllyTeamID) -> table<string,string>?
Parameters
AllyTeamIDallyTeamID
Returns
table<string,string>?

Spring.AreTeamsAllied (function) view source 

Spring.AreTeamsAllied(TeamID, TeamID) -> boolean?
Parameters
TeamIDteamID1
TeamIDteamID2
Returns
boolean?

Spring.ArePlayersAllied (function) view source 

Spring.ArePlayersAllied(PlayerID, PlayerID) -> boolean?
Parameters
PlayerIDplayerID1
PlayerIDplayerID2
Returns
boolean?

Spring.GetAllUnits (function) view source

Get a list of all unitIDs

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 UnsyncedRead.GetVisibleUnits

Spring.GetAllUnits() -> UnitID[]
Returns
UnitID[]unitIDs

Spring.GetTeamUnits (function) view source 

Spring.GetTeamUnits(TeamID) -> UnitID[]?
Parameters
TeamIDteamID
Returns
UnitID[]?unitIDs

Spring.GetTeamUnitsSorted (function) view source 

Spring.GetTeamUnitsSorted(TeamID) -> table<UnitDefID,UnitID[]>
Parameters
TeamIDteamID
Returns
table<UnitDefID,UnitID[]>unitsByDef
A table where keys are unitDefIDs and values are arrays of unitIDs

Spring.GetTeamUnitsCounts (function) view source 

Spring.GetTeamUnitsCounts(TeamID) -> table<UnitDefID,integer>?
Parameters
TeamIDteamID
Returns
table<UnitDefID,integer>?countByUnit
A table where keys are unitDefIDs and values are counts.

Spring.GetTeamUnitsByDefs (function) view source 

Spring.GetTeamUnitsByDefs(TeamID, (UnitDefID|UnitDefID[])) -> UnitID[]?
Parameters
TeamIDteamID
(UnitDefID|UnitDefID[])unitDefIDs
Returns
UnitID[]?unitIDs

Spring.GetTeamUnitDefCount (function) view source 

Spring.GetTeamUnitDefCount(TeamID, UnitDefID) -> integer?
Parameters
TeamIDteamID
UnitDefIDunitDefID
Returns
integer?count

Spring.GetTeamUnitCount (function) view source 

Spring.GetTeamUnitCount(TeamID) -> integer?
Parameters
TeamIDteamID
Returns
integer?count

Spring.GetUnitsInRectangle (function) view source 

Spring.GetUnitsInRectangle(number, number, number, number, integer?) -> UnitID[]
Parameters
numberxmin
numberzmin
numberxmax
numberzmax
integer?allegiance
Returns
UnitID[]unitIDs

Spring.GetUnitsInBox (function) view source 

Spring.GetUnitsInBox(number, number, number, number, number, number, integer?) -> UnitID[]
Parameters
numberxmin
numberymin
numberzmin
numberxmax
numberymax
numberzmax
integer?allegiance
Returns
UnitID[]unitIDs

Spring.GetUnitsInCylinder (function) view source 

Spring.GetUnitsInCylinder(number, number, number, TeamID?) -> UnitID[]
Parameters
numberx
numberz
numberradius
TeamID?teamID
filter by team, defaults to all units
Returns
UnitID[]unitIDs

Spring.GetUnitsInSphere (function) view source 

Spring.GetUnitsInSphere(number, number, number, number) -> UnitID[]
Parameters
numberx
numbery
numberz
numberradius
Returns
UnitID[]unitIDs

Spring.GetUnitsInPlanes (function) view 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 

Spring.GetUnitsInPlanes(Plane[], integer?) -> UnitID[]
Parameters
Plane[]planes
integer?allegiance
Returns
UnitID[]unitIDs

Spring.GetUnitArrayCentroid (function) view source

Returns the centroid of an array of units

Returns nil for an empty array

Spring.GetUnitArrayCentroid(table) -> number, number, number
Parameters
tableunits
{ unitID, unitID, … }
Returns
numbercenterX
numbercenterY
numbercenterZ

Spring.GetUnitMapCentroid (function) view source

Returns the centroid of a map of units

Returns nil for an empty map

Spring.GetUnitMapCentroid(table) -> number, number, number
Parameters
tableunits
{ [unitID] = true, [unitID] = true, … }
Returns
numbercenterX
numbercenterY
numbercenterZ

Spring.GetUnitNearestAlly (function) view source 

Spring.GetUnitNearestAlly(UnitID, number?) -> UnitID?
Parameters
UnitIDunitID
number?range
(Default: 1.0e9)
Returns
UnitID?unitID

Spring.GetUnitNearestEnemy (function) view source 

Spring.GetUnitNearestEnemy(UnitID, number?, boolean?, boolean?, boolean?) -> UnitID?
Parameters
UnitIDunitID
number?range
(Default: 1.0e9) range of the search.
boolean?useLOS
(Default: true) requires LOS/radar visibility of allied team.
boolean?sphereDistTest
(Default: false) determines if using spherical(3D, includes target radius) or cylindrical(2D) search.
boolean?checkSightDist
(Default: false) determine if during filter process, if candidate distance to be within candidate LOS radius.
Returns
UnitID?unitID

Spring.GetClosestEnemyUnit (function) view source

Returns the enemy unit closest to a position.
Spring.GetClosestEnemyUnit(number, number, number, number?, AllyTeamID?, boolean?, boolean?, boolean?) -> UnitID?
Parameters
numberx
x coordinate of query position
numbery
y coordinate of query position
numberz
z coordinate of query position
number?range
(Default: 1.0e9)
AllyTeamID?allyTeamID
whose enemies to consider, always own in non-full-read contexts
boolean?useLOS
(Default: true) requires LOS/radar visibility or not. Always true in non-full-read contexts
boolean?sphereDistTest
(Default: false) For non-LOS mode only. Determines if using spherical(3D, includes target radius) or cylindrical(2D) search
boolean?checkSightDist
(Default: false) For non-LOS mode only. Determine if during filter process, if candidate distance to be within candidate LOS radius
Returns
UnitID?unitID

Spring.GetFeaturesInRectangle (function) view source 

Spring.GetFeaturesInRectangle(number, number, number, number) -> FeatureID[]
Parameters
numberxmin
numberzmin
numberxmax
numberzmax
Returns
FeatureID[]featureIDs

Spring.GetFeaturesInSphere (function) view source 

Spring.GetFeaturesInSphere(number, number, number, number) -> FeatureID[]
Parameters
numberx
numbery
numberz
numberradius
Returns
FeatureID[]featureIDs

Spring.GetFeaturesInCylinder (function) view source 

Spring.GetFeaturesInCylinder(number, number, number, integer?) -> FeatureID[]
Parameters
numberx
numberz
numberradius
integer?allegiance
Returns
FeatureID[]featureIDs

Spring.GetAllProjectiles (function) view source 

Spring.GetAllProjectiles(boolean?, boolean?) -> ProjectileID[]
Parameters
boolean?excludeWeaponProjectiles
(Default: false)
boolean?excludePieceProjectiles
(Default: false)
Returns
ProjectileID[]projectileIDs

Spring.GetProjectilesInRectangle (function) view source 

Spring.GetProjectilesInRectangle(number, number, number, number, boolean?, boolean?) -> ProjectileID[]
Parameters
numberxmin
numberzmin
numberxmax
numberzmax
boolean?excludeWeaponProjectiles
(Default: false)
boolean?excludePieceProjectiles
(Default: false)
Returns
ProjectileID[]projectileIDs

Spring.GetProjectilesInSphere (function) view source 

Spring.GetProjectilesInSphere(number, number, number, number, boolean?, boolean?) -> ProjectileID[]
Parameters
numberx
numbery
numberz
numberradius
boolean?excludeWeaponProjectiles
(Default: false)
boolean?excludePieceProjectiles
(Default: false)
Returns
ProjectileID[]projectileIDs

Spring.ValidUnitID (function) view source

Get whether a unitID is valid

Dead units are not valid.

Spring.ValidUnitID(UnitID) -> boolean
Parameters
UnitIDunitID
Returns
boolean

Spring.GetUnitStates (function) view source

Gets various states for the given unit.
Spring.GetUnitStates(UnitID, false, true, true) -> number, number, number, boolean, boolean, boolean, boolean, boolean?, boolean?
Parameters
UnitIDunitID
falseretTable
Return a table instead of multiple values. Defaults to true
truebinState
Include binary state (activated, etc)? Defaults to retTable
trueamtState
Include Air/Hover MoveType state if available? Defaults to retTable
Returns
numberfireState
numbermoveState
numberautorepairlevel
-1 if not set
booleanrepeat
booleancloak
booleanactive
booleantrajectory
boolean?autoLand
boolean?loopbackAttack

Spring.GetUnitArmored (function) view source 

Spring.GetUnitArmored(UnitID) -> boolean?, number
Parameters
UnitIDunitID
Returns
boolean?armored
numberarmorMultiple

Spring.GetUnitIsActive (function) view source 

Spring.GetUnitIsActive(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?isActive

Spring.GetUnitIsCloaked (function) view source 

Spring.GetUnitIsCloaked(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?isCloaked

Spring.GetUnitSeismicSignature (function) view source 

Spring.GetUnitSeismicSignature(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?seismicSignature

Spring.GetUnitLeavesGhost (function) view source

Get whether unit leaves static radar ghosts.
Spring.GetUnitLeavesGhost() -> number?
Returns
number?

Spring.GetUnitSelfDTime (function) view source 

Spring.GetUnitSelfDTime(UnitID) -> integer?
Parameters
UnitIDunitID
Returns
integer?selfDTime

Spring.GetUnitStockpile (function) view source 

Spring.GetUnitStockpile(UnitID) -> integer?, integer?, number?
Parameters
UnitIDunitID
Returns
integer?numStockpiled
integer?numStockpileQued
number?buildPercent

Spring.GetUnitSensorRadius (function) view source 

Spring.GetUnitSensorRadius(UnitID, string) -> integer?
Parameters
UnitIDunitID
stringtype
one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
Returns
integer?radius

Spring.GetUnitPosErrorParams (function) view source 

Spring.GetUnitPosErrorParams(UnitID, AllyTeamID?) -> number?, number, number, number, number, number, integer, boolean
Parameters
UnitIDunitID
AllyTeamID?allyTeamID
Returns
number?posErrorVectorX
numberposErrorVectorY
numberposErrorVectorZ
numberposErrorDeltaX
numberposErrorDeltaY
numberposErrorDeltaZ
integernextPosErrorUpdate
booleanposErrorBit

Spring.GetUnitTooltip (function) view source 

Spring.GetUnitTooltip(UnitID) -> string?
Parameters
UnitIDunitID
Returns
string?

Spring.GetUnitDefID (function) view source 

Spring.GetUnitDefID(UnitID) -> UnitDefID?
Parameters
UnitIDunitID
Returns
UnitDefID?

Spring.GetUnitMoveDefID (function) view source

Returns a numerical movedef ID and its name. For things that have no movedef, returns false (to tell them apart from unreadable units while keeping the if not x pattern usable). For now, the numerical ID is not too useful so you can use the name, but this may get deprecated at some point.
Spring.GetUnitMoveDefID(UnitID) -> (integer|false)?, string?
Parameters
UnitIDunitID
Returns
(integer|false)?moveDefID
string?moveDefName

Spring.GetUnitTeam (function) view source 

Spring.GetUnitTeam(UnitID) -> TeamID?
Parameters
UnitIDunitID
Returns
TeamID?

Spring.GetUnitAllyTeam (function) view source 

Spring.GetUnitAllyTeam(UnitID) -> AllyTeamID?
Parameters
UnitIDunitID
Returns
AllyTeamID?

Spring.GetUnitNeutral (function) view source

Checks if a unit is neutral (NOT Gaia!)

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.

Spring.GetUnitNeutral(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?

Spring.GetUnitHealth (function) view source 

Spring.GetUnitHealth(UnitID) -> number?, number, number, number, number
Parameters
UnitIDunitID
Returns
number?health
numbermaxHealth
numberparalyzeDamage
numbercaptureProgress
numberbuildProgress
between 0.0-1.0

Spring.GetUnitIsDead (function) view source 

Spring.GetUnitIsDead(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?

Spring.GetUnitIsStunned (function) view source

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.

Spring.GetUnitIsStunned(UnitID) -> boolean?, boolean, boolean
Parameters
UnitIDunitID
Returns
boolean?stunnedOrBuilt
unit is disabled
booleanstunned
unit is either stunned via EMP or being transported by a non-fireplatform
booleanbeingBuilt
unit is under construction

Spring.GetUnitIsBeingBuilt (function) view source 

Spring.GetUnitIsBeingBuilt(UnitID) -> boolean, number
Parameters
UnitIDunitID
Returns
booleanbeingBuilt
numberbuildProgress

Spring.GetUnitResources (function) view source 

Spring.GetUnitResources(UnitID) -> number?, number, number, number
Parameters
UnitIDunitID
Returns
number?metalMake
numbermetalUse
numberenergyMake
numberenergyUse

Spring.GetUnitStorage (function) view source 

Spring.GetUnitStorage(UnitID) -> number, number
Parameters
UnitIDunitID
Returns
numbermetalStorage
Unit’s metal storage
numberenergyStorage
Unit’s energy storage

Spring.GetUnitCosts (function) view source 

Spring.GetUnitCosts(UnitID) -> number?, number, number
Parameters
UnitIDunitID
Returns
number?buildTime
numbermetalCost
numberenergyCost

Spring.GetUnitCostTable (function) view source 

Spring.GetUnitCostTable(UnitID) -> ResourceCost?, number?
Parameters
UnitIDunitID
Returns
ResourceCost?cost
The cost of the unit, or nil if invalid.
number?buildTime
The build time the unit, or nil if invalid.

Spring.GetUnitMetalExtraction (function) view source 

Spring.GetUnitMetalExtraction(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?metalExtraction

Spring.GetUnitExperience (function) view source 

Spring.GetUnitExperience(UnitID) -> number, number
Parameters
UnitIDunitID
Returns
numberxp
[0.0; +∞)
numberlimXp
[0.0; 1.0) as experience approaches infinity

Spring.GetUnitHeight (function) view source 

Spring.GetUnitHeight(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?

Spring.GetUnitRadius (function) view source 

Spring.GetUnitRadius(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?

Spring.GetUnitBuildeeRadius (function) view source

Gets the unit’s radius for when targeted by build, repair, reclaim-type commands.
Spring.GetUnitBuildeeRadius(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?

Spring.GetUnitMass (function) view source 

Spring.GetUnitMass(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?

Spring.GetUnitPosition (function) view source 

Spring.GetUnitPosition(UnitID, boolean?, boolean?) -> number?, number, number, number?, number, number, number?, number, number
Parameters
UnitIDunitID
boolean?midPos
(Default: false) return midpoint as well
boolean?aimPos
(Default: false) return aimpoint as well
Returns
number?basePointX
numberbasePointY
numberbasePointZ
number?midPointX
numbermidPointY
numbermidPointZ
number?aimPointX
numberaimPointY
numberaimPointZ

Spring.GetUnitBasePosition (function) view source

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

See Spring.GetUnitPosition

Spring.GetUnitBasePosition(UnitID) -> number?, number?, number?
Parameters
UnitIDunitID
Returns
number?posX
number?posY
number?posZ

Spring.GetUnitVectors (function) view source 

Spring.GetUnitVectors(UnitID) -> float3?, float3, float3
Parameters
UnitIDunitID
Returns
float3?front
float3up
float3right

Spring.GetUnitRotation (function) view source

Note: PYR order
Spring.GetUnitRotation(UnitID) -> number, number, number
Parameters
UnitIDunitID
Returns
numberpitch
Rotation in X axis
numberyaw
Rotation in Y axis
numberroll
Rotation in Z axis

Spring.GetUnitDirection (function) view source 

Spring.GetUnitDirection(UnitID) -> number, number, number, number, number, number, number, number, number
Parameters
UnitIDunitID
Returns
numberfrontDirX
numberfrontDirY
numberfrontDirZ
numberrightDirX
numberrightDirY
numberrightDirZ
numberupDirX
numberupDirY
numberupDirZ

Spring.GetUnitHeading (function) view source 

Spring.GetUnitHeading(UnitID, boolean?) -> number
Parameters
UnitIDunitID
boolean?convertToRadians
(Default: false)
Returns
numberheading

Spring.GetUnitVelocity (function) view source 

Spring.GetUnitVelocity(UnitID) -> nil
Parameters
UnitIDunitID

Spring.GetUnitBuildFacing (function) view source 

Spring.GetUnitBuildFacing(UnitID) -> FacingInteger?
Parameters
UnitIDunitID
Returns
FacingInteger?buildFacing
facing of footprint, 0 - 3

Spring.GetUnitIsBuilding (function) view source

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

Works for both mobile builders and factories.

Spring.GetUnitIsBuilding(UnitID) -> UnitID?
Parameters
UnitIDunitID
Returns
UnitID?buildeeUnitID

Spring.GetUnitWorkerTask (function) view source

Checks a builder’s current task

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).

Spring.GetUnitWorkerTask(UnitID) -> integer, integer
Parameters
UnitIDunitID
Returns
integercmdID
of the relevant command
integertargetID
if applicable (all except RESTORE)

Spring.GetUnitEffectiveBuildRange (function) view source

Useful for setting move goals manually.
Spring.GetUnitEffectiveBuildRange(UnitID, UnitDefID?) -> number
Parameters
UnitIDunitID
UnitDefID?buildeeDefID
Returns
numbereffectiveBuildRange
counted to the center of prospective buildee; buildRange if buildee nil

Spring.GetUnitCurrentBuildPower (function) view source 

Spring.GetUnitCurrentBuildPower(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?buildPower
nil if the unit is neither a builder nor a factory.

Spring.GetUnitHarvestStorage (function) view source

Get a unit’s carried resources

Checks resources being carried internally by the unit.

Spring.GetUnitHarvestStorage(UnitID) -> number, number, number, number
Parameters
UnitIDunitID
Returns
numberstoredMetal
numbermaxStoredMetal
numberstoredEnergy
numbermaxStoredEnergy

Spring.GetUnitBuildParams (function) view source

Get the build range of an allied builder unit.
Spring.GetUnitBuildParams(UnitID, ("buildRange"|"buildDistance")) -> number?
Parameters
UnitIDunitID
("buildRange"|"buildDistance")paramName
Returns
number?buildDistance
The builder’s build range, or nil if unitID is not an allied builder unit.

Spring.GetUnitBuildParams (function overload 1) view source

Get whether an allied builder unit’s range tests are 3D.
Spring.GetUnitBuildParams(UnitID, "buildRange3D") -> boolean?
Parameters
UnitIDunitID
"buildRange3D"paramName
Returns
boolean?buildRange3D
true if range tests use spheres, false if they use infinite cylinders, or nil if unitID is not an allied builder unit.

Spring.GetUnitInBuildStance (function) view source

Is builder in build stance

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

Spring.GetUnitInBuildStance(UnitID) -> boolean
Parameters
UnitIDunitID
Returns
booleaninBuildStance

Spring.GetUnitNanoPieces (function) view source

Get construction FX attachment points

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.

Spring.GetUnitNanoPieces(UnitID) -> integer[]
Parameters
UnitIDunitID
Returns
integer[]pieceArray

Spring.GetUnitTransporter (function) view source

Get the transport carrying the unit

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

Spring.GetUnitTransporter(UnitID) -> UnitID?
Parameters
UnitIDunitID
Returns
UnitID?transportUnitID

Spring.GetUnitIsTransporting (function) view source

Get units being transported
Spring.GetUnitIsTransporting(UnitID) -> UnitID[]?
Parameters
UnitIDunitID
Returns
UnitID[]?transporteeArray
An array of unitIDs being transported by this unit, or nil if not a transport.

Spring.GetUnitShieldState (function) view source 

Spring.GetUnitShieldState(UnitID, integer?) -> integer, number
Parameters
UnitIDunitID
integer?weaponNum
Optional if the unit has just one shield
Returns
integerisEnabled
Warning, number not boolean. 0 or 1
numbercurrentPower

Spring.GetUnitFlanking (function) view source

When called without a key, returns every value. When called with one of “mode”, “moveFactor”, “minDamage” or “maxDamage” returns just that single number, and with “dir” returns just dirX, dirY, dirZ.
Spring.GetUnitFlanking(UnitID) -> number, number, number, number, number, number, number, number
Parameters
UnitIDunitID
Returns
numbermode
numbermoveFactor
numberminDamage
numbermaxDamage
numberdirX
numberdirY
numberdirZ
numbermobility
The amount of mobility the unit has collected up to now.

Spring.GetUnitMaxRange (function) view source

Get a unit’s engagement range

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.

Spring.GetUnitMaxRange(UnitID) -> number
Parameters
UnitIDunitID
Returns
numbermaxRange

Spring.GetUnitWeaponState (function) view source

Check the state of a unit’s weapon

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.

Spring.GetUnitWeaponState(UnitID, integer, string?) -> number
Parameters
UnitIDunitID
integerweaponNum
string?stateName
Returns
numberstateValue

Spring.GetUnitWeaponDamages (function) view source 

Spring.GetUnitWeaponDamages(UnitID) -> nil
Parameters
UnitIDunitID

Spring.GetUnitWeaponVectors (function) view source 

Spring.GetUnitWeaponVectors(UnitID, integer) -> number?, number, number, number, number, number
Parameters
UnitIDunitID
integerweaponNum
1-indexed weapon number
Returns
number?posX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ

Spring.GetUnitWeaponTryTarget (function) view source 

Spring.GetUnitWeaponTryTarget(UnitID, integer, UnitID) -> boolean
Parameters
UnitIDunitID
integerweaponNum
UnitIDtargetID
Returns
booleancanTarget

Spring.GetUnitWeaponTryTarget (function overload 1) view source 

Spring.GetUnitWeaponTryTarget(UnitID, integer, number, number, number) -> boolean
Parameters
UnitIDunitID
integerweaponNum
numberposX
numberposY
numberposZ
Returns
booleancanTarget

Spring.GetUnitWeaponTestTarget (function) view source 

Spring.GetUnitWeaponTestTarget(UnitID, integer, UnitID) -> boolean
Parameters
UnitIDunitID
integerweaponID
weapon number (1-based Lua index)
UnitIDtargetUnitID
enemy unit to test (when fewer than five arguments)
Returns
booleanvalidTarget

Spring.GetUnitWeaponTestTarget (function overload 1) view source 

Spring.GetUnitWeaponTestTarget(UnitID, integer, number, number, number) -> boolean
Parameters
UnitIDunitID
integerweaponID
weapon number (1-based Lua index)
numbertargetX
world X to test (with targetY, targetZ; used when at least five arguments are passed)
numbertargetY
numbertargetZ
Returns
booleanvalidTarget

Spring.GetUnitWeaponTestRange (function) view source 

Spring.GetUnitWeaponTestRange(UnitID, integer, UnitID) -> boolean
Parameters
UnitIDunitID
integerweaponNum
UnitIDtargetID
Returns
booleaninRange

Spring.GetUnitWeaponTestRange (function overload 1) view source 

Spring.GetUnitWeaponTestRange(UnitID, integer, number, number, number) -> boolean
Parameters
UnitIDunitID
integerweaponNum
numberposX
numberposY
numberposZ
Returns
booleaninRange

Spring.GetUnitWeaponHaveFreeLineOfFire (function) view source 

Spring.GetUnitWeaponHaveFreeLineOfFire(UnitID, integer, UnitID) -> boolean
Parameters
UnitIDunitID
integerweaponNum
UnitIDtargetID
Returns
booleanhaveFreeLineOfFire

Spring.GetUnitWeaponHaveFreeLineOfFire (function overload 1) view source 

Spring.GetUnitWeaponHaveFreeLineOfFire(UnitID, integer, number, number, number) -> boolean
Parameters
UnitIDunitID
integerweaponNum
numbersrcPosX
numbersrcPosY
numbersrcPosZ
Returns
booleanhaveFreeLineOfFire

Spring.GetUnitWeaponHaveFreeLineOfFire (function overload 2) view source 

Spring.GetUnitWeaponHaveFreeLineOfFire(UnitID, integer, number, number, number, UnitID) -> boolean
Parameters
UnitIDunitID
integerweaponNum
numbersrcPosX
numbersrcPosY
numbersrcPosZ
UnitIDtargetID
Returns
booleanhaveFreeLineOfFire

Spring.GetUnitWeaponHaveFreeLineOfFire (function overload 3) view source 

Spring.GetUnitWeaponHaveFreeLineOfFire(UnitID, integer, number, number, number, number, number, number) -> boolean
Parameters
UnitIDunitID
integerweaponNum
numbersrcPosX
numbersrcPosY
numbersrcPosZ
numbertgtPosX
numbertgtPosY
numbertgtPosZ
Returns
booleanhaveFreeLineOfFire

Spring.GetUnitWeaponCanFire (function) view source 

Spring.GetUnitWeaponCanFire(UnitID, integer, boolean?, boolean?, boolean?) -> boolean
Parameters
UnitIDunitID
integerweaponNum
boolean?ignoreAngleGood
boolean?ignoreTargetType
boolean?ignoreRequestedDir
Returns
booleancanFire

Spring.GetUnitWeaponTarget (function) view source

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.

Spring.GetUnitWeaponTarget(UnitID, integer) -> 0, boolean
Parameters
UnitIDunitID
integerweaponNum
Returns
0TargetType
none
booleanisUserTarget

Spring.GetUnitWeaponTarget (function overload 1) view source

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.

Spring.GetUnitWeaponTarget(UnitID, integer) -> 1, boolean, UnitID
Parameters
UnitIDunitID
integerweaponNum
Returns
1TargetType
unit
booleanisUserTarget
UnitIDtargetUnitID

Spring.GetUnitWeaponTarget (function overload 2) view source

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.

Spring.GetUnitWeaponTarget(UnitID, integer) -> 2, boolean, float3
Parameters
UnitIDunitID
integerweaponNum
Returns
2TargetType
position
booleanisUserTarget
float3targetPosition

Spring.GetUnitWeaponTarget (function overload 3) view source

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.

Spring.GetUnitWeaponTarget(UnitID, integer) -> 3, boolean, ProjectileID
Parameters
UnitIDunitID
integerweaponNum
Returns
3TargetType
projectileID
booleanisUserTarget
ProjectileIDtargetProjectileId

Spring.GetUnitEstimatedPath (function) view source 

Spring.GetUnitEstimatedPath(UnitID) -> nil
Parameters
UnitIDunitID

Spring.GetUnitLastAttacker (function) view source 

Spring.GetUnitLastAttacker(UnitID) -> UnitID?
Parameters
UnitIDunitID
Returns
UnitID?attackerUnitID
nil if the unit has no last attacker or the attacker is not visible.

Spring.GetUnitLastAttackedPiece (function) view source 

Spring.GetUnitLastAttackedPiece(UnitID) -> nil
Parameters
UnitIDunitID

Spring.GetUnitCollisionVolumeData (function) view source 

Spring.GetUnitCollisionVolumeData(UnitID) -> nil
Parameters
UnitIDunitID

Spring.GetUnitPieceCollisionVolumeData (function) view source 

Spring.GetUnitPieceCollisionVolumeData(UnitID, integer) -> number?, number?, number?, number?, number?, number?, integer?, integer?, integer?, boolean?
Parameters
UnitIDunitID
integerpieceIndex
1-based local-model piece index
Returns
number?scaleX
number?scaleY
number?scaleZ
number?offsetX
number?offsetY
number?offsetZ
integer?volumeType
integer?testType
integer?primaryAxis
boolean?disabled
Returns no values when unitID is invalid or not in line of sight, or when pieceIndex is invalid.

Spring.GetUnitSeparation (function) view source 

Spring.GetUnitSeparation(UnitID, UnitID, boolean?, boolean?) -> number?
Parameters
UnitIDunitID1
UnitIDunitID2
boolean?direction
(Default: false) to subtract from, default unitID1 - unitID2
boolean?subtractRadii
(Default: false) whether units radii should be subtracted from the total
Returns
number?

Spring.GetUnitFeatureSeparation (function) view source 

Spring.GetUnitFeatureSeparation(UnitID, FeatureID, boolean?) -> number
Parameters
UnitIDunitID
FeatureIDfeatureID
boolean?flat
(Default: false) if true, XZ (2D) distance; otherwise 3D distance
Returns
numberdistance

Spring.GetUnitDefDimensions (function) view source 

Spring.GetUnitDefDimensions(UnitDefID) -> UnitDefDimensions?
Parameters
UnitDefIDunitDefID
Returns
UnitDefDimensions?dimensions

Spring.GetCEGID (function) view source 

Spring.GetCEGID() -> integer
Returns
integercegID

Spring.GetUnitBlocking (function) view source 

Spring.GetUnitBlocking(UnitID) -> boolean?, boolean, boolean, boolean, boolean, boolean, boolean
Parameters
UnitIDunitID
Returns
boolean?isBlocking
booleanisSolidObjectCollidable
booleanisProjectileCollidable
booleanisRaySegmentCollidable
booleancrushable
booleanblockEnemyPushing
booleanblockHeightChanges

Spring.GetUnitMoveTypeData (function) view source 

Spring.GetUnitMoveTypeData(UnitID) -> nil
Parameters
UnitIDunitID

Spring.GetUnitMaxWantedSpeed (function) view source 

Spring.GetUnitMaxWantedSpeed(UnitID) -> number?
Parameters
UnitIDunitID
Returns
number?maxWantedSpeed
Same as maxWantedSpeed in Spring.GetUnitMoveTypeData.

Spring.GetUnitCurrentCommand (function) view source

Get a command from a units command queue.

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

See Spring.GetFactoryCommands for getting factory build queue commands

Spring.GetUnitCurrentCommand(UnitID, integer?) -> CMD?, (integer|CommandOptionBit)?, integer?, number? ...
Parameters
UnitIDunitID
unitID when invalid this function returns nil.
integer?cmdIndex
(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
CMD?cmdID
(integer|CommandOptionBit)?options
integer?tag
number? ...Command
parameters.

Spring.GetUnitCommands (function) view source

Get the commands for a unit.

Same as Spring.GetCommandQueue

Spring.GetUnitCommands(UnitID, integer) -> Command[]
Parameters
UnitIDunitID
integercount
Maximum amount of commands to return, -1 returns all commands.
Returns
Command[]commands

Spring.GetUnitCommands (function overload 1) view source

Get the count of commands for a unit.

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

Spring.GetUnitCommands(UnitID, 0) -> integer
Parameters
UnitIDunitID
0count
Returns the number of commands in the units queue.
Returns
integercmdCount
The number of commands in the unit queue.

Spring.GetFactoryCommands (function) view source

Get the number or list of commands for a factory

See Spring.GetFactoryCommandCount to get the count of commands., Spring.GetFactoryCounts to get command counts grouped by cmdID.

Spring.GetFactoryCommands(UnitID, integer) -> Command[]
Parameters
UnitIDunitID
integercount
Maximum amount of commands to return, -1 returns all commands.
Returns
Command[]commands

Spring.GetFactoryCommands (function overload 1) view source

Get the count of commands for a factory.

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

See Spring.GetFactoryCommandCount for replacement function.

Spring.GetFactoryCommands(UnitID, 0) -> integer
Parameters
UnitIDunitID
0count
Returns the number of commands in the factory queue.
Returns
integercmdCount
The number of commands in the factory queue.

Spring.GetUnitCommandCount (function) view source

Get the number of commands in a unit’s queue.
Spring.GetUnitCommandCount(UnitID) -> integer
Parameters
UnitIDunitID
Returns
integercmdCount
The number of commands in the unit’s queue.

Spring.GetFactoryCommandCount (function) view source

Get the number of commands in a factory queue.

See Spring.GetFactoryCommands to get the factory commands., Spring.GetFactoryCounts to get command counts grouped by cmdID.

Spring.GetFactoryCommandCount(UnitID) -> integer
Parameters
UnitIDunitID
Returns
integercmdCount
The number of commands in the factory queue.

Spring.GetFactoryBuggerOff (function) view source 

Spring.GetFactoryBuggerOff(UnitID) -> boolean?, number, number, number, boolean, boolean
Parameters
UnitIDunitID
Returns
boolean?boPerform
nil if the unit does not exist or is not a factory.
numberboOffset
numberboRadius
numberboRelHeading
booleanboSherical
booleanboForced

Spring.GetFactoryCounts (function) view source

Gets the build queue of a factory
Spring.GetFactoryCounts(UnitID, integer?, boolean?) -> table<number,number>?
Parameters
UnitIDunitID
integer?count
(Default: -1) Number of commands to retrieve, -1 for all.
boolean?addCmds
(Default: false) Retrieve commands other than buildunit
Returns
table<number,number>?counts
Build queue count by unitDefID or -cmdID, or nil if unit is not found.

Spring.GetCommandQueue (function) view source

Get the commands for a unit.

Same as Spring.GetUnitCommands

Deprecated: Use Spring.GetUnitCommands instead.

Spring.GetCommandQueue(UnitID, integer) -> Command[]
Parameters
UnitIDunitID
integercount
Number of commands to return, -1 returns all commands, 0 returns command count.
Returns
Command[]commands

Spring.GetCommandQueue (function overload 1) view source

Get the count of commands for a unit.

Same as Spring.GetUnitCommands

Deprecated: Use Spring.GetUnitCommandCount instead.

Spring.GetCommandQueue(UnitID, 0) -> integer
Parameters
UnitIDunitID
0count
Returns the number of commands in the units queue.
Returns
integercmdCount
The number of commands in the unit queue.

Spring.GetFullBuildQueue (function) view source

Returns the build queue
Spring.GetFullBuildQueue(UnitID) -> table<UnitDefID,integer>?
Parameters
UnitIDunitID
Returns
table<UnitDefID,integer>?buildqueue
indexed by unitDefID with count values

Spring.GetRealBuildQueue (function) view source

Returns the build queue cleaned of things the unit can’t build itself
Spring.GetRealBuildQueue(UnitID) -> table<UnitDefID,integer>?
Parameters
UnitIDunitID
Returns
table<UnitDefID,integer>?buildqueue
indexed by unitDefID with count values

Spring.GetUnitCmdDescs (function) view source 

Spring.GetUnitCmdDescs(UnitID) -> nil
Parameters
UnitIDunitID

Spring.FindUnitCmdDesc (function) view source 

Spring.FindUnitCmdDesc(UnitID, integer) -> integer?
Parameters
UnitIDunitID
integercmdID
Returns
integer?

Spring.ValidFeatureID (function) view source 

Spring.ValidFeatureID(FeatureID) -> boolean
Parameters
FeatureIDfeatureID
Returns
boolean

Spring.GetAllFeatures (function) view source 

Spring.GetAllFeatures() -> FeatureID[]
Returns
FeatureID[]featureIDs

Spring.GetFeatureDefID (function) view source 

Spring.GetFeatureDefID(FeatureID) -> FeatureDefID?
Parameters
FeatureIDfeatureID
Returns
FeatureDefID?

Spring.GetFeatureTeam (function) view source 

Spring.GetFeatureTeam(FeatureID) -> TeamID?
Parameters
FeatureIDfeatureID
Returns
TeamID?

Spring.GetFeatureAllyTeam (function) view source 

Spring.GetFeatureAllyTeam(FeatureID) -> AllyTeamID?
Parameters
FeatureIDfeatureID
Returns
AllyTeamID?

Spring.GetFeatureHealth (function) view source 

Spring.GetFeatureHealth(FeatureID) -> number?, number, number
Parameters
FeatureIDfeatureID
Returns
number?health
numberdefHealth
numberresurrectProgress

Spring.GetFeatureHeight (function) view source 

Spring.GetFeatureHeight(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?

Spring.GetFeatureRadius (function) view source 

Spring.GetFeatureRadius(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?

Spring.GetFeatureMass (function) view source 

Spring.GetFeatureMass(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?

Spring.GetFeaturePosition (function) view source 

Spring.GetFeaturePosition(FeatureID) -> number?, number?, number?
Parameters
FeatureIDfeatureID
Returns
number?x
number?y
number?z

Spring.GetFeatureSeparation (function) view source 

Spring.GetFeatureSeparation(FeatureID, FeatureID, boolean?) -> number?
Parameters
FeatureIDfeatureID1
FeatureIDfeatureID2
boolean?direction
(Default: false) to subtract from, default featureID1 - featureID2
Returns
number?

Spring.GetFeatureRotation (function) view source

Note: PYR order
Spring.GetFeatureRotation(FeatureID) -> number?, number?, number?
Parameters
FeatureIDfeatureID
Returns
number?pitch
Rotation in X axis
number?yaw
Rotation in Y axis
number?roll
Rotation in Z axis

Spring.GetFeatureDirection (function) view source 

Spring.GetFeatureDirection(FeatureID) -> number?, number?, number?, number?, number?, number?, number?, number?, number?
Parameters
FeatureIDfeatureID
Returns
number?frontDirX
number?frontDirY
number?frontDirZ
number?rightDirX
number?rightDirY
number?rightDirZ
number?upDirX
number?upDirY
number?upDirZ

Spring.GetFeatureVelocity (function) view source

Returns nil if no feature found with ID.
Spring.GetFeatureVelocity(FeatureID) -> number?, number?, number?, number?
Parameters
FeatureIDfeatureID
Returns
number?x
number?y
number?z
number?w

Spring.GetFeatureHeading (function) view source 

Spring.GetFeatureHeading(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?heading

Spring.GetFeatureResources (function) view source 

Spring.GetFeatureResources(FeatureID) -> number?, number, number, number, number, number
Parameters
FeatureIDfeatureID
Returns
number?metal
numberdefMetal
numberenergy
numberdefEnergy
numberreclaimLeft
numberreclaimTime

Spring.GetFeatureBlocking (function) view source 

Spring.GetFeatureBlocking(FeatureID) -> boolean?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?
Parameters
FeatureIDfeatureID
Returns
boolean?isBlocking
boolean?isSolidObjectCollidable
boolean?isProjectileCollidable
boolean?isRaySegmentCollidable
boolean?crushable
boolean?blockEnemyPushing
boolean?blockHeightChanges

Spring.GetFeatureNoSelect (function) view source 

Spring.GetFeatureNoSelect(FeatureID) -> boolean?
Parameters
FeatureIDfeatureID
Returns
boolean?

Spring.GetFeatureResurrect (function) view source

Returns nil if no feature found with ID.
Spring.GetFeatureResurrect(FeatureID) -> (string|"")?, FacingInteger
Parameters
FeatureIDfeatureID
Returns
(string|"")?featureDefName
FacingIntegerbuildFacing
facing of footprint, 0 - 3

Spring.GetFeatureLastAttackedPiece (function) view source 

Spring.GetFeatureLastAttackedPiece(FeatureID) -> (string|"")?, integer?
Parameters
FeatureIDfeatureID
Returns
(string|"")?pieceName
Last hit piece name
integer?frame
frame it was last hit on, nil when featureID is not valid

Spring.GetFeatureCollisionVolumeData (function) view source 

Spring.GetFeatureCollisionVolumeData(FeatureID) -> CollisionVolumeData?
Parameters
FeatureIDfeatureID
Returns
CollisionVolumeData?

Spring.GetFeaturePieceCollisionVolumeData (function) view source 

Spring.GetFeaturePieceCollisionVolumeData(FeatureID) -> CollisionVolumeData?
Parameters
FeatureIDfeatureID
Returns
CollisionVolumeData?

Spring.GetFeatureFireTime (function) view source

Get the feature current fire timer.
Spring.GetFeatureFireTime(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?fireTime
in seconds, nil when featureID is invalid.

Spring.GetFeatureSmokeTime (function) view source

Get the feature current smoke timer.
Spring.GetFeatureSmokeTime(FeatureID) -> number?
Parameters
FeatureIDfeatureID
Returns
number?smokeTime
in seconds, nil when featureID is invalid.

Spring.GetProjectilePosition (function) view source 

Spring.GetProjectilePosition(ProjectileID) -> number?, number?, number?
Parameters
ProjectileIDprojectileID
Returns
number?posX
number?posY
number?posZ

Spring.GetProjectileDirection (function) view source 

Spring.GetProjectileDirection(ProjectileID) -> number?, number?, number?
Parameters
ProjectileIDprojectileID
Returns
number?dirX
number?dirY
number?dirZ

Spring.GetProjectileVelocity (function) view source 

Spring.GetProjectileVelocity(ProjectileID) -> number?, number?, number?, number?
Parameters
ProjectileIDprojectileID
Returns
number?velX
number?velY
number?velZ
number?velW

Spring.GetProjectileGravity (function) view source 

Spring.GetProjectileGravity(ProjectileID) -> number?
Parameters
ProjectileIDprojectileID
Returns
number?

Spring.GetPieceProjectileParams (function) view source 

Spring.GetPieceProjectileParams(ProjectileID) -> integer?, number, number, number, number, number
Parameters
ProjectileIDprojectileID
Returns
integer?explosionFlags
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
numberspinAngle
numberspinSpeed
numberspinVectorX
numberspinVectorY
numberspinVectorZ

Spring.GetProjectileTarget (function) view source

targetTypeInt is one of:

  • string.byte(‘g’) ground
  • string.byte(‘u’) unit
  • string.byte(‘f’) feature
  • string.byte(‘p’) projectile
Spring.GetProjectileTarget(ProjectileID) -> integer?, (UnitID|FeatureID|ProjectileID|float3)
Parameters
ProjectileIDprojectileID
Returns
integer?targetTypeInt
The type of target.
(UnitID|FeatureID|ProjectileID|float3)target
targetID or targetPos when targetTypeInt == string.byte(‘g’)

Spring.GetProjectileIsIntercepted (function) view source 

Spring.GetProjectileIsIntercepted(ProjectileID) -> boolean?
Parameters
ProjectileIDprojectileID
Returns
boolean?

Spring.GetProjectileTimeToLive (function) view source 

Spring.GetProjectileTimeToLive(ProjectileID) -> integer?
Parameters
ProjectileIDprojectileID
Returns
integer?

Spring.GetProjectileOwnerID (function) view source 

Spring.GetProjectileOwnerID(ProjectileID) -> UnitID?
Parameters
ProjectileIDprojectileID
Returns
UnitID?

Spring.GetProjectileTeamID (function) view source 

Spring.GetProjectileTeamID(ProjectileID) -> TeamID?
Parameters
ProjectileIDprojectileID
Returns
TeamID?

Spring.GetProjectileAllyTeamID (function) view source 

Spring.GetProjectileAllyTeamID(ProjectileID) -> AllyTeamID?
Parameters
ProjectileIDprojectileID
Returns
AllyTeamID?

Spring.GetProjectileType (function) view source 

Spring.GetProjectileType(ProjectileID) -> boolean?, boolean
Parameters
ProjectileIDprojectileID
Returns
boolean?weapon
booleanpiece

Spring.GetProjectileDefID (function) view source 

Spring.GetProjectileDefID(ProjectileID) -> WeaponDefID?
Parameters
ProjectileIDprojectileID
Returns
WeaponDefID?

Spring.GetPieceProjectileName (function) view source

Returns the name of the model piece from which a piece projectile was spawned. Returns nil for other projectiles including weapons
Spring.GetPieceProjectileName(ProjectileID) -> string?
Parameters
ProjectileIDprojectileID
Returns
string?pieceName

Spring.GetProjectileDamages (function) view source

tag is one of:

  • “paralyzeDamageTime”
  • “impulseFactor”
  • “impulseBoost”
  • “craterMult”
  • “craterBoost”
  • “dynDamageExp”
  • “dynDamageMin”
  • “dynDamageRange”
  • “dynDamageInverted”
  • “craterAreaOfEffect”
  • “damageAreaOfEffect”
  • “edgeEffectiveness”
  • “explosionSpeed”

It can also be an armor type index, to get the damage against it.

Spring.GetProjectileDamages(ProjectileID, string) -> number?
Parameters
ProjectileIDprojectileID
stringtag
The damage property, or an armor type index.
Returns
number?

Spring.IsPosInMap (function) view source 

Spring.IsPosInMap(number, number) -> boolean, boolean
Parameters
numberx
numberz
Returns
booleaninPlayArea
whether the position is in the active play area
booleaninMap
whether the position is in the full map area (currently this is the same as above)

Spring.GetGroundHeight (function) view source

Get ground height

On sea, this returns the negative depth of the seafloor

Spring.GetGroundHeight(number, number) -> number
Parameters
numberx
numberz
Returns
number

Spring.GetWaterPlaneLevel (function) view source

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.

See Spring.GetWaterLevel

Spring.GetWaterPlaneLevel() -> number
Returns
numberwaterPlaneLevel

Spring.GetWaterLevel (function) view source

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.

Spring.GetWaterLevel(number, number) -> number
Parameters
numberx
numberz
Returns
numberwaterLevel

Spring.GetGroundOrigHeight (function) view source

Get ground height as it was at game start

Returns the original height before the ground got deformed

Spring.GetGroundOrigHeight(number, number) -> number
Parameters
numberx
numberz
Returns
number

Spring.GetGroundNormal (function) view source 

Spring.GetGroundNormal(number, number, boolean?) -> number, number, number, number
Parameters
numberx
numberz
boolean?smoothed
(Default: false) raw or smoothed center normal
Returns
numbernormalX
numbernormalY
numbernormalZ
numberslope

Spring.GetGroundInfo (function) view source 

Spring.GetGroundInfo(number, number) -> integer, integer, integer, string, number, number, number, number, number, number, boolean
Parameters
numberx
numberz
Returns
integerix
integeriz
integerterrainTypeIndex
stringname
numbermetalExtraction
numberhardness
numbertankSpeed
numberkbotSpeed
numberhoverSpeed
numbershipSpeed
booleanreceiveTracks

Spring.GetGroundBlocked (function) view source 

Spring.GetGroundBlocked(number, number, number?, number?) -> string?, (UnitID|FeatureID)?
Parameters
numberx
world x coordinate (or xMin when using 4-arg form)
numberz
world z coordinate (or zMin when using 4-arg form)
number?x2
world xMax (4-arg rectangle form)
number?z2
world zMax (4-arg rectangle form)
Returns
string?objectType
“feature” or “unit”
(UnitID|FeatureID)?objectID
the feature or unit ID

Spring.GetGroundExtremes (function) view source 

Spring.GetGroundExtremes() -> number, number, number, number
Returns
numberinitMinHeight
numberinitMaxHeight
numbercurrMinHeight
numbercurrMaxHeight

Spring.GetTerrainTypeData (function) view source 

Spring.GetTerrainTypeData(integer) -> integer, string, number, number, number, number, number, boolean
Parameters
integerterrainTypeInfo
Returns
integerindex
stringname
numberhardness
numbertankSpeed
numberkbotSpeed
numberhoverSpeed
numbershipSpeed
booleanreceiveTracks

Spring.GetGrass (function) view source 

Spring.GetGrass(number, number) -> number
Parameters
numberx
numberz
Returns
number

Spring.GetSmoothMeshHeight (function) view source 

Spring.GetSmoothMeshHeight(number, number) -> number
Parameters
numberx
numberz
Returns
numberheight

Spring.TestMoveOrder (function) view source 

Spring.TestMoveOrder(UnitDefID, number, number, number, number?, number?, number?, boolean?, boolean?, boolean?) -> boolean
Parameters
UnitDefIDunitDefID
numberposX
numberposY
numberposZ
number?dirX
(Default: 0.0)
number?dirY
(Default: 0.0)
number?dirZ
(Default: 0.0)
boolean?testTerrain
(Default: true)
boolean?testObjects
(Default: true)
boolean?centerOnly
(Default: false)
Returns
boolean

Spring.TestBuildOrder (function) view source 

Spring.TestBuildOrder(UnitDefID, number, number, number, Facing) -> BuildOrderBlockedStatus, FeatureID?
Parameters
UnitDefIDunitDefID
numberx
numbery
numberz
Facingfacing
Returns
BuildOrderBlockedStatusblocking
FeatureID?featureID
A reclaimable feature in the way.

Spring.TestBuildOrderOverlap (function) view source 

Spring.TestBuildOrderOverlap(BuildOrderSpec, BuildOrderSpec) -> boolean, boolean
Parameters
BuildOrderSpecqueuedBuild
BuildOrderSpecproposedBuild
Returns
booleanoverlaps
Whether the builds conflict under the queued-build overlap rules.
booleancancels
Whether the proposed build would cancel the earlier queued build.

Spring.Pos2BuildPos (function) view source

Snaps a position to the building grid
Spring.Pos2BuildPos(UnitDefID, number, number, number, number?) -> number, number, number
Parameters
UnitDefIDunitDefID
numberposX
numberposY
numberposZ
number?buildFacing
(Default: 0) one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3
Returns
numberbuildPosX
numberbuildPosY
numberbuildPosZ

Spring.ClosestBuildPos (function) view source 

Spring.ClosestBuildPos(TeamID, UnitDefID, number, number, number, number, number, number) -> number, number, number
Parameters
TeamIDteamID
UnitDefIDunitDefID
numberposX
numberposY
numberposZ
numbersearchRadius
numberminDistance
numberbuildFacing
one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3
Returns
numberbuildPosX
numberbuildPosY
numberbuildPosZ

Spring.GetPositionLosState (function) view source 

Spring.GetPositionLosState(number, number, number, AllyTeamID?) -> boolean, boolean, boolean, boolean
Parameters
numberposX
numberposY
numberposZ
AllyTeamID?allyTeamID
Returns
booleaninLosOrRadar
booleaninLos
booleaninRadar
booleaninJammer

Spring.IsPosInLos (function) view source 

Spring.IsPosInLos(number, number, number, AllyTeamID?) -> boolean
Parameters
numberposX
numberposY
numberposZ
AllyTeamID?allyTeamID
Returns
boolean

Spring.IsPosInRadar (function) view source 

Spring.IsPosInRadar(number, number, number, AllyTeamID?) -> boolean
Parameters
numberposX
numberposY
numberposZ
AllyTeamID?allyTeamID
Returns
boolean

Spring.IsPosInAirLos (function) view source 

Spring.IsPosInAirLos(number, number, number, AllyTeamID?) -> boolean
Parameters
numberposX
numberposY
numberposZ
AllyTeamID?allyTeamID
Returns
boolean

Spring.GetUnitLosState (function) view source

Get unit los state (bitmask)
Spring.GetUnitLosState(UnitID, AllyTeamID?, true) -> (LosMask|integer)?
Parameters
UnitIDunitID
AllyTeamID?allyTeamID
trueraw
Return a bitmask.
Returns
(LosMask|integer)?bitmask
A bitmask of LosMask bits

Spring.GetUnitLosState (function overload 1) view source

Get unit los state (table)
Spring.GetUnitLosState(UnitID, AllyTeamID?, false?) -> table<("los"|"radar"...),boolean>?
Parameters
UnitIDunitID
AllyTeamID?allyTeamID
false?raw
(Default: false) Return a table.
Returns
table<("los"|"radar"...),boolean>?los
A table of LOS state names as keys and booleans as values, or nil if unitID is invalid.

Spring.IsUnitInLos (function) view source 

Spring.IsUnitInLos(UnitID, AllyTeamID?) -> boolean
Parameters
UnitIDunitID
AllyTeamID?allyTeamID
defaults to the calling widget/gadget’s ally team
Returns
booleaninLos

Spring.IsUnitInAirLos (function) view source 

Spring.IsUnitInAirLos(UnitID, AllyTeamID?) -> boolean
Parameters
UnitIDunitID
AllyTeamID?allyTeamID
defaults to the calling widget/gadget’s ally team
Returns
booleaninAirLos

Spring.IsUnitInRadar (function) view source 

Spring.IsUnitInRadar(UnitID, AllyTeamID?) -> boolean
Parameters
UnitIDunitID
AllyTeamID?allyTeamID
defaults to the calling widget/gadget’s ally team
Returns
booleaninRadar

Spring.IsUnitInJammer (function) view source 

Spring.IsUnitInJammer(UnitID, AllyTeamID) -> boolean
Parameters
UnitIDunitID
AllyTeamIDallyTeamID
Returns
booleaninJammer

Spring.GetModelRootPiece (function) view source 

Spring.GetModelRootPiece(string) -> integer
Parameters
stringmodelName
Returns
integerindex
of the root piece

Spring.GetModelPieceMap (function) view source 

Spring.GetModelPieceMap(string) -> table<string,integer>?
Parameters
stringmodelName
Returns
table<string,integer>?pieceInfos
where keys are piece names and values are indices

Spring.GetModelPieceList (function) view source 

Spring.GetModelPieceList(string) -> string[]?
Parameters
stringmodelName
Returns
string[]?pieceNames

Spring.GetUnitRootPiece (function) view source 

Spring.GetUnitRootPiece(UnitID) -> integer
Parameters
UnitIDunitID
Returns
integerindex
of the root piece

Spring.GetUnitPieceMap (function) view source 

Spring.GetUnitPieceMap(UnitID) -> table<string,integer>?
Parameters
UnitIDunitID
Returns
table<string,integer>?pieceInfos
where keys are piece names and values are indices

Spring.GetUnitPieceList (function) view source 

Spring.GetUnitPieceList(UnitID) -> string[]
Parameters
UnitIDunitID
Returns
string[]pieceNames

Spring.GetUnitPieceInfo (function) view source 

Spring.GetUnitPieceInfo(UnitID, integer) -> PieceInfo?
Parameters
UnitIDunitID
integerpieceIndex
Returns
PieceInfo?pieceInfo

Spring.GetUnitPiecePosDir (function) view source 

Spring.GetUnitPiecePosDir(UnitID, integer) -> number?, number, number, number, number, number
Parameters
UnitIDunitID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ

Spring.GetUnitPiecePosition (function) view source 

Spring.GetUnitPiecePosition(UnitID, integer) -> number?, number, number
Parameters
UnitIDunitID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ

Spring.GetUnitPieceDirection (function) view source 

Spring.GetUnitPieceDirection(UnitID, integer) -> number?, number, number
Parameters
UnitIDunitID
integerpieceIndex
Returns
number?dirX
numberdirY
numberdirZ

Spring.GetUnitPieceMatrix (function) view source 

Spring.GetUnitPieceMatrix(UnitID, integer) -> number?, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
UnitIDunitID
integerpieceIndex
Returns
number?m11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.GetFeatureRootPiece (function) view source 

Spring.GetFeatureRootPiece(FeatureID) -> integer
Parameters
FeatureIDfeatureID
Returns
integerindex
of the root piece

Spring.GetFeaturePieceMap (function) view source 

Spring.GetFeaturePieceMap(FeatureID) -> table<string,integer>
Parameters
FeatureIDfeatureID
Returns
table<string,integer>pieceInfos
where keys are piece names and values are indices

Spring.GetFeaturePieceList (function) view source 

Spring.GetFeaturePieceList(FeatureID) -> string[]
Parameters
FeatureIDfeatureID
Returns
string[]pieceNames

Spring.GetFeaturePieceInfo (function) view source 

Spring.GetFeaturePieceInfo(FeatureID, integer) -> PieceInfo?
Parameters
FeatureIDfeatureID
integerpieceIndex
Returns
PieceInfo?pieceInfo

Spring.GetFeaturePiecePosDir (function) view source 

Spring.GetFeaturePiecePosDir(FeatureID, integer) -> number?, number, number, number, number, number
Parameters
FeatureIDfeatureID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ

Spring.GetFeaturePiecePosition (function) view source 

Spring.GetFeaturePiecePosition(FeatureID, integer) -> number?, number, number
Parameters
FeatureIDfeatureID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ

Spring.GetFeaturePieceDirection (function) view source 

Spring.GetFeaturePieceDirection(FeatureID, integer) -> number?, number, number
Parameters
FeatureIDfeatureID
integerpieceIndex
Returns
number?dirX
numberdirY
numberdirZ

Spring.GetFeaturePieceMatrix (function) view source 

Spring.GetFeaturePieceMatrix(FeatureID, integer) -> number?, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
FeatureIDfeatureID
integerpieceIndex
Returns
number?m11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.GetUnitScriptPiece (function) view source 

Spring.GetUnitScriptPiece(UnitID) -> integer[]
Parameters
UnitIDunitID
Returns
integer[]pieceIndices

Spring.GetUnitScriptPiece (function overload 1) view source 

Spring.GetUnitScriptPiece(UnitID, integer) -> integer
Parameters
UnitIDunitID
integerscriptPiece
Returns
integerpieceIndex

Spring.GetUnitScriptNames (function) view source 

Spring.GetUnitScriptNames(UnitID) -> table<string,integer>
Parameters
UnitIDunitID
Returns
table<string,integer>pieceInfos
where keys are piece names and values are piece indices

Spring.TraceRayInDirection (function) view source

Traces a ray from a position in a direction

Returns all unit and/or feature hits along a ray, sorted by distance from the start position.

Spring.TraceRayInDirection(number, number, number, number, number, number, number, string) -> table[]
Parameters
numberposX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ
numbermaxLength
stringtype
Object type to test: “unit”, “feature”, or “both”
Returns
table[]hits
Array of {hitLength, objectID, objectType} entries

Spring.TraceRayBetweenPositions (function) view source

Traces a ray between two positions

Checks for unit and/or feature collisions between two positions and returns all hits sorted by distance from the start position.

Spring.TraceRayBetweenPositions(number, number, number, number, number, number, string) -> table[]
Parameters
numberstartX
numberstartY
numberstartZ
numberendX
numberendY
numberendZ
stringtype
Object type to test: “unit”, “feature”, or “both”
Returns
table[]hits
Array of {hitLength, objectID, objectType} entries

Spring.TraceRayGroundInDirection (function) view source

Checks for a ground collision in given direction

Checks if there is surface (ground, optionally water) towards a vector and returns the distance to the closest hit and its position, if any.

Spring.TraceRayGroundInDirection(number, number, number, number, number, number, number?, boolean?) -> number?, number?, number?, number?
Parameters
numberposX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ
number?maxLength
(Default: 999999)
boolean?testWater
(Default: true)
Returns
number?rayLength
number?posX
number?posY
number?posZ

Spring.TraceRayGroundBetweenPositions (function) view source

Checks for a ground collision between two positions

Checks if there is surface (ground, optionally water) between two positions and returns the distance to the closest hit and its position, if any.

Spring.TraceRayGroundBetweenPositions(number, number, number, number, number, number, boolean?) -> number, number, number, number
Parameters
numberstartX
numberstartY
numberstartZ
numberendX
numberendY
numberendZ
boolean?testWater
(Default: true)
Returns
numberrayLength
numberposX
numberposY
numberposZ

Spring.GetRadarErrorParams (function) view source 

Spring.GetRadarErrorParams(AllyTeamID) -> number?, number, number
Parameters
AllyTeamIDallyTeamID
Returns
number?radarErrorSize
actual radar error size (when allyTeamID is allied to current team) or base radar error size
numberbaseRadarErrorSize
numberbaseRadarErrorMult

Spring.GetMetalMapSize (function) view source 

Spring.GetMetalMapSize() -> integer, integer
Returns
integerx
X coordinate in worldspace / Game.metalMapSquareSize.
integerz
Z coordinate in worldspace / Game.metalMapSquareSize.

Spring.GetMetalAmount (function) view source

Returns the amount of metal on a single square.
Spring.GetMetalAmount(integer, integer) -> number
Parameters
integerx
X coordinate in worldspace / Game.metalMapSquareSize.
integerz
Z coordinate in worldspace / Game.metalMapSquareSize.
Returns
numberamount

Spring.SetMetalAmount (function) view source

Sets the amount of metal on a single square.
Spring.SetMetalAmount(integer, integer, number) -> nil
Parameters
integerx
X coordinate in worldspace / Game.metalMapSquareSize.
integerz
Z coordinate in worldspace / Game.metalMapSquareSize.
numbermetalAmount
must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
Returns
nil

Spring.GetMetalExtraction (function) view source 

Spring.GetMetalExtraction(integer, integer) -> number
Parameters
integerx
X coordinate in worldspace / Game.metalMapSquareSize.
integerz
Z coordinate in worldspace / Game.metalMapSquareSize.
Returns
numberextraction

Fields

MoveCtrl MoveCtrlview source
UnitScriptTable UnitScriptview source
ObjectRenderingTable UnitRenderingview source
ObjectRenderingTable FeatureRenderingview source
integer ALL_UNITSview source
integer MY_UNITSview source
integer ALLY_UNITSview source
integer ENEMY_UNITSview source

Callins (class) view source

Functions called by the Engine.

To use these callins in a widget, prepend widget: and, for a gadget, prepend gadget:. For example:

lua function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID) – … end

Some functions may differ between (synced) gadget and widgets. This is because all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget. e.g. information about an enemy unit only detected via radar and not yet in LOS.

In such cases the full (synced) param list is documented.

Attention: Some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace.

See Gadget, Widget, Menu, Intro, SyncedCallins, UnsyncedCallins

Members

Callins:Initialize (function) view source

Called when the addon is (re)loaded.
Callins:Initialize() -> nil

Callins:LoadCode (function) view source

Called when the game is (re)loaded.
Callins:LoadCode() -> nil

Callins:Shutdown (function) view source

Called when the addon or the game is shutdown.
Callins:Shutdown() -> nil
Returns
nil

Callins:GotChatMsg (function) view source

Called when a player issues a UI command e.g. types /foo or /luarules foo.
Callins:GotChatMsg(string, PlayerID) -> nil
Parameters
stringmsg
PlayerIDplayerID

Callins:Load (function) view source

Called after GamePreload and before GameStart. See Lua_SaveLoad.
Callins:Load(table) -> nil
Parameters
tablezipReader

Callins:GamePreload (function) view source

Called before the 0 gameframe.

Is not called when a saved game is loaded.

Callins:GamePreload() -> nil

Callins:GameStart (function) view source

Called upon the start of the game.

Is not called when a saved game is loaded.

Callins:GameStart() -> nil

Callins:GameOver (function) view source

Called when the game ends
Callins:GameOver(AllyTeamID[]) -> nil
Parameters
AllyTeamID[]winningAllyTeams
list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

Callins:GamePaused (function) view source

Called when the game is paused.
Callins:GamePaused(PlayerID, boolean) -> nil
Parameters
PlayerIDplayerID
booleanpaused

Callins:GameFrame (function) view source

Called for every game simulation frame (30 per second).
Callins:GameFrame(integer) -> nil
Parameters
integerframe
Starts at frame 1

Callins:GameFramePost (function) view source

Called at the end of every game simulation frame
Callins:GameFramePost(integer) -> nil
Parameters
integerframe
Starts at frame 1

Callins:GameID (function) view source

Called once to deliver the gameID
Callins:GameID(string) -> nil
Parameters
stringgameID
encoded in hex.

Callins:TeamDied (function) view source

Called when a team dies (see Spring.KillTeam).
Callins:TeamDied(TeamID) -> nil
Parameters
TeamIDteamID

Callins:TeamChanged (function) view source 

Callins:TeamChanged(TeamID) -> nil
Parameters
TeamIDteamID

Callins:PlayerChanged (function) view source

Called whenever a player’s status changes e.g. becoming a spectator.
Callins:PlayerChanged(PlayerID) -> nil
Parameters
PlayerIDplayerID

Callins:PlayerAdded (function) view source

Called whenever a new player joins the game.
Callins:PlayerAdded(PlayerID) -> nil
Parameters
PlayerIDplayerID

Callins:PlayerRemoved (function) view source

Called whenever a player is removed from the game.
Callins:PlayerRemoved(PlayerID, integer) -> nil
Parameters
PlayerIDplayerID
integerreason

Callins:UnitCreated (function) view source

Called at the moment the unit is created.
Callins:UnitCreated(UnitID, UnitDefID, TeamID, UnitID?) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
UnitID?builderID

Callins:UnitFinished (function) view source

Called at the moment the unit is completed.
Callins:UnitFinished(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitFromFactory (function) view source

Called when a factory finishes construction of a unit.
Callins:UnitFromFactory(UnitID, UnitDefID, TeamID, UnitID, UnitDefID, boolean) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
UnitIDfactID
UnitDefIDfactDefID
booleanuserOrders

Callins:UnitReverseBuilt (function) view source

Called when a living unit becomes a nanoframe again.
Callins:UnitReverseBuilt(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitConstructionDecayed (function) view source

Called when a unit being built starts decaying.
Callins:UnitConstructionDecayed(UnitID, UnitDefID, TeamID, number, number, number) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
numbertimeSinceLastBuild
numberiterationPeriod
numberpart

Callins:UnitDestroyed (function) view source

Called when a unit is destroyed.
Callins:UnitDestroyed(UnitID, UnitDefID, TeamID, UnitID?, UnitDefID?, TeamID?, WeaponDefID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
UnitID?attackerID
Subject to visibility rules
UnitDefID?attackerDefID
Subject to visibility rules
TeamID?attackerTeam
Subject to visibility rules
WeaponDefIDweaponDefID

Callins:UnitTaken (function) view source

Called when a unit is transferred between teams. This is called before UnitGiven and in that moment unit is still assigned to the oldTeam.
Callins:UnitTaken(UnitID, UnitDefID, TeamID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDoldTeam
TeamIDnewTeam

Callins:UnitGiven (function) view source

Called when a unit is transferred between teams. This is called after UnitTaken and in that moment unit is assigned to the newTeam.
Callins:UnitGiven(UnitID, UnitDefID, TeamID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDnewTeam
TeamIDoldTeam

Callins:UnitIdle (function) view source

Called when a unit is idle (empty command queue).
Callins:UnitIdle(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitCommand (function) view source

Called after when a unit accepts a command, after AllowCommand returns true.
Callins:UnitCommand(UnitID, UnitDefID, TeamID, integer, table, CommandOptions, integer) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
integercmdID
tablecmdParams
CommandOptionsoptions
integercmdTag

Callins:UnitCmdDone (function) view source

Called when a unit completes a command.
Callins:UnitCmdDone(UnitID, UnitDefID, TeamID, integer, table, CommandOptions, integer) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
integercmdID
tablecmdParams
CommandOptionsoptions
integercmdTag

Callins:UnitDamaged (function) view source

Called when a unit is damaged (after UnitPreDamaged).
Callins:UnitDamaged(UnitID, UnitDefID, TeamID, number, number, WeaponDefID, ProjectileID, UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
numberdamage
numberparalyzer
WeaponDefIDweaponDefID
ProjectileIDprojectileID
UnitIDattackerID
UnitDefIDattackerDefID
TeamIDattackerTeam

Callins:UnitStunned (function) view source

Called when a unit changes its stun status.
Callins:UnitStunned(UnitID, UnitDefID, TeamID, boolean) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
booleanstunned

Callins:UnitExperience (function) view source

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.

Callins:UnitExperience(UnitID, UnitDefID, TeamID, number, number) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
numberexperience
numberoldExperience

Callins:UnitHarvestStorageFull (function) view source

Called when a unit’s harvestStorage is full (according to its unitDef’s entry).
Callins:UnitHarvestStorageFull(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitSeismicPing (function) view source

Called when a unit emits a seismic ping.

See seismicSignature.

Callins:UnitSeismicPing(number, number, number, number, AllyTeamID, UnitID, UnitDefID) -> nil
Parameters
numberx
numbery
numberz
numberstrength
AllyTeamIDallyTeam
UnitIDunitID
UnitDefIDunitDefID

Callins:UnitEnteredRadar (function) view source

Called when a unit enters radar of an allyteam.

Also called when a unit enters LOS without any radar coverage.

Callins:UnitEnteredRadar(UnitID, TeamID, AllyTeamID, UnitDefID) -> nil
Parameters
UnitIDunitID
TeamIDunitTeam
AllyTeamIDallyTeam
UnitDefIDunitDefID

Callins:UnitEnteredLos (function) view source

Called when a unit enters LOS of an allyteam.

Its called after the unit is in LOS, so you can query that unit.

Callins:UnitEnteredLos(UnitID, TeamID, AllyTeamID, UnitDefID) -> nil
Parameters
UnitIDunitID
TeamIDunitTeam
AllyTeamIDallyTeam
who’s LOS the unit entered.
UnitDefIDunitDefID

Callins:UnitLeftRadar (function) view source

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.

Callins:UnitLeftRadar(UnitID, TeamID, AllyTeamID, UnitDefID) -> nil
Parameters
UnitIDunitID
TeamIDunitTeam
AllyTeamIDallyTeam
UnitDefIDunitDefID

Callins:UnitLeftLos (function) view source

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.

Callins:UnitLeftLos(UnitID, TeamID, AllyTeamID, UnitDefID) -> nil
Parameters
UnitIDunitID
TeamIDunitTeam
AllyTeamIDallyTeam
UnitDefIDunitDefID

Callins:UnitLoaded (function) view source

Called when a unit is loaded by a transport.
Callins:UnitLoaded(UnitID, UnitDefID, TeamID, UnitID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
UnitIDtransportID
TeamIDtransportTeam

Callins:UnitUnloaded (function) view source

Called when a unit is unloaded by a transport.
Callins:UnitUnloaded(UnitID, UnitDefID, TeamID, UnitID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
UnitIDtransportID
TeamIDtransportTeam

Callins:UnitEnteredUnderwater (function) view source 

Callins:UnitEnteredUnderwater(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitEnteredWater (function) view source 

Callins:UnitEnteredWater(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitLeftAir (function) view source 

Callins:UnitLeftAir(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitLeftUnderwater (function) view source 

Callins:UnitLeftUnderwater(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitLeftWater (function) view source 

Callins:UnitLeftWater(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitEnteredAir (function) view source 

Callins:UnitEnteredAir(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitCloaked (function) view source

Called when a unit cloaks.
Callins:UnitCloaked(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitDecloaked (function) view source

Called when a unit decloaks.
Callins:UnitDecloaked(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitUnitCollision (function) view source

Called when two units collide.

Both units must be registered with Script.SetWatchUnit.

Callins:UnitUnitCollision(UnitID, UnitID) -> nil
Parameters
UnitIDcolliderID
UnitIDcollideeID

Callins:UnitFeatureCollision (function) view source

Called when a unit collides with a feature.

The unit must be registered with Script.SetWatchUnit and the feature registered with Script.SetWatchFeature.

Callins:UnitFeatureCollision(UnitID, UnitID) -> nil
Parameters
UnitIDcolliderID
UnitIDcollideeID

Callins:UnitMoveFailed (function) view source 

Callins:UnitMoveFailed(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:UnitArrivedAtGoal (function) view source 

Callins:UnitArrivedAtGoal(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:RenderUnitDestroyed (function) view source

Called just before a unit is invalid, after it finishes its death animation.
Callins:RenderUnitDestroyed(UnitID, UnitDefID, TeamID) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam

Callins:FeatureCreated (function) view source

Called when a feature is created.
Callins:FeatureCreated(FeatureID, AllyTeamID) -> nil
Parameters
FeatureIDfeatureID
AllyTeamIDallyTeamID

Callins:FeatureDestroyed (function) view source

Called when a feature is destroyed.
Callins:FeatureDestroyed(FeatureID, AllyTeamID) -> nil
Parameters
FeatureIDfeatureID
AllyTeamIDallyTeamID

Callins:FeatureDamaged (function) view source

Called when a feature is damaged.
Callins:FeatureDamaged(FeatureID, FeatureDefID, TeamID, number, WeaponDefID, ProjectileID, UnitID, UnitDefID, TeamID) -> nil
Parameters
FeatureIDfeatureID
FeatureDefIDfeatureDefID
TeamIDfeatureTeam
numberdamage
WeaponDefIDweaponDefID
ProjectileIDprojectileID
UnitIDattackerID
UnitDefIDattackerDefID
TeamIDattackerTeam

Callins:ProjectileCreated (function) view source

Called when the projectile is created.

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 Script.SetWatchProjectile, Script.SetWatchWeapon

Callins:ProjectileCreated(ProjectileID, UnitID, WeaponDefID) -> nil
Parameters
ProjectileIDproID
UnitIDproOwnerID
WeaponDefIDweaponDefID

Callins:ProjectileDestroyed (function) view source

Called when the projectile is destroyed.

See Script.SetWatchProjectile, Script.SetWatchWeapon

Callins:ProjectileDestroyed(ProjectileID, UnitID, WeaponDefID) -> nil
Parameters
ProjectileIDproID
UnitIDownerID
WeaponDefIDproWeaponDefID

Callins:Explosion (function) view source

Called when an explosion occurs.

Only called for weaponDefIDs registered via Script.SetWatchExplosion or Script.SetWatchWeapon.

See Script.SetWatchExplosion, Script.SetWatchWeapon

Callins:Explosion(WeaponDefID, number, number, number, UnitID, ProjectileID) -> boolean
Parameters
WeaponDefIDweaponDefID
numberpx
numberpy
numberpz
UnitIDattackerID
ProjectileIDprojectileID
Returns
booleannoGfx
if then no graphical effects are drawn by the engine for this explosion.

Callins:StockpileChanged (function) view source

Called when a units stockpile of weapons increases or decreases.
Callins:StockpileChanged(UnitID, UnitDefID, TeamID, integer, integer, integer) -> nil
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
integerweaponNum
integeroldCount
integernewCount

Callins:RecvLuaMsg (function) view source

Receives messages from unsynced sent via Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.
Callins:RecvLuaMsg(string, PlayerID) -> nil
Parameters
stringmsg
PlayerIDplayerID

Callins:Save (function) view source

Called when a chat command ‘/save’ or ‘/savegame’ is received.
Callins:Save(table) -> nil
Parameters
tablezip
a userdatum representing the savegame zip file. See Lua_SaveLoad.

Callins:UnsyncedHeightMapUpdate (function) view source

Called when the unsynced copy of the height-map is altered.
Callins:UnsyncedHeightMapUpdate() -> integer, integer, integer, integer
Returns
integerx1
integerz1
integerx2
integerz2

Callins:Update (function) view source

Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.
Callins:Update(number) -> nil
Parameters
numberdt
the time since the last update.

Callins:ViewResize (function) view source

Called whenever the window is resized.
Callins:ViewResize(integer, integer) -> nil
Parameters
integerviewSizeX
integerviewSizeY

Callins:FontsChanged (function) view source

Called whenever fonts are updated. Signals the game display lists and other caches should be discarded.

Gets called before other Update and Draw callins.

Callins:FontsChanged() -> nil

Callins:SunChanged (function) view source 

Callins:SunChanged() -> nil

Callins:NanoParticleUpdate (function) view source

Batched nano particle lifecycle changes.

Only sent while the NanoParticlesGL4 and NanoParticlesUpdateLuaUI springsettings are both on, and only for the sampled fraction of particles set by NanoParticlesUpdateLuaUISampleRate - one event per particle per frame would overwhelm any consumer. Intended for deferred-lighting widgets.

Events are passed as one flat numeric array to keep the marshalling cost down. Each event occupies 13 consecutive entries: {operation, lightID, px, py, pz, vx, vy, vz, remainingLife, r, g, b, builderBuildSpeed}.

Operations are 1 = spawn, 2 = update, 3 = remove, 4 = reset.

A particle’s lifetime is fixed when it spawns, so remainingLife is exact and consumers are expected to expire their own state from it; operation 3 is reserved and currently never sent. A reset means every previously reported lightID is gone and any state keyed on them should be dropped; it is always the first event of its batch.

Particles are not projectiles and have no projectile ID; lightID is unique, negative, and only valid until the particle expires or a reset arrives.

Callins:NanoParticleUpdate(number[], integer, integer) -> nil
Parameters
number[]events
Flat event records.
integereventCount
Number of records in events.
integergameFrame
Current simulation frame.

Callins:DefaultCommand (function) view source

Used to set the default command when a unit is selected.
Callins:DefaultCommand(("unit"|"feature"), ObjectID, integer) -> integer
Parameters
("unit"|"feature")type
The type of the object pointed at.
ObjectIDid
The unitID or featureID.
integercmd
The current command ID.
Returns
integercmdID
The command ID to use as the default, or nil to keep the current ID.

Callins:DrawGenesis (function) view source

Use this callin to update textures, shaders, etc.

Doesn’t render to screen! Also available to LuaMenu.

Callins:DrawGenesis() -> nil

Callins:DrawWorld (function) view source

Spring draws command queues, ‘map stuff’, and map marks.
Callins:DrawWorld() -> nil

Callins:DrawWorldPreUnit (function) view source

Spring draws units, features, some water types, cloaked units, and the sun.
Callins:DrawWorldPreUnit() -> nil

Callins:DrawPreDecals (function) view source

Called before decals are drawn
Callins:DrawPreDecals() -> nil

Callins:DrawWaterPost (function) view source 

Callins:DrawWaterPost() -> nil

Callins:DrawShadowPassTransparent (function) view source

Invoked after semi-transparent shadows pass is about to conclude

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.

Callins:DrawShadowPassTransparent() -> nil

Callins:DrawWorldShadow (function) view source 

Callins:DrawWorldShadow() -> nil

Callins:DrawWorldReflection (function) view source 

Callins:DrawWorldReflection() -> nil

Callins:DrawWorldRefraction (function) view source 

Callins:DrawWorldRefraction() -> nil

Callins:DrawGroundPreForward (function) view source

Runs at the start of the forward pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).
Callins:DrawGroundPreForward() -> nil

Callins:DrawGroundPostForward (function) view source 

Callins:DrawGroundPostForward() -> nil

Callins:DrawGroundPreDeferred (function) view source

Runs at the start of the deferred pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).
Callins:DrawGroundPreDeferred() -> nil

Callins:DrawGroundDeferred (function) view source 

Callins:DrawGroundDeferred() -> nil

Callins:DrawGroundPostDeferred (function) view source

This runs at the end of its respective deferred pass.

Allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and DrawWorldPreUnit) via gl.CopyToTexture.

Callins:DrawGroundPostDeferred() -> nil

Callins:DrawUnitsPostDeferred (function) view source

Runs at the end of the unit deferred pass.

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.

Callins:DrawUnitsPostDeferred() -> nil

Callins:DrawFeaturesPostDeferred (function) view source

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.
Callins:DrawFeaturesPostDeferred() -> nil

Callins:DrawShadowUnitsLua (function) view source 

Callins:DrawShadowUnitsLua() -> nil

Callins:DrawShadowFeaturesLua (function) view source 

Callins:DrawShadowFeaturesLua() -> nil

Callins:DrawBuildSquare (function) view source

Called when build square data is computed, before engine rendering. Grid dimensions can be inferred from UnitDefs[unitDefID].xsize and UnitDefs[unitDefID].zsize. Grid origin in square coords: x - xsize/2, z - zsize/2 (accounting for facing).
Callins:DrawBuildSquare(UnitDefID, integer, integer, number, table) -> nil
Parameters
UnitDefIDunitDefID
integerx
build position x
integerz
build position z
numberfacing
build facing
tablestatuses
flat 1D row-major array of BuildSquareStatus values: BLOCKED=0, OCCUPIED=1, RECLAIMABLE=2, OPEN=3

Callins:DrawWorldPreParticles (function) view source

DrawWorldPreParticles is called multiples times per draw frame. Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction.
Callins:DrawWorldPreParticles(boolean, boolean, boolean, boolean) -> nil
Parameters
booleandrawAboveWater
booleandrawBelowWater
booleandrawReflection
booleandrawRefraction

Callins:DrawScreen (function) view source

Also available to LuaMenu.
Callins:DrawScreen(integer, integer) -> nil
Parameters
integerviewSizeX
integerviewSizeY

Callins:DrawScreenEffects (function) view source 

Callins:DrawScreenEffects(integer, integer) -> nil
Parameters
integerviewSizeX
integerviewSizeY

Callins:DrawScreenPost (function) view source

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).

Note: This callin is invoked after the software rendered cursor (configuration variable HardwareCursor=0) is drawn.

Callins:DrawScreenPost(integer, integer) -> nil
Parameters
integerviewSizeX
integerviewSizeY

Callins:DrawInMiniMap (function) view source 

Callins:DrawInMiniMap(integer, integer) -> nil
Parameters
integersx
relative to the minimap’s position and scale.
integersy
relative to the minimap’s position and scale.

Callins:DrawInMiniMapBackground (function) view source 

Callins:DrawInMiniMapBackground(integer, integer) -> nil
Parameters
integersx
relative to the minimap’s position and scale.
integersy
relative to the minimap’s position and scale.

Callins:GameProgress (function) view source

Called every 60 frames, calculating delta between GameFrame and GameProgress.

Can give an ETA about catching up with simulation for mid-game join players.

Callins:GameProgress(integer) -> nil
Parameters
integerserverFrameNum

Callins:KeyBindingsChanged (function) view source

Called after a keybinding command runs.

Called when:

  • A keybinding command runs, e.g. bind k action. This may fire even when nothing actually changed (e.g. a redundant bind), so treat it as “a binding command ran”, not a guarantee that bindings differ. An operation covering multiple keybindings fires a single event at the end, e.g. keyreload.
  • Any operation that changes how actions are retrieved from input triggers happened, e.g. fakemeta space.

Nothing is passed; call Spring.GetKeyBindings to read the current state.

Callins:KeyBindingsChanged() -> nil

Callins:KeyMapChanged (function) view source

Called when the keymap changes

Can be caused due to a change in language or keyboard

Callins:KeyMapChanged() -> nil

Callins:KeyPress (function) view source

Called repeatedly when a key is pressed down.

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.

Callins:KeyPress(integer, KeyModifiers, boolean, string, integer, integer, table?) -> boolean
Parameters
integerkeyCode
KeyModifiersmods
booleanisRepeat
If you want an action to occur only once check for isRepeat == false.
stringlabel
the name of the key
integerutf32char
(deprecated) always 0
integerscanCode
table?actionList
the list of actions for this keypress, when available
Returns
booleanhalt
whether to halt the chain for consumers of the keypress

Callins:KeyRelease (function) view source

Called when the key is released.
Callins:KeyRelease(integer, KeyModifiers, string, integer, integer, table?) -> boolean
Parameters
integerkeyCode
KeyModifiersmods
stringlabel
the name of the key
integerutf32char
(deprecated) always 0
integerscanCode
table?actionList
the list of actions for this keyrelease, when available
Returns
boolean

Callins:TextInput (function) view source

Called whenever a key press results in text input.
Callins:TextInput(string) -> nil
Parameters
stringutf8char

Callins:TextEditing (function) view source 

Callins:TextEditing(string, integer, integer) -> nil
Parameters
stringutf8
integerstart
integerlength

Callins:MousePress (function) view source

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.

Callins:MousePress(integer, integer, integer) -> boolean
Parameters
integerx
integery
integerbutton
Returns
booleanbecomeMouseOwner

Callins:MouseRelease (function) view source

Called when a mouse button is released.

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.

Callins:MouseRelease(integer, integer, integer) -> boolean
Parameters
integerx
integery
integerbutton
Returns
booleanbecomeMouseOwner

Callins:MouseMove (function) view source

Called when the mouse is moved.
Callins:MouseMove(integer, integer, integer, integer, integer) -> nil
Parameters
integerx
final x position
integery
final y position
integerdx
distance travelled in x
integerdy
distance travelled in y
integerbutton

Callins:MouseWheel (function) view source

Called when the mouse wheel is moved.
Callins:MouseWheel(boolean, number) -> nil
Parameters
booleanup
the direction
numbervalue
the amount travelled

Callins:IsAbove (function) view source

Called every Update.

Must return true for Mouse* events and Spring.GetToolTip to be called.

Callins:IsAbove(integer, integer) -> boolean
Parameters
integerx
integery
Returns
booleanisAbove

Callins:GetTooltip (function) view source

Called when Spring.IsAbove returns true.
Callins:GetTooltip(integer, integer) -> string
Parameters
integerx
integery
Returns
stringtooltip

Callins:ActiveCommandChanged (function) view source

Called when a command is issued.
Callins:ActiveCommandChanged(integer?, integer?) -> nil
Parameters
integer?cmdId
integer?cmdType

Callins:CameraRotationChanged (function) view source

Called whenever the camera rotation changes
Callins:CameraRotationChanged(number, number, number) -> nil
Parameters
numberrotX
Camera rotation around the x axis in radians.
numberrotY
Camera rotation around the y axis in radians.
numberrotZ
Camera rotation around the z axis in radians.

Callins:CameraPositionChanged (function) view source

Called whenever the camera position changes
Callins:CameraPositionChanged(number, number, number) -> nil
Parameters
numberposX
Camera position x in world coordinates
numberposY
Camera position y in world coordinates
numberposZ
Camera position z in world coordinates

Callins:MiniMapRotationChanged (function) view source

Called when the MiniMap rotation changes
Callins:MiniMapRotationChanged(number, number) -> nil
Parameters
numbernewRot
MiniMap rotation in radians
numberoldRot
MiniMap old rotation in radians

Callins:MiniMapStateChanged (function) view source

Called when the MiniMap minimizes or maximizes changes
Callins:MiniMapStateChanged(boolean, boolean, boolean) -> nil
Parameters
booleanisMinimized
booleanisMaximized
booleanisSlaved

Callins:MiniMapGeometryChanged (function) view source

Called when the MiniMap Geometry changes
Callins:MiniMapGeometryChanged(integer, integer, integer, integer, integer, integer, integer, integer) -> nil
Parameters
integernewPosX
New x position in pixels.
integernewPosY
New y position in pixels.
integernewDimX
New width in pixels.
integernewDimY
New height in pixels.
integeroldPosX
Old x position in pixels.
integeroldPosY
Old y position in pixels.
integeroldDimX
Old width in pixels.
integeroldDimY
Old height in pixels.

Callins:CommandNotify (function) view source

Called when a command is issued.
Callins:CommandNotify(integer, table, CommandOptions) -> boolean
Parameters
integercmdID
tablecmdParams
CommandOptionsoptions
Returns
booleandelete
Returning true deletes the command and does not send it through the network.

Callins:AllowQuit (function) view source

Called when the window is about to be closed (close button, Alt+F4, or a quit request from the OS).

Every unsynced handle is asked and one false is enough to keep the game running. Spring.Quit and /quitforce do not ask, so a game that vetoed can still quit later and the user can always force an exit. One click can trigger this twice, once per SDL event. Not asked while the game is still loading, so LuaIntro never receives it.

Callins:AllowQuit() -> boolean
Returns
booleanallow
false keeps the game running

Callins:AddConsoleLine (function) view source

Called when text is entered into the console (e.g. Spring.Echo).
Callins:AddConsoleLine(string, integer) -> nil
Parameters
stringmsg
integerpriority

Callins:GroupChanged (function) view source

Called when a unit is added to or removed from a control group.
Callins:GroupChanged(GroupID) -> nil
Parameters
GroupIDgroupID

Callins:WorldTooltip (function) view source 

Callins:WorldTooltip("unit", UnitID) -> string
Parameters
"unit"type
UnitIDunitId
Returns
stringtooltip

Callins:WorldTooltip (function overload 1) view source 

Callins:WorldTooltip("feature", FeatureID) -> string
Parameters
"feature"type
FeatureIDfeatureId
Returns
stringtooltip

Callins:WorldTooltip (function overload 2) view source 

Callins:WorldTooltip("ground", number, number, number) -> string
Parameters
"ground"type
numberposX
numberposY
numberposZ
Returns
stringtooltip

Callins:WorldTooltip (function overload 3) view source 

Callins:WorldTooltip("selection") -> string
Parameters
"selection"type
Returns
stringtooltip

Callins:MapDrawCmd (function) view source 

Callins:MapDrawCmd(PlayerID, "point", number, number, number, string) -> nil
Parameters
PlayerIDplayerID
"point"type
numberposX
numberposY
numberposZ
stringlabel

Callins:MapDrawCmd (function overload 1) view source 

Callins:MapDrawCmd(PlayerID, "line", number, number, number, number, number, number) -> nil
Parameters
PlayerIDplayerID
"line"type
numberpos1X
numberpos1Y
numberpos1Z
numberpos2X
numberpos2Y
numberpos2Z

Callins:MapDrawCmd (function overload 2) view source 

Callins:MapDrawCmd(PlayerID, "erase", number, number, number, number) -> nil
Parameters
PlayerIDplayerID
"erase"type
numberposX
numberposY
numberposZ
numberradius

Callins:GameSetup (function) view source

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.

Callins:GameSetup(READY_MESSAGE, boolean, table<PlayerID,READY_STATE>) -> boolean?, boolean?
Parameters
READY_MESSAGEstate
the current message the engine would display to the player
booleanready
whether the player is currently ready or not
table<PlayerID,READY_STATE>playerStates
indexed by playerID
Returns
boolean?gameHandled
disables the engine ui when true
boolean?newReady
whether the player is ready (ignored unless gameHandled = true)

Callins:RecvSkirmishAIMessage (function) view source 

Callins:RecvSkirmishAIMessage(TeamID, string) -> nil
Parameters
TeamIDaiTeam
stringdataStr

Callins:DownloadQueued (function) view source

Called when a Pr-downloader download is queued
Callins:DownloadQueued(integer, string, string) -> nil
Parameters
integerid
stringname
stringtype

Callins:DownloadStarted (function) view source

Called when a Pr-downloader download is started via VFS.DownloadArchive.
Callins:DownloadStarted(integer) -> nil
Parameters
integerid

Callins:DownloadFinished (function) view source

Called when a Pr-downloader download finishes successfully.
Callins:DownloadFinished(integer) -> nil
Parameters
integerid

Callins:DownloadFailed (function) view source

Called when a Pr-downloader download fails to complete.
Callins:DownloadFailed(integer, integer) -> nil
Parameters
integerid
integererrorID

Callins:DownloadProgress (function) view source

Called incrementally during a Pr-downloader download.
Callins:DownloadProgress(integer, integer, integer) -> nil
Parameters
integerid
integerdownloaded
integertotal

SyncedCallins (class) view source

Functions called by the Engine (Synced).

Members

SyncedCallins:CommandFallback (function) view source

Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine).
SyncedCallins:CommandFallback(UnitID, UnitDefID, TeamID, integer, number[], CommandOptions, integer) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
integercmdID
number[]cmdParams
CommandOptionscmdOptions
integercmdTag
Returns
booleanremoveCmd
whether to remove the command from the queue

SyncedCallins:AllowCommand (function) view source

Called when the command is given, before the unit’s queue is altered.

The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.

SyncedCallins:AllowCommand(UnitID, UnitDefID, TeamID, integer, number[], CommandOptions, integer, boolean, boolean) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
integercmdID
number[]cmdParams
CommandOptionscmdOptions
integercmdTag
booleansynced
booleanfromLua
Returns
booleanallowCmd
whether it should be let into the queue.

SyncedCallins:AllowUnitCreation (function) view source

Called just before unit is created.
SyncedCallins:AllowUnitCreation(UnitDefID, UnitID, TeamID, number, number, number, FacingInteger) -> boolean, boolean
Parameters
UnitDefIDunitDefID
UnitIDbuilderID
TeamIDbuilderTeam
numberx
numbery
numberz
FacingIntegerfacing
Returns
booleanallow
booleandropOrder

SyncedCallins:AllowUnitTransfer (function) view source

Called just before a unit is transferred to a different team.
SyncedCallins:AllowUnitTransfer(UnitID, UnitDefID, TeamID, TeamID, boolean) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDoldTeam
TeamIDnewTeam
booleancapture
Returns
booleanallow
whether or not the transfer is permitted.

SyncedCallins:AllowUnitBuildStep (function) view source

Called just before a unit progresses its build percentage.
SyncedCallins:AllowUnitBuildStep(UnitID, TeamID, UnitID, UnitDefID, number) -> boolean
Parameters
UnitIDbuilderID
TeamIDbuilderTeam
UnitIDunitID
UnitDefIDunitDefID
numberpart
Returns
booleanallow
whether or not the build makes progress.

SyncedCallins:AllowUnitCaptureStep (function) view source 

SyncedCallins:AllowUnitCaptureStep(UnitID, TeamID, UnitID, UnitDefID, number) -> boolean
Parameters
UnitIDbuilderID
TeamIDbuilderTeam
UnitIDunitID
UnitDefIDunitDefID
numberpart
Returns
booleanallow
whether or not the capture makes progress.

SyncedCallins:AllowUnitTransport (function) view source 

SyncedCallins:AllowUnitTransport(UnitID, UnitDefID, TeamID, UnitID, UnitDefID, TeamID) -> boolean
Parameters
UnitIDtransporterID
UnitDefIDtransporterUnitDefID
TeamIDtransporterTeam
UnitIDtransporteeID
UnitDefIDtransporteeUnitDefID
TeamIDtransporteeTeam
Returns
booleanallow
whether or not the transport is allowed

SyncedCallins:AllowUnitTransportLoad (function) view source 

SyncedCallins:AllowUnitTransportLoad(UnitID, UnitDefID, TeamID, UnitID, UnitDefID, TeamID, number, number, number) -> boolean
Parameters
UnitIDtransporterID
UnitDefIDtransporterUnitDefID
TeamIDtransporterTeam
UnitIDtransporteeID
UnitDefIDtransporteeUnitDefID
TeamIDtransporteeTeam
numberx
numbery
numberz
Returns
booleanallow
whether or not the transport load is allowed

SyncedCallins:AllowUnitTransportUnload (function) view source 

SyncedCallins:AllowUnitTransportUnload(UnitID, UnitDefID, TeamID, UnitID, UnitDefID, TeamID, number, number, number) -> boolean
Parameters
UnitIDtransporterID
UnitDefIDtransporterUnitDefID
TeamIDtransporterTeam
UnitIDtransporteeID
UnitDefIDtransporteeUnitDefID
TeamIDtransporteeTeam
numberx
numbery
numberz
Returns
booleanallow
whether or not the transport unload is allowed

SyncedCallins:AllowUnitCloak (function) view source 

SyncedCallins:AllowUnitCloak(UnitID, UnitID?) -> boolean
Parameters
UnitIDunitID
UnitID?enemyID
Returns
booleanallow
whether unit is allowed to cloak

SyncedCallins:AllowUnitDecloak (function) view source 

SyncedCallins:AllowUnitDecloak(UnitID, ObjectID?, integer?) -> boolean
Parameters
UnitIDunitID
ObjectID?objectID
integer?weaponNum
Returns
booleanallow
whether unit is allowed to decloak

SyncedCallins:AllowUnitKamikaze (function) view source 

SyncedCallins:AllowUnitKamikaze(UnitID, UnitID) -> boolean
Parameters
UnitIDunitID
UnitIDtargetID
Returns
booleanallow
whether unit is allowed to selfd

SyncedCallins:AllowFeatureCreation (function) view source

Called just before feature is created.
SyncedCallins:AllowFeatureCreation(FeatureDefID, TeamID, number, number, number) -> boolean
Parameters
FeatureDefIDfeatureDefID
TeamIDteamID
numberx
numbery
numberz
Returns
booleanallow
whether or not the creation is permitted

SyncedCallins:AllowFeatureBuildStep (function) view source

Called just before a feature changes its build percentage.

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.

SyncedCallins:AllowFeatureBuildStep(UnitID, TeamID, FeatureID, FeatureDefID, number) -> boolean
Parameters
UnitIDbuilderID
TeamIDbuilderTeam
FeatureIDfeatureID
FeatureDefIDfeatureDefID
numberpart
Returns
booleanallow
whether or not the change is permitted

SyncedCallins:AllowResourceLevel (function) view source

Called when a team sets the sharing level of a resource.
SyncedCallins:AllowResourceLevel(TeamID, string, number) -> boolean
Parameters
TeamIDteamID
stringres
numberlevel
Returns
booleanallow
whether or not the sharing level is permitted

SyncedCallins:AllowResourceTransfer (function) view source

Called just before resources are transferred between players.
SyncedCallins:AllowResourceTransfer(TeamID, TeamID, string, number) -> boolean
Parameters
TeamIDoldTeamID
TeamIDnewTeamID
stringres
numberamount
Returns
booleanallow
whether or not the transfer is permitted.

SyncedCallins:ResourceExcess (function) view source

Called when excess resources are added. Accumulates all excesses within a single gameframe.
SyncedCallins:ResourceExcess(table) -> boolean
Parameters
tableexcesses
Returns
booleanhandled
whether or not Lua handled the event

SyncedCallins:AllowDirectUnitControl (function) view source

Determines if this unit can be controlled directly in FPS view.
SyncedCallins:AllowDirectUnitControl(UnitID, UnitDefID, TeamID, PlayerID) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
PlayerIDplayerID
Returns
booleanallow

SyncedCallins:AllowBuilderHoldFire (function) view source

Called when a construction unit wants to “use his nano beams”.

action is one of the following:

SyncedCallins:AllowBuilderHoldFire(UnitID, UnitDefID, (-1|CMD)) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
(-1|CMD)action
The action the builder wants to perform.
Returns
booleanactionAllowed

SyncedCallins:AllowStartPosition (function) view source

Whether a start position should be allowed

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.
  
SyncedCallins:AllowStartPosition(PlayerID, TeamID, integer, number, number, number, number, number, number) -> boolean
Parameters
PlayerIDplayerID
TeamIDteamID
integerreadyState
numberclampedX
numberclampedY
numberclampedZ
numberrawX
numberrawY
numberrawZ
Returns
booleanallow

SyncedCallins:MoveCtrlNotify (function) view source

Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.
SyncedCallins:MoveCtrlNotify(UnitID, UnitDefID, TeamID, integer) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
integerdata
was supposed to indicate the type of notification but currently never has a value other than 1 (“unit hit the ground”).
Returns
booleanengineControl
whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true).

SyncedCallins:TerraformComplete (function) view source

Called when pre-building terrain levelling terraforms are completed (c.f. levelGround)
SyncedCallins:TerraformComplete(UnitID, UnitDefID, TeamID, UnitID, UnitDefID, TeamID) -> boolean
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
UnitIDbuildUnitID
UnitDefIDbuildUnitDefID
TeamIDbuildUnitTeam
Returns
booleanstop
if true the current build order is terminated

SyncedCallins:UnitPreDamaged (function) view source

Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.

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

SyncedCallins:UnitPreDamaged(UnitID, UnitDefID, TeamID, number, boolean, DamageWeaponDefID?, ProjectileID?, UnitID?, UnitDefID?, TeamID?) -> number, number
Parameters
UnitIDunitID
UnitDefIDunitDefID
TeamIDunitTeam
numberdamage
booleanparalyzer
DamageWeaponDefID?weaponDefID
Synced Only
ProjectileID?projectileID
Synced Only
UnitID?attackerID
Synced Only
UnitDefID?attackerDefID
Synced Only
TeamID?attackerTeam
Synced Only
Returns
numbernewDamage
numberimpulseMult

SyncedCallins:FeaturePreDamaged (function) view source

Called before damage is applied to the feature.

Allows fine control over how much damage and impulse is applied.

SyncedCallins:FeaturePreDamaged(FeatureID, FeatureDefID, TeamID, number, DamageWeaponDefID, ProjectileID, UnitID, UnitDefID, TeamID) -> number, number
Parameters
FeatureIDfeatureID
FeatureDefIDfeatureDefID
TeamIDfeatureTeam
numberdamage
DamageWeaponDefIDweaponDefID
ProjectileIDprojectileID
UnitIDattackerID
UnitDefIDattackerDefID
TeamIDattackerTeam
Returns
numbernewDamage
numberimpulseMult

SyncedCallins:ShieldPreDamaged (function) view source

Called before any engine shield-vs-projectile logic executes.
SyncedCallins:ShieldPreDamaged(ProjectileID, UnitID, integer, UnitID, boolean, integer?, UnitID?, number, number, number, number, number, number) -> boolean
Parameters
ProjectileIDprojectileID
-1 when the weapon type is BeamLaser or LightningCannon
UnitIDprojectileOwnerID
-1 when the weapon type is BeamLaser or LightningCannon
integershieldWeaponNum
UnitIDshieldCarrierID
booleanbounceProjectile
integer?beamEmitterWeaponNum
present only when the weapon type is BeamLaser or LightningCannon
UnitID?beamEmitterUnitID
present only when the weapon type is BeamLaser or LightningCannon
numberstartX
numberstartY
numberstartZ
numberhitX
numberhitY
numberhitZ
Returns
booleanhandle
if true the gadget handles the collision event and the engine does not remove the projectile

SyncedCallins:AllowWeaponTargetCheck (function) view source

Determines if this weapon can automatically generate targets itself. See also commandFire weaponDef tag.

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

See Script.SetWatchAllowTarget, Script.SetWatchWeapon

SyncedCallins:AllowWeaponTargetCheck(UnitID, integer, WeaponDefID) -> boolean, boolean
Parameters
UnitIDattackerID
integerattackerWeaponNum
WeaponDefIDattackerWeaponDefID
Returns
booleanallowCheck
booleanignoreCheck

SyncedCallins:AllowWeaponTarget (function) view source

Controls blocking of a specific target from being considered during a weapon’s periodic auto-targeting sweep.

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

See Script.SetWatchAllowTarget, Script.SetWatchWeapon

SyncedCallins:AllowWeaponTarget(UnitID, UnitID, integer, WeaponDefID, number) -> boolean, number
Parameters
UnitIDattackerID
UnitIDtargetID
integerattackerWeaponNum
WeaponDefIDattackerWeaponDefID
numberdefPriority
Returns
booleanallowed
numbernewPriority
The new priority for this target (if you don’t want to change it, return defPriority). Lower priority targets are targeted first.

SyncedCallins:AllowWeaponInterceptTarget (function) view source

Controls blocking of a specific intercept target from being considered during an interceptor weapon’s periodic auto-targeting sweep.

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

See Script.SetWatchAllowTarget, Script.SetWatchWeapon

SyncedCallins:AllowWeaponInterceptTarget(UnitID, integer, ProjectileID) -> boolean
Parameters
UnitIDinterceptorUnitID
integerinterceptorWeaponID
ProjectileIDtargetProjectileID
Returns
booleanallowed

SyncedCallins.SendToUnsynced (function) view source

Invoke UnsyncedCallins:RecvFromSynced callin with the given 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.

See UnsyncedCallins:RecvFromSynced

SyncedCallins.SendToUnsynced([(table|boolean|string|number)?, ]*) -> nil
Parameters
(table|boolean|string|number)?...
Arguments.

UnsyncedCallins (class) view source

Functions called by the Engine (Unsynced).

Members

UnsyncedCallins:RecvFromSynced (function) view source

Receives data sent via SendToUnsynced callout.
UnsyncedCallins:RecvFromSynced([any, ]*) -> nil
Parameters
any...

UnsyncedCallins:DrawUnit (function) view source

For custom rendering of units

Deprecated

UnsyncedCallins:DrawUnit(UnitID, integer) -> boolean
Parameters
UnitIDunitID
integerdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawFeature (function) view source

For custom rendering of features

Deprecated

UnsyncedCallins:DrawFeature(FeatureID, integer) -> boolean
Parameters
FeatureIDfeatureID
integerdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawShield (function) view source

For custom rendering of shields.

Deprecated

UnsyncedCallins:DrawShield(UnitID, integer, integer) -> boolean
Parameters
UnitIDunitID
integerweaponID
integerdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawProjectile (function) view source

For custom rendering of weapon (& other) projectiles

Deprecated

UnsyncedCallins:DrawProjectile(ProjectileID, integer) -> boolean
Parameters
ProjectileIDprojectileID
integerdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawMaterial (function) view source

Deprecated

UnsyncedCallins:DrawMaterial(integer, integer) -> boolean
Parameters
integeruuid
integerdrawMode
Returns
booleansuppressEngineDraw

gl (table) view source

Callouts for OpenGL API

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

See GL

Members

gl.GetShaderLog (function) view source

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.
gl.GetShaderLog() -> string
Returns
stringinfoLog

gl.CreateShader (function) view source

Create a shader.
gl.CreateShader(ShaderParams) -> integer
Parameters
ShaderParamsshaderParams
Returns
integershaderID

gl.DeleteShader (function) view source

Deletes a shader identified by shaderID
gl.DeleteShader(integer) -> boolean?
Parameters
integershaderID
Returns
boolean?deleted
nil if shaderID is nil.

gl.UseShader (function) view source

Binds a shader program identified by shaderID. Pass 0 to disable the shader. Returns whether the shader was successfully bound.
gl.UseShader(integer) -> boolean
Parameters
integershaderID
Returns
booleanlinked

gl.ActiveShader (function) view source

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.)!

gl.ActiveShader(integer, function, [any, ]*) -> nil
Parameters
integershaderID
functionfunc
any...
Arguments

gl.GetActiveUniforms (function) view source

Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, …).
gl.GetActiveUniforms(integer) -> ActiveUniform[]
Parameters
integershaderID
Returns
ActiveUniform[]activeUniforms

gl.GetUniformLocation (function) view source

Returns the locationID of a shaders uniform. Needed for changing uniform values with function gl.Uniform.
gl.GetUniformLocation(integer, string) -> GL
Parameters
integershaderID
stringname
Returns
GLlocationID

gl.GetSubroutineIndex (function) view source

Returns the subroutine index for a shader program.
gl.GetSubroutineIndex(integer, integer, string) -> integer?
Parameters
integershaderID
integershaderType
stringname
Returns
integer?index
Returns no value when shader support is unavailable or shaderID is invalid.

gl.SetUnitBufferUniforms (function) view source

Writes user-defined model uniforms for a unit.
gl.SetUnitBufferUniforms(UnitID, number[], integer?) -> integer
Parameters
UnitIDunitID
number[]values
integer?offset
Returns
integercount

gl.SetFeatureBufferUniforms (function) view source

Writes user-defined model uniforms for a feature.
gl.SetFeatureBufferUniforms(FeatureID, number[], integer?) -> integer
Parameters
FeatureIDfeatureID
number[]values
integer?offset
Returns
integercount

gl.Uniform (function) view source

Sets the uniform float value at the locationID for the currently active shader. Shader must be activated before setting uniforms.
gl.Uniform((GL|string), number, number?, number?, number?) -> nil
Parameters
(GL|string)locationID
uniformName
numberf1
number?f2
number?f3
number?f4

gl.UniformFloat (function) view source

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

Alias of Uniform

gl.UniformFloat((GL|string), number, number?, number?, number?) -> nil
Parameters
(GL|string)locationID
uniformName
numberf1
number?f2
number?f3
number?f4

gl.UniformInt (function) view source

Sets the uniform int value at the locationID for the currently active shader. Shader must be activated before setting uniforms.
gl.UniformInt((string|integer), integer, integer?, integer?, integer?) -> nil
Parameters
(string|integer)locationID
uniformName
integerint1
integer?int2
integer?int3
integer?int4

gl.UniformArray (function) view source

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

Shader must be activated before setting uniforms.

gl.UniformArray((string|integer), UniformArrayType, number[]) -> nil
Parameters
(string|integer)locationID
uniformName
UniformArrayTypetype
number[]uniforms
Array up to 1024 elements

gl.UniformMatrix (function) view source

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.

gl.UniformMatrix((string|integer), MatrixName) -> nil
Parameters
(string|integer)locationID
uniformName
MatrixNamematrix
Name of common matrix.

gl.UniformMatrix (function overload 1) view source

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.

gl.UniformMatrix((string|integer), number[]) -> nil
Parameters
(string|integer)locationID
uniformName
number[]matrix
A 2x2, 3x3 or 4x4 matrix.

gl.UniformSubroutine (function) view source

Selects a subroutine for the active shader program.
gl.UniformSubroutine(integer, integer) -> nil
Parameters
integershaderType
integerindex

gl.GetEngineUniformBufferDef (function) view source

Return the GLSL compliant definition of UniformMatricesBuffer(idx=0) or UniformParamsBuffer(idx=1) structure.
gl.GetEngineUniformBufferDef(integer) -> string
Parameters
integerindex
Returns
stringglslDefinition

gl.GetEngineModelUniformDataDef (function) view source

Return the GLSL compliant definition of ModelUniformData structure (per Unit/Feature buffer available on GPU)
gl.GetEngineModelUniformDataDef(integer) -> string
Parameters
integerindex
Returns
stringglslDefinition

gl.GetEngineModelUniformDataSize (function) view source

Return the current size values of ModelUniformData structure (per Unit/Feature buffer available on GPU)
gl.GetEngineModelUniformDataSize(integer) -> integer, integer
Parameters
integerindex
Returns
integersizeInElements
integersizeInBytesOnCPU

gl.SetGeometryShaderParameter (function) view source

Sets the Geometry shader parameters for shaderID. Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri)
gl.SetGeometryShaderParameter(integer, GL, integer) -> nil
Parameters
integershaderID
GLkey
integervalue
Returns
nil

gl.SetTesselationShaderParameter (function) view source

Sets the tesselation shader parameters for shaderID.

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

gl.SetTesselationShaderParameter(integer, integer) -> nil
Parameters
integerparam
integervalue
Returns
nil

gl.LoadFont (function) view source

Load a font from a file.
gl.LoadFont(string, integer?, integer?, number?) -> LuaFont
Parameters
stringfontFile
integer?size
integer?outlineWidth
number?outlineWeight
Returns
LuaFontfont

gl.DeleteFont (function) view source

Delete a font object.
gl.DeleteFont(LuaFont) -> nil
Parameters
LuaFontfont

gl.AddFallbackFont (function) view source

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).

gl.AddFallbackFont(string) -> boolean
Parameters
stringfilePath
VFS path to the file, for example “fonts/myfont.ttf”. Uses VFS.RAW_FIRST access mode.
Returns
booleansuccess

gl.ClearFallbackFonts (function) view source

Clears all fallback fonts.

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

gl.ClearFallbackFonts() -> nil
Returns
nil

gl.GetVAO (function) view source

Example: local myVAO = gl.GetVAO() if myVAO == nil then Spring.Echo(“Failed to get VAO”) end 
gl.GetVAO() -> VAO?
Returns
VAO?vao
The VAO ref on success, else nil

gl.CreateRBO (function) view source 

gl.CreateRBO(integer, integer, CreateRBOData) -> RBO
Parameters
integerxsize
integerysize
CreateRBODatadata
Returns
RBO

gl.DeleteRBO (function) view source 

gl.DeleteRBO(RBO) -> nil
Parameters
RBOrbo

gl.HasExtension (function) view source 

gl.HasExtension(string) -> boolean
Parameters
stringext
Returns
boolean

gl.GetNumber (function) view source

Get the value or values of a selected parameter.
gl.GetNumber(GL, integer?) -> number ...
Parameters
GLpname
integer?count
(Default: 1) Number of values to return, in range [1, 64].
Returns
number ...

gl.GetString (function) view source

Get a string describing the current OpenGL connection.
gl.GetString(GL) -> string
Parameters
GLpname
Returns
stringvalue
"[NULL]" if the driver returns no string for pname.

gl.GetScreenViewTrans (function) view source 

gl.GetScreenViewTrans() -> number, number, number
Returns
numberx
numbery
numberz

gl.GetViewSizes (function) view source 

gl.GetViewSizes() -> integer, integer
Returns
integerx
integery

gl.GetViewRange (function) view source 

gl.GetViewRange() -> number, number, number, number
Returns
numbernearPlaneDist
numberfarPlaneDist
numberminViewRange
numbermaxViewRange

gl.SlaveMiniMap (function) view source 

gl.SlaveMiniMap(boolean) -> nil
Parameters
booleannewMode

gl.ConfigMiniMap (function) view source 

gl.ConfigMiniMap(integer, integer, integer, integer) -> nil
Parameters
integerpx
integerpy
integersx
integersy

gl.DrawMiniMap (function) view source 

gl.DrawMiniMap(boolean?) -> nil
Parameters
boolean?defaultTransform
(Default: true)

gl.DrawMiniMapIcons (function) view source

Draws all unit icons visible to the given perspective (as on the minimap: team colors, radar dots, LOS rules, ghost dimming) for a map-space rectangle, without involving the actual minimap.

The rectangle is mapped onto the unit square under the current transform: (left,top) -> (0,0), (right,bottom) -> (1,1). Callers position, scale, rotate or flip the result via their own matrices, e.g. inside gl.RenderToTexture. Blending, scissor and viewport state are left to the caller.

gl.DrawMiniMapIcons(number, number, number, number, number, integer?, boolean?, boolean?) -> nil
Parameters
numberleft
map-space rectangle edges in elmos; left < right and top < bottom (top = smaller z) are required, mirror via your own transform instead
numbertop
numberright
numberbottom
numbericonSize
base icon half-size in elmos, scaled per icon by its icontypes.lua size
integer?allyTeam
(Default: your allyTeam) perspective to render; other allyteams require a full-read handle
boolean?fullView
(Default: true when spectating in full view with a full-read handle) draw every unit at its true position; true requires a full-read handle, false is always allowed
boolean?highlightSelected
(Default: true) draw the local player’s selected units white. Other players’ selections are unknown to the engine — when rendering another perspective, pass false and overlay that viewer’s selection yourself

gl.BeginText (function) view source

Begin a block of text commands.

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 gl.BlendFunc, gl.BlendFuncSeparate

gl.BeginText(boolean?) -> nil
Parameters
boolean?userDefinedBlending
When true doesn’t set the gl.BlendFunc automatically. Defaults to false.

gl.EndText (function) view source 

gl.EndText() -> nil

gl.Text (function) view source

options is a 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)
gl.Text(string, number, number, number?, string?) -> nil
Parameters
stringtext
numberx
numbery
number?size
string?options
Concatenated string of option characters.
Returns
nil

gl.GetTextWidth (function) view source 

gl.GetTextWidth(string) -> number
Parameters
stringtext
Returns
numberwidth

gl.GetTextHeight (function) view source 

gl.GetTextHeight(string) -> number, number, integer
Parameters
stringtext
Returns
numberheight
numberdescender
integerlines

gl.Unit (function) view source

Draw the unit, applying transform.
gl.Unit(UnitID, boolean?, integer?, boolean?, boolean?) -> nil
Parameters
UnitIDunitID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: false) Skip the DrawUnit callin.
boolean?fullModel
(Default: true)

gl.UnitRaw (function) view source

Draw the unit without applying transform.

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

gl.UnitRaw(UnitID, boolean?, integer?, boolean?, boolean?) -> nil
Parameters
UnitIDunitID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: true) Skip the DrawUnit callin.
boolean?fullModel
(Default: true)

gl.UnitTextures (function) view source 

gl.UnitTextures(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanpush
If true, push the render state; if false, pop it.

gl.UnitShape (function) view source 

gl.UnitShape(UnitDefID, TeamID, boolean?, boolean?, boolean?) -> nil
Parameters
UnitDefIDunitDefID
TeamIDteamID
boolean?rawState
(Default: true)
boolean?toScreen
(Default: false)
boolean?opaque
(Default: true) If true, draw opaque; if false, draw alpha.

gl.UnitShapeTextures (function) view source 

gl.UnitShapeTextures(UnitDefID, boolean) -> nil
Parameters
UnitDefIDunitDefID
booleanpush
If true, push the render state; if false, pop it.

gl.UnitMultMatrix (function) view source 

gl.UnitMultMatrix(UnitID) -> nil
Parameters
UnitIDunitID

gl.UnitPiece (function) view source 

gl.UnitPiece(UnitID, integer) -> nil
Parameters
UnitIDunitID
integerpieceID

gl.UnitPieceMatrix (function) view source 

gl.UnitPieceMatrix(UnitID, integer) -> nil
Parameters
UnitIDunitID
integerpieceID

gl.UnitPieceMultMatrix (function) view source 

gl.UnitPieceMultMatrix(UnitID, integer) -> nil
Parameters
UnitIDunitID
integerpieceID

gl.Feature (function) view source

Draw the feature, applying transform.
gl.Feature(FeatureID, boolean?, integer?, boolean?) -> nil
Parameters
FeatureIDfeatureID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: false) Skip the DrawFeature callin.

gl.FeatureRaw (function) view source

Draw the unit without applying transform.

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

gl.FeatureRaw(FeatureID, boolean?, integer?, boolean?) -> nil
Parameters
FeatureIDfeatureID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: true) Skip the DrawFeature callin.

gl.FeatureTextures (function) view source 

gl.FeatureTextures(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleanpush
If true, push the render state; if false, pop it.

gl.FeatureShape (function) view source 

gl.FeatureShape(FeatureDefID, TeamID, boolean?, boolean?, boolean?) -> nil
Parameters
FeatureDefIDfeatureDefID
TeamIDteamID
boolean?rawState
(Default: true)
boolean?toScreen
(Default: false)
boolean?opaque
(Default: true) If true, draw opaque; if false, draw alpha.

gl.FeatureShapeTextures (function) view source 

gl.FeatureShapeTextures(FeatureDefID, boolean) -> nil
Parameters
FeatureDefIDfeatureDefID
booleanpush
If true, push the render state; if false, pop it.

gl.FeatureMultMatrix (function) view source 

gl.FeatureMultMatrix(FeatureID) -> nil
Parameters
FeatureIDfeatureID

gl.FeaturePiece (function) view source 

gl.FeaturePiece(FeatureID, integer) -> nil
Parameters
FeatureIDfeatureID
integerpieceID

gl.FeaturePieceMatrix (function) view source 

gl.FeaturePieceMatrix(FeatureID, integer) -> nil
Parameters
FeatureIDfeatureID
integerpieceID

gl.FeaturePieceMultMatrix (function) view source 

gl.FeaturePieceMultMatrix(FeatureID, integer) -> nil
Parameters
FeatureIDfeatureID
integerpieceID

gl.DrawListAtUnit (function) view source 

gl.DrawListAtUnit(UnitID, integer, boolean?, number?, number?, number?, number?, number?, number?, number?) -> nil
Parameters
UnitIDunitID
integerlistIndex
boolean?useMidPos
(Default: true)
number?scaleX
(Default: 1.0)
number?scaleY
(Default: 1.0)
number?scaleZ
(Default: 1.0)
number?degrees
(Default: 0.0)
number?rotX
(Default: 0.0)
number?rotY
(Default: 1.0)
number?rotZ
(Default: 0.0)

gl.DrawFuncAtUnit (function) view source 

gl.DrawFuncAtUnit(UnitID, boolean?, fun(...), [any, ]*) -> nil
Parameters
UnitIDunitID
boolean?useMidPos
(Default: true)
fun(...)func
Function to call.
any...
Arguments passed to function.

gl.DrawGroundCircle (function) view source 

gl.DrawGroundCircle(number, number, number, number, integer) -> nil
Parameters
numberposX
numberposY
numberposZ
numberradius
integerresolution

gl.DrawGroundCircle (function overload 1) view source 

gl.DrawGroundCircle(number, number, number, number, integer, number, number?, WeaponDefID?) -> nil
Parameters
numberposX
numberposY
numberposZ
numberradius
integerresolution
numberslope
number?gravity
WeaponDefID?weaponDefID

gl.DrawGroundQuad (function) view source 

gl.DrawGroundQuad(number, number, number, number, nil, boolean?) -> nil
Parameters
numberx0
numberz0
numberx1
numberz1
niluseNorm
No longer used.
boolean?useTxcd
(Default: false)

gl.DrawGroundQuad (function overload 1) view source 

gl.DrawGroundQuad(number, number, number, number, nil, number, number, number, number) -> nil
Parameters
numberx0
numberz0
numberx1
numberz1
niluseNorm
No longer used.
numbertu0
numbertv0
numbertu1
numbertv1

gl.Shape (function) view source 

gl.Shape(GL, VertexData[]) -> nil
Parameters
GLtype
VertexData[]vertices

gl.BeginEnd (function) view source 

gl.BeginEnd(GL, fun(...), [any, ]*) -> nil
Parameters
GLprimMode
fun(...)func
Function to call.
any...
Arguments passed to function.

gl.Vertex (function) view source 

gl.Vertex(xy) -> nil
Parameters
xyv

gl.Vertex (function overload 1) view source 

gl.Vertex(xyz) -> nil
Parameters
xyzv

gl.Vertex (function overload 2) view source 

gl.Vertex(xyzw) -> nil
Parameters
xyzwv

gl.Vertex (function overload 3) view source 

gl.Vertex(number, number, number?, number?) -> nil
Parameters
numberx
numbery
number?z
number?w

gl.Normal (function) view source 

gl.Normal(xyz) -> nil
Parameters
xyzv

gl.Normal (function overload 1) view source 

gl.Normal(number, number, number) -> nil
Parameters
numberx
numbery
numberz

gl.TexCoord (function) view source 

gl.TexCoord((number)) -> nil
Parameters
(number)coord

gl.TexCoord (function overload 1) view source 

gl.TexCoord(xy) -> nil
Parameters
xycoord

gl.TexCoord (function overload 2) view source 

gl.TexCoord(xyz) -> nil
Parameters
xyzcoord

gl.TexCoord (function overload 3) view source 

gl.TexCoord(xyzw) -> nil
Parameters
xyzwcoord

gl.TexCoord (function overload 4) view source 

gl.TexCoord(number, number?, number?, number?) -> nil
Parameters
numbers
number?t
number?r
number?q

gl.MultiTexCoord (function) view source 

gl.MultiTexCoord(integer, (number)) -> nil
Parameters
integertexNum
(number)coord

gl.MultiTexCoord (function overload 1) view source 

gl.MultiTexCoord(integer, xy) -> nil
Parameters
integertexNum
xycoord

gl.MultiTexCoord (function overload 2) view source 

gl.MultiTexCoord(integer, xyz) -> nil
Parameters
integertexNum
xyzcoord

gl.MultiTexCoord (function overload 3) view source 

gl.MultiTexCoord(integer, xyzw) -> nil
Parameters
integertexNum
xyzwcoord

gl.MultiTexCoord (function overload 4) view source 

gl.MultiTexCoord(integer, number, number?, number?, number?) -> nil
Parameters
integertexNum
numbers
number?t
number?r
number?q

gl.SecondaryColor (function) view source 

gl.SecondaryColor(rgb) -> nil
Parameters
rgbcolor

gl.SecondaryColor (function overload 1) view source 

gl.SecondaryColor(number, number, number) -> nil
Parameters
numberr
numberg
numberb

gl.FogCoord (function) view source 

gl.FogCoord(number) -> nil
Parameters
numbercoord

gl.EdgeFlag (function) view source 

gl.EdgeFlag(boolean) -> nil
Parameters
booleanflag

gl.Rect (function) view source 

gl.Rect(number, number, number, number) -> nil
Parameters
numberx1
numbery1
numberx2
numbery2

gl.TexRect (function) view source 

gl.TexRect(number, number, number, number, boolean?, boolean?) -> nil
Parameters
numberx1
numbery1
numberx2
numbery2
boolean?flipSCoords
boolean?flipTCoords

gl.TexRect (function overload 1) view source 

gl.TexRect(number, number, number, number, number, number, number, number) -> nil
Parameters
numberx1
numbery1
numberx2
numbery2
numbers1
numbert1
numbers2
numbert2

gl.DispatchCompute (function) view source 

gl.DispatchCompute(integer?, integer, integer, integer?) -> nil
Parameters
integer?numGroupX
integernumGroupY
integernumGroupZ
integer?barriers
(Default: 0)

gl.MemoryBarrier (function) view source 

gl.MemoryBarrier(integer?) -> nil
Parameters
integer?barriers
(Default: 4)

gl.Color (function) view source 

gl.Color(number, number, number, number?) -> nil
Parameters
numberr
Red.
numberg
Green.
numberb
Blue.
number?a
(Default: 1.0) Alpha.

gl.Color (function overload 1) view source 

gl.Color(rgba) -> nil
Parameters
rgbacolor
Color with alpha.

gl.Color (function overload 2) view source 

gl.Color(rgb) -> nil
Parameters
rgbcolor
Color.

gl.Material (function) view source 

gl.Material(Material) -> nil
Parameters
Materialmaterial

gl.ResetState (function) view source 

gl.ResetState() -> nil

gl.ResetMatrices (function) view source 

gl.ResetMatrices() -> nil

gl.Lighting (function) view source 

gl.Lighting(boolean) -> nil
Parameters
booleanenable

gl.ShadeModel (function) view source 

gl.ShadeModel(GL) -> nil
Parameters
GLmodel

gl.Scissor (function) view source 

gl.Scissor(boolean) -> nil
Parameters
booleanenable

gl.Scissor (function overload 1) view source 

gl.Scissor(integer, integer, integer, integer) -> nil
Parameters
integerx
integery
integerw
integerh

gl.Viewport (function) view source 

gl.Viewport(integer, integer, integer, integer) -> nil
Parameters
integerx
integery
integerw
integerh

gl.ColorMask (function) view source

Enable or disable writing of frame buffer color components.
gl.ColorMask(boolean) -> nil
Parameters
booleanrgba

gl.ColorMask (function overload 1) view source

Enable or disable writing of frame buffer color components.
gl.ColorMask(boolean, boolean, boolean, boolean) -> nil
Parameters
booleanred
booleangreen
booleanblue
booleanalpha

gl.DepthMask (function) view source

Enable or disable writing into the depth buffer.
gl.DepthMask(boolean) -> nil
Parameters
booleanenable

gl.DepthTest (function) view source

Enable or disable depth test.
gl.DepthTest(boolean) -> nil
Parameters
booleanenable

gl.DepthTest (function overload 1) view source

Enable depth test and specify the depth comparison function.

depthFunction accepts GL.NEVER, GL.LESS, GL.EQUAL, GL.LEQUAL, GL.GREATER, GL.NOTEQUAL, GL.GEQUAL, and GL.ALWAYS.

gl.DepthTest(GL) -> nil
Parameters
GLdepthFunction
The depth comparison function.

gl.DepthClamp (function) view source 

gl.DepthClamp(boolean) -> nil
Parameters
booleanenable

gl.Culling (function) view source 

gl.Culling(boolean) -> nil
Parameters
booleanenable

gl.Culling (function overload 1) view source

Enable culling and set culling mode.

mode accepts GL.FRONT, GL.BACK, and GL.FRONT_AND_BACK.

gl.Culling(GL) -> nil
Parameters
GLmode
Whether front- or back-facing facets are candidates for culling.

gl.LogicOp (function) view source 

gl.LogicOp(boolean) -> nil
Parameters
booleanenable

gl.LogicOp (function overload 1) view source

Specify a logical pixel operation for rendering.

opCode accepts GL.CLEAR, GL.SET, GL.COPY, GL.COPY_INVERTED, GL.NOOP, GL.INVERT, GL.AND, GL.NAND, GL.OR, GL.NOR, GL.XOR, GL.EQUIV, GL.AND_REVERSE, GL.AND_INVERTED, GL.OR_REVERSE, and GL.OR_INVERTED.

gl.LogicOp(GL) -> nil
Parameters
GLopCode
The logical operation.

gl.Fog (function) view source 

gl.Fog(boolean) -> nil
Parameters
booleanenable

gl.Blending (function) view source 

gl.Blending(boolean) -> nil
Parameters
booleanenable

gl.Blending (function overload 1) view source 

gl.Blending(("add"|"alpha_add"|"alpha"|"reset"|"color"|"modulate"...)) -> nil
Parameters
("add"|"alpha_add"|"alpha"|"reset"|"color"|"modulate"...)mode

gl.Blending (function overload 2) view source 

gl.Blending(GL, GL) -> nil
Parameters
GLsrc
GLdst

gl.BlendEquation (function) view source 

gl.BlendEquation(GL) -> nil
Parameters
GLmode

gl.BlendFunc (function) view source 

gl.BlendFunc(GL, GL) -> nil
Parameters
GLsrc
GLdst

gl.BlendEquationSeparate (function) view source 

gl.BlendEquationSeparate(GL, GL) -> nil
Parameters
GLmodeRGB
GLmodeAlpha

gl.BlendFuncSeparate (function) view source 

gl.BlendFuncSeparate(GL, GL, GL, GL) -> nil
Parameters
GLsrcRGB
GLdstRGB
GLsrcAlpha
GLdstAlpha

gl.AlphaTest (function) view source 

gl.AlphaTest(boolean) -> nil
Parameters
booleanenable

gl.AlphaTest (function overload 1) view source

Specify the alpha test function.

func accepts GL.NEVER, GL.LESS, GL.EQUAL, GL.LEQUAL, GL.GREATER, GL.NOTEQUAL, GL.GEQUAL, and GL.ALWAYS.

ref is clamped to the range [0, 1], where 0 represents the lowest possible alpha value and 1 the highest possible value.

gl.AlphaTest(GL, number) -> nil
Parameters
GLfunc
The alpha comparison function.
numberref
The reference value that incoming alpha values are compared to.

gl.AlphaToCoverage (function) view source 

gl.AlphaToCoverage(boolean) -> nil
Parameters
booleanenable

gl.PolygonMode (function) view source

Select polygon rasterization mode.

face must be GL.FRONT for front-facing polygons, GL.BACK for back-facing polygons, or GL.FRONT_AND_BACK for front- and back-facing polygons.

mode accepts GL.POINT, GL.LINE, and GL.FILL.

gl.PolygonMode(GL, GL) -> nil
Parameters
GLface
The polygons that mode applies to.
GLmode
How the polygons will be rasterized.

gl.PolygonOffset (function) view source 

gl.PolygonOffset(boolean) -> nil
Parameters
booleanenable

gl.PolygonOffset (function overload 1) view source 

gl.PolygonOffset(number, number) -> nil
Parameters
numberfactor
Scale factor for a variable depth offset for each polygon.
numberunits
Multiplied by an implementation-specific value to create a constant depth offset.

gl.StencilTest (function) view source 

gl.StencilTest(boolean) -> nil
Parameters
booleanenable

gl.StencilMask (function) view source

Control the front and back writing of individual bits in the stencil planes.
gl.StencilMask(integer) -> nil
Parameters
integermask
Bit mask to enable and disable writing of individual bits in the stencil planes.

gl.StencilFunc (function) view source

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

func accepts GL.NEVER, GL.LESS, GL.EQUAL, GL.LEQUAL, GL.GREATER, GL.NOTEQUAL, GL.GEQUAL, and GL.ALWAYS.

ref is clamped to the range [0, 2^n - 1], where n is the number of bitplanes in the stencil buffer.

gl.StencilFunc(GL, integer, integer) -> nil
Parameters
GLfunc
The test function.
integerref
The reference value for the stencil test.
integermask
ANDed with both the reference value and the stored stencil value when the test is done.

gl.StencilOp (function) view source

Set front and back stencil test actions.

fail, zfail and zpass accept GL.KEEP, GL.ZERO, GL.REPLACE, GL.INCR, GL.INCR_WRAP, GL.DECR, GL.DECR_WRAP, and GL.INVERT.

zpass also applies when the stencil test passes and either there is no depth buffer or depth testing is not enabled.

gl.StencilOp(GL, GL, GL) -> nil
Parameters
GLfail
The action to take when the stencil test fails.
GLzfail
The action when the stencil test passes, but the depth test fails.
GLzpass
The action when both the stencil test and the depth test pass.

gl.StencilMaskSeparate (function) view source

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

face accepts GL.FRONT, GL.BACK, and GL.FRONT_AND_BACK.

gl.StencilMaskSeparate(GL, integer) -> nil
Parameters
GLface
Whether the front and/or back stencil writemask is updated.
integermask
Bit mask to enable and disable writing of individual bits in the stencil planes.

gl.StencilFuncSeparate (function) view source

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

face accepts GL.FRONT, GL.BACK, and GL.FRONT_AND_BACK.

func accepts GL.NEVER, GL.LESS, GL.EQUAL, GL.LEQUAL, GL.GREATER, GL.NOTEQUAL, GL.GEQUAL, and GL.ALWAYS.

ref is clamped to the range [0, 2^n - 1], where n is the number of bitplanes in the stencil buffer.

gl.StencilFuncSeparate(GL, GL, integer, integer) -> nil
Parameters
GLface
Whether front and/or back stencil state is updated.
GLfunc
The test function.
integerref
The reference value for the stencil test.
integermask
ANDed with both the reference value and the stored stencil value when the test is done.

gl.StencilOpSeparate (function) view source

Set front and/or back stencil test actions.

face accepts GL.FRONT, GL.BACK, and GL.FRONT_AND_BACK.

fail, zfail and zpass accept GL.KEEP, GL.ZERO, GL.REPLACE, GL.INCR, GL.INCR_WRAP, GL.DECR, GL.DECR_WRAP, and GL.INVERT.

zpass also applies when the stencil test passes and either there is no depth buffer or depth testing is not enabled.

gl.StencilOpSeparate(GL, GL, GL, GL) -> nil
Parameters
GLface
Whether front and/or back stencil state is updated.
GLfail
The action to take when the stencil test fails.
GLzfail
The action when the stencil test passes, but the depth test fails.
GLzpass
The action when both the stencil test and the depth test pass.

gl.LineStipple (function) view source 

gl.LineStipple(boolean) -> nil
Parameters
booleanenable

gl.LineStipple (function overload 1) view source 

gl.LineStipple(string) -> nil
Parameters
stringignoredString
The value of this string is ignored, but it still does something.

gl.LineStipple (function overload 2) view source 

gl.LineStipple(integer, integer, integer?) -> nil
Parameters
integerfactor
integerpattern
integer?shift

gl.LineWidth (function) view source 

gl.LineWidth(number) -> nil
Parameters
numberwidth

gl.PointSize (function) view source 

gl.PointSize(number) -> nil
Parameters
numbersize

gl.PointSprite (function) view source 

gl.PointSprite(boolean, boolean?, boolean?) -> nil
Parameters
booleanenable
boolean?enableCoordReplace
boolean?coordOrigin
true for upper left, false for lower left, otherwise no change.

gl.PointParameter (function) view source 

gl.PointParameter(number, number, number, number?, number?, number?) -> nil
Parameters
numberatten0
numberatten1
numberatten2
number?sizeMin
number?sizeMax
number?sizeFade

gl.Texture (function) view source 

gl.Texture(integer, boolean?) -> boolean
Parameters
integertexNum
boolean?enable
Returns
boolean

gl.Texture (function overload 1) view source 

gl.Texture(boolean) -> boolean
Parameters
booleanenable
Returns
boolean

gl.Texture (function overload 2) view source 

gl.Texture(integer, string) -> boolean
Parameters
integertexNum
stringimage
Returns
boolean

gl.Texture (function overload 3) view source 

gl.Texture(string) -> boolean
Parameters
stringimage
Returns
boolean

gl.CreateTexture (function) view source 

gl.CreateTexture(integer, integer, Texture) -> string?
Parameters
integerxsize
integerysize
Texturetexture
Returns
string?texName

gl.CreateTexture (function overload 1) view source 

gl.CreateTexture(integer, integer, integer, Texture) -> string?
Parameters
integerxsize
integerysize
integerzsize
Texturetexture
Returns
string?texName

gl.ChangeTextureParams (function) view source 

gl.ChangeTextureParams(string, Texture) -> nil
Parameters
stringtexName
Textureparams

gl.DeleteTexture (function) view source 

gl.DeleteTexture(string) -> boolean
Parameters
stringtexName
Returns
boolean

gl.DeleteTextureFBO (function) view source 

gl.DeleteTextureFBO(string) -> boolean
Parameters
stringtexName
Returns
boolean

gl.TextureInfo (function) view source 

gl.TextureInfo(string) -> TextureInfo
Parameters
stringtexName
Returns
TextureInfotextureInfo

gl.CopyToTexture (function) view source 

gl.CopyToTexture(string, integer, integer, integer, integer, integer, integer, GL?, GL?) -> nil
Parameters
stringtexName
integerxoff
integeryoff
integerx
integery
integerw
integerh
GL?target
GL?level

gl.CopyImageSubData (function) view source 

gl.CopyImageSubData(string, integer, integer, integer, integer, string, integer, integer, integer, integer, integer, integer, integer) -> nil
Parameters
stringsrcName
integersrcLevel
integersrcX
integersrcY
integersrcZ
stringdstName
integerdstLevel
integerdstX
integerdstY
integerdstZ
integerwidth
integerheight
integerdepth

gl.RenderToTexture (function) view source 

gl.RenderToTexture(string, fun(...), [any, ]*) -> nil
Parameters
stringtexName
fun(...)func
any...
Arguments to the function.

gl.GenerateMipmap (function) view source 

gl.GenerateMipmap(string) -> nil
Parameters
stringtexName

gl.ActiveTexture (function) view source 

gl.ActiveTexture(integer, function, [any, ]*) -> nil
Parameters
integertexNum
functionfunc
any...
Arguments to the function.

gl.TexEnv (function) view source 

gl.TexEnv(GL, GL, number) -> nil
Parameters
GLtarget
GLpname
numbervalue

gl.TexEnv (function overload 1) view source 

gl.TexEnv(GL, GL, number?, number?, number?, number?) -> nil
Parameters
GLtarget
GLpname
number?r
(Default: 0.0)
number?g
(Default: 0.0)
number?b
(Default: 0.0)
number?a
(Default: 0.0)

gl.MultiTexEnv (function) view source 

gl.MultiTexEnv(integer, GL, GL, number?) -> nil
Parameters
integertexNum
GLtarget
GLpname
number?value

gl.MultiTexEnv (function overload 1) view source 

gl.MultiTexEnv(integer, GL, GL, number?, number?, number?, number?) -> nil
Parameters
integertexNum
GLtarget
GLpname
number?r
(Default: 0.0)
number?g
(Default: 0.0)
number?b
(Default: 0.0)
number?a
(Default: 0.0)

gl.TexGen (function) view source 

gl.TexGen(GL, boolean) -> nil
Parameters
GLtarget
booleanstate

gl.TexGen (function overload 1) view source 

gl.TexGen(GL, GL, number?) -> nil
Parameters
GLtarget
GLpname
number?value

gl.TexGen (function overload 2) view source 

gl.TexGen(GL, GL, number?, number?, number?, number?) -> nil
Parameters
GLtarget
GLpname
number?r
(Default: 0.0)
number?g
(Default: 0.0)
number?b
(Default: 0.0)
number?a
(Default: 0.0)

gl.MultiTexGen (function) view source 

gl.MultiTexGen(integer, GL, boolean) -> nil
Parameters
integertexNum
GLtarget
booleanstate

gl.MultiTexGen (function overload 1) view source 

gl.MultiTexGen(integer, GL, GL, number?) -> nil
Parameters
integertexNum
GLtarget
GLpname
number?value

gl.MultiTexGen (function overload 2) view source 

gl.MultiTexGen(integer, GL, GL, number?, number?, number?, number?) -> nil
Parameters
integertexNum
GLtarget
GLpname
number?r
(Default: 0.0)
number?g
(Default: 0.0)
number?b
(Default: 0.0)
number?a
(Default: 0.0)

gl.BindImageTexture (function) view source

For format parameters refer to https://registry.khronos.org/OpenGL-Refpages/gl4/html/glBindImageTexture.xhtml and https://recoilengine.org/docs/lua-api/#GL.RGBA32F and further

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)

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

gl.CreateTextureAtlas (function) view source 

gl.CreateTextureAtlas(integer, integer, integer?) -> string
Parameters
integerxsize
integerysize
integer?allocType
Returns
stringtexName

gl.FinalizeTextureAtlas (function) view source 

gl.FinalizeTextureAtlas(string) -> boolean
Parameters
stringtexName
Returns
boolean

gl.DeleteTextureAtlas (function) view source 

gl.DeleteTextureAtlas(string) -> boolean
Parameters
stringtexName
Returns
boolean

gl.AddAtlasTexture (function) view source 

gl.AddAtlasTexture(string, string) -> nil
Parameters
stringtexName
stringsubAtlasTexName

gl.GetAtlasTexture (function) view source 

gl.GetAtlasTexture(string, string) -> number, number, number, number
Parameters
stringtexName
stringsubAtlasTexName
Returns
numberx1
numberx2
numbery1
numbery2

gl.GetEngineAtlasTextures (function) view source 

gl.GetEngineAtlasTextures(("$explosions"|"$groundfx")) -> table<string,float4>
Parameters
("$explosions"|"$groundfx")atlasName
Returns
table<string,float4>atlasTextures
Table of x1,x2,y1,y2 coordinates by texture name.

gl.Clear (function) view source 

gl.Clear(GL) -> nil
Parameters
GLbits
any buffer bit mask (e.g. GL.STENCIL_BUFFER_BIT). Clears with current/default values.

gl.Clear (function overload 1) view source 

gl.Clear(GL, number) -> nil
Parameters
GLbits
GL.DEPTH_BUFFER_BIT or GL.STENCIL_BUFFER_BIT.
numberval

gl.Clear (function overload 2) view source 

gl.Clear(GL, number, number, number, number) -> nil
Parameters
GLbits
GL.COLOR_BUFFER_BIT or GL.ACCUM_BUFFER_BIT.
numberr
numberg
numberb
numbera

gl.SwapBuffers (function) view source 

gl.SwapBuffers() -> nil

gl.Translate (function) view source 

gl.Translate(number, number, number) -> nil
Parameters
numberx
numbery
numberz

gl.Scale (function) view source 

gl.Scale(number, number, number) -> nil
Parameters
numberx
numbery
numberz

gl.Rotate (function) view source 

gl.Rotate(number, number, number, number) -> nil
Parameters
numberr
numberx
numbery
numberz

gl.Ortho (function) view source 

gl.Ortho(number, number, number, number, number, number) -> nil
Parameters
numberleft
numberright
numberbottom
numbertop
numbernear
numberfar

gl.Frustum (function) view source 

gl.Frustum(number, number, number, number, number, number) -> nil
Parameters
numberleft
numberright
numberbottom
numbertop
numbernear
numberfar

gl.Billboard (function) view source 

gl.Billboard() -> nil

gl.Light (function) view source 

gl.Light(integer, boolean) -> nil
Parameters
integerlight
booleanenable

gl.Light (function overload 1) view source 

gl.Light(integer, GL, GL) -> nil
Parameters
integerlight
GLpname
GLparam

gl.Light (function overload 2) view source 

gl.Light(integer, GL, number, number, number, number?) -> nil
Parameters
integerlight
GLpname
numberr
numberg
numberb
number?a

gl.ClipPlane (function) view source 

gl.ClipPlane(integer, boolean) -> nil
Parameters
integerplane
booleanenable

gl.ClipPlane (function overload 1) view source 

gl.ClipPlane(integer, number, number, number, number) -> nil
Parameters
integerplane
numberequation0
numberequation1
numberequation2
numberequation3

gl.ClipDistance (function) view source 

gl.ClipDistance(integer, boolean) -> nil
Parameters
integerclipId
booleanenable

gl.MatrixMode (function) view source 

gl.MatrixMode(GL) -> nil
Parameters
GLmode

gl.LoadIdentity (function) view source 

gl.LoadIdentity() -> nil

gl.LoadMatrix (function) view source 

gl.LoadMatrix(string) -> nil
Parameters
stringmatrix

gl.LoadMatrix (function overload 1) view source 

gl.LoadMatrix(Matrix4x4) -> nil
Parameters
Matrix4x4matrix

gl.LoadMatrix (function overload 2) view source 

gl.LoadMatrix() -> number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Returns
numberm11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

gl.MultMatrix (function) view source 

gl.MultMatrix(string) -> nil
Parameters
stringmatrixName

gl.MultMatrix (function overload 1) view source 

gl.MultMatrix(Matrix4x4) -> nil
Parameters
Matrix4x4matrix

gl.MultMatrix (function overload 2) view source 

gl.MultMatrix(number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number) -> nil
Parameters
numberm11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

gl.PushMatrix (function) view source 

gl.PushMatrix() -> nil

gl.PopMatrix (function) view source 

gl.PopMatrix() -> nil

gl.PushPopMatrix (function) view source 

gl.PushPopMatrix(GL, fun(), [any, ]*) -> nil
Parameters
GLmatMode1
fun()func
any...
Arguments to the function.

gl.PushPopMatrix (function overload 1) view source 

gl.PushPopMatrix(fun(), [any, ]*) -> nil
Parameters
fun()func
any...
Arguments to the function.

gl.GetMatrixData (function) view source

Get value at index of matrix.
gl.GetMatrixData(GL, integer) -> number
Parameters
GLtype
Matrix type (GL.PROJECTION, GL.MODELVIEW, GL.TEXTURE).
integerindex
Matrix index in range [1, 16].
Returns
numbervalue
The value at the given index.

gl.GetMatrixData (function overload 1) view source 

gl.GetMatrixData(GL) -> Matrix4x4
Parameters
GLtype
Matrix type (GL.PROJECTION, GL.MODELVIEW, GL.TEXTURE).
Returns
Matrix4x4

gl.GetMatrixData (function overload 2) view source 

gl.GetMatrixData(integer) -> number
Parameters
integerindex
Matrix index in range [1, 16].
Returns
numbervalue
The value at the given index.

gl.GetMatrixData (function overload 3) view source 

gl.GetMatrixData(MatrixName) -> Matrix4x4
Parameters
MatrixNamename
Returns
Matrix4x4

gl.PushAttrib (function) view source 

gl.PushAttrib(GL?) -> nil
Parameters
GL?mask
(Default: GL.ALL_ATTRIB_BITS)

gl.PopAttrib (function) view source 

gl.PopAttrib() -> nil

gl.UnsafeState (function) view source 

gl.UnsafeState(GL, fun(), [any, ]*) -> nil
Parameters
GLstate
fun()func
any...
Arguments to the function.

gl.UnsafeState (function overload 1) view source 

gl.UnsafeState(GL, boolean, fun(), [any, ]*) -> nil
Parameters
GLstate
booleanreverse
fun()func
any...
Arguments to the function.

gl.GetFixedState (function) view source 

gl.GetFixedState(string, boolean?) -> boolean, any ...
Parameters
stringparam
boolean?toStr
(Default: false)
Returns
booleanenabled
any ...values

gl.CreateList (function) view source 

gl.CreateList(fun(), [any, ]*) -> integer
Parameters
fun()func
any...
Arguments to the function.
Returns
integerlistID
0 if the list could not be generated or func errored.

gl.CallList (function) view source 

gl.CallList(integer) -> nil
Parameters
integerlistIndex

gl.DeleteList (function) view source 

gl.DeleteList(integer) -> nil
Parameters
integerlistIndex

gl.Flush (function) view source 

gl.Flush() -> nil

gl.Finish (function) view source 

gl.Finish() -> nil

gl.ReadPixels (function) view source

Get single pixel.

format is one of the GL pixel format constants. One value is returned per component of the format, in the order the format names them, so GL.BGRA returns blue, green, red and alpha:

GL.COLOR_INDEX, GL.ALPHA, GL.LUMINANCE and GL.LUMINANCE_ALPHA were removed in the core profile, and are only accepted while running in the compatibility profile, i.e. with the ForceCoreContext config unset. GL.COLOR_INDEX additionally requires a color-index color buffer, which Recoil never creates. GL.STENCIL_INDEX and GL.DEPTH_COMPONENT require the read buffer to actually have the matching attachment.

gl.ReadPixels(integer, integer, 1, 1, GL?) -> number ...
Parameters
integerx
integery
1w
1h
GL?format
(Default: GL.RGBA)
Returns
number ...Color
value (color size based on format).

gl.ReadPixels (function overload 1) view source

Get column of pixels.
gl.ReadPixels(integer, integer, 1, integer, GL?) -> (number|number[])[]
Parameters
integerx
integery
1w
integerh
GL?format
(Default: GL.RGBA)
Returns
(number|number[])[]colors
Column of color values (color size based on format), indexed by row.

gl.ReadPixels (function overload 2) view source

Get row of pixels.
gl.ReadPixels(integer, integer, integer, 1, GL?) -> (number|number[])[]
Parameters
integerx
integery
integerw
1h
GL?format
(Default: GL.RGBA)
Returns
(number|number[])[]colors
Row of color values (color size based on format), indexed by column.

gl.ReadPixels (function overload 3) view source

Get rows of pixels.
gl.ReadPixels(integer, integer, integer, integer, GL?) -> (number|number[])[][]
Parameters
integerx
integery
integerw
integerh
GL?format
(Default: GL.RGBA)
Returns
(number|number[])[][]colors
Array of rows of color values (color size based on format), bottom row first: colors[y][x].

gl.SaveImage (function) view source 

gl.SaveImage(integer, integer, integer, integer, string, SaveImageOptions?) -> boolean?
Parameters
integerx
integery
integerwidth
integerheight
stringfilename
SaveImageOptions?options
Returns
boolean?success

gl.CreateQuery (function) view source

Creates a GL query object.

Timer targets (GL.TIME_ELAPSED, GL.TIMESTAMP) need OpenGL 3.3 or ARB_timer_query; without it nil is returned. A GL.TIMESTAMP query is written with gl.QueryCounter, the other targets are measured over a function with gl.RunQuery.

gl.CreateQuery(integer?) -> any
Parameters
integer?target
(Default: GL.SAMPLES_PASSED) One of GL.SAMPLES_PASSED, GL.ANY_SAMPLES_PASSED, GL.ANY_SAMPLES_PASSED_CONSERVATIVE, GL.PRIMITIVES_GENERATED, GL.TIME_ELAPSED, GL.TIMESTAMP.
Returns
anyquery

gl.DeleteQuery (function) view source 

gl.DeleteQuery(any) -> nil
Parameters
anyquery

gl.RunQuery (function) view source

Runs the query over the GL calls made by func.

The query’s target decides what is counted: samples that passed the depth test (GL.SAMPLES_PASSED, GL.ANY_SAMPLES_PASSED*), primitives emitted (GL.PRIMITIVES_GENERATED) or GPU nanoseconds spent (GL.TIME_ELAPSED). Queries of the same target cannot be nested, and GL.TIMESTAMP queries use gl.QueryCounter instead.

gl.RunQuery(any, fun(...), [any, ]*) -> nil
Parameters
anyquery
fun(...)func
any...
Arguments passed to func.

gl.QueryCounter (function) view source

Records the GPU timestamp (nanoseconds) into a GL.TIMESTAMP query once the GPU reaches this point of the command stream. The difference between two timestamps is the GPU time spent between them; unlike GL.TIME_ELAPSED ranges these nest freely.

May be unavailable and nil if the platform supports neither OpenGL 3.3 nor ARB_timer_query.

gl.QueryCounter(any) -> nil
Parameters
anyquery
A query created with gl.CreateQuery(GL.TIMESTAMP).

gl.GetQuery (function) view source

Reads the result of a query.

Results become available only after the GPU has executed the queried commands, usually a frame or two later. With blocking the call stalls until then; without it nil is returned while the result is still pending, so queries from the previous frame can be read without a GPU sync.

Note that a GL.TIMESTAMP value is a 64-bit nanosecond counter that Lua’s single precision numbers cannot hold exactly; use gl.GetQueryDelta to measure between two.

gl.GetQuery(any, boolean?) -> number?
Parameters
anyquery
boolean?blocking
(Default: true) Wait for the result.
Returns
number?result
Sample count, primitive count, or nanoseconds for timer queries; nil if not yet available and blocking is false.

gl.GetQueryDelta (function) view source

Returns the GPU nanoseconds between two GL.TIMESTAMP queries recorded with gl.QueryCounter.

The subtraction happens on the 64-bit values, so the result stays exact where the raw timestamps would not survive the trip into Lua’s single precision numbers.

May be unavailable and nil if the platform supports neither OpenGL 3.3 nor ARB_timer_query.

gl.GetQueryDelta(any, any, boolean?) -> number?
Parameters
anystartQuery
anyendQuery
boolean?blocking
(Default: true) Wait for both results.
Returns
number?nanoseconds
nil if a result is not yet available and blocking is false.

gl.GetGlobalTexNames (function) view source 

gl.GetGlobalTexNames() -> string[]
Returns
string[]texNames
List of texture names.

gl.GetGlobalTexCoords (function) view source 

gl.GetGlobalTexCoords() -> number, number, number, number
Returns
numberxstart
numberystart
numberxend
numberyend

gl.GetShadowMapParams (function) view source 

gl.GetShadowMapParams() -> number, number, number, number
Returns
numberx
numbery
numberz
numberw

gl.GetAtmosphere (function) view source 

gl.GetAtmosphere() -> number, number, number
Returns
numberlightDirX
numberlightDirY
numberlightDirZ

gl.GetAtmosphere (function overload 1) view source 

gl.GetAtmosphere(("fogStart"|"fogEnd"|"pos"|"fogColor"|"skyColor"|"sunColor"...)) -> any ...
Parameters
("fogStart"|"fogEnd"|"pos"|"fogColor"|"skyColor"|"sunColor"...)param
Returns
any ...

gl.GetSun (function) view source 

gl.GetSun() -> number, number, number
Returns
numberlightDirX
numberlightDirY
numberlightDirZ

gl.GetSun (function overload 1) view source 

gl.GetSun(("pos"|"dir"|"specularExponent"|"shadowDensity"|"diffuse"|"ambient"...), ("ground"|"unit")) -> number?, number?, number?
Parameters
("pos"|"dir"|"specularExponent"|"shadowDensity"|"diffuse"|"ambient"...)param
("ground"|"unit")mode
(Default: “ground”)
Returns
number?data1
number?data2
number?data3

gl.GetWaterRendering (function) view source 

gl.GetWaterRendering(string) -> any ...
Parameters
stringkey
Returns
any ...value

gl.GetMapRendering (function) view source 

gl.GetMapRendering(string) -> any ...
Parameters
stringkey
Returns
any ...value

gl.ObjectLabel (function) view source

Labels an object for use with debugging tools. May be unavailable and nil if the platform doesn’t support the feature.
gl.ObjectLabel(GL, integer, string) -> nil
Parameters
GLobjectTypeIdentifier
Specifies the type of object being labeled.
integerobjectID
Specifies the name or ID of the object to label.
stringlabel
A string containing the label to be assigned to the object.

gl.PushDebugGroup (function) view source

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.

gl.PushDebugGroup(integer, string, boolean?) -> nil
Parameters
integerid
A numeric identifier for the group, can be any unique number.
stringmessage
A human-readable string describing the debug group. Will be truncated if longer than driver-specific limit
boolean?sourceIsThirdParty
Set the source tag, true for GL_DEBUG_SOURCE_THIRD_PARTY, false for GL_DEBUG_SOURCE_APPLICATION. default false
Returns
nil

gl.PopDebugGroup (function) view source

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.
gl.PopDebugGroup() -> nil
Returns
nil

gl.CreateFBO (function) view source 

gl.CreateFBO(FBODescription) -> FBO
Parameters
FBODescriptionfboDesc
Returns
FBOfbo

gl.DeleteFBO (function) view source

This doesn’t delete the attached objects!
gl.DeleteFBO(FBO) -> nil
Parameters
FBOfbo

gl.IsValidFBO (function) view source 

gl.IsValidFBO(FBO, GL?) -> boolean, GL?
Parameters
FBOfbo
GL?target
Returns
booleanvalid
GL?status

gl.ActiveFBO (function) view source 

gl.ActiveFBO(FBO, fun(...), [any, ]*) -> nil
Parameters
FBOfbo
fun(...)func
any...
args

gl.ActiveFBO (function overload 1) view source 

gl.ActiveFBO(FBO, GL?, fun(...), [any, ]*) -> nil
Parameters
FBOfbo
GL?target
fun(...)func
any...
args

gl.RawBindFBO (function) view source

Bind default or specified via rawFboId numeric id of FBO
gl.RawBindFBO(nil, GL?, integer?) -> nil
Parameters
nilfbo
GL?target
(Default: GL_FRAMEBUFFER_EXT)
integer?rawFboId
(Default: 0)
Returns
nil

gl.RawBindFBO (function overload 1) view source 

gl.RawBindFBO(FBO, GL?) -> integer
Parameters
FBOfbo
GL?target
(Default: fbo.target)
Returns
integerpreviouslyBoundRawFboId

gl.BlitFBO (function) view source

needs GLAD_GL_EXT_framebuffer_blit
gl.BlitFBO(integer, integer, integer, integer, integer, integer, integer, integer, GL?, GL?) -> nil
Parameters
integerx0Src
integery0Src
integerx1Src
integery1Src
integerx0Dst
integery0Dst
integerx1Dst
integery1Dst
GL?mask
(Default: GL_COLOR_BUFFER_BIT)
GL?filter
(Default: GL_NEAREST)

gl.BlitFBO (function overload 1) view source

needs GLAD_GL_EXT_framebuffer_blit
gl.BlitFBO(FBO, integer, integer, integer, integer, FBO, integer, integer, integer, integer, GL?, GL?) -> nil
Parameters
FBOfboSrc
integerx0Src
integery0Src
integerx1Src
integery1Src
FBOfboDst
integerx0Dst
integery0Dst
integerx1Dst
integery1Dst
GL?mask
(Default: GL_COLOR_BUFFER_BIT)
GL?filter
(Default: GL_NEAREST)

gl.ClearAttachmentFBO (function) view source

needs Platform.glVersionNum >= 30 Clears the “attachment” of the currently bound FBO type “target” with “clearValues”
gl.ClearAttachmentFBO(GL?, (GL|Attachment), number?, number?, number?, number?) -> boolean
Parameters
GL?target
(Default: GL.FRAMEBUFFER)
(GL|Attachment)attachment
(e.g. “color0” or GL.COLOR_ATTACHMENT0)
number?clearValue0
(Default: 0)
number?clearValue1
(Default: 0)
number?clearValue2
(Default: 0)
number?clearValue3
(Default: 0)
Returns
booleansuccess

gl.GetVBO (function) view source

Example:

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

bufferType accepts the following:

See GL.OpenGL_Buffer_Types

gl.GetVBO(GL?, boolean?) -> VBO?
Parameters
GL?bufferType
(Default: GL.ARRAY_BUFFER) The buffer type to use.
boolean?freqUpdated
(Default: true) true to update frequently, false to update only once.
Returns
VBO?VBO
The VBO ref on success, or nil if not supported or an error occurred.

GL (field)

GL (enum) view source

Constants for OpenGL API

For callouts related to OpenGL usage in Recoil, see gl.

See gl

integer POINTSview source
integer LINESview source
integer LINE_LOOPview source
integer LINE_STRIPview source
integer TRIANGLESview source
integer TRIANGLE_STRIPview source
integer TRIANGLE_FANview source
integer QUADSview source
integer QUAD_STRIPview source
integer POLYGONview source
integer LINE_STRIP_ADJACENCYview source
integer LINES_ADJACENCYview source
integer TRIANGLE_STRIP_ADJACENCYview source
integer TRIANGLES_ADJACENCYview source
integer PATCHESview source
integer ZEROview source
integer ONEview source
integer SRC_COLORview source
integer ONE_MINUS_SRC_COLORview source
integer SRC_ALPHAview source
integer ONE_MINUS_SRC_ALPHAview source
integer DST_ALPHAview source
integer ONE_MINUS_DST_ALPHAview source
integer DST_COLORview source
integer ONE_MINUS_DST_COLORview source
integer SRC_ALPHA_SATURATEview source
integer FUNC_ADDview source
integer FUNC_SUBTRACTview source
integer FUNC_REVERSE_SUBTRACTview source
integer MINview source
integer MAXview source
integer NEVERview source
integer LESSview source
integer EQUALview source
integer LEQUALview source
integer GREATERview source
integer NOTEQUALview source
integer GEQUALview source
integer ALWAYSview source
integer CLEARview source
integer ANDview source
integer AND_REVERSEview source
integer COPYview source
integer AND_INVERTEDview source
integer NOOPview source
integer XORview source
integer ORview source
integer NORview source
integer EQUIVview source
integer INVERTview source
integer OR_REVERSEview source
integer COPY_INVERTEDview source
integer OR_INVERTEDview source
integer NANDview source
integer SETview source
integer BACKview source
integer FRONTview source
integer FRONT_AND_BACKview source
integer POINTview source
integer LINEview source
integer FILLview source
integer FLATview source
integer SMOOTHview source
integer MODELVIEWview source
integer PROJECTIONview source
integer TEXTUREview source
integer NEARESTview source
integer LINEARview source
integer NEAREST_MIPMAP_NEARESTview source
integer LINEAR_MIPMAP_NEARESTview source
integer NEAREST_MIPMAP_LINEARview source
integer LINEAR_MIPMAP_LINEARview source
integer REPEATview source
integer MIRRORED_REPEATview source
integer CLAMPview source
integer CLAMP_TO_EDGEview source
integer CLAMP_TO_BORDERview source
integer TEXTURE_ENVview source
integer TEXTURE_ENV_MODEview source
integer TEXTURE_ENV_COLORview source
integer MODULATEview source
integer DECALview source
integer BLENDview source
integer REPLACEview source
integer TEXTURE_FILTER_CONTROLview source
integer TEXTURE_LOD_BIASview source
integer TEXTURE_GEN_MODEview source
integer EYE_PLANEview source
integer OBJECT_PLANEview source
integer EYE_LINEARview source
integer OBJECT_LINEARview source
integer SPHERE_MAPview source
integer NORMAL_MAPview source
integer REFLECTION_MAPview source
integer Sview source
integer Tview source
integer Rview source
integer Qview source
integer CURRENT_BITview source
integer POINT_BITview source
integer LINE_BITview source
integer POLYGON_BITview source
integer POLYGON_STIPPLE_BITview source
integer PIXEL_MODE_BITview source
integer LIGHTING_BITview source
integer FOG_BITview source
integer DEPTH_BUFFER_BITview source
integer ACCUM_BUFFER_BITview source
integer STENCIL_BUFFER_BITview source
integer VIEWPORT_BITview source
integer TRANSFORM_BITview source
integer ENABLE_BITview source
integer COLOR_BUFFER_BITview source
integer HINT_BITview source
integer EVAL_BITview source
integer LIST_BITview source
integer TEXTURE_BITview source
integer SCISSOR_BITview source
integer ALL_ATTRIB_BITSview source
integer FOG_HINTview source
integer PERSPECTIVE_CORRECTION_HINTview source
integer DONT_CAREview source
integer FASTESTview source
integer NICESTview source
integer KEEPview source
integer INCRview source
integer DECRview source
integer INCR_WRAPview source
integer DECR_WRAPview source
integer AMBIENTview source
integer DIFFUSEview source
integer SPECULARview source
integer POSITIONview source
integer SPOT_DIRECTIONview source
integer SPOT_EXPONENTview source
integer SPOT_CUTOFFview source
integer CONSTANT_ATTENUATIONview source
integer LINEAR_ATTENUATIONview source
integer QUADRATIC_ATTENUATIONview source
integer VERTEX_SHADERview source
integer TESS_CONTROL_SHADERview source
integer TESS_EVALUATION_SHADERview source
integer GEOMETRY_SHADER_EXTview source
integer FRAGMENT_SHADERview source
integer GEOMETRY_INPUT_TYPE_EXTview source
integer GEOMETRY_OUTPUT_TYPE_EXTview source
integer GEOMETRY_VERTICES_OUT_EXTview source
integer PATCH_VERTICESview source
integer PATCH_DEFAULT_OUTER_LEVELview source
integer PATCH_DEFAULT_INNER_LEVELview source
integer BYTEview source
integer UNSIGNED_BYTEview source
integer SHORTview source
integer UNSIGNED_SHORTview source
integer INTview source
integer UNSIGNED_INTview source
integer FLOATview source
integer FLOAT_VEC4view source
integer INT_VEC4view source
integer UNSIGNED_INT_VEC4view source
integer FLOAT_MAT4view source
integer ELEMENT_ARRAY_BUFFERview source
integer ARRAY_BUFFERview source
integer UNIFORM_BUFFERview source
integer SHADER_STORAGE_BUFFERview source
integer TEXTURE_1Dview source
integer TEXTURE_2Dview source
integer TEXTURE_2D_ARRAYview source
integer TEXTURE_3Dview source
integer TEXTURE_CUBE_MAPview source
integer TEXTURE_2D_MULTISAMPLEview source
integer RGBA32Fview source
integer RGBA16Fview source
integer RG32Fview source
integer RG16Fview source
integer R11F_G11F_B10Fview source
integer R32Fview source
integer R16Fview source
integer RGBA32UIview source
integer RGBA16UIview source
integer RGB10_A2UIview source
integer RGBA8UIview source
integer RG32UIview source
integer RG16UIview source
integer RG8UIview source
integer R32UIview source
integer R16UIview source
integer R8UIview source
integer RGBA32Iview source
integer RGBA16Iview source
integer RGBA8Iview source
integer RG32Iview source
integer RG16Iview source
integer RG8Iview source
integer R32Iview source
integer R16Iview source
integer R8Iview source
integer RGBA16view source
integer RGB10_A2view source
integer RGBA8view source
integer RG16view source
integer RG8view source
integer R16view source
integer R8view source
integer RGBA16_SNORMview source
integer RGBA8_SNORMview source
integer RG16_SNORMview source
integer RG8_SNORMview source
integer R16_SNORMview source
integer R8_SNORMview source
integer DEPTH_COMPONENT16view source
integer DEPTH_COMPONENT24view source
integer DEPTH_COMPONENT32view source
integer DEPTH_COMPONENT32Fview source
integer READ_ONLYview source
integer WRITE_ONLYview source
integer READ_WRITEview source
integer VERTEX_ATTRIB_ARRAY_BARRIER_BITview source
integer ELEMENT_ARRAY_BARRIER_BITview source
integer UNIFORM_BARRIER_BITview source
integer TEXTURE_FETCH_BARRIER_BITview source
integer SHADER_IMAGE_ACCESS_BARRIER_BITview source
integer COMMAND_BARRIER_BITview source
integer PIXEL_BUFFER_BARRIER_BITview source
integer TEXTURE_UPDATE_BARRIER_BITview source
integer BUFFER_UPDATE_BARRIER_BITview source
integer FRAMEBUFFER_BARRIER_BITview source
integer TRANSFORM_FEEDBACK_BARRIER_BITview source
integer ATOMIC_COUNTER_BARRIER_BITview source
integer SHADER_STORAGE_BARRIER_BITview source
integer ALL_BARRIER_BITSview source
integer COLOR_ATTACHMENT0view source
integer COLOR_ATTACHMENT1view source
integer COLOR_ATTACHMENT2view source
integer COLOR_ATTACHMENT3view source
integer COLOR_ATTACHMENT4view source
integer COLOR_ATTACHMENT5view source
integer COLOR_ATTACHMENT6view source
integer COLOR_ATTACHMENT7view source
integer COLOR_ATTACHMENT8view source
integer COLOR_ATTACHMENT9view source
integer COLOR_ATTACHMENT10view source
integer COLOR_ATTACHMENT11view source
integer COLOR_ATTACHMENT12view source
integer COLOR_ATTACHMENT13view source
integer COLOR_ATTACHMENT14view source
integer COLOR_ATTACHMENT15view source
integer DEPTH_ATTACHMENTview source
integer STENCIL_ATTACHMENTview source
integer COLOR_ATTACHMENT0_EXTview source
integer COLOR_ATTACHMENT1_EXTview source
integer COLOR_ATTACHMENT2_EXTview source
integer COLOR_ATTACHMENT3_EXTview source
integer COLOR_ATTACHMENT4_EXTview source
integer COLOR_ATTACHMENT5_EXTview source
integer COLOR_ATTACHMENT6_EXTview source
integer COLOR_ATTACHMENT7_EXTview source
integer COLOR_ATTACHMENT8_EXTview source
integer COLOR_ATTACHMENT9_EXTview source
integer COLOR_ATTACHMENT10_EXTview source
integer COLOR_ATTACHMENT11_EXTview source
integer COLOR_ATTACHMENT12_EXTview source
integer COLOR_ATTACHMENT13_EXTview source
integer COLOR_ATTACHMENT14_EXTview source
integer COLOR_ATTACHMENT15_EXTview source
integer DEPTH_ATTACHMENT_EXTview source
integer STENCIL_ATTACHMENT_EXTview source
integer BUFFERview source
integer SHADERview source
integer PROGRAMview source
integer VERTEX_ARRAYview source
integer QUERYview source
integer PROGRAM_PIPELINEview source
integer TRANSFORM_FEEDBACKview source
integer RENDERBUFFERview source
integer FRAMEBUFFERview source
integer COLOR_INDEXview source
integer STENCIL_INDEXview source
integer DEPTH_COMPONENTview source
integer REDview source
integer GREENview source
integer BLUEview source
integer ALPHAview source
integer RGview source
integer RGBview source
integer RGBAview source
integer BGRview source
integer BGRAview source
integer LUMINANCEview source
Only accepted in the compatibility profile, i.e. with ForceCoreContext unset.
integer LUMINANCE_ALPHAview source
Only accepted in the compatibility profile, i.e. with ForceCoreContext unset.
integer SAMPLES_PASSEDview source
integer ANY_SAMPLES_PASSEDview source
integer ANY_SAMPLES_PASSED_CONSERVATIVEview source
integer PRIMITIVES_GENERATEDview source
integer TIME_ELAPSEDview source
integer TIMESTAMPview source

RmlUi (table) view source

Global functions for Recoil’s RmlUi implementation.

Members

RmlUi.CreateContext (function) view source

Create a new context.
RmlUi.CreateContext(string) -> RmlUi.Context?
Parameters
stringname
Returns
RmlUi.Context?nil
if failed.

RmlUi.RemoveContext (function) view source

Remove a context.
RmlUi.RemoveContext((string|RmlUi.Context)) -> nil
Parameters
(string|RmlUi.Context)context

RmlUi.LoadFontFace (function) view source

Load a font face.
RmlUi.LoadFontFace(string, boolean?, RmlUi.font_weight?, number?) -> boolean
Parameters
stringfile_path
boolean?fallback
RmlUi.font_weight?weight
number?face_index
The index of the font face within a font collection.
Returns
booleansuccess

RmlUi.GetContext (function) view source

Get a context by name.
RmlUi.GetContext(string) -> RmlUi.Context?
Parameters
stringname
Returns
RmlUi.Context?nil
if failed.

RmlUi.RegiserEventType (function) view source

Register a new event type.
RmlUi.RegiserEventType(string, boolean?, boolean?, RmlUi.default_action_phase?) -> RmlUi.EventID
Parameters
stringevent_type
boolean?interruptible
boolean?bubbles
RmlUi.default_action_phase?default_phase
Returns
RmlUi.EventID

RmlUi.AddTranslationString (function) view source

Add a translation string.
RmlUi.AddTranslationString(string, string) -> boolean
Parameters
stringkey
stringtranslation
Returns
booleansuccess

RmlUi.ClearTranslations (function) view source

Clear registered translations.
RmlUi.ClearTranslations() -> nil

RmlUi.SetMouseCursorAlias (function) view source

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.
RmlUi.SetMouseCursorAlias(string, string) -> nil
Parameters
stringrml_name
name used in rml script
stringrecoil_name
name used in recoil

RmlUi.SetDebugContext (function) view source

Set which context the debug inspector is meant to inspect.
RmlUi.SetDebugContext((string|RmlUi.Context)) -> nil
Parameters
(string|RmlUi.Context)context

RmlUi.ClearDocumentPathRequests (function) view source

Clear the list of paths requested for a document for the purpose of GetDocumentPathRequests. Does not clear anything else related to those requests themselves.
RmlUi.ClearDocumentPathRequests(string) -> nil
Parameters
stringdocument_path
path of document

RmlUi.GetDocumentPathRequests (function) view source

Retrieve the list of paths requested by the loaded RML document since the most recent RmlUi.ClearDocumentPathRequests call.
RmlUi.GetDocumentPathRequests(string) -> string[]
Parameters
stringdocument_path
path of document
Returns
string[]array
of paths requested by the document

Fields

RmlUi.ElementText ElementText
RmlUi.ElementTabSet ElementTabSet
RmlUi.ElementProgress ElementProgress
RmlUi.Vector2i Vector2i
RmlUi.Vector2f Vector2f
RmlUi.ElementForm ElementForm
RmlUi.ElementFormControl ElementFormControl
RmlUi.ElementFormControlInput ElementFormControlInput
RmlUi.ElementFormControlSelect ElementFormControlSelect
RmlUi.ElementFormControlTextArea ElementFormControlTextArea
RmlUi.ElementPtr ElementPtr
RmlUi.Context[] contextsview source
string versionview source
RmlUi version
RmlUi.key_identifier key_identifier
RmlUi.key_modifier key_modifier
RmlUi.font_weight font_weight
RmlUi.default_action_phase default_action_phase
RmlUi.SolLuaDataModel<T> SolLuaDataModel
RmlUi.EventListener EventListener
RmlUi.Element Element
RmlUi.Context Context
RmlUi.RmlModalFlag RmlModalFlag
RmlUi.RmlFocusFlag RmlFocusFlag
RmlUi.Document Document
RmlUi.RmlEventPhase RmlEventPhase
RmlUi.EventParametersProxy EventParametersProxy
RmlUi.Event Event

CameraState (class)

Parameters for camera state.

Highly dependent on the type of the current camera controller.

Fields

CameraName name
The camera name.
CameraMode mode
The camera mode.
number? fov
number? px
Position X of the ground point in screen center.
number? py
Position Y of the ground point in screen center.
number? pz
Position Z of the ground point in screen center.
number? dx
Camera direction vector X.
number? dy
Camera direction vector Y.
number? dz
Camera direction vector Z.
number? rx
Camera rotation angle on X axis. (spring)
number? ry
Camera rotation angle on Y axis. (spring)
number? rz
Camera rotation angle on Z axis. (spring)
number? angle
Camera rotation angle on X axis (aka tilt/pitch). (ta)
number? flipped
-1 for when south is down, 1 for when north is down. (ta)
number? dist
Camera distance from the ground. (spring)
number? height
Camera distance from the ground. (ta)
number? oldHeight
Camera distance from the ground, cannot be changed. (rot)

FBO (class) view source

User Data FBO

IconData (class) view source

Icon Data

Fields

string nameview source
string? fileNameview source
number? sizeview source
Relative size of the icon
number? distanceview source
When squared used as a icon length multiplier
number? drawOrderview source
Sort priority for icon drawing; icons with higher values are drawn on top of lower ones
boolean? radiusAdjustview source
Controls whether the unit radius affects the icon size
TexCoords? srcTexCoordsview source
TexCoords atlasTexCoordsview source
atlasIndex points to $icons0 or $icons1 texture

Intro (class) view source

Inherits Callins

See Callins

Members

Intro:DrawLoadScreen (function) view source

Draws custom load screens.
Intro:DrawLoadScreen() -> nil

Intro:LoadProgress (function) view source 

Intro:LoadProgress(string, boolean) -> nil
Parameters
stringmessage
booleanreplaceLastLine

LuaFont (class) view source

Lua opengl font object.

See gl.LoadFont

Members

LuaFont:Print (function) view source

Draws text in screen space at the given position.
LuaFont:Print(string, number, number, number?, string?) -> nil
Parameters
stringtext
numberx
numbery
number?size
Defaults to the font’s point size.
string?options
Flag characters for alignment, outline, shadow, scaling, etc. (e.g. “co” for center and outline).

LuaFont:PrintWorld (function) view source

Draws text in world space at the given position.
LuaFont:PrintWorld(string, number, number, number, number?, string?) -> nil
Parameters
stringtext
numberx
numbery
numberz
number?size
Defaults to the font’s point size.
string?options
Flag characters for alignment, outline, shadow, scaling, etc. (e.g. “co” for center and outline).

LuaFont:Begin (function) view source

Begin a block of font commands.

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 gl.BlendFunc, gl.BlendFuncSeparate

LuaFont:Begin(boolean?) -> nil
Parameters
boolean?userDefinedBlending
When true doesn’t set the gl.BlendFunc automatically. Defaults to false.

LuaFont:End (function) view source

Ends a font command block started with LuaFont:Begin.
LuaFont:End() -> nil

LuaFont:SubmitBuffered (function) view source

Draws text printed with the buffered option.

See gl.BlendFunc, gl.BlendFuncSeparate

LuaFont:SubmitBuffered(boolean?, boolean?) -> nil
Parameters
boolean?noBillboarding
When false sets 3d billboard mode. Defaults to true.
boolean?userDefinedBlending
When true doesn’t set the gl.BlendFunc automatically. Defaults to false.

LuaFont:WrapText (function) view source

Wraps text to fit within a maximum width (and optional max height), in-place.
LuaFont:WrapText(string, number, number?, number?) -> string, integer
Parameters
stringtext
numbermaxWidth
number?maxHeight
Defaults to an engine-defined maximum height.
number?size
Defaults to the font’s point size.
Returns
stringwrappedText
integerlineCount

LuaFont:GetTextWidth (function) view source

Returns the horizontal extent of a string for this font at its current size.
LuaFont:GetTextWidth(string) -> number
Parameters
stringtext
Returns
numberwidth

LuaFont:GetTextHeight (function) view source

Returns layout metrics for a string: total height, descender depth, and line count.
LuaFont:GetTextHeight(string) -> number, number, integer
Parameters
stringtext
Returns
numberheight
numberdescender
integerlines

LuaFont:SetTextColor (function) view source

Sets the RGBA color used when drawing text (fill).
LuaFont:SetTextColor(table) -> nil
Parameters
tablecolor
Four-component RGBA array ({r, g, b, a}), or pass r, g, b, and optional a as separate numbers (requires at least three numeric components after the font).

LuaFont:SetOutlineColor (function) view source

Sets the RGBA color used for text outline when outline rendering is enabled.
LuaFont:SetOutlineColor(table) -> nil
Parameters
tablecolor
Four-component RGBA array ({r, g, b, a}), or pass r, g, b, and optional a as separate numbers (requires at least three numeric components after the font).

LuaFont:SetAutoOutlineColor (function) view source

When enabled, outline color is derived automatically instead of using SetOutlineColor.
LuaFont:SetAutoOutlineColor(boolean) -> nil
Parameters
booleanenabled

Menu (class) view source

Inherits Callins

See Callins

Members

Menu:ActivateMenu (function) view source

Called whenever LuaMenu is on with no game loaded.
Menu:ActivateMenu() -> nil

Menu:ActivateGame (function) view source

Called whenever LuaMenu is on with a game loaded.
Menu:ActivateGame() -> nil

Menu:AllowDraw (function) view source

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.
Menu:AllowDraw() -> boolean
Returns
booleanallowDraw

MoveCtrl (class) view source

Accessed via Spring.MoveCtrl.

Members

MoveCtrl.IsEnabled (function) view source 

MoveCtrl.IsEnabled(UnitID) -> boolean?
Parameters
UnitIDunitID
Returns
boolean?isEnabled

MoveCtrl.Enable (function) view source 

MoveCtrl.Enable(UnitID) -> nil
Parameters
UnitIDunitID

MoveCtrl.Disable (function) view source 

MoveCtrl.Disable(UnitID) -> nil
Parameters
UnitIDunitID

MoveCtrl.SetTag (function) view source 

MoveCtrl.SetTag(UnitID, integer) -> nil
Parameters
UnitIDunitID
integertag

MoveCtrl.GetTag (function) view source 

MoveCtrl.GetTag(integer?) -> integer?
Parameters
integer?tag
Returns
integer?tag
nil if the unit is not using a script move type.

MoveCtrl.SetProgressState (function) view source 

MoveCtrl.SetProgressState(UnitID, (0|1|2|"done"|"active"|"failed")) -> nil
Parameters
UnitIDunitID
(0|1|2|"done"|"active"|"failed")state

MoveCtrl.SetExtrapolate (function) view source 

MoveCtrl.SetExtrapolate(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanextrapolate

MoveCtrl.SetPhysics (function) view source 

MoveCtrl.SetPhysics(UnitID, number, number, number, number, number, number, number, number, number) -> nil
Parameters
UnitIDunitID
numberposX
Position X component.
numberposY
Position Y component.
numberposZ
Position Z component.
numbervelX
Velocity X component.
numbervelY
Velocity Y component.
numbervelZ
Velocity Z component.
numberrotX
Rotation X component.
numberrotY
Rotation Y component.
numberrotZ
Rotation Z component.

MoveCtrl.SetPosition (function) view source 

MoveCtrl.SetPosition(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberposX
Position X component.
numberposY
Position Y component.
numberposZ
Position Z component.

MoveCtrl.SetVelocity (function) view source 

MoveCtrl.SetVelocity(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numbervelX
Velocity X component.
numbervelY
Velocity Y component.
numbervelZ
Velocity Z component.

MoveCtrl.SetRelativeVelocity (function) view source 

MoveCtrl.SetRelativeVelocity(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberrelVelX
Relative velocity X component.
numberrelVelY
Relative velocity Y component.
numberrelVelZ
Relative velocity Z component.

MoveCtrl.SetRotation (function) view source 

MoveCtrl.SetRotation(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberrotX
Rotation X component.
numberrotY
Rotation Y component.
numberrotZ
Rotation Z component.

MoveCtrl.SetRotationOffset (function) view source

Deprecated

MoveCtrl.SetRotationOffset() -> nil

MoveCtrl.SetRotationVelocity (function) view source 

MoveCtrl.SetRotationVelocity(UnitID, number, number, number) -> nil
Parameters
UnitIDunitID
numberrotVelX
Rotation velocity X component.
numberrotVelY
Rotation velocity Y component.
numberrotVelZ
Rotation velocity Z component.

MoveCtrl.SetHeading (function) view source 

MoveCtrl.SetHeading(UnitID, Heading) -> nil
Parameters
UnitIDunitID
Headingheading

MoveCtrl.SetTrackSlope (function) view source 

MoveCtrl.SetTrackSlope(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleantrackSlope

MoveCtrl.SetTrackGround (function) view source 

MoveCtrl.SetTrackGround(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleantrackGround

MoveCtrl.SetTrackLimits (function) view source 

MoveCtrl.SetTrackLimits(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleantrackLimits

MoveCtrl.SetGroundOffset (function) view source 

MoveCtrl.SetGroundOffset(UnitID, number) -> nil
Parameters
UnitIDunitID
numbergroundOffset

MoveCtrl.SetGravity (function) view source 

MoveCtrl.SetGravity(UnitID, number) -> nil
Parameters
UnitIDunitID
numbergravityFactor

MoveCtrl.SetDrag (function) view source 

MoveCtrl.SetDrag(UnitID, number) -> nil
Parameters
UnitIDunitID
numberdrag

MoveCtrl.SetWindFactor (function) view source 

MoveCtrl.SetWindFactor(UnitID, number) -> nil
Parameters
UnitIDunitID
numberwindFactor

MoveCtrl.SetLimits (function) view source 

MoveCtrl.SetLimits(UnitID, number, number, number, number, number, number) -> nil
Parameters
UnitIDunitID
numberminX
Minimum position X component.
numberminY
Minimum position Y component.
numberminZ
Minimum position Z component.
numbermaxX
Maximum position X component.
numbermaxY
Maximum position Y component.
numbermaxZ
Maximum position Z component.

MoveCtrl.SetNoBlocking (function) view source 

MoveCtrl.SetNoBlocking(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleannoBlocking

MoveCtrl.SetCollideStop (function) view source 

MoveCtrl.SetCollideStop(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleancollideStop

MoveCtrl.SetLimitsStop (function) view source 

MoveCtrl.SetLimitsStop(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanlimitsStop

MoveCtrl.SetGunshipMoveTypeData (function) view source 

MoveCtrl.SetGunshipMoveTypeData(UnitID, HoverAirMoveType) -> integer
Parameters
UnitIDunitID
HoverAirMoveTypemoveType
Returns
integernumAssignedValues

MoveCtrl.SetGunshipMoveTypeData (function overload 1) view source 

MoveCtrl.SetGunshipMoveTypeData(UnitID, (GenericMoveTypeBooleanKey|"collide"|"dontLand"|"airStrafe"|"useSmoothMesh"|"bankingAllowed"), boolean) -> integer
Parameters
UnitIDunitID
(GenericMoveTypeBooleanKey|"collide"|"dontLand"|"airStrafe"|"useSmoothMesh"|"bankingAllowed")key
booleanvalue
Returns
integernumAssignedValues

MoveCtrl.SetGunshipMoveTypeData (function overload 2) view source 

MoveCtrl.SetGunshipMoveTypeData(UnitID, (GenericMoveTypeNumberKey|"wantedHeight"|"accRate"|"decRate"|"turnRate"|"altitudeRate"|"currentBank"|"currentPitch"...), number) -> integer
Parameters
UnitIDunitID
(GenericMoveTypeNumberKey|"wantedHeight"|"accRate"|"decRate"|"turnRate"|"altitudeRate"|"currentBank"|"currentPitch"...)key
numbervalue
Returns
integernumAssignedValues

MoveCtrl.SetAirMoveTypeData (function) view source 

MoveCtrl.SetAirMoveTypeData(UnitID, StrafeAirMoveType) -> integer
Parameters
UnitIDunitID
StrafeAirMoveTypemoveType
Returns
integernumAssignedValues

MoveCtrl.SetAirMoveTypeData (function overload 1) view source 

MoveCtrl.SetAirMoveTypeData(UnitID, (GenericMoveTypeBooleanKey|"collide"|"useSmoothMesh"|"loopbackAttack"), boolean) -> integer
Parameters
UnitIDunitID
(GenericMoveTypeBooleanKey|"collide"|"useSmoothMesh"|"loopbackAttack")key
booleanvalue
Returns
integernumAssignedValues

MoveCtrl.SetAirMoveTypeData (function overload 2) view source 

MoveCtrl.SetAirMoveTypeData(UnitID, (GenericMoveTypeNumberKey|"wantedHeight"|"turnRadius"|"accRate"|"decRate"|"maxAcc"|"maxDec"|"maxBank"...), number) -> integer
Parameters
UnitIDunitID
(GenericMoveTypeNumberKey|"wantedHeight"|"turnRadius"|"accRate"|"decRate"|"maxAcc"|"maxDec"|"maxBank"...)key
numbervalue
Returns
integernumAssignedValues

MoveCtrl.SetAirMoveTypeData (function overload 3) view source 

MoveCtrl.SetAirMoveTypeData(UnitID, ("maneuverBlockTime"), integer) -> integer
Parameters
UnitIDunitID
("maneuverBlockTime")key
integervalue
Returns
integernumAssignedValues

MoveCtrl.SetGroundMoveTypeData (function) view source 

MoveCtrl.SetGroundMoveTypeData(UnitID, GroundMoveType) -> integer
Parameters
UnitIDunitID
GroundMoveTypemoveType
Returns
integernumAssignedValues

MoveCtrl.SetGroundMoveTypeData (function overload 1) view source 

MoveCtrl.SetGroundMoveTypeData(UnitID, (GenericMoveTypeBooleanKey|"atGoal"|"atEndOfPath"|"pushResistant"), boolean) -> integer
Parameters
UnitIDunitID
(GenericMoveTypeBooleanKey|"atGoal"|"atEndOfPath"|"pushResistant")key
booleanvalue
Returns
integernumAssignedValues

MoveCtrl.SetGroundMoveTypeData (function overload 2) view source 

MoveCtrl.SetGroundMoveTypeData(UnitID, (GenericMoveTypeNumberKey|"turnRate"|"turnAccel"|"accRate"|"decRate"|"myGravity"|"maxReverseDist"|"minReverseAngle"...), number) -> integer
Parameters
UnitIDunitID
(GenericMoveTypeNumberKey|"turnRate"|"turnAccel"|"accRate"|"decRate"|"myGravity"|"maxReverseDist"|"minReverseAngle"...)key
numbervalue
Returns
integernumAssignedValues

MoveCtrl.SetGroundMoveTypeData (function overload 3) view source 

MoveCtrl.SetGroundMoveTypeData(UnitID, ("minScriptChangeHeading"), integer) -> integer
Parameters
UnitIDunitID
("minScriptChangeHeading")key
integervalue
Returns
integernumAssignedValues

MoveCtrl.SetMoveDef (function) view source 

MoveCtrl.SetMoveDef(UnitID, (string|integer)) -> boolean
Parameters
UnitIDunitID
(string|integer)moveDef
Name or path type of the MoveDef.
Returns
booleansuccess
true if the MoveDef was set, false if unitID or moveDef were invalid, or if the unit does not support a MoveDef.

ObjectRenderingTable (class) view source

Members

ObjectRenderingTable.GetLODCount (function) view source

Get the number of LOD levels and the current LOD.
ObjectRenderingTable.GetLODCount(ObjectID) -> integer, integer
Parameters
ObjectIDobjectID
Returns
integerlodCount
integercurrentLOD

ObjectRenderingTable.SetLODCount (function) view source

Set the number of LOD levels.
ObjectRenderingTable.SetLODCount(ObjectID, integer) -> nil
Parameters
ObjectIDobjectID
integerlodCount
Returns
nil

ObjectRenderingTable.SetLODLength (function) view source

Set the LOD transition length for a given level.
ObjectRenderingTable.SetLODLength(ObjectID, integer, number) -> nil
Parameters
ObjectIDobjectID
integerlodLevel
numberlodLength
Returns
nil

ObjectRenderingTable.SetLODDistance (function) view source

Set the LOD transition distance for a given level (scaled for 45-degree FOV).
ObjectRenderingTable.SetLODDistance(ObjectID, integer, number) -> nil
Parameters
ObjectIDobjectID
integerlodLevel
numberlodDistance
Returns
nil

ObjectRenderingTable.SetPieceList (function) view source

Set a display list for a piece at a given LOD and material.
ObjectRenderingTable.SetPieceList(ObjectID, integer, integer, [any, ]*) -> nil
Parameters
ObjectIDobjectID
integerlodLevel
integerpiece
any...
Returns
nil

ObjectRenderingTable.GetMaterial (function) view source

Get a material reference for a LOD level.
ObjectRenderingTable.GetMaterial(ObjectID, integer, string) -> userdata
Parameters
ObjectIDobjectID
integerlodLevel
stringmaterialName
Returns
userdatamatRef

ObjectRenderingTable.SetMaterial (function) view source

Set a material for a LOD level.
ObjectRenderingTable.SetMaterial(ObjectID, integer, string, table) -> nil
Parameters
ObjectIDobjectID
integerlodLevel
stringmaterialName
tablematerialTable
Returns
nil

ObjectRenderingTable.SetMaterialLastLOD (function) view source

Set the last LOD level that uses a given material.
ObjectRenderingTable.SetMaterialLastLOD(ObjectID, string, integer) -> nil
Parameters
ObjectIDobjectID
stringmaterialName
integerlastLOD
Returns
nil

ObjectRenderingTable.SetMaterialDisplayLists (function) view source

Set display lists for a material.
ObjectRenderingTable.SetMaterialDisplayLists(ObjectID, integer, string, table) -> nil
Parameters
ObjectIDobjectID
integerlodLevel
stringmaterialName
tabledisplayListTable
Returns
nil

ObjectRenderingTable.SetDeferredMaterialUniform (function) view source 

ObjectRenderingTable.SetDeferredMaterialUniform(ObjectID, [any, ]*) -> nil
Parameters
ObjectIDobjectID
any...
uniform values
Returns
nil

ObjectRenderingTable.SetForwardMaterialUniform (function) view source 

ObjectRenderingTable.SetForwardMaterialUniform(ObjectID, [any, ]*) -> nil
Parameters
ObjectIDobjectID
any...
uniform values
Returns
nil

ObjectRenderingTable.ClearDeferredMaterialUniform (function) view source 

ObjectRenderingTable.ClearDeferredMaterialUniform(ObjectID, [any, ]*) -> nil
Parameters
ObjectIDobjectID
any...
uniform indices
Returns
nil

ObjectRenderingTable.ClearForwardMaterialUniform (function) view source 

ObjectRenderingTable.ClearForwardMaterialUniform(ObjectID, [any, ]*) -> nil
Parameters
ObjectIDobjectID
any...
uniform indices
Returns
nil

ObjectRenderingTable.SetUnitLuaDraw (function) view source

Enable or disable custom Lua drawing for a unit.
ObjectRenderingTable.SetUnitLuaDraw(UnitID, boolean) -> nil
Parameters
UnitIDunitID
booleanenable
Returns
nil

ObjectRenderingTable.SetFeatureLuaDraw (function) view source

Enable or disable custom Lua drawing for a feature.
ObjectRenderingTable.SetFeatureLuaDraw(FeatureID, boolean) -> nil
Parameters
FeatureIDfeatureID
booleanenable
Returns
nil

ObjectRenderingTable.SetProjectileLuaDraw (function) view source

Enable or disable custom Lua drawing for a projectile.
ObjectRenderingTable.SetProjectileLuaDraw(ProjectileID, boolean) -> nil
Parameters
ProjectileIDprojectileID
booleanenable
Returns
nil

ObjectRenderingTable.Debug (function) view source

Print debug info about the object’s material data.
ObjectRenderingTable.Debug(ObjectID) -> nil
Parameters
ObjectIDobjectID
Returns
nil

PlatformVideoMode (class) view source

Fields

integer displayview source
string displayNameview source
integer wview source
integer hview source
integer bppview source
integer hzview source

RBO (class) view source

User Data RBO

Fields

GL target
GL format
integer xsize
integer ysize
boolean valid
integer samples
will return globalRendering->msaaLevel for multisampled RBO or 0 otherwise

RmlUi.Context (class) view source

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:

Members

RmlUi.Context:AddEventListener (function) view source

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.
RmlUi.Context:AddEventListener(string, RmlUi.Element, boolean, boolean) -> nil
Parameters
stringevent
RmlUi.Elementscript
booleanelement_context
booleanin_capture_phase

RmlUi.Context:CreateDocument (function) view source

Creates a new document with the tag name of tag.
RmlUi.Context:CreateDocument(string) -> RmlUi.Document
Parameters
stringtag
Returns
RmlUi.Document

RmlUi.Context:LoadDocument (function) view source

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.
RmlUi.Context:LoadDocument(string) -> RmlUi.Document
Parameters
stringdocument_path
Returns
RmlUi.Document

RmlUi.Context:GetDocument (function) view source 

RmlUi.Context:GetDocument(string) -> nil
Parameters
stringname

RmlUi.Context:Render (function) view source

Renders the context.
RmlUi.Context:Render() -> boolean
Returns
boolean

RmlUi.Context:UnloadAllDocuments (function) view source

Closes all documents currently loaded with the context.
RmlUi.Context:UnloadAllDocuments() -> nil

RmlUi.Context:UnloadDocument (function) view source

Unloads a specific document within the context.
RmlUi.Context:UnloadDocument(RmlUi.Document) -> nil
Parameters
RmlUi.Documentdocument

RmlUi.Context:Update (function) view source

Updates the context.
RmlUi.Context:Update() -> boolean
Returns
boolean

RmlUi.Context:OpenDataModel (function) view source

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.
RmlUi.Context:OpenDataModel(string, T, table) -> RmlUi.SolLuaDataModel<T>
Parameters
stringname
Tmodel
tablewidget
Returns
RmlUi.SolLuaDataModel<T>

RmlUi.Context:RemoveDataModel (function) view source

Removes a data model from the context.
RmlUi.Context:RemoveDataModel(string) -> nil
Parameters
stringname

RmlUi.Context:ProcessMouseMove (function) view source

Processes a mouse move event.
RmlUi.Context:ProcessMouseMove(RmlUi.Vector2f) -> boolean
Parameters
RmlUi.Vector2fposition
Returns
boolean

RmlUi.Context:ProcessMouseButtonDown (function) view source

Processes a mouse button down event.
RmlUi.Context:ProcessMouseButtonDown(RmlUi.MouseButton, integer) -> boolean
Parameters
RmlUi.MouseButtonbutton
integerkey_modifier_state
Returns
boolean

RmlUi.Context:ProcessMouseButtonUp (function) view source

Processes a mouse button up event.
RmlUi.Context:ProcessMouseButtonUp(RmlUi.MouseButton, integer) -> boolean
Parameters
RmlUi.MouseButtonbutton
integerkey_modifier_state
Returns
boolean

RmlUi.Context:ProcessMouseWheel (function) view source

Processes a mouse wheel event.
RmlUi.Context:ProcessMouseWheel((RmlUi.Vector2f|number), integer) -> boolean
Parameters
(RmlUi.Vector2f|number)delta
integerkey_modifier_state
Returns
boolean

RmlUi.Context:ProcessMouseLeave (function) view source

Processes a mouse leave event.
RmlUi.Context:ProcessMouseLeave() -> boolean
Returns
boolean

RmlUi.Context:IsMouseInteracting (function) view source

Returns true if the mouse is currently interacting with the context, false if not.
RmlUi.Context:IsMouseInteracting() -> boolean
Returns
boolean

RmlUi.Context:ProcessKeyDown (function) view source

Processes a key down event.
RmlUi.Context:ProcessKeyDown(RmlUi.key_identifier, integer) -> boolean
Parameters
RmlUi.key_identifierkey
integerkey_modifier_state
Returns
boolean

RmlUi.Context:ProcessKeyUp (function) view source

Processes a key up event.
RmlUi.Context:ProcessKeyUp(RmlUi.key_identifier, integer) -> boolean
Parameters
RmlUi.key_identifierkey
integerkey_modifier_state
Returns
boolean

RmlUi.Context:ProcessTextInput (function) view source

Processes a text input event.
RmlUi.Context:ProcessTextInput(string) -> boolean
Parameters
stringtext
Returns
boolean

RmlUi.Context:EnableMouseCursor (function) view source

Enables or disables the mouse cursor for the context.
RmlUi.Context:EnableMouseCursor(boolean) -> nil
Parameters
booleanenable

RmlUi.Context:ActivateTheme (function) view source

Activates a theme for the context.
RmlUi.Context:ActivateTheme(string, boolean) -> nil
Parameters
stringtheme_name
booleanactivate

RmlUi.Context:IsThemeActive (function) view source

Returns true if the theme is active, false if not.
RmlUi.Context:IsThemeActive(string) -> boolean
Parameters
stringtheme_name
Returns
boolean

RmlUi.Context:GetElementAtPoint (function) view source

Returns the element at the point specified by point.
RmlUi.Context:GetElementAtPoint(RmlUi.Vector2f, RmlUi.Element?) -> RmlUi.Element
Parameters
RmlUi.Vector2fpoint
RmlUi.Element?ignore
Returns
RmlUi.Element

RmlUi.Context:PullDocumentToFront (function) view source

Pulls the document to the front of the context.
RmlUi.Context:PullDocumentToFront(RmlUi.Document) -> nil
Parameters
RmlUi.Documentdocument

RmlUi.Context:PushDocumentToBack (function) view source

Pushes the document to the back of the context.
RmlUi.Context:PushDocumentToBack(RmlUi.Document) -> nil
Parameters
RmlUi.Documentdocument

Fields

RmlUi.Vector2i dimensionsview source
number dp_ratioview source
RmlUi.Document[] documentsview source
RmlUi.Element focus_elementview source
RmlUi.Element hover_elementview source
string nameview source
RmlUi.Element root_elementview source

RmlUi.Document (class) view source

Inherits 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:

Members

RmlUi.Document:PullToFront (function) view source

Pulls the document in front of other documents within its context with a similar z-index.
RmlUi.Document:PullToFront() -> nil

RmlUi.Document:PushToBack (function) view source

Pushes the document behind other documents within its context with a similar z-index.
RmlUi.Document:PushToBack() -> nil

RmlUi.Document:Show (function) view source

Shows the document.
RmlUi.Document:Show(RmlUi.RmlModalFlag?, RmlUi.RmlFocusFlag?) -> nil
Parameters
RmlUi.RmlModalFlag?modal
Defaults to Focus
RmlUi.RmlFocusFlag?focus

RmlUi.Document:Hide (function) view source

Hides the document.
RmlUi.Document:Hide() -> nil

RmlUi.Document:Close (function) view source

Hides and closes the document, destroying its contents.
RmlUi.Document:Close() -> nil

RmlUi.Document:CreateElement (function) view source

Instances an element with a tag of tag_name.
RmlUi.Document:CreateElement(string) -> RmlUi.ElementPtr
Parameters
stringtag_name
Returns
RmlUi.ElementPtr

RmlUi.Document:CreateTextNode (function) view source

Instances a text element containing the string text.
RmlUi.Document:CreateTextNode(string) -> RmlUi.ElementPtr
Parameters
stringtext
Returns
RmlUi.ElementPtr

RmlUi.Document:ReloadStyleSheet (function) view source

Reload the active style sheet.
RmlUi.Document:ReloadStyleSheet(boolean?) -> nil
Parameters
boolean?load

RmlUi.Document:LoadInlineScript (function) view source

Load scripts as if it were in the script tag.
RmlUi.Document:LoadInlineScript(string, string?, integer?) -> nil
Parameters
stringcontent
string?source
integer?source_line

RmlUi.Document:LoadExternalScript (function) view source

Load an external script.
RmlUi.Document:LoadExternalScript(string) -> nil
Parameters
stringsource_path

RmlUi.Document:UpdateDocument (function) view source

Update the Document.
RmlUi.Document:UpdateDocument() -> nil

RmlUi.Document:AppendToStyleSheet (function) view source

Append text to style sheet.
RmlUi.Document:AppendToStyleSheet(string) -> nil
Parameters
stringcontent

Fields

string titleview source
RmlUi.Context contextview source
string urlview source
boolean modalview source
Is it modal?
table widgetview source
A table of data that can be accessed in onevent attributes. It doesn’t have to be a widget.

RmlUi.Element (class) view source

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.

Members

RmlUi.Element:AddEventListener (function) view source

Adds an event listener to the element.
RmlUi.Element:AddEventListener(string, (function|string), boolean) -> nil
Parameters
stringevent
(function|string)listener
booleanin_capture_phase

RmlUi.Element:AppendChild (function) view source

Appends element as a child to this element.
RmlUi.Element:AppendChild(RmlUi.ElementPtr) -> RmlUi.ElementPtr
Parameters
RmlUi.ElementPtrelement
Returns
RmlUi.ElementPtr

RmlUi.Element:Blur (function) view source

Removes input focus from this element.
RmlUi.Element:Blur() -> nil

RmlUi.Element:Click (function) view source

Fakes a click on this element.
RmlUi.Element:Click() -> nil

RmlUi.Element:DispatchEvent (function) view source

Dispatches an event to this element.
RmlUi.Element:DispatchEvent(string, table, string) -> boolean
Parameters
stringevent
tableparameters
stringinterruptible
Returns
boolean

RmlUi.Element:Focus (function) view source

Gives input focus to this element.
RmlUi.Element:Focus() -> nil

RmlUi.Element:GetAttribute (function) view source

Returns the value of the attribute named name. If no such attribute exists, the empty string will be returned.
RmlUi.Element:GetAttribute(string) -> string?
Parameters
stringname
Returns
string?

RmlUi.Element:GetElementById (function) view source

Returns the descendant element with an id of id.
RmlUi.Element:GetElementById(string) -> RmlUi.Element?
Parameters
stringid
Returns
RmlUi.Element?

RmlUi.Element:GetElementsByTagName (function) view source

Returns a list of all descendant elements with the tag of tag_name.
RmlUi.Element:GetElementsByTagName(string) -> RmlUi.ElementPtr[]
Parameters
stringtag_name
Returns
RmlUi.ElementPtr[]

RmlUi.Element:QuerySelector (function) view source

JQuery-like element selector
RmlUi.Element:QuerySelector(string) -> RmlUi.ElementPtr?
Parameters
stringquery
Returns
RmlUi.ElementPtr?

RmlUi.Element:QuerySelectorAll (function) view source

JQuery-like element selector
RmlUi.Element:QuerySelectorAll(string) -> RmlUi.ElementPtr[]
Parameters
stringselectors
Returns
RmlUi.ElementPtr[]

RmlUi.Element:Matches (function) view source

Checks if the current element matches the given RCSS selector(s).
RmlUi.Element:Matches(string) -> boolean
Parameters
stringselectors
Returns
boolean

RmlUi.Element:HasAttribute (function) view source

Returns True if the element has a value for the attribute named name, False if not.
RmlUi.Element:HasAttribute(string) -> boolean
Parameters
stringname
Returns
boolean

RmlUi.Element:HasChildNodes (function) view source

Returns True if the element has at least one child node, false if not.
RmlUi.Element:HasChildNodes() -> boolean
Returns
boolean

RmlUi.Element:InsertBefore (function) view source

Inserts the element element as a child of this element, directly before adjacent_element in the list of children.
RmlUi.Element:InsertBefore(RmlUi.ElementPtr, RmlUi.Element) -> RmlUi.Element?
Parameters
RmlUi.ElementPtrelement
RmlUi.Elementadjacent_element
Returns
RmlUi.Element?

RmlUi.Element:IsClassSet (function) view source

Returns true if the class name is set on the element, false if not.
RmlUi.Element:IsClassSet(string) -> boolean
Parameters
stringname
Returns
boolean

RmlUi.Element:RemoveAttribute (function) view source

Removes the attribute named name from the element.
RmlUi.Element:RemoveAttribute(string) -> nil
Parameters
stringname

RmlUi.Element:RemoveChild (function) view source

Removes the child element element from this element.
RmlUi.Element:RemoveChild(RmlUi.Element) -> boolean
Parameters
RmlUi.Elementelement
Returns
boolean

RmlUi.Element:ReplaceChild (function) view source

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.
RmlUi.Element:ReplaceChild(RmlUi.ElementPtr, RmlUi.Element) -> boolean
Parameters
RmlUi.ElementPtrinserted_element
RmlUi.Elementreplaced_element
Returns
boolean

RmlUi.Element:ScrollIntoView (function) view source

Scrolls this element into view if its ancestors have hidden overflow.
RmlUi.Element:ScrollIntoView(boolean) -> nil
Parameters
booleanalign_with_top

RmlUi.Element:SetAttribute (function) view source

Sets the value of the attribute named name to value.
RmlUi.Element:SetAttribute(string, string) -> nil
Parameters
stringname
stringvalue

RmlUi.Element:SetClass (function) view source

Sets (if value is true) or clears (if value is false) the class name on the element.
RmlUi.Element:SetClass(string, boolean) -> nil
Parameters
stringname
booleanvalue

RmlUi.Element:GetElementsByClassName (function) view source 

RmlUi.Element:GetElementsByClassName(string) -> RmlUi.Element[]
Parameters
stringclass_name
Returns
RmlUi.Element[]

RmlUi.Element:Clone (function) view source 

RmlUi.Element:Clone() -> RmlUi.ElementPtr
Returns
RmlUi.ElementPtr

RmlUi.Element:Closest (function) view source 

RmlUi.Element:Closest() -> RmlUi.Element?
Returns
RmlUi.Element?

RmlUi.Element:SetPseudoClass (function) view source 

RmlUi.Element:SetPseudoClass(string) -> nil
Parameters
stringclass_name

RmlUi.Element:IsPseudoClassSet (function) view source 

RmlUi.Element:IsPseudoClassSet(string) -> boolean
Parameters
stringclass_name
Returns
boolean

RmlUi.Element:ArePseudoCLassesSet (function) view source 

RmlUi.Element:ArePseudoCLassesSet(string[]) -> boolean
Parameters
string[]class_names
Returns
boolean

RmlUi.Element:GetActivePseudoCLasses (function) view source 

RmlUi.Element:GetActivePseudoCLasses() -> string[]
Returns
string[]

RmlUi.Element:IsPointWithinElement (function) view source

Is a screen-space point within this element?
RmlUi.Element:IsPointWithinElement(RmlUi.Vector2f) -> boolean
Parameters
RmlUi.Vector2fpoint
Returns
boolean

RmlUi.Element:ProcessDefaultAction (function) view source 

RmlUi.Element:ProcessDefaultAction(RmlUi.Event) -> nil
Parameters
RmlUi.Eventevent

RmlUi.Element:IsVisible (function) view source

True if the element is visible, false otherwise.
RmlUi.Element:IsVisible() -> boolean
Returns
boolean

RmlUi.Element:GetValue (function) view source

Get the value of this element.
RmlUi.Element:GetValue() -> (string|number|"")
Returns
(string|number|"")value
Returns number if it has the tag “input”, a string if it has the tag “textarea”, else an empty string.

RmlUi.Element:GetChild (function) view source 

RmlUi.Element:GetChild(integer) -> RmlUi.Element?
Parameters
integerindex
Returns
RmlUi.Element?

Fields

string class_nameview source
Name of the class.
string idview source
ID of this element, in the context of <span id=“foo”>.
string inner_rmlview source
Gets or sets the inner RML (markup) content of the element.
integer scroll_leftview source
Gets or sets the number of pixels that the content of the element is scrolled from the left.
integer scroll_topview source
Gets or sets the number of pixels that the content of the element is scrolled from the top.
RmlUi.ElementAttributesProxy attributesview source
Read-only. Proxy for accessing element attributes.
RmlUi.ElementChildNodesProxy child_nodesview source
Read-only. Proxy for accessing child nodes of the element.
integer client_leftview source
Read-only. The width of the left border of the element in pixels.
integer client_heightview source
Read-only. The inner height of the element in pixels, including padding but not the horizontal scrollbar height, border, or margin.
integer client_topview source
Read-only. The width of the top border of the element in pixels.
integer client_widthview source
Read-only. The inner width of the element in pixels, including padding but not the vertical scrollbar width, border, or margin.
RmlUi.Element? first_childview source
Read-only. The first child element, or nil if there are no children.
RmlUi.Element? last_childview source
Read-only. The last child element, or nil if there are no children.
RmlUi.Element? next_siblingview source
Read-only. The next sibling element, or nil if there is none.
integer offset_heightview source
Read-only. The height of the element including vertical padding and borders, in pixels.
integer offset_leftview source
Read-only. The distance from the inner left edge of the offset parent, in pixels.
RmlUi.Element offset_parentview source
Read-only. The closest positioned ancestor element.
integer offset_topview source
Read-only. The distance from the inner top edge of the offset parent, in pixels.
integer offset_widthview source
Read-only. The width of the element including horizontal padding and borders, in pixels.
RmlUi.Document owner_documentview source
Read-only. The document that owns this element.
RmlUi.Element? parent_nodeview source
Read-only. The parent node of this element, or nil if there is none.
RmlUi.Element? previous_siblingview source
Read-only. The previous sibling element, or nil if there is none.
integer scroll_heightview source
Read-only. The total height of the element’s content, including content not visible on the screen due to overflow.
integer scroll_widthview source
Read-only. The total width of the element’s content, including content not visible on the screen due to overflow.
RmlUi.ElementStyleProxy styleview source
Read-only. Proxy for accessing and modifying the element’s style properties.
string tag_nameview source
Read-only. The tag name of the element.
string addressview source
Read-only. The address of the element in the document tree.
integer absolute_leftview source
Read-only. The absolute left position of the element relative to the document.
integer absolute_topview source
Read-only. The absolute top position of the element relative to the document.
integer baselineview source
Read-only. The baseline position of the element.
integer line_heightview source
Read-only. The computed line height of the element.
boolean visibleview source
Read-only. True if the element is visible, false otherwise.
integer z_indexview source
Read-only. The computed z-index of the element.

RmlUi.ElementForm (class) view source

Inherits RmlUi.Element

Members

RmlUi.ElementForm:Submit (function) view source 

RmlUi.ElementForm:Submit(string?, string?) -> nil
Parameters
string?name
string?value

RmlUi.ElementFormControl (class) view source

Inherits RmlUi.Element

Fields

boolean disabledview source
string nameview source
string valueview source
boolean submittedview source

RmlUi.ElementFormControlInput (class) view source

Inherits RmlUi.Element RmlUi.ElementFormControl

Members

RmlUi.ElementFormControlInput:Select (function) view source

Selects all text.
RmlUi.ElementFormControlInput:Select() -> nil

RmlUi.ElementFormControlInput:SetSelection (function) view source

Selects the text in the given character range.
RmlUi.ElementFormControlInput:SetSelection(integer, integer) -> nil
Parameters
integerselection_start
The first character to be selected.
integerselection_end
The first character after the selection.

RmlUi.ElementFormControlInput:GetSelection (function) view source

Retrieves the selection range and text.
RmlUi.ElementFormControlInput:GetSelection() -> any
Returns
anyselection_start
The first character selected; selection_end The first character after the selection; selected_text The selected text.

Fields

boolean checkedview source
integer maxlengthview source
integer sizeview source
integer maxview source
integer minview source
integer stepview source

RmlUi.ElementFormControlSelect (class) view source

Inherits RmlUi.Element RmlUi.ElementFormControl

Members

RmlUi.ElementFormControlSelect:Add (function) view source 

RmlUi.ElementFormControlSelect:Add(RmlUi.Element, integer?) -> nil
Parameters
RmlUi.Elementelement
integer?before

RmlUi.ElementFormControlSelect:Remove (function) view source 

RmlUi.ElementFormControlSelect:Remove(integer) -> nil
Parameters
integerindex

RmlUi.ElementFormControlSelect:RemoveAll (function) view source 

RmlUi.ElementFormControlSelect:RemoveAll() -> nil

RmlUi.ElementFormControlTextArea (class) view source

Inherits RmlUi.Element RmlUi.ElementFormControl

Members

RmlUi.ElementFormControlTextArea:Select (function) view source

Selects all text.
RmlUi.ElementFormControlTextArea:Select() -> nil

RmlUi.ElementFormControlTextArea:SetSelection (function) view source

Selects the text in the given character range.
RmlUi.ElementFormControlTextArea:SetSelection(integer, integer) -> nil
Parameters
integerselection_start
The first character to be selected.
integerselection_end
The first character after the selection.

RmlUi.ElementFormControlTextArea:GetSelection (function) view source

Retrieves the selection range and text.
RmlUi.ElementFormControlTextArea:GetSelection() -> any
Returns
anyselection_start
The first character selected; selection_end The first character after the selection; selected_text The selected text.

Fields

integer colsview source
integer maxlengthview source
integer rowsview source
boolean wordwrapview source

RmlUi.ElementProgress (class) view source

Inherits RmlUi.Element

Fields

number valueview source
number maxview source

RmlUi.ElementPtr (class) view source

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.

RmlUi.ElementTabSet (class) view source

Inherits RmlUi.Element

Members

RmlUi.ElementTabSet:SetPanel (function) view source

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.
RmlUi.ElementTabSet:SetPanel(integer, string) -> nil
Parameters
integerindex
stringrml

RmlUi.ElementTabSet:SetTab (function) view source

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.
RmlUi.ElementTabSet:SetTab(integer, string) -> nil
Parameters
integerindex
stringrml

RmlUi.ElementTabSet:RemoveTab (function) view source 

RmlUi.ElementTabSet:RemoveTab(integer) -> nil
Parameters
integerindex

Fields

integer active_tabview source
integer num_tabsview source

RmlUi.ElementText (class) view source

Inherits RmlUi.Element

Fields

string textview source

RmlUi.Event (class) view source

An event that happens to an element.

Members

RmlUi.Event:StopPropagation (function) view source 

RmlUi.Event:StopPropagation() -> nil

RmlUi.Event:StopImmediatePropagation (function) view source 

RmlUi.Event:StopImmediatePropagation() -> nil

Fields

RmlUi.Element current_elementview source
string typeview source
RmlUi.Element target_elementview source
What element it happened to
RmlUi.EventParametersProxy parametersview source
RmlUi.RmlEventPhase event_phaseview source
boolean interruptibleview source
boolean propagatingview source
boolean immediate_propagatingview source

RmlUi.EventListener (class) view source

Event listener interface

Members

RmlUi.EventListener.OnAttach (function) view source 

RmlUi.EventListener.OnAttach(RmlUi.Element) -> nil
Parameters
RmlUi.Elementelement

RmlUi.EventListener.OnDetach (function) view source 

RmlUi.EventListener.OnDetach(RmlUi.Element) -> nil
Parameters
RmlUi.Elementelement

RmlUi.EventListener.ProcessEvent (function) view source 

RmlUi.EventListener.ProcessEvent(RmlUi.Event) -> nil
Parameters
RmlUi.Eventevent

RmlUi.SolLuaDataModel (class) view source

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.

Members

RmlUi.SolLuaDataModel:__SetDirty (function) view source

Set a table property dirty to trigger a rerender
RmlUi.SolLuaDataModel:__SetDirty(string) -> nil
Parameters
stringproperty

RmlUi.Vector2f (class) view source

Two-dimensional float vector

Members

RmlUi.Vector2f.new (function) view source 

RmlUi.Vector2f.new(number, number) -> RmlUi.Vector2f
Parameters
numberx
numbery
Returns
RmlUi.Vector2f

Fields

number xview source
number yview source
number magnitudeview source

RmlUi.Vector2i (class) view source

Two-dimensional integral vector.

Members

RmlUi.Vector2i.new (function) view source 

RmlUi.Vector2i.new(integer, integer) -> RmlUi.Vector2i
Parameters
integerx
integery
Returns
RmlUi.Vector2i

Fields

integer xview source
integer yview source
number magnitudeview source

RulesParams (class) view source

Inherits table<string,integer>

RulesSyncedCallins (class)

Inherits Callins UnsyncedCallins SyncedCallins

Callins that are sent to the synced lua file: LuaRules/main.lua

RulesUnsyncedCallins (class)

Inherits Callins UnsyncedCallins

Callins that are sent to the unsynced lua file: LuaRules/draw.lua

SunLightingParams (class) view source

The parameter table for sun lighting.

See Spring.SetSunLighting

Fields

number? specularExponent
number? groundShadowDensity
number? modelShadowDensity
rgba? groundAmbientColor
rgba? groundDiffuseColor
rgba? groundSpecularColor
rgba? unitAmbientColor
rgba? modelAmbientColor
rgba? unitDiffuseColor
rgba? modelDiffuseColor
rgba? unitSpecularColor
rgba? modelSpecularColor

TexCoords (class) view source

Fields

number x0
left coordinate in the normalized range
number x1
right coordinate in the normalized range
number y0
top coordinate in the normalized range
number y1
bottom coordinate in the normalized range
integer? atlasIndex
Means the atlas page number in case the texture is arrayed or points to another sequential texture in other rare cases

TextColorCode (class)

Indicator bytes representing color code operations during font rendering

Fields

string Color
Indicates that the following bytes contain color code information
string ColorAndOutline
Indicates that the following bytes contain color code and outline information
string Reset
Indicates reset of the current color

UI (class) view source

Inherits Callins

See Callins

Members

UI:ConfigureLayout (function) view source 

UI:ConfigureLayout() -> nil

UnitScriptTable (class) view source

UnitScript API — controls unit animation, piece visibility, and COB values. Accessed via Spring.UnitScript (synced only).

Members

UnitScriptTable.CreateScript (function) view source

Create a Lua unit script for the given unit, replacing any existing script.
UnitScriptTable.CreateScript(UnitID, table<string,function>) -> nil
Parameters
UnitIDunitID
table<string,function>callIns
Returns
nil

UnitScriptTable.UpdateCallIn (function) view source

Update or remove a callIn on a unit script.
UnitScriptTable.UpdateCallIn(UnitID, string, (function)?) -> nil
Parameters
UnitIDunitID
stringcallin
(function)?func
Returns
nil

UnitScriptTable.CallAsUnit (function) view source

Execute a function in the context of a unit’s script environment.
UnitScriptTable.CallAsUnit(UnitID, function, [any, ]*) -> any ...
Parameters
UnitIDunitID
functionfunc
any...
arguments passed to func
Returns
any ...values
returned by func

UnitScriptTable.GetUnitCOBValue (function) view source

Get a COB/script value for a unit (synced gadget API).
UnitScriptTable.GetUnitCOBValue(UnitID, integer, [number, ]*) -> integer
Parameters
UnitIDunitID
integerval
COB value ID (use COB constants)
number...
optional extra args for certain COB values
Returns
integervalue

UnitScriptTable.GetUnitValue (function) view source

Get a COB/script value. Must be called from within a UnitScript callin.
UnitScriptTable.GetUnitValue(integer) -> integer
Parameters
integerval
COB value ID (use COB constants)
Returns
integervalue

UnitScriptTable.SetUnitCOBValue (function) view source

Set a COB/script value for a unit (synced gadget API).
UnitScriptTable.SetUnitCOBValue(UnitID, integer, (boolean|integer)) -> nil
Parameters
UnitIDunitID
integerval
COB value ID (use COB constants)
(boolean|integer)param
value to set
Returns
nil

UnitScriptTable.SetUnitValue (function) view source

Set a COB/script value. Must be called from within a UnitScript callin.
UnitScriptTable.SetUnitValue(integer, (boolean|integer)) -> nil
Parameters
integerval
COB value ID (use COB constants)
(boolean|integer)param
value to set
Returns
nil

UnitScriptTable.SetPieceVisibility (function) view source

Set visibility of a piece. Must be called from within a UnitScript callin.
UnitScriptTable.SetPieceVisibility(integer, boolean) -> nil
Parameters
integerpiece
1-indexed piece number
booleanvisible
Returns
nil

UnitScriptTable.EmitSfx (function) view source

Emit a special effect at a piece. Must be called from within a UnitScript callin.
UnitScriptTable.EmitSfx(integer, (string|integer)) -> nil
Parameters
integerpiece
1-indexed piece number
(string|integer)type
SFX type constant or CEG name
Returns
nil

UnitScriptTable.AttachUnit (function) view source

Attach a unit to a piece of another unit.
UnitScriptTable.AttachUnit(integer, UnitID) -> nil
Parameters
integerpiece
1-indexed piece number
UnitIDtransporteeID
Returns
nil

UnitScriptTable.DropUnit (function) view source

Drop a transported unit.
UnitScriptTable.DropUnit(UnitID) -> nil
Parameters
UnitIDtransporteeID
Returns
nil

UnitScriptTable.Explode (function) view source

Explode a piece with the given flags.
UnitScriptTable.Explode(integer, integer) -> nil
Parameters
integerpiece
1-indexed piece number
integerflags
SFX explosion flags (bitfield)
Returns
nil

UnitScriptTable.ShowFlare (function) view source

Show a flare at a piece.
UnitScriptTable.ShowFlare(integer) -> nil
Parameters
integerpiece
1-indexed piece number
Returns
nil

UnitScriptTable.Spin (function) view source

Start spinning a piece around an axis.
UnitScriptTable.Spin(integer, integer, number, number?) -> nil
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
numberspeed
angular speed in radians/frame
number?accel
angular acceleration (Default: 0, instant)
Returns
nil

UnitScriptTable.StopSpin (function) view source

Stop spinning a piece.
UnitScriptTable.StopSpin(integer, integer, number?) -> nil
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
number?decel
angular deceleration (Default: 0, instant)
Returns
nil

UnitScriptTable.Turn (function) view source

Turn a piece to an angle. If speed is 0 or omitted, turns instantly.
UnitScriptTable.Turn(integer, integer, number, number?) -> nil
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
numberdestination
target angle in radians
number?speed
angular speed (Default: 0, instant)
Returns
nil

UnitScriptTable.Move (function) view source

Move a piece along an axis. If speed is 0 or omitted, moves instantly.
UnitScriptTable.Move(integer, integer, number, number?) -> nil
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
numberdestination
target position
number?speed
movement speed (Default: 0, instant)
Returns
nil

UnitScriptTable.Scale (function) view source

Scale a piece. If speed is 0 or omitted, scales instantly.
UnitScriptTable.Scale(integer, number, number?) -> nil
Parameters
integerpiece
1-indexed piece number
numberdestination
target scale factor
number?speed
scaling speed (Default: 0, instant)
Returns
nil

UnitScriptTable.IsInTurn (function) view source

Check if a piece is currently turning.
UnitScriptTable.IsInTurn(integer, integer) -> boolean
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
Returns
boolean

UnitScriptTable.IsInMove (function) view source

Check if a piece is currently moving.
UnitScriptTable.IsInMove(integer, integer) -> boolean
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
Returns
boolean

UnitScriptTable.IsInSpin (function) view source

Check if a piece is currently spinning.
UnitScriptTable.IsInSpin(integer, integer) -> boolean
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
Returns
boolean

UnitScriptTable.IsInScale (function) view source

Check if a piece is currently scaling.
UnitScriptTable.IsInScale(integer) -> boolean
Parameters
integerpiece
1-indexed piece number
Returns
boolean

UnitScriptTable.WaitForTurn (function) view source

Check whether the calling thread needs to wait for a turn to finish.
UnitScriptTable.WaitForTurn(integer, integer) -> boolean
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
Returns
booleanneedsWait

UnitScriptTable.WaitForMove (function) view source

Check whether the calling thread needs to wait for a move to finish.
UnitScriptTable.WaitForMove(integer, integer) -> boolean
Parameters
integerpiece
1-indexed piece number
integeraxis
axis (1=x, 2=y, 3=z)
Returns
booleanneedsWait

UnitScriptTable.WaitForScale (function) view source

Check whether the calling thread needs to wait for a scale to finish.
UnitScriptTable.WaitForScale(integer) -> boolean
Parameters
integerpiece
1-indexed piece number
Returns
booleanneedsWait

UnitScriptTable.SetDeathScriptFinished (function) view source

Signal that the Killed callin has finished. Must be called from Killed.
UnitScriptTable.SetDeathScriptFinished(integer?) -> nil
Parameters
integer?wreckLevel
(Default: -1)
Returns
nil

UnitScriptTable.GetPieceTranslation (function) view source

Get the local translation of a piece relative to its rest position.
UnitScriptTable.GetPieceTranslation(integer) -> number, number, number
Parameters
integerpiece
1-indexed piece number
Returns
numberx
numbery
numberz

UnitScriptTable.GetPieceRotation (function) view source

Get the rotation of a piece in radians.
UnitScriptTable.GetPieceRotation(integer) -> number, number, number
Parameters
integerpiece
1-indexed piece number
Returns
numberrx
numberry
numberrz

UnitScriptTable.GetPieceScale (function) view source

Get the scale factor of a piece.
UnitScriptTable.GetPieceScale(integer) -> number
Parameters
integerpiece
1-indexed piece number
Returns
numberscale

UnitScriptTable.GetPiecePosDir (function) view source

Get the world-space emit position and direction of a piece.
UnitScriptTable.GetPiecePosDir(integer) -> number, number, number, number, number, number
Parameters
integerpiece
1-indexed piece number
Returns
numberposX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ

UnitScriptTable.GetActiveUnitID (function) view source

Get the unit ID of the currently executing unit script.
UnitScriptTable.GetActiveUnitID() -> UnitID?
Returns
UnitID?unitID

VAO (class) view source

Vertex Array Object

See LuaVAO.GetVAO, rts/Lua/LuaVAOImpl.cpp

Members

VAO:Delete (function) view source 

VAO:Delete() -> nil
Returns
nil

VAO:AttachVertexBuffer (function) view source

Attaches a VBO to be used as a vertex buffer
VAO:AttachVertexBuffer(VBO) -> nil
Parameters
VBOvbo
Returns
nil

VAO:AttachInstanceBuffer (function) view source

Attaches a VBO to be used as an instance buffer
VAO:AttachInstanceBuffer(VBO) -> nil
Parameters
VBOvbo
Returns
nil

VAO:AttachIndexBuffer (function) view source

Attaches a VBO to be used as an index buffer
VAO:AttachIndexBuffer(VBO) -> nil
Parameters
VBOvbo
Returns
nil

VAO:DrawArrays (function) view source 

VAO:DrawArrays(GL, integer?, integer?, integer?, integer?) -> nil
Parameters
GLglEnum
primitivesMode
integer?vertexCount
integer?vertexFirst
integer?instanceCount
integer?instanceFirst
Returns
nil

VAO:DrawElements (function) view source 

VAO:DrawElements(GL, integer?, integer?, integer?, integer?, integer?) -> nil
Parameters
GLglEnum
primitivesMode
integer?drawCount
integer?baseIndex
integer?instanceCount
integer?baseVertex
integer?baseInstance
Returns
nil

VAO:AddUnitsToSubmission (function) view source 

VAO:AddUnitsToSubmission((UnitID|UnitID[])) -> integer
Parameters
(UnitID|UnitID[])unitIDs
Returns
integersubmittedCount

VAO:AddFeaturesToSubmission (function) view source 

VAO:AddFeaturesToSubmission((FeatureID|FeatureID[])) -> integer
Parameters
(FeatureID|FeatureID[])featureIDs
Returns
integersubmittedCount

VAO:AddUnitDefsToSubmission (function) view source 

VAO:AddUnitDefsToSubmission((UnitDefID|UnitDefID[])) -> integer
Parameters
(UnitDefID|UnitDefID[])unitDefIDs
Returns
integersubmittedCount

VAO:AddFeatureDefsToSubmission (function) view source 

VAO:AddFeatureDefsToSubmission((FeatureDefID|FeatureDefID[])) -> integer
Parameters
(FeatureDefID|FeatureDefID[])featureDefIDs
Returns
integersubmittedCount

VAO:RemoveFromSubmission (function) view source 

VAO:RemoveFromSubmission(integer) -> nil
Parameters
integerindex
Returns
nil

VAO:Submit (function) view source 

VAO:Submit() -> nil
Returns
nil

VBO (class) view source

Vertex Buffer Object

See LuaVBO.GetVBO, rts/Lua/LuaVBOImpl.cpp

Members

VBO:Delete (function) view source 

VBO:Delete() -> nil
Returns
nil

VBO:Define (function) view source

Specify the kind of VBO you will be using.

lua 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:

lua {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.

See GL.OpenGL_Data_Types, VBO:Upload

VBO:Define(integer, (integer|VBOAttributeDef[])) -> nil
Parameters
integersize
The maximum number of elements this VBO can have.
(integer|VBOAttributeDef[])attribs
When integer, the maximum number of elements this VBO can have. Otherwise, an array of arrays specifying the layout.
Returns
nil

VBO:GetBufferSize (function) view source 

VBO:GetBufferSize() -> integer, integer, integer
Returns
integerelementsCount
integerbufferSizeInBytes
integersize

VBO:Upload (function) view source

Uploads data into the VBO.

If attributeIndex is 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.

See VBO:Define

VBO:Upload(number[], integer?, integer?, integer?, integer?) -> number[], integer, (integer|(integer,integer,integer,integer))
Parameters
number[]vboData
Array of values to upload into the VBO.
integer?attributeIndex
(Default: -1) The attribute to upload to, or all attributes.
integer?elemOffset
(Default: 0) The index in destination VBO (on GPU) at which storing begins.
integer?luaStartIndex
(Default: 1) The index of vboData at which copying begins.
integer?luaFinishIndex
(Default: #vboData) The index of vboData at which copying ends.
Returns
number[]indexData
integerelemOffset
(integer|(integer,integer,integer,integer))attrID

VBO:Download (function) view source 

VBO:Download(integer?, integer?, integer?, boolean?) -> number[]
Parameters
integer?attributeIndex
(Default: -1) When supplied with non-default value: only data from specified attribute will be downloaded - otherwise all attributes are downloaded.
integer?elementOffset
(Default: 0) download data starting from this element
integer?elementCount
number of elements to download
boolean?forceGPURead
(Default: false) Force downloading the data from GPU buffer as opposed to using shadow RAM buffer.
Returns
number[]vboData

VBO:ModelsVBO (function) view source

Binds engine side vertex or index VBO containing models (units, features) data.

Also fills in VBO definition data as they’re set for engine models (no need to do VBO:Define()).

VBO:ModelsVBO() -> integer?
Returns
integer?size
buffer size in bytes

VBO:InstanceDataFromUnitDefIDs (function) view source

Fills in attribute data for each specified unitDefID

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 such as palette index and number of pieces.

Data Layout: SInstanceData: , traOffset{ matOffset_ } // updated during the following draw frames , uniOffset{ uniOffset_ } // updated during the following draw frames , info{ paletteIndex, numPieces } // not updated during the following draw frames , aux1 { 0u } 

VBO:InstanceDataFromUnitDefIDs((UnitDefID|UnitDefID[]), integer, integer?, integer?) -> (integer,integer,integer,integer), integer, integer
Parameters
(UnitDefID|UnitDefID[])unitDefIDs
integerattrID
integer?teamIdOpt
integer?elementOffset
Returns
(integer,integer,integer,integer)instanceData
integerelementOffset
integerattrID

VBO:InstanceDataFromFeatureDefIDs (function) view source

Fills in attribute data for each specified featureDefID

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 such as palette index and number of pieces.

Data Layout SInstanceData: , traOffset{ matOffset_ } // updated during the following draw frames , uniOffset{ uniOffset_ } // updated during the following draw frames , info{ paletteIndex, numPieces } // not updated during the following draw frames , aux1 { 0u } 

VBO:InstanceDataFromFeatureDefIDs((FeatureDefID|FeatureDefID[]), integer, integer?, integer?) -> (integer,integer,integer,integer), integer, integer
Parameters
(FeatureDefID|FeatureDefID[])featureDefIDs
integerattrID
integer?teamIdOpt
integer?elementOffset
Returns
(integer,integer,integer,integer)instanceData
integerelementOffset
integerattrID

VBO:InstanceDataFromUnitIDs (function) view source

Fills in attribute data for each specified unitID

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 such as palette index and number of pieces.

Data Layout

SInstanceData: , traOffset{ matOffset_ } // updated during the following draw frames , uniOffset{ uniOffset_ } // updated during the following draw frames , info{ paletteIndex, numPieces } // not updated during the following draw frames , aux1 { 0u } 

VBO:InstanceDataFromUnitIDs((UnitID|UnitID[]), integer, integer?, integer?) -> (integer,integer,integer,integer), integer, integer
Parameters
(UnitID|UnitID[])unitIDs
integerattrID
integer?teamIdOpt
integer?elementOffset
Returns
(integer,integer,integer,integer)instanceData
integerelementOffset
integerattrID

VBO:InstanceDataFromFeatureIDs (function) view source

Fills in attribute data for each specified featureID

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 such as palette index and number of pieces.

VBO:InstanceDataFromFeatureIDs((FeatureID|FeatureID[]), integer, integer?, integer?) -> (integer,integer,integer,integer), integer, integer
Parameters
(FeatureID|FeatureID[])featureIDs
integerattrID
integer?teamIdOpt
integer?elementOffset
Returns
(integer,integer,integer,integer)instanceData
integerelementOffset
integerattrID

VBO:MatrixDataFromProjectileIDs (function) view source 

VBO:MatrixDataFromProjectileIDs((ProjectileID|ProjectileID[]), integer, integer?, integer?) -> number[], integer, (integer|(integer,integer,integer,integer))
Parameters
(ProjectileID|ProjectileID[])projectileIDs
integerattrID
integer?teamIdOpt
integer?elementOffset
Returns
number[]matDataVec
Flattened 4x4 matrix(es)
integerelemOffset
(integer|(integer,integer,integer,integer))attrID

VBO:BindBufferRange (function) view source

Bind a range within a buffer object to an indexed buffer target

Generally mimics https://registry.khronos.org/OpenGL-Refpages/gl4/html/glBindBufferRange.xhtml except offset and size are specified in number of elements / element indices.

VBO:BindBufferRange(integer, integer?, integer?, GL?) -> integer
Parameters
integerindex
Should be in the range between 5 < index < GL_MAX_UNIFORM_BUFFER_BINDINGS value (usually 31).
integer?elementOffset
integer?elementCount
GL?target
glEnum
Returns
integerbindingIndex
when successful, -1 otherwise

VBO:UnbindBufferRange (function) view source 

VBO:UnbindBufferRange(integer, integer?, integer?, GL?) -> integer
Parameters
integerindex
integer?elementOffset
integer?elementCount
GL?target
glEnum
Returns
integerbindingIndex
when successful, -1 otherwise

VBO:DumpDefinition (function) view source

Logs the definition of the VBO to the console
VBO:DumpDefinition() -> nil
Returns
nil

VBO:CopyTo (function) view source

Copy the contents of the VBO to another VBO.

Destination VBO is expected to have sufficient allocation size, otherwise the copying will gracefully fail.

VBO:CopyTo(VBO, integer) -> boolean
Parameters
VBOdestVBO
integercopySizeInBytes
Returns
booleansuccess

VBO:GetID (function) view source

Gets the OpenGL Buffer ID
VBO:GetID() -> integer
Returns
integerbufferID

rgb (class)

Color triple (RGB)

Fields

number [1]
Red value.
number [2]
Green value.
number [3]
Blue value.

rgba (class)

Color quadruple (RGBA)

Fields

number [1]
Red value.
number [2]
Green value.
number [3]
Blue value.
number [4]
Alpha value.

xy (class)

Cartesian double (XY)

Fields

number [1]
x
number [2]
y

xyz (class)

Cartesian triple (XYZ)

Fields

number [1]
x
number [2]
y
number [3]
z

xyzw (class)

Cartesian quadruple (XYZW)

Fields

number [1]
x
number [2]
y
number [3]
z
number [4]
w

CMD (enum) view source

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.

See Spring.GiveOrderToUnit, Spring.GiveOrderArrayToUnitArray, Spring.GetUnitCurrentCommand, Callins:AllowCommand

128 OPT_ALTview source
64 OPT_CTRLview source
32 OPT_SHIFTview source
16 OPT_RIGHTview source
8 OPT_INTERNALview source
4 OPT_METAview source
-1 MOVESTATE_NONEview source
0 MOVESTATE_HOLDPOSview source
1 MOVESTATE_MANEUVERview source
2 MOVESTATE_ROAMview source
-1 FIRESTATE_NONEview source
0 FIRESTATE_HOLDFIREview source
1 FIRESTATE_RETURNFIREview source
2 FIRESTATE_FIREATWILLview source
3 FIRESTATE_FIREATNEUTRALview source
1 WAITCODE_TIMEview source
2 WAITCODE_DEATHview source
3 WAITCODE_SQUADview source
4 WAITCODE_GATHERview source
0 STOPview source

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.

1 INSERTview source
2 REMOVEview source

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: lua Spring.GiveOrderToUnit(unitID, CMD.REMOVE, CMD.ATTACK)

Delete all attack and fight orders from unit, or factory rally queue if factory: lua Spring.GiveOrderToUnit(unitID, CMD.REMOVE, {CMD.ATTACK, CMD.FIGHT}, CMD.OPT_ALT)

Delete commands with specific tags: lua Spring.GiveOrderToUnit(unitID, CMD.REMOVE, {tag1, tag2, tag3})

Delete all commands to build units with UnitDef ids unitDefId1 and unitDefId2 from factory queue: lua Spring.GiveOrderToUnit(unitID, CMD.REMOVE, {-unitDefId1, -unitDefId2}, CMD.OPT_ALT + CMD.OPT_CTRL)

5 WAITview source

Makes the unit suspend processing its command queue until wait is removed.

Accepts no parameters.

6 TIMEWAITview source

Makes the unit suspend processing its command queue for a given duration.

  • params {duration} Time to wait in seconds.
7 DEATHWAITview source

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}.
8 SQUADWAITview source

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.
9 GATHERWAITview source

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.

10 MOVEview source
15 PATROLview source
16 FIGHTview source
20 ATTACKview source

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. lua Spring.GiveOrderToUnit(unitID, CMD.ATTACK, targetID)

Area attack of radius 50 at map position 1000,1000 with height 100: lua Spring.GiveOrderToUnit(unitID, CMD.ATTACK, {1000,100,1000,50})

Ground attack at map position 1000,1000 with height 100: lua Spring.GiveOrderToUnit(unitID, CMD.ATTACK, {1000,100,1000})

21 AREA_ATTACKview source
25 GUARDview source
35 GROUPSELECTview source
36 GROUPADDview source
37 GROUPCLEARview source
40 REPAIRview source
45 FIRE_STATEview source
50 MOVE_STATEview source
55 SETBASEview source
60 INTERNALview source
65 SELFDview source
75 LOAD_UNITSview source
76 LOAD_ONTOview source
80 UNLOAD_UNITSview source
81 UNLOAD_UNITview source
85 ONOFFview source
90 RECLAIMview source
95 CLOAKview source
100 STOCKPILEview source
105 MANUALFIREview source
105 DGUNview source
110 RESTOREview source
115 REPEATview source
120 TRAJECTORYview source
125 RESURRECTview source
130 CAPTUREview source
135 AUTOREPAIRLEVELview source
20 LOOPBACKATTACKview source
145 IDLEMODEview source

CMDTYPE (enum) view source

Command type constants

Note, the CMDTYPE[] table is bidirectional. That means: CMDTYPE[CMDTYPE.ICON] := “CMDTYPE_ICON”

integer ICONview source
Expect 0 parameters in return.
integer ICON_MODEview source
Expect 1 parameter in return (number selected mode).
integer ICON_MAPview source
Expect 3 parameters in return (mappos).
integer ICON_AREAview source
Expect 4 parameters in return (mappos+radius).
integer ICON_UNITview source
Expect 1 parameters in return (unitid).
integer ICON_UNIT_OR_MAPview source
Expect 1 parameters in return (unitid) or 3 parameters in return (mappos).
integer ICON_FRONTview source
Expect 3 or 6 parameters in return (middle and right side of front if a front was defined).
integer ICON_UNIT_OR_AREAview source
Expect 1 parameter in return (unitid) or 4 parameters in return (mappos+radius).
integer NEXTview source
Expect command page used with CMD_INTERNAL.
integer PREVview source
Expect command page used with CMD_INTERNAL.
integer ICON_UNIT_FEATURE_OR_AREAview source
Expect 1 parameter in return (unitid or Game.maxUnits+featureid) or 4 parameters in return (mappos+radius).
integer ICON_BUILDINGview source
Expect 3 parameters in return (mappos).
integer CUSTOMview source
Expect with CMD_INTERNAL.
integer ICON_UNIT_OR_RECTANGLEview source
Expect 1 parameter in return (unitid) or 3 parameters in return (mappos) or 6 parameters in return (startpos+endpos).
integer NUMBERview source
Expect 1 parameter in return (number).

COB (enum) view source

COB constants
integer ACTIVATIONview source
integer STANDINGMOVEORDERSview source
integer STANDINGFIREORDERSview source
integer HEALTHview source
integer INBUILDSTANCEview source
integer BUSYview source
integer PIECE_XZview source
integer PIECE_Yview source
integer UNIT_XZview source
integer UNIT_Yview source
integer UNIT_HEIGHTview source
integer XZ_ATANview source
integer XZ_HYPOTview source
integer ATANview source
integer HYPOTview source
integer GROUND_HEIGHTview source
integer BUILD_PERCENT_LEFTview source
integer YARD_OPENview source
integer BUGGER_OFFview source
integer ARMOREDview source
integer IN_WATERview source
integer CURRENT_SPEEDview source
integer VETERAN_LEVELview source
integer ON_ROADview source
integer MAX_IDview source
integer MY_IDview source
integer UNIT_TEAMview source
integer UNIT_BUILD_PERCENT_LEFTview source
integer UNIT_ALLIEDview source
integer MAX_SPEEDview source
integer CLOAKEDview source
integer WANT_CLOAKview source
integer GROUND_WATER_HEIGHTview source
integer UPRIGHTview source
integer POWview source
integer PRINTview source
integer HEADINGview source
integer TARGET_IDview source
integer LAST_ATTACKER_IDview source
integer LOS_RADIUSview source
integer AIR_LOS_RADIUSview source
integer RADAR_RADIUSview source
integer JAMMER_RADIUSview source
integer SONAR_RADIUSview source
integer SONAR_JAM_RADIUSview source
integer SEISMIC_RADIUSview source
integer DO_SEISMIC_PINGview source
integer CURRENT_FUELview source
integer TRANSPORT_IDview source
integer SHIELD_POWERview source
integer STEALTHview source
integer CRASHINGview source
integer CHANGE_TARGETview source
integer CEG_DAMAGEview source
integer COB_IDview source
integer PLAY_SOUNDview source
integer KILL_UNITview source
integer SET_WEAPON_UNIT_TARGETview source
integer SET_WEAPON_GROUND_TARGETview source
integer SONAR_STEALTHview source
integer REVERSINGview source
integer FLANK_B_MODEview source
integer FLANK_B_DIRview source
integer FLANK_B_MOBILITY_ADDview source
integer FLANK_B_MAX_DAMAGEview source
integer FLANK_B_MIN_DAMAGEview source
integer WEAPON_RELOADSTATEview source
integer WEAPON_RELOADTIMEview source
integer WEAPON_ACCURACYview source
integer WEAPON_SPRAYview source
integer WEAPON_RANGEview source
integer WEAPON_PROJECTILE_SPEEDview source
integer MINview source
integer MAXview source
integer ABSview source
integer GAME_FRAMEview source
integer PIECE_HEADINGview source
integer PIECE_PITCHview source

LOG (enum) view source

See Spring.Log

20 DEBUGview source
30 INFOview source
35 NOTICEview source
Engine default.
37 DEPRECATEDview source
40 WARNINGview source
50 ERRORview source
60 FATALview source

READY_MESSAGE (enum) view source

"Waiting for players" WAITINGview source
"Waiting for players, press key to force start" HOST_WAITINGview source
when waiting and currently the host, key is the first key bound to the action forcestart
"Choose start pos" CHOOSE_POSview source
when current player is not ready and is not a spectator
"Starting in n" STARTINGview source
where n is the number of seconds

READY_STATE (enum) view source

"missing" MISSINGview source
when the player hasn’t joined yet (NETMSG_PLAYERNAME wasn’t received)
"ready" READYview source
"notready" NOT_READYview source

RmlUi.RmlEventPhase (enum) view source

integer Noneview source
integer Captureview source
integer Targetview source
integer Bubbleview source

RmlUi.RmlFocusFlag (enum) view source

integer Noneview source
integer Documentview source
integer Keepview source
integer Autoview source

RmlUi.RmlModalFlag (enum) view source

integer Noneview source
integer Modalview source
integer Keepview source

RmlUi.default_action_phase (enum) view source

integer Autoview source
integer Targetview source
integer TargetAndBubbleview source

RmlUi.font_weight (enum) view source

integer Autoview source
integer Normalview source
integer Boldview source

RmlUi.key_identifier (enum) view source

integer 0view source
integer 1view source
integer 2view source
integer 3view source
integer 4view source
integer 5view source
integer 6view source
integer 7view source
integer 8view source
integer 9view source
integer UNKNOWNview source
integer SPACEview source
integer Aview source
integer Bview source
integer Cview source
integer Dview source
integer Eview source
integer Fview source
integer Gview source
integer Hview source
integer Iview source
integer Jview source
integer Kview source
integer Lview source
integer Mview source
integer Nview source
integer Oview source
integer Pview source
integer Qview source
integer Rview source
integer Sview source
integer Tview source
integer Uview source
integer Vview source
integer Wview source
integer Xview source
integer Yview source
integer Zview source
integer OEM_1view source
integer OEM_PLUSview source
integer OEM_COMMAview source
integer OEM_MINUSview source
integer OEM_PERIODview source
integer OEM_2view source
integer OEM_3view source
integer OEM_4view source
integer OEM_5view source
integer OEM_6view source
integer OEM_7view source
integer OEM_8view source
integer OEM_102view source
integer NUMPAD0view source
integer NUMPAD1view source
integer NUMPAD2view source
integer NUMPAD3view source
integer NUMPAD4view source
integer NUMPAD5view source
integer NUMPAD6view source
integer NUMPAD7view source
integer NUMPAD8view source
integer NUMPAD9view source
integer NUMPADENTERview source
integer MULTIPLYview source
integer ADDview source
integer SEPARATORview source
integer SUBTRACTview source
integer DECIMALview source
integer DIVIDEview source
integer OEM_NEC_EQUALview source
integer BACKview source
integer TABview source
integer CLEARview source
integer RETURNview source
integer PAUSEview source
integer CAPITALview source
integer KANAview source
integer HANGULview source
integer JUNJAview source
integer FINALview source
integer HANJAview source
integer KANJIview source
integer ESCAPEview source
integer CONVERTview source
integer NONCONVERTview source
integer ACCEPTview source
integer MODECHANGEview source
integer PRIORview source
integer NEXTview source
integer ENDview source
integer HOMEview source
integer LEFTview source
integer UPview source
integer RIGHTview source
integer DOWNview source
integer SELECTview source
integer PRINTview source
integer EXECUTEview source
integer SNAPSHOTview source
integer INSERTview source
integer DELETEview source
integer HELPview source
integer LWINview source
integer RWINview source
integer APPSview source
integer POWERview source
integer SLEEPview source
integer WAKEview source
integer F1view source
integer F2view source
integer F3view source
integer F4view source
integer F5view source
integer F6view source
integer F7view source
integer F8view source
integer F9view source
integer F10view source
integer F11view source
integer F12view source
integer F13view source
integer F14view source
integer F15view source
integer F16view source
integer F17view source
integer F18view source
integer F19view source
integer F20view source
integer F21view source
integer F22view source
integer F23view source
integer F24view source
integer NUMLOCKview source
integer SCROLLview source
integer OEM_FJ_JISHOview source
integer OEM_FJ_MASSHOUview source
integer OEM_FJ_TOUROKUview source
integer OEM_FJ_LOYAview source
integer OEM_FJ_ROYAview source
integer LSHIFTview source
integer RSHIFTview source
integer LCONTROLview source
integer RCONTROLview source
integer LMENUview source
integer RMENUview source
integer BROWSER_BACKview source
integer BROWSER_FORWARDview source
integer BROWSER_REFRESHview source
integer BROWSER_STOPview source
integer BROWSER_SEARCHview source
integer BROWSER_FAVORITESview source
integer BROWSER_HOMEview source
integer VOLUME_MUTEview source
integer VOLUME_DOWNview source
integer VOLUME_UPview source
integer MEDIA_NEXT_TRACKview source
integer MEDIA_PREV_TRACKview source
integer MEDIA_STOPview source
integer MEDIA_PLAY_PAUSEview source
integer LAUNCH_MAILview source
integer LAUNCH_MEDIA_SELECTview source
integer LAUNCH_APP1view source
integer LAUNCH_APP2view source
integer OEM_AXview source
integer ICO_HELPview source
integer ICO_00view source
integer PROCESSKEYview source
integer ICO_CLEARview source
integer ATTNview source
integer CRSELview source
integer EXSELview source
integer EREOFview source
integer PLAYview source
integer ZOOMview source
integer PA1view source
integer OEM_CLEARview source

RmlUi.key_modifier (enum) view source

integer CTRLview source
integer SHIFTview source
integer ALTview source
integer METAview source
integer CAPSLOCKview source
integer NUMLOCKview source
integer SCROLLLOCKview source

SFX (enum) view source

integer SHATTERview source
Piece flag for Spring.UnitScript.Explode.
integer EXPLODEview source
Piece flag for Spring.UnitScript.Explode.
integer EXPLODE_ON_HITview source
Piece flag for Spring.UnitScript.Explode.
integer FALLview source
Piece flag for Spring.UnitScript.Explode.
integer SMOKEview source
Piece flag for Spring.UnitScript.Explode.
integer FIREview source
Piece flag for Spring.UnitScript.Explode.
integer NONEview source
Piece flag for Spring.UnitScript.Explode.
integer NO_CEG_TRAILview source
Piece flag for Spring.UnitScript.Explode.
integer NO_HEATCLOUDview source
Piece flag for Spring.UnitScript.Explode.
integer RECURSIVEview source
Piece flag for Spring.UnitScript.Explode.
integer VTOLview source
Piece flag for Spring.UnitScript.EmitSfx.
integer WAKEview source
Piece flag for Spring.UnitScript.EmitSfx.
integer REVERSE_WAKEview source
Piece flag for Spring.UnitScript.EmitSfx.
integer WHITE_SMOKEview source
Piece flag for Spring.UnitScript.EmitSfx.
integer BLACK_SMOKEview source
Piece flag for Spring.UnitScript.EmitSfx.
integer BUBBLEview source
Piece flag for Spring.UnitScript.EmitSfx.
integer CEGview source
Piece flag for Spring.UnitScript.EmitSfx.
integer FIRE_WEAPONview source
Piece flag for Spring.UnitScript.EmitSfx.
integer DETONATE_WEAPONview source
Piece flag for Spring.UnitScript.EmitSfx.
integer GLOBALview source
Piece flag for Spring.UnitScript.EmitSfx.

CMD (field)

CMDTYPE (field)

COB (field)

COBSCALE (field) view source

LOG (field)

LosMask (field)

LuaFont (field)

ProjectileTargetType (field)

READY_MESSAGE (field)

READY_STATE (field)

SFX (field)

SYNCED (field) view source

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.

VAO (field)

Encoding (table) view source

Lua Encoding API

Members

Encoding.DecodeBase64 (function) view source

Decodes a base64 string

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

Encoding.DecodeBase64(string) -> string
Parameters
stringtext
Text to decode
Returns
stringdecoded
Decoded text

Encoding.EncodeBase64 (function) view source

Encodes a base64 string
Encoding.EncodeBase64(string, boolean?) -> string
Parameters
stringtext
Text to encode
boolean?stripPadding
Remove padding (= characters) at the end when ’true’. Defaults to true.
Returns
stringencoded
Encoded text

Encoding.IsValidBase64 (function) view source

Validates a base64 string
Encoding.IsValidBase64(string) -> boolean
Parameters
stringtext
Text to validate
Returns
booleanvalid
Whether the text is valid base64

Encoding.DecodeBase64Url (function) view source

Decodes a base64url string

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

Encoding.DecodeBase64Url(string) -> string
Parameters
stringtext
Text to decode
Returns
stringdecoded
Decoded text

Encoding.EncodeBase64Url (function) view source

Encodes a base64url string
Encoding.EncodeBase64Url(string) -> string
Parameters
stringtext
Text to encode
Returns
stringencoded
Encoded text

Encoding.IsValidBase64Url (function) view source

Validates a base64url string
Encoding.IsValidBase64Url(string) -> boolean
Parameters
stringtext
Text to validate
Returns
booleanvalid
Whether the text is valid base64url

Engine (table) view source

Engine specific information.

Fields

string versionview source
“Major.Minor.PatchSet” for releases, “Major.Minor.PatchSet-CommitNum-gHash branch” otherwise
string versionFullview source
“Major.Minor.PatchSet” for releases, “Major.Minor.PatchSet-CommitNum-gHash branch” otherwise. Will also include (buildFlags), if there’re any.
string versionMajorview source
Major part of the named release version
string versionMinorview source
Minor part of the named release version
string versionPatchSetview source
Build number of the named release version
string commitsNumberview source
Number of commits after the latest named release, non-zero indicates a “dev” build
string buildFlagsview source
Gets additional engine buildflags, e.g. “Debug” or “Sync-Debug”
FeatureSupport featureSupportview source
Table containing various engine features as keys; use for cross-version compat
integer wordSizeview source
Indicates the build type always 64 these days
integer gameSpeedview source
Number of simulation gameframes per second
TextColorCode textColorCodesview source
Table containing keys that represent the color code operations during font rendering

Game (table) view source

Game specific information

Fields

integer maxTeamsview source
Maximum number of teams, including the Gaia team.
integer maxPlayersview source
Maximum number of players.
integer gameSpeedview source
Number of simulation gameframes per second
integer squareSizeview source
Divide Game.mapSizeX or Game.mapSizeZ by this to get engine’s “mapDims” coordinates. The resolution of height, yard and type maps.
integer metalMapSquareSizeview source
The resolution of metalmap (for use in API such as Spring.GetMetalAmount etc.)
integer buildSquareSizeview source
Size of a build grid square in elmos (squareSize * buildGridResolution).
integer buildGridResolutionview source
Resolution of the native build placement grid, in heightmap squares.
integer footprintScaleview source
Multiplier for unit, feature and move def footprint sizes, which are expressed in “TA units”.
(0|1|2|3) startPosTypeview source
0 fixed, 1 random, 2 choose in game, 3 choose before game.
boolean ghostedBuildingsview source
string? demoPlayNameview source
Base name of the demo being played, or nil if not playing a demo.
integer maxUnitsview source
number windMinview source
number windMaxview source
boolean mapDamageview source
Whether map damage (terrain deformation) is enabled.
integer mapXview source
Map size along the x axis, in map units (512 elmos).
integer mapYview source
Map size along the z axis, in map units (512 elmos).
integer mapSizeXview source
Map size along the x axis in worldspace/opengl coords. Divide by Game.squareSize to get engine’s “mapDims” coordinates
integer mapSizeZview source
Map size along the z axis in worldspace/opengl coords. Divide by Game.squareSize to get engine’s “mapDims” coordinates
string mapNameview source
The map’s human readable name.
string mapDescriptionview source
The map’s description.
number mapHardnessview source
number extractorRadiusview source
Extraction radius for mines.
number tidalview source
number waterDamageview source
number gravityview source
Gravity in elmos per second squared.
string gameNameview source
The game’s human readable name, without version.
string gameShortNameview source
The game’s short name, without version.
string gameVersionview source
The game’s version.
string gameMutatorview source
string gameDescview source
The game’s description.
string modNameview source
The game’s human readable name, including version.
string modShortNameview source
Same as Game.gameShortName.
string modVersionview source
Same as Game.gameVersion.
string modMutatorview source
Same as Game.gameMutator.
string modDescview source
Same as Game.gameDesc.
boolean constructionDecayview source
Whether constructions without builders decay.
integer constructionDecayTimeview source
How long until constructions without builders start decaying.
number constructionDecaySpeedview source
How fast constructions without builders decay.
boolean useYardmapsForQueuedBuildOverlapview source
Whether queued build overlap uses yardmap cells instead of full footprints.
integer multiReclaimview source
0 = 1 reclaimer per feature max, otherwise unlimited.
integer reclaimMethodview source
0 = gradual reclaim, 1 = all reclaimed at end, otherwise reclaim in reclaimMethod chunks.
integer reclaimUnitMethodview source
0 = revert to wireframe and gradual reclaim, 1 = subtract HP and give full metal at end.
number reclaimUnitEnergyCostFactorview source
How much energy reclaiming a unit costs.
number reclaimUnitEfficiencyview source
How much metal reclaiming a unit returns.
number reclaimFeatureEnergyCostFactorview source
How much energy reclaiming a feature costs.
boolean reclaimUnitDrainHealthview source
Whether wireframe reclaim drains health.
boolean reclaimAllowEnemiesview source
Whether enemy units can be reclaimed.
boolean reclaimAllowAlliesview source
Whether allied units can be reclaimed.
number repairEnergyCostFactorview source
How much energy repair costs.
number resurrectEnergyCostFactorview source
How much energy resurrection costs.
number captureEnergyCostFactorview source
How much energy capture costs.
integer transportAirview source
If 0, every aircraft gets cantBeTransported = true in its unit def.
integer transportShipview source
If 0, every unit using a ship move def gets cantBeTransported = true in its unit def.
integer transportHoverview source
If 0, every unit using a hovercraft move def gets cantBeTransported = true in its unit def.
integer transportGroundview source
If 0, every unit using a tank or kbot move def gets cantBeTransported = true in its unit def.
integer fireAtKilledview source
1 if units fire at enemies running their Killed() script, otherwise 0.
integer fireAtCrashingview source
1 if units fire at crashing aircraft, otherwise 0.
integer requireSonarUnderWaterview source
1 if underwater units are not in LOS unless also in sonar, otherwise 0.
boolean paralyzeOnMaxHealthview source
Whether paralysis depends on max health rather than current health.
number paralyzeDeclineRateview source
Time it takes for paralysis to decay by 100%, in seconds.
boolean allowEnginePlayerlistview source
boolean nativeExcessSharingview source
whether the engine handles excess resources overflow
string mapChecksumview source
SHA-512 checksum of the map archive, as hex.
string modChecksumview source
SHA-512 checksum of the game archive, as hex.
table<string,integer> springCategoriesview source
Example: lua { [“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 }
table<(string|integer),(string|integer)> armorTypesview source

(bidirectional)

Example: lua { [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, … }

TextColorCode textColorCodesview source
Table containing keys that represent the color code operations during font rendering.
{ Debris = integer, GroundCollision = integer, ObjectCollision = integer, ... } envDamageTypesview source
Environmental damage types. {def}IDs of environmental-damage sources.
{ noEnemies = integer, noFriendlies = integer, noFeatures = integer, ... } collisionFlagsview source
Weapon avoidance and projectile collision flags.
{ Tank = integer, KBot = integer, Hover = integer, Boat = integer, ... } speedModClassesview source
Move def speed-modifier types.
{ HitNothing = integer, HitGround = integer, HitLimit = integer, ... } scriptNotifyTypesview source
MoveCtrl script-notify types.

Platform (table) view source

Platform specific information

Fields

string gpuview source
Full GPU device name
("Nvidia"|"Intel"|"ATI"|"Mesa"|"Unknown") gpuVendorview source
integer gpuMemorySizeview source
Size of total GPU memory in MBs; only available for “Nvidia”, (rest are 0)
string glVersionShortview source
major.minor.buildNumber
integer glVersionNumview source
string glslVersionShortview source
major.minor
string glslVersionNumview source
string glVersionview source
Full version
string glVendorview source
string glRendererview source
string glslVersionview source
Full version
string gladVersionview source
string glewVersionview source
integer sdlVersionCompiledMajorview source
integer sdlVersionCompiledMinorview source
integer sdlVersionCompiledPatchview source
integer sdlVersionLinkedMajorview source
integer sdlVersionLinkedMinorview source
integer sdlVersionLinkedPatchview source
PlatformVideoMode[] availableVideoModesview source
integer numDisplaysview source
boolean glSupportNonPowerOfTwoTexview source
boolean glSupportTextureQueryLODview source
boolean glSupportMSAAFrameBufferview source
boolean glHaveAMDview source
boolean glHaveNVidiaview source
boolean glHaveIntelview source
boolean glHaveGLSLview source
boolean glHaveGL4view source
integer glSupportDepthBufferBitDepthview source
boolean glSupportRestartPrimitiveview source
boolean glSupportClipSpaceControlview source
boolean glSupportFragDepthLayoutview source
boolean glSupportSeamlessCubeMapsview source
string osNameview source
full name of the OS
string osVersionview source
("Windows"|"Linux"|"MacOSX"|"FreeBSD"|"Unknown") osFamilyview source
string architectureview source
CPU architecture (e.g., “x86_64”, “arm64”)
string hwConfigview source
integer cpuLogicalCoresview source
integer cpuPhysicalCoresview source
string cpuBrandview source
number totalRAMview source
Total physical system RAM in MBs.
string sysInfoHashview source
string macAddrHashview source
boolean isHeadlessview source
Is this a headless build which only simulates and doesnt offer interactive IO?
boolean hasSyncChecksumsview source
Whether the engine was built with sync-check support (i.e. Spring.GetPrevFrameSyncChecksum() returns a meaningful value).

Script (table)

Members

Script.GetWatchUnit (function) view source

Query whether any callins are registered for a unitDefID.

See Script.SetWatchUnit

Script.GetWatchUnit(UnitDefID) -> boolean
Parameters
UnitDefIDunitDefID
Returns
booleanwatched
Watch status.

Script.GetWatchFeature (function) view source

Query whether any callins are registered for a featureDefID.

See Script.SetWatchFeature

Script.GetWatchFeature(FeatureDefID) -> boolean
Parameters
FeatureDefIDfeatureDefID
Returns
booleanwatched
true if callins are registered, otherwise false.

Script.GetWatchWeapon (function) view source

Query whether any callins are registered for a weaponDefID.

Same as calling: lua Script.GetWatchExplosion(weaponDefID) or Script.GetWatchProjectile(weaponDefID) or Script.GetWatchAllowTarget(weaponDefID)

See Script.SetWatchWeapon

Script.GetWatchWeapon(WeaponDefID) -> boolean
Parameters
WeaponDefIDweaponDefID
Returns
booleanwatched
true if watch is enabled for any weaponDefID callins.

Script.GetWatchExplosion (function) view source

Query whether explosion callins are registered for a weaponDefID.

See Script.SetWatchExplosion

Script.GetWatchExplosion(WeaponDefID) -> boolean
Parameters
WeaponDefIDweaponDefID
Returns
booleanwatched
true if callins are registered, otherwise false.

Script.GetWatchProjectile (function) view source

Query whether projectile callins are registered for a weaponDefID.

See Script.SetWatchProjectile

Script.GetWatchProjectile(WeaponDefID) -> boolean
Parameters
WeaponDefIDweaponDefID
Returns
booleanwatched
true if callins are registered, otherwise false.

Script.GetWatchAllowTarget (function) view source

Query whether weapon targeting callins are registered for a weaponDefID.

See Script.SetWatchAllowTarget

Script.GetWatchAllowTarget(WeaponDefID) -> boolean
Parameters
WeaponDefIDweaponDefID
Returns
booleanwatched
true if callins are registered, otherwise false.

Script.SetWatchUnit (function) view source

Register or deregister unitDefID for expensive callins.

See Script.GetWatchUnit, Callins:UnitFeatureCollision, Callins:UnitUnitCollision, Callins:UnitMoveFailed

Script.SetWatchUnit(UnitDefID, boolean) -> nil
Parameters
UnitDefIDunitDefID
booleanwatch
Whether to register or deregister.

Script.SetWatchFeature (function) view source

Register or deregister featureDefID for expensive callins.

See Script.GetWatchFeature, Callins:UnitFeatureCollision

Script.SetWatchFeature(FeatureDefID, boolean) -> nil
Parameters
FeatureDefIDfeatureDefID
booleanwatch
Whether to register or deregister.

Script.SetWatchWeapon (function) view source

Register or deregister weaponDefID for all expensive callins.

Equivalent to calling:

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

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

See Script.GetWatchWeapon, Script.SetWatchExplosion, Script.SetWatchProjectile, Script.SetWatchAllowTarget

Script.SetWatchWeapon(WeaponDefID, boolean) -> nil
Parameters
WeaponDefIDweaponDefID
booleanwatch
Whether to register or deregister.

Script.SetWatchExplosion (function) view source

Register or deregister weaponDefID for explosion callins.

See Script.GetWatchExplosion, Callins:Explosion

Script.SetWatchExplosion(WeaponDefID, boolean) -> nil
Parameters
WeaponDefIDweaponDefID
booleanwatch
Whether to register or deregister.

Script.SetWatchProjectile (function) view source

Register or deregister weaponDefID for expensive projectile callins.

See Script.GetWatchProjectile, Callins:ProjectileCreated, Callins:ProjectileDestroyed

Script.SetWatchProjectile(WeaponDefID, boolean) -> nil
Parameters
WeaponDefIDweaponDefID
weaponDefID for weapons or -1 to watch for debris.
booleanwatch
Whether to register or deregister.

Script.SetWatchAllowTarget (function) view source

Register or deregister weaponDefID for weapon targeting callins.

See Script.GetWatchAllowTarget, SyncedCallins:AllowWeaponTargetCheck, SyncedCallins:AllowWeaponTarget, SyncedCallins:AllowWeaponInterceptTarget

Script.SetWatchAllowTarget(WeaponDefID, boolean) -> nil
Parameters
WeaponDefIDweaponDefID
booleanwatch
Whether to register or deregister.

Script.IsEngineMinVersion (function) view source 

Script.IsEngineMinVersion(integer, integer?, integer?) -> boolean
Parameters
integerminMajorVer
integer?minMinorVer
(Default: 0)
integer?minCommits
(Default: 0)
Returns
booleansatisfiesMin
true if the engine version is greater or equal to the specified version, otherwise false.

Script.PermitHelperAIs (function) view source 

Script.PermitHelperAIs(boolean) -> nil
Parameters
booleanpermit

Script.Kill (function) view source 

Script.Kill(string?) -> nil
Parameters
string?killMessage
Kill message.

Script.GetName (function) view source 

Script.GetName() -> string
Returns
stringname

Script.GetSynced (function) view source 

Script.GetSynced() -> boolean
Returns
booleansynced

Script.GetFullCtrl (function) view source 

Script.GetFullCtrl() -> boolean
Returns
booleanfullCtrl

Script.GetFullRead (function) view source 

Script.GetFullRead() -> boolean
Returns
booleanfullRead

Script.GetCtrlTeam (function) view source 

Script.GetCtrlTeam() -> TeamID
Returns
TeamIDteamID

Script.GetReadTeam (function) view source 

Script.GetReadTeam() -> TeamID
Returns
TeamIDteamID

Script.GetReadAllyTeam (function) view source 

Script.GetReadAllyTeam() -> AllyTeamID
Returns
AllyTeamIDallyTeamID

Script.GetSelectTeam (function) view source 

Script.GetSelectTeam() -> TeamID
Returns
TeamIDteamID

Script.GetGlobal (function) view source 

Script.GetGlobal() -> integer?
Returns
integer?global

Script.GetRegistry (function) view source 

Script.GetRegistry() -> integer?
Returns
integer?registry

Script.DelayByFrames (function) view source 

Script.DelayByFrames(integer, fun(...)) -> nil
Parameters
integerframeDelay
fun(...)func

Script.UpdateCallIn (function) view source 

Script.UpdateCallIn(string) -> nil
Parameters
stringname
Returns
nil

Fields

-1 NO_ACCESS_TEAMview source
-2 ALL_ACCESS_TEAMview source

VFS (table) view source

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 “foobar.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

Members

VFS.Include (function) view source

Loads and runs lua code from a file in the VFS.

The path is relative to the main Spring directory, e.g.

lua VFS.Include(‘LuaUI/includes/filename.lua’, nil, vfsmode)

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.

VFS.Include(string, table?, string?) -> any
Parameters
stringfilename
Path to file, lowercase only. Use linux style path separators, e.g. “foo/bar.txt”.
table?environment
(Default: the current function environment) The global environment for the included file.
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
Returns
anymodule
The return value of the included file.

VFS.LoadFile (function) view source

Load raw text data from the VFS.

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.

VFS.LoadFile(string, string?) -> string?
Parameters
stringfilename
Path to file, lowercase only. Use linux style path separators, e.g. “foo/bar.txt”.
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
Returns
string?data
The contents of the file.

VFS.FileExists (function) view source

Check if file exists in VFS.

Example usage:

lua if VFS.FileExists(“mapconfig/custom_lava_config.lua”, VFS.MAP) then

…

end 

VFS.FileExists(string, string?) -> boolean
Parameters
stringfilename
Path to file, lowercase only. Use linux style path separators, e.g. “foo/bar.txt”.
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
Returns
booleanexists
true if the file exists, otherwise false.

VFS.DirList (function) view source

List files in a directory.

Example usage:

lua local luaFiles = VFS.DirList(‘units/’, ‘*.lua’, nil, true) 

VFS.DirList(string, string?, string?, boolean?) -> string[]
Parameters
stringdirectory
Path to directory, lowercase only. Use linux style path separators, e.g. “foo/bar/".
string?pattern
(Default: "*")
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
boolean?recursive
(Default: false)
Returns
string[]filenames

VFS.SubDirs (function) view source

List sub-directories in a directory.

Example usage:

lua local files = VFS.SubDirs(‘sounds/voice/’ .. language, ‘*’) for _, file in ipairs(files) do # … end 

VFS.SubDirs(string, string?, string?, boolean?) -> string[]
Parameters
stringdirectory
Path to directory, lowercase only. Use linux style path separators, e.g. “foo/bar/".
string?pattern
(Default: "*")
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
boolean?recursive
(Default: false)
Returns
string[]dirnames

VFS.GetFileAbsolutePath (function) view source 

VFS.GetFileAbsolutePath(string, string?) -> string?
Parameters
stringfilename
Path to file, lowercase only. Use linux style path separators, e.g. “foo/bar.txt”.
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
Returns
string?absolutePath

VFS.GetArchiveContainingFile (function) view source 

VFS.GetArchiveContainingFile(string, string?) -> string?
Parameters
stringfilename
Path to file, lowercase only. Use linux style path separators, e.g. “foo/bar.txt”.
string?mode
VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (i.e. location) from which to include files.
Returns
string?archiveName

VFS.UseArchive (function) view source

Temporarily load an archive from the VFS and run the given function, which can make usage of the files in the archive.
VFS.UseArchive(string, fun(...)) -> any ...
Parameters
stringarchiveName
fun(...)func
Returns
any ...Results
of the given function

VFS.CompressFolder (function) view source

Compresses the specified folder.
VFS.CompressFolder(string, string?, string?, boolean?, string?) -> nil
Parameters
stringfolderPath
string?archiveType
(Default: “zip”) The compression type (can currently be only “zip”).
string?compressedFilePath
(Default: folderPath .. “.sdz”)
boolean?includeFolder
(Default: false) Whether the archive should have the specified folder as root.
string?mode

VFS.ZlibCompress (function) view source 

VFS.ZlibCompress(string) -> string?
Parameters
stringuncompressed
Data to compress.
Returns
string?compressed
Compressed data, or nil on error.

VFS.ZlibDecompress (function) view source 

VFS.ZlibDecompress(string) -> string?
Parameters
stringcompressed
Data to decompress.
Returns
string?uncompressed
Uncompressed data, or nil on error.

VFS.CalculateHash (function) view source

Calculates hash of a given string.

  • MD5 gets base64 encoded.
  • SHA512 gets hex encoded.
VFS.CalculateHash(string, HashType) -> string?
Parameters
stringinput
HashTypehashType
Hash type.
Returns
string?hash

VFS.VerifyEd25519 (function) view source

Verifies an Ed25519 signature.

All arguments are binary strings. The signature must be 64 bytes and the public key must be 32 bytes.

VFS.VerifyEd25519(string, string, string) -> boolean
Parameters
stringmessage
stringsignature
stringpublicKey
Returns
booleanvalid

VFS.PackU8 (function) view source

Convert unsigned 8-bit integer(s) to binary string.
VFS.PackU8([integer, ]*) -> string
Parameters
integer...
Numbers to pack.
Returns
string

VFS.PackU8 (function overload 1) view source

Convert unsigned 8-bit integer(s) to binary string.
VFS.PackU8(integer[]) -> string
Parameters
integer[]numbers
Numbers to pack.
Returns
string

VFS.PackU16 (function) view source

Convert unsigned 16-bit integer(s) to binary string.
VFS.PackU16([integer, ]*) -> string
Parameters
integer...
Numbers to pack.
Returns
string

VFS.PackU16 (function overload 1) view source

Convert unsigned 16-bit integer(s) to binary string.
VFS.PackU16(integer[]) -> string
Parameters
integer[]numbers
Numbers to pack.
Returns
string

VFS.PackU32 (function) view source

Convert unsigned 32-bit integer(s) to binary string.
VFS.PackU32([integer, ]*) -> string
Parameters
integer...
Numbers to pack.
Returns
string

VFS.PackU32 (function overload 1) view source

Convert unsigned 32-bit integer(s) to binary string.
VFS.PackU32(integer[]) -> string
Parameters
integer[]numbers
Numbers to pack.
Returns
string

VFS.PackS8 (function) view source

Convert signed 8-bit integer(s) to binary string.
VFS.PackS8([integer, ]*) -> string
Parameters
integer...
Numbers to pack.
Returns
string

VFS.PackS8 (function overload 1) view source

Convert signed 8-bit integer(s) to binary string.
VFS.PackS8(integer[]) -> string
Parameters
integer[]numbers
Numbers to pack.
Returns
string

VFS.PackS16 (function) view source

Convert signed 16-bit integer(s) to binary string.
VFS.PackS16([integer, ]*) -> string
Parameters
integer...
Numbers to pack.
Returns
string

VFS.PackS16 (function overload 1) view source

Convert signed 16-bit integer(s) to binary string.
VFS.PackS16(integer[]) -> string
Parameters
integer[]numbers
Numbers to pack.
Returns
string

VFS.PackS32 (function) view source

Convert signed 32-bit integer(s) to binary string.
VFS.PackS32([integer, ]*) -> string
Parameters
integer...
Numbers to pack.
Returns
string

VFS.PackS32 (function overload 1) view source

Convert signed 32-bit integer(s) to binary string.
VFS.PackS32(integer[]) -> string
Parameters
integer[]numbers
Numbers to pack.
Returns
string

VFS.PackF32 (function) view source

Convert signed 32-bit float(s) to binary string.
VFS.PackF32([number, ]*) -> string?
Parameters
number...
Numbers to pack.
Returns
string?

VFS.PackF32 (function overload 1) view source

Convert signed 32-bit float(s) to binary string.
VFS.PackF32(number[]) -> string?
Parameters
number[]numbers
Numbers to pack.
Returns
string?

VFS.UnpackU8 (function) view source

Convert a binary string to an unsigned 8-bit integer.
VFS.UnpackU8(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.UnpackU16 (function) view source

Convert a binary string to an unsigned 16-bit integer.
VFS.UnpackU16(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.UnpackU32 (function) view source

Convert a binary string to an unsigned 32-bit integer.
VFS.UnpackU32(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.UnpackS8 (function) view source

Convert a binary string to a signed 8-bit integer.
VFS.UnpackS8(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.UnpackS16 (function) view source

Convert a binary string to a signed 16-bit integer.
VFS.UnpackS16(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.UnpackS32 (function) view source

Convert a binary string to a signed 32-bit integer.
VFS.UnpackS32(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.UnpackF32 (function) view source

Convert a binary string to a signed 32-bit float.
VFS.UnpackF32(string, integer?) -> integer
Parameters
stringstr
Binary string.
integer?pos
Byte offset.
Returns
integer

VFS.GetMaps (function) view source 

VFS.GetMaps() -> string[]
Returns
string[]mapNames

VFS.GetGames (function) view source 

VFS.GetGames() -> string[]
Returns
string[]gameNames

VFS.GetAllArchives (function) view source 

VFS.GetAllArchives() -> string[]
Returns
string[]archiveNames

VFS.HasArchive (function) view source 

VFS.HasArchive() -> boolean
Returns
booleanhasArchive

VFS.GetLoadedArchives (function) view source 

VFS.GetLoadedArchives() -> string[]
Returns
string[]archiveNames

VFS.GetArchivePath (function) view source 

VFS.GetArchivePath(string) -> string?
Parameters
stringarchiveName
Returns
string?archivePath

VFS.GetArchiveInfo (function) view source 

VFS.GetArchiveInfo(string) -> ArchiveInfo?
Parameters
stringarchiveName
Returns
ArchiveInfo?archiveInfo

VFS.GetArchiveDependencies (function) view source 

VFS.GetArchiveDependencies(string) -> string[]
Parameters
stringarchiveName
Returns
string[]archiveNames

VFS.GetArchiveReplaces (function) view source 

VFS.GetArchiveReplaces(string) -> string[]
Parameters
stringarchiveName
Returns
string[]archiveNames

VFS.GetArchiveChecksum (function) view source 

VFS.GetArchiveChecksum(string) -> string, string
Parameters
stringarchiveName
Returns
stringsingleArchiveChecksum
stringcompleteArchiveChecksum

VFS.GetNameFromRapidTag (function) view source 

VFS.GetNameFromRapidTag(string) -> string
Parameters
stringrapidTag
Returns
stringarchiveName

VFS.GetAvailableAIs (function) view source

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.

VFS.GetAvailableAIs(string?, string?) -> AIInfo[]
Parameters
string?gameArchiveName
string?mapArichiveName
Returns
AIInfo[]ais

VFS.DownloadArchive (function) view source

Queue an archive download through pr-downloader.
VFS.DownloadArchive(string, string) -> nil
Parameters
stringfilename
Archive or rapid package name.
stringcategory
One of map, game, or engine.

VFS.AbortDownload (function) view source

Abort a queued or active archive download.
VFS.AbortDownload(integer) -> boolean
Parameters
integerid
Download queue identifier.
Returns
booleanremoved
Whether a matching queued or active download was removed.

VFS.ScanAllDirs (function) view source

Rescan all data directories for newly added archives.
VFS.ScanAllDirs() -> nil

Fields

"r" RAWview source
Only select uncompressed files.
"M" GAMEview source
"m" MAPview source
"b" BASEview source
"e" MENUview source
"Mmeb" ZIPview source
Only select compressed files (.sdz, .sd7).
"rMmeb" RAW_FIRSTview source
Try uncompressed files first, then compressed.
"Mmebr" ZIP_FIRSTview source
Try compressed files first, then uncompressed.
"M" MODview source
Older spelling for VFS.GAME
"r" RAW_ONLYview source
"Mmeb" ZIP_ONLYview source

tracy (table)

Members

tracy.LuaTracyPlotConfig (function) view source

Configure custom appearance for a Tracy plot for use in debugging or profiling
tracy.LuaTracyPlotConfig(string, ("Number"|"Percentage"|"Memory")?, boolean?, boolean?, integer?) -> nil
Parameters
stringplotName
name of the plot to customize
("Number"|"Percentage"|"Memory")?plotFormatType
(Default: “Number”)
boolean?stepwise
(Default: true) stepwise chart
boolean?fill
(Default: false) whether to fill color
integer?color
(Default: 0xFFFFFF) uint32 number as BGR color

tracy.LuaTracyPlot (function) view source

Update a Tracy plot with a value
tracy.LuaTracyPlot(string, number) -> nil
Parameters
stringplotName
Which LuaPlot should be updated
numberplotValue
the number to show on the Tracy plot

tracy.ZoneBegin (function) 

tracy.ZoneBegin(string) -> nil
Parameters
stringname

tracy.ZoneBeginN (function) 

tracy.ZoneBeginN(string) -> nil
Parameters
stringname

tracy.ZoneBeginS (function) 

tracy.ZoneBeginS(string) -> nil
Parameters
stringname

tracy.ZoneBeginNS (function) 

tracy.ZoneBeginNS(string) -> nil
Parameters
stringname

tracy.ZoneEnd (function) 

tracy.ZoneEnd() -> nil

tracy.ZoneText (function) 

tracy.ZoneText(string) -> nil
Parameters
stringtext

tracy.ZoneName (function) 

tracy.ZoneName(string) -> nil
Parameters
stringname

tracy.Message (function) 

tracy.Message(string) -> nil
Parameters
stringtext

Command (class) view source

Fields

integer id
number[]? params
CommandOptions? options

CollisionVolumeData (class) view source

Parameters related to a collision volume.

Fields

("ellipsoid"|"cylinder"|"box"|"sphere") type
type
number scaleX
number scaleY
number scaleZ
number offsetX
number offsetY
number offsetZ
number boundingRadius
boolean defaultToSphere
boolean defaultToFootPrint
boolean defaultToPieceTree

ArchiveInfo (class) view source

Fields

string name
string shortname
string version
string mutator
string game
string shortgame
string description
string mapfile
ModType modtype

CreateCommand (class) view source

Used when assigning multiple commands at once.

Fields

(CMD|integer) [1]
Command ID.
CreateCommandParams? [2]
Parameters for the given command.
CreateCommandOptions? [3]
Command options.
integer? [4]
Timeout.

xz (class) view source

Fields

number x
number y

ResourceCost (class) view source

Fields

number metal
number energy

ProjectileTargetType (enum) view source

102 featureview source
ASCII number for the character f
112 projectileview source
ASCII number for the character p
117 unitview source
ASCII number for the character u

VertexData (class) view source

Fields

xyz? vert
xyz? v
Short for vert.
float3? norm
float3? n
Short for norm.
float2? texcoord
float2? t
Short for texcoord.
float4? color
float4? c
Short for color.

SideSpec (class) view source

Side spec

See Spring.GetSideData

Fields

string sideName

Returned when getting arrays of side specifications.

Lowercase side name.

string caseName
Original case side name.
string startUnit

CreateRBOData (class) view source

Fields

GL target
GL format
integer? samples
any number here will result in creation of multisampled RBO

UnitState (class) view source

Fields

integer firestate
integer movestate
boolean? repeat
boolean? cloak
boolean? active
boolean? trajectory
boolean? autoland
number? autorepairlevel
boolean? loopbackattack

CameraVectors (class) view source

Fields

xyz forward
xyz up
xyz right
xyz topFrustumPlane
xyz botFrustumPlane
xyz lftFrustumPlane
xyz rgtFrustumPlane

Configuration (class) view source

Contains data about a configuration, only name and type are guaranteed

Fields

string name
string type
string description
string defaultValue
string minimumValue
string maximumValue
string safemodeValue
string declarationFile
string declarationLine
boolean readOnly

CallAsTeamOptions (class) view source

Fields

TeamID ctrl
TeamID read
TeamID select

VBOAttributeDef (class) view source

Fields

integer? id
string? name

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.

integer? size
GL? type

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:

boolean? normalized

(Defaults: false)

It’s possible to submit normals without normalizing them first, normalized will make sure data is normalized.

MapRenderingParams (class) view source

Map rendering params

Fields

rgba? splatTexMults
rgba? splatTexScales
boolean? voidWater
boolean? voidGround
boolean? splatDetailNormalDiffuseAlpha

KeyModifiers (class) view source

Key Modifier Params

Fields

boolean alt
Alt key pressed
boolean ctrl
Ctrl key pressed
boolean meta
Meta/GUI key pressed
boolean shift
Shift key pressed

RmlUi.EventParametersProxy (class) view source

Keyboard and mouse input data associated with an event.

Fields

RmlUi.EventParametersProxy.MouseButton button
integer mouse_x
integer mouse_y
RmlUi.EventParametersProxy.TrueFalse scroll_lock_key
RmlUi.EventParametersProxy.TrueFalse meta_key
RmlUi.EventParametersProxy.TrueFalse ctrl_key
RmlUi.EventParametersProxy.TrueFalse shift_key
RmlUi.EventParametersProxy.TrueFalse caps_lock_key
RmlUi.EventParametersProxy.TrueFalse alt_key

CommandOptions (class) view source

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.

Fields

(CommandOptionBit|integer) coded
Bitmask of command options.
boolean alt
Alt key pressed.
boolean ctrl
Ctrl key pressed.
boolean shift
Shift key pressed.
boolean right
Right mouse key pressed.
boolean meta
Meta key (space) pressed.
boolean internal

ShaderParams (class) view source

Fields

string? vertex
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.
string? tcs
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.
string? tes
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.
string? geometry
The “Geometry” or Geometry-shader can create new vertices and vertice-stripes from points.
string? fragment

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.

UniformParam<number>? uniform
UniformParam<integer>? uniformInt
UniformParam<number>? uniformFloat
UniformParam<number>? uniformMatrix
integer? geoInputType
inType
integer? geoOutputType
outType
integer? geoOutputVerts
maxVerts
string? definitions
string of shader #defines"

SoundDeviceSpec (class) view source

Contains data about a sound device.

Fields

string name

AIInfo (class) view source

Fields

string shortName
string version
boolean isLuaAI

ControlPoint (class) view source

NURBS control point.

Fields

number [1]
x
number [2]
y
number [3]
z
number [4]
weight

losAccess (class) view source

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.

Fields

boolean? private
only readable by the ally (default)
boolean? allied
readable by ally + ingame allied
boolean? inlos
readable if the unit is in LOS
boolean? inradar
readable if the unit is in AirLOS
boolean? public
readable by all

GroundMoveType (class) view source

Inherits GenericMoveType

Fields

boolean? atGoal
boolean? atEndOfPath
boolean? pushResistant
integer? minScriptChangeHeading
number? turnRate
number? turnAccel
number? accRate
number? decRate
number? myGravity
number? maxReverseDist
number? minReverseAngle
number? maxReverseSpeed
number? sqSkidSpeedMult

LosMask (enum) view source

1 INLOSview source
the unit is currently in the los of the allyteam
2 INRADARview source
the unit is currently in radar from the allyteam
4 PREVLOSview source
the unit has previously been in los from the allyteam
8 CONTRADARview source
the unit has continuously been in radar since it was last inlos by the allyteam

CommandDescription (class) view source

Contains data about a command.

Fields

(CMD|integer)? id
CMDTYPE? type
string? name
string? action
string? tooltip
string? texture
string? cursor
boolean? queueing
boolean? hidden
boolean? disabled
boolean? showUnique
boolean? onlyTexture
string[]? params

StrafeAirMoveType (class) view source

Inherits GenericMoveType

Fields

boolean? collide
boolean? useSmoothMesh
boolean? loopbackAttack
integer? maneuverBlockTime
number? wantedHeight
number? turnRadius
number? accRate
number? decRate
number? maxAcc
Synonym for accRate.
number? maxDec
Synonym for decRate.
number? maxBank
number? maxPitch
number? maxAileron
number? maxElevator
number? maxRudder
number? attackSafetyDistance
number? myGravity

FBODescription (class) view source

Fields

string? depth
string? stencil
string? color0
string? color1
string? color2
string? color3
string? color4
string? color5
string? color6
string? color7
string? color8
string? color9
string? color10
string? color11
string? color12
string? color13
string? color14
string? color15
(integer|GL)[]? drawbuffers
e.g. { GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}
(integer|GL)? readbuffer
e.g. GL_COLOR_ATTACHMENT0_EXT

Texture (class) view source

Fields

GL? target
integer? format
GL? min_filter
GL? mag_filter
GL? wrap_s
GL? wrap_t
GL? wrap_r
number? compareFunc
number? lodBias
number? aniso

AtmosphereParams (class) view source

Fields

number? fogStart
number? fogEnd
rgba? sunColor
rgba? skyColor
rgba? cloudColor
xyzw? skyAxisAngle
rotation axis and angle in radians of skybox orientation

FeatureSupport (class) view source

Fields

boolean NegativeGetUnitCurrentCommand
Whether Spring.GetUnitCurrentCommand allows negative indices to look from the end
boolean hasExitOnlyYardmaps
Whether yardmaps accept ’e’ (exit only) and ‘u’ (unbuildable, walkable)
integer rmlUiApiVersion
Version of Recoil’s rmlUI API
boolean noAutoShowMetal
Whether the engine switches to the metal view when selecting a “build metal extractor” command (yes if false)
integer maxPiecesPerModel
How many pieces supported for 3d models?
number gunshipCruiseAltitudeMultiplier
For gunships, the cruiseAltitude from the unit def is multiplied by this much
boolean noRefundForConstructionDecay
Whether there is no refund for construction decay (100% metal back if false)
boolean noRefundForFactoryCancel
Whether there is no refund for factory cancel (100% metal back if false)
boolean noOffsetForFeatureID
Whether featureID from various interfaces (targetID for Reclaim commands, ownerID from SpringGetGroundDecalOwner, etc) needs to be offset by Game.maxUnits
boolean noHandicapForReclaim
Whether handicap is applied to income from reclaim
boolean groupAddDoesntSelect
Whether ‘group add’ also selects the group (does both if false)
boolean deadTeamsKeepUnitLimit
Whether engine redistributes dead team unitlimit to allies (false) or keeps it as-is (true)
boolean reliableLuaMapShaders
Whether forward-only Lua map shaders activate without a deferred draw and Spring.SetMapShader program swaps refresh cached uniform locations
boolean nanoParticleUpdateCallin
Whether LuaUI receives batched NanoParticleUpdate lifecycle events
boolean nanoParticlesGL4
Whether the engine has the standalone shader-based nano particle effect (the NanoParticles* springsettings)
boolean modelVertexColor
Whether glTF COLOR_0 is loaded into the models VBO (color, attribute 15; opaque white when absent)
integer liveConfigChanges
Version of the set of springsettings that apply without a restart, bumped when more are added (1: those listed in the 2026.09 changelog)

KeyBinding (class) view source

Contains data about a keybinding

Fields

string command
string extra
string boundWith

Matrix4x4 (class) view source

Fields

number [1]
Element at [1,1]
number [2]
Element at [1,2]
number [3]
Element at [1,3]
number [4]
Element at [1,4]
number [5]
Element at [2,1]
number [6]
Element at [2,2]
number [7]
Element at [2,3]
number [8]
Element at [2,4]
number [9]
Element at [3,1]
number [10]
Element at [3,2]
number [11]
Element at [3,3]
number [12]
Element at [3,4]
number [13]
Element at [4,1]
number [14]
Element at [4,2]
number [15]
Element at [4,3]
number [16]
Element at [4,4]

WaterParams (class) view source

Water params

Fields

rgb? absorb
rgb? baseColor
rgb? minColor
rgb? surfaceColor
rgb? diffuseColor
rgb? specularColor
rgb? planeColor
string? texture
file
string? foamTexture
file
string? normalTexture
file
number? damage
number? repeatX
number? repeatY
number? surfaceAlpha
number? ambientFactor
number? diffuseFactor
number? specularFactor
number? specularPower
number? fresnelMin
number? fresnelMax
number? fresnelPower
number? reflectionDistortion
number? blurBase
number? blurExponent
number? perlinStartFreq
number? perlinLacunarity
number? perlinAmplitude
number? windSpeed
number? waveOffsetFactor
number? waveLength
number? waveFoamDistortion
number? waveFoamIntensity
number? causticsResolution
number? causticsStrength
integer? numTiles
boolean? shoreWaves
boolean? forceRendering
boolean? hasWaterPlane

HoverAirMoveType (class) view source

Inherits GenericMoveType

Fields

boolean? collide
boolean? dontLand
boolean? airStrafe
boolean? useSmoothMesh
boolean? bankingAllowed
number? wantedHeight
number? accRate
number? decRate
number? turnRate
number? altitudeRate
number? currentBank
number? currentPitch
number? maxDrift

TeamStats (class) view source

Fields

integer time
integer frame
number metalUsed
number metalProduced
number metalExcess
number metalReceived
number metalSent
number energyUsed
number energyProduced
number energyExcess
number energyReceived
number energySent
number damageDealt
number damageReceived
integer unitsProduced
integer unitsDied
integer unitsReceived
integer unitsSent
integer unitsCaptured
integer unitsOutCaptured

WeaponDamages (class) view source

Parameters for damage

Fields

integer paralyzeDamageTime
number impulseFactor
number impulseBoost
number craterMult
number craterBoost
number dynDamageExp
number dynDamageMin
number dynDamageRange
number dynDamageInverted
Set to true if a non-zero value is passed, false is zero is passed.
number craterAreaOfEffect
number damageAreaOfEffect
number edgeEffectiveness
number explosionSpeed

ExplosionParams (class) view source

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.

Fields

WeaponDefID? weaponDef
UnitID? owner
UnitID? hitUnit
FeatureID? hitFeature
number? craterAreaOfEffect
number? damageAreaOfEffect
number? edgeEffectiveness
number? explosionSpeed
number? gfxMod
boolean? impactOnly
boolean? ignoreOwner
boolean? damageGround

GenericMoveType (class) view source

Fields

number? maxSpeed
number? maxWantedSpeed
number? maneuverLeash
number? waterline
boolean? useWantedSpeed[0]
Use wanted speed for individual orders.
boolean? useWantedSpeed[1]
Use wanted speed for formation orders.

UnitDefDimensions (class) view source

Fields

number height
number radius
number midx
number minx
number maxx
number midy
number miny
number maxy
number midz
number minz
number maxz

WeaponState (class) view source

Parameter for weapon states

Fields

integer? reloadState
integer? reloadFrame
Alias for reloadState.
number? reloadTime
integer? reaimTime
number? accuracy
number? sprayAngle
number? range
If you change the range of a weapon with dynamic damage make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
number? projectileSpeed
integer? burst
number? burstRate
integer? projectiles
integer? salvoLeft
integer? nextSalvo
number? aimReady
Set to true if a non-zero value is passed, false is zero is passed.
integer? forceAim
integer? avoidFlags
integer? collisionFlags
number? ttl
How many seconds the projectile should live

UniformParam (class) view source

Inherits { [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;

glsl uniform vec4 teamColor;

LightParams (class) view source

Parameters for lighting

Fields

{ px: number, py: number, pz: number } position
{ dx: number, dy: number, dz: number } direction
{ blue: number, green: number, red: number } ambientColor
{ blue: number, green: number, red: number } diffuseColor
{ blue: number, green: number, red: number } specularColor
{ ambientWeight: number, diffuseWeight: number, specularWeight: number } intensityWeight
{ ambientBlueDecay: number, ambientGreenDecay: number, ambientRedDecay: number } ambientDecayRate
Per-frame decay of ambientColor (spread over TTL frames).
{ diffuseBlueDecay: number, diffuseGreenDecay: number, diffuseRedDecay: number } diffuseDecayRate
Per-frame decay of diffuseColor (spread over TTL frames).
{ specularBlueDecay: number, specularGreenDecay: number, specularRedDecay: number } specularDecayRate
Per-frame decay of specularColor (spread over TTL frames).
{ ambientDecayType: number, diffuseDecayType: number, specularDecayType: number } decayFunctionType
If value is 0.0 then the *DecayRate values will be interpreted as linear, otherwise exponential.
number radius
number fov
number ttl
number priority
boolean ignoreLOS

TextureInfo (class) view source

Fields

integer xsize
integer ysize
integer zsize
integer id
GL target

Roster (class) view source

Contains data about a player

Fields

string name
PlayerID playerID
TeamID teamID
AllyTeamID allyTeamID
boolean spectator
number cpuUsage
CPU usage. 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
number pingTime
if -1, the player is pathfinding

Material (class) view source

Fields

number shininess
(rgb|rgba) ambidiff
(rgb|rgba) ambient
(rgb|rgba) diffuse
(rgb|rgba) specular
(rgb|rgba) emission

ActiveUniform (class) view source

Fields

string name
string type
String name of GL_* constant.
integer length
The character length of name.
integer size
GL location

SaveImageOptions (class) view source

Fields

boolean? alpha
(Default: false)
boolean? yflip
(Default: true)
boolean? grayscale16bit
(Default: false)
GL? readbuffer
(Default: current read buffer)

BuildOrderSpec (class) view source

Fields

integer [1]
unitDefID
number [2]
x
number [3]
y
number [4]
z
Facing [5]
facing

SetUnitHealthAmounts (class) view source

Fields

number? health
Set the unit’s health.
number? capture
Set the unit’s capture progress.
number? paralyze
Set the unit’s paralyze damage.
number? build
Set the unit’s build progress.

Plane (class) view source

Fields

number normalVecX
number normalVecY
number normalVecZ
number d

PieceInfo (class) view source

Fields

string name
string parent
string[] children
names
boolean empty
(number,number,number) min
(x,y,z)
(number,number,number) max
(x,y,z)
(number,number,number) offset
(x,y,z)

ProjectileParams (class) view source

Fields

xyz? pos
xyz? speed
xyz? spread
xyz? error
xyz? end
UnitID? owner
TeamID? team
number? ttl
number? gravity
number? tracking
number? maxRange
number? startAlpha
number? endAlpha
string? model
string? cegTag

Aliases

StorageName
("metalStorage"|"energyStorage"|"ms"|"es")
ProjectileID
integer
ObjectID
(UnitID|FeatureID)
ResourceUsage
table<ResourceName,number>
RmlUi.ElementStyleProxyview source
{ [string]: string }
DecalID
integer
float4
xyzw { [1] = number, [2] = number, [3] = number, [4] = number, }
PlayerID
integer
GenericMoveTypeNumberKeyview source
("maxSpeed"|"maxWantedSpeed"|"maneuverLeash"|"waterline")
CameraMode
(0|1|2|3|4|5|6)
ModTypeview source
(0|1|3|4)
Headingview source
integer
Attachmentview source
("depth"|"stencil"|"color0"|"color1"|"color2"|"color3"|"color4"|"color5"|"color6"|"color7"|"color8"|"color9"|"color10"|"color11"|"color12"|"color13"|"color14"|"color15")
CommandOptionNameview source
("right"|"alt"|"ctrl"|"shift"|"meta")
UnitID
integer
CreateCommandParamsview source
(number[]|number)
FacingIntegerview source
(0|1|2|3)
CameraName
("ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy")
TeamID
integer
RmlUi.EventParametersProxy.TrueFalseview source
(0|1)
CreateCommandOptionsview source
(CommandOptionName[]|table<CommandOptionName,boolean>|CommandOptionBit|integer)
DrawFlagview source
(0|1|2|4|8|16|32|128)
RmlUi.ElementAttributesProxyview source
{ [string]: (boolean|string|number) }
UnitDefID
integer
WeaponDefID
integer
HashTypeview source
(0|1)
RmlUi.SelectOptionsProxyNodeview source
{ element: RmlUi.Element, value: string }
DrawMaskview source
integer
float2
xy { [1] = number, [2] = number, }
AllyTeamID
integer
RmlUi.EventIDview source
(0|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17|18|19|20|21|22|23|24|25|26|27|28|29|30|31|32|33|integer)
RmlUi.StyleProxyview source
{ [string]: string }
RmlUi.SelectOptionsProxyview source
RmlUi.SelectOptionsProxyNode[]
MatrixNameview source
("view"|"projection"|"viewprojection"|"viewinverse"|"projectioninverse"|"viewprojectioninverse"|"billboard"|"shadow"|"camera"|"camprj"|"caminv"|"camprjinv")
LogLevelview source
(integer|"debug"|"info"|"notice"|"warning"|"deprecated"|"error"|"fatal")
RmlUi.MouseButtonview source
(0|1|2)
ResourceName
("metal"|"energy"|"m"|"e")
LosTableview source
table<("los"|"radar"|"prevLos"|"contRadar"),boolean>
RmlUi.EventParametersProxy.MouseButtonview source
(0|1|2)
GenericMoveTypeBooleanKeyview source
("useWantedSpeed[0]"|"useWantedSpeed[1]")
UniformArrayTypeview source
(1|2|3)
DamageWeaponDefIDview source
(WeaponDefID|-1|-2|-3|-4|-5|-6|-7)
FeatureDefID
integer
RmlUi.ElementChildNodesProxyview source
RmlUi.Element[]
BuildOrderBlockedStatusview source
(0|1|2|3)
FeatureID
integer
CommandOptionBitview source
(4|8|16|32|64|128)
SoundChannelview source
("general"|"battle"|"sfx"|"unitreply"|"voice"|"userinterface"|"ui"|0|1|2|3)
Facingview source
(0|1|2|3|"s"|"e"|"n"|"w"|"south"|"east"|"north"|"west")
float3
xyz { [1] = number, [2] = number, [3] = number, }
GroupID
integer
TargetTypeview source
(0|1|2|3)