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.IsReplay (function)

[source]
Spring.IsReplay() -> boolean?
Returns
boolean?isReplay

Spring.GetReplayLength (function)

[source]
Spring.GetReplayLength() -> number?
Returns
number?timeInSeconds

Spring.GetGameName (function)

[source]
Spring.GetGameName() -> string
Returns
stringname

Spring.GetMenuName (function)

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

Spring.GetProfilerTimeRecord (function)

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

Spring.GetProfilerRecordNames (function)

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

Spring.GetLuaMemUsage (function)

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

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

Spring.GetTimer (function)

Get a timer with millisecond resolution

[source]

Spring.GetTimer() -> integer
Returns
integer

Spring.GetTimerMicros (function)

Get a timer with microsecond resolution

[source]

Spring.GetTimerMicros() -> integer
Returns
integer

Spring.GetFrameTimer (function)

Get a timer for the start of the frame

[source]

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)

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

[source]
Spring.GetNumDisplays() -> number
Returns
numbernumDisplays
as returned by SDL_GetNumVideoDisplays

Spring.GetViewGeometry (function)

Get main view geometry (map and game rendering)

[source]

Spring.GetViewGeometry() -> number, number, number, number
Returns
numberviewSizeX
in px
numberviewSizeY
in px
numberviewPosX
offset from leftmost screen left border in px
numberviewPosY
offset from bottommost screen bottom border in px

Spring.GetDualViewGeometry (function)

Get dual view geometry (minimap when enabled)

[source]

Spring.GetDualViewGeometry() -> number, number, number, number
Returns
numberdualViewSizeX
in px
numberdualViewSizeY
in px
numberdualViewPosX
offset from leftmost screen left border in px
numberdualViewPosY
offset from bottommost screen bottom border in px

Spring.GetWindowGeometry (function)

Get main window geometry

[source]

Spring.GetWindowGeometry() -> number, number, number, number, number, number, number, number
Returns
numberwinSizeX
in px
numberwinSizeY
in px
numberwinPosX
in px
numberwinPosY
in px
numberwindowBorderTop
in px
numberwindowBorderLeft
in px
numberwindowBorderBottom
in px
numberwindowBorderRight
in px

Spring.GetWindowDisplayMode (function)

Get main window display mode

[source]

Spring.GetWindowDisplayMode() -> number, number, number, number
Returns
numberwidth
in px
numberheight
in px
numberbits
per pixel
numberrefresh
rate in Hz

Spring.GetScreenGeometry (function)

Get screen geometry

[source]

Spring.GetScreenGeometry(number?, boolean?) -> number, number, number, number, number, number, number, number, number?, number?, number?, number?
Parameters
number?displayIndex
(Default: -1)
boolean?queryUsable
(Default: false)
Returns
numberscreenSizeX
in px
numberscreenSizeY
in px
numberscreenPosX
in px
numberscreenPosY
in px
numberwindowBorderTop
in px
numberwindowBorderLeft
in px
numberwindowBorderBottom
in px
numberwindowBorderRight
in px
number?screenUsableSizeX
in px
number?screenUsableSizeY
in px
number?screenUsablePosX
in px
number?screenUsablePosY
in px

Spring.GetMiniMapGeometry (function)

Get minimap geometry

[source]

Spring.GetMiniMapGeometry() -> number, number, number, number, boolean, boolean
Returns
numberminimapPosX
in px
numberminimapPosY
in px
numberminimapSizeX
in px
numberminimapSizeY
in px
booleanminimized
booleanmaximized

Spring.GetMiniMapRotation (function)

Get minimap rotation

[source]

Spring.GetMiniMapRotation() -> number
Returns
numberamount
in radians

Spring.GetMiniMapDualScreen (function)

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

Spring.GetSelectionBox (function)

Get vertices from currently active selection box

[source]

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)

[source]
Spring.GetDrawSelectionInfo() -> boolean
Returns
boolean

Spring.IsAboveMiniMap (function)

[source]
Spring.IsAboveMiniMap(number, number) -> boolean
Parameters
numberx
numbery
Returns
booleanisAbove

Spring.GetDrawFrame (function)

[source]
Spring.GetDrawFrame() -> number, number
Returns
numberlow_16bit
numberhigh_16bit

Spring.GetFrameTimeOffset (function)

[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.GetLastUpdateSeconds (function)

[source]
Spring.GetLastUpdateSeconds() -> number?
Returns
number?lastUpdateSeconds

Spring.GetVideoCapturingMode (function)

[source]
Spring.GetVideoCapturingMode() -> boolean
Returns
booleanallowRecord

Spring.IsUnitAllied (function)

[source]
Spring.IsUnitAllied(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?isAllied
nil with unitID cannot be parsed

Spring.IsUnitSelected (function)

[source]
Spring.IsUnitSelected(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?isSelected
nil when unitID cannot be parsed

Spring.GetUnitLuaDraw (function)

[source]
Spring.GetUnitLuaDraw(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?draw
nil when unitID cannot be parsed

Spring.GetUnitNoDraw (function)

[source]
Spring.GetUnitNoDraw(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?nil
when unitID cannot be parsed

Spring.GetUnitEngineDrawMask (function)

[source]
Spring.GetUnitEngineDrawMask(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?nil
when unitID cannot be parsed

Spring.GetUnitAlwaysUpdateMatrix (function)

[source]
Spring.GetUnitAlwaysUpdateMatrix(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?nil
when unitID cannot be parsed

Spring.GetUnitDrawFlag (function)

[source]
Spring.GetUnitDrawFlag(integer) -> number?
Parameters
integerunitID
Returns
number?nil
when unitID cannot be parsed

Spring.GetUnitNoMinimap (function)

[source]
Spring.GetUnitNoMinimap(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?nil
when unitID cannot be parsed

Spring.GetUnitNoGroup (function)

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

[source]

Spring.GetUnitNoGroup(integer) -> boolean?
Parameters
integerunitID
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)

[source]
Spring.GetUnitNoSelect(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?noSelect
nil when unitID cannot be parsed.

Spring.UnitIconGetDraw (function)

[source]
Spring.UnitIconGetDraw(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?drawIcon

Spring.GetUnitIconData (function)

Get unit icon data

[source]

See Spring.GetIconData

Spring.GetUnitIconData(number, boolean?) -> IconData
Parameters
numberunitID
boolean?fullData
(Default: false) Whether additional information about the icon is returned, otherwise only name and atlasTexCoords are returned
Returns
IconDataiconData

Spring.GetIconData (function)

Get icon data

[source]

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
IconDataiconData

Spring.GetAllIconDataArray (function)

Get icon data

[source]

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

[source]
Spring.GetUnitSelectionVolumeData(integer) -> number?, number, number, number, number, number, number, number, number, boolean
Parameters
integerunitID
Returns
number?scaleX
nil when unitID cannot be parsed
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numbervolumeType
numberuseContHitTest
numbergetPrimaryAxis
booleanignoreHits

Spring.GetFeatureLuaDraw (function)

[source]
Spring.GetFeatureLuaDraw(integer) -> boolean?
Parameters
integerfeatureID
Returns
boolean?nil
when featureID cannot be parsed

Spring.GetFeatureNoDraw (function)

[source]
Spring.GetFeatureNoDraw(integer) -> boolean?
Parameters
integerfeatureID
Returns
boolean?nil
when featureID cannot be parsed

Spring.GetFeatureEngineDrawMask (function)

[source]
Spring.GetFeatureEngineDrawMask(integer) -> boolean?
Parameters
integerfeatureID
Returns
boolean?nil
when featureID cannot be parsed

Spring.GetFeatureAlwaysUpdateMatrix (function)

[source]
Spring.GetFeatureAlwaysUpdateMatrix(integer) -> boolean?
Parameters
integerfeatureID
Returns
boolean?nil
when featureID cannot be parsed

Spring.GetFeatureDrawFlag (function)

[source]
Spring.GetFeatureDrawFlag(integer) -> number?
Parameters
integerfeatureID
Returns
number?nil
when featureID cannot be parsed

Spring.GetFeatureSelectionVolumeData (function)

[source]
Spring.GetFeatureSelectionVolumeData(integer) -> number?, number, number, number, number, number, number, number, number, boolean
Parameters
integerfeatureID
Returns
number?scaleX
nil when unitID cannot be parsed
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numbervolumeType
numberuseContHitTest
numbergetPrimaryAxis
booleanignoreHits

Spring.GetUnitTransformMatrix (function)

[source]
Spring.GetUnitTransformMatrix(integer) -> number?, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
integerunitID
Returns
number?m11
nil when unitID cannot be parsed
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.GetFeatureTransformMatrix (function)

[source]
Spring.GetFeatureTransformMatrix(integer) -> number?, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
integerfeatureID
Returns
number?m11
nil when featureID cannot be parsed
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.IsUnitInView (function)

[source]
Spring.IsUnitInView(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?inView
nil when unitID cannot be parsed

Spring.IsUnitVisible (function)

[source]
Spring.IsUnitVisible(integer, number?, boolean) -> boolean?
Parameters
integerunitID
number?radius
unitRadius when not specified
booleancheckIcon
Returns
boolean?isVisible
nil when unitID cannot be parsed

Spring.IsUnitIcon (function)

[source]
Spring.IsUnitIcon(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?isUnitIcon
nil when unitID cannot be parsed

Spring.IsAABBInView (function)

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

Spring.IsSphereInView (function)

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

Spring.GetUnitViewPosition (function)

[source]
Spring.GetUnitViewPosition(integer, boolean?) -> number?, number, number
Parameters
integerunitID
boolean?midPos
(Default: false)
Returns
number?x
nil when unitID cannot be parsed
numbery
numberz

Spring.GetVisibleUnits (function)

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

Spring.GetVisibleFeatures (function)

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

Spring.GetVisibleProjectiles (function)

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

Spring.GetRenderUnits (function)

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

Spring.GetRenderUnits (function overload 1)

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

Spring.GetRenderUnitsDrawFlagChanged (function)

[source]

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

Spring.GetRenderUnitsDrawFlagChanged(true) -> integer[], DrawFlag[]
Parameters
truesendMask
Whether to send objects draw flags as second return.
Returns
integer[]ids
DrawFlag[]unitDrawFlags

Spring.GetRenderUnitsDrawFlagChanged (function overload 1)

[source]

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

Spring.GetRenderUnitsDrawFlagChanged(false?) -> integer[]
Parameters
false?sendMask
Whether to send objects draw flags as second return.
Returns
integer[]ids

Spring.GetRenderFeatures (function)

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

Spring.GetRenderFeatures (function overload 1)

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

Spring.GetRenderFeaturesDrawFlagChanged (function)

[source]

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

Spring.GetRenderFeaturesDrawFlagChanged(true) -> integer[], DrawFlag[]
Parameters
truesendMask
Whether to send objects draw flags as second return.
Returns
integer[]ids
DrawFlag[]unitDrawFlags

Spring.GetRenderFeaturesDrawFlagChanged (function overload 1)

[source]

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

Spring.GetRenderFeaturesDrawFlagChanged(false?) -> integer[]
Parameters
false?sendMask
Whether to send objects draw flags as second return.
Returns
integer[]ids

Spring.ClearUnitsPreviousDrawFlag (function)

[source]
Spring.ClearUnitsPreviousDrawFlag() -> nil

Spring.ClearFeaturesPreviousDrawFlag (function)

[source]
Spring.ClearFeaturesPreviousDrawFlag() -> nil

Spring.GetUnitsInScreenRectangle (function)

Get units inside a rectangle area on the map

[source]

Spring.GetUnitsInScreenRectangle(number, number, number, number, number?) -> number[]?
Parameters
numberleft
numbertop
numberright
numberbottom
number?allegiance
(Default: -1) teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4
Returns
number[]?unitIDs

Spring.GetFeaturesInScreenRectangle (function)

Get features inside a rectangle area on the map

[source]

Spring.GetFeaturesInScreenRectangle(number, number, number, number) -> number[]?
Parameters
numberleft
numbertop
numberright
numberbottom
Returns
number[]?featureIDs

Spring.GetLocalPlayerID (function)

[source]
Spring.GetLocalPlayerID() -> integer
Returns
integerplayerID

Spring.GetLocalTeamID (function)

[source]
Spring.GetLocalTeamID() -> integer
Returns
integerteamID

Spring.GetLocalAllyTeamID (function)

[source]
Spring.GetLocalAllyTeamID() -> integer
Returns
integerallyTeamID

Spring.GetSpectatingState (function)

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

Spring.GetSelectedUnits (function)

[source]
Spring.GetSelectedUnits() -> number[]
Returns
number[]unitIDs

Spring.GetSelectedUnitsSorted (function)

Get selected units aggregated by unitDefID

[source]

Spring.GetSelectedUnitsSorted() -> table<number,number[]>, integer
Returns
table<number,number[]>where
keys are unitDefIDs and values are unitIDs
integerthe
number of unitDefIDs

Spring.GetSelectedUnitsCounts (function)

Get an aggregate count of selected units per unitDefID

[source]

Spring.GetSelectedUnitsCounts() -> table<number,number>, integer
Returns
table<number,number>unitsCounts
where keys are unitDefIDs and values are counts
integerthe
number of unitDefIDs

Spring.GetSelectedUnitsCount (function)

Returns the amount of selected units

[source]

Spring.GetSelectedUnitsCount() -> number
Returns
numberselectedUnitsCount

Spring.GetBoxSelectionByEngine (function)

Get if selection box is handled by engine.

[source]

See Spring.SetBoxSelectionByEngine

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

Spring.IsGUIHidden (function)

[source]
Spring.IsGUIHidden() -> boolean
Returns
boolean

Spring.HaveShadows (function)

[source]
Spring.HaveShadows() -> boolean
Returns
booleanshadowsLoaded

Spring.HaveAdvShading (function)

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

Spring.GetWaterMode (function)

[source]

See rts/Rendering/Env/IWater.h

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

Spring.GetMapDrawMode (function)

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

Spring.GetMapSquareTexture (function)

[source]
Spring.GetMapSquareTexture(number, number, number, string, number?) -> boolean?
Parameters
numbertexSquareX
numbertexSquareY
numberlodMin
stringluaTexName
number?lodMax
(Default: lodMin)
Returns
boolean?success

Spring.GetLosViewColors (function)

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

Spring.GetNanoProjectileParams (function)

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

Get available cameras.

[source]

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

Spring.GetCameraState (function)

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

Spring.GetCameraState (function overload 1)

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

Spring.GetCameraPosition (function)

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

Spring.GetCameraDirection (function)

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

Spring.GetCameraRotation (function)

Get camera rotation in radians.

[source]

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)

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

Spring.GetCameraVectors (function)

[source]
Spring.GetCameraVectors() -> CameraVectors
Returns
CameraVectors

Spring.WorldToScreenCoords (function)

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

Spring.TraceScreenRay (function)

Get information about a ray traced from screen to world position

[source]

Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown).

Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true).

This will only work for units & objects with the default collision sphere. Per Piece collision and custom collision objects are not supported.

The unit must be selectable, to appear to a screen trace ray.

Spring.TraceScreenRay(number, number, boolean?, boolean?, boolean?, boolean?, number?) -> string?, (number|string|xyz)?, (number|string)?, xyz?
Parameters
numberscreenX
position on x axis in mouse coordinates (origin on left border of view)
numberscreenY
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
(number|string|xyz)?unitID
or feature, position triple when onlyCoords=true
(number|string)?featureID
or ground
xyz?coords

Spring.GetPixelDir (function)

[source]
Spring.GetPixelDir(number, number) -> number, number, number
Parameters
numberx
numbery
Returns
numberdirX
numberdirY
numberdirZ

Spring.GetTeamColor (function)

[source]
Spring.GetTeamColor(integer) -> number?, number?, number?, number?
Parameters
integerteamID
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)

[source]
Spring.GetTeamOrigColor(integer) -> number?, number?, number?, number?
Parameters
integerteamID
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.GetDrawSeconds (function)

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

Spring.GetSoundDevices (function)

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

Spring.GetSoundStreamTime (function)

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

Spring.GetSoundEffectParams (function)

[source]
Spring.GetSoundEffectParams() -> nil

Spring.GetFPS (function)

[source]
Spring.GetFPS() -> number
Returns
numberfps

Spring.GetGameSpeed (function)

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

Spring.GetGameState (function)

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

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

Spring.GetDefaultCommand (function)

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

Spring.GetActiveCmdDescs (function)

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

Spring.GetActiveCmdDesc (function)

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

Spring.GetCmdDescIndex (function)

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

Spring.GetBuildFacing (function)

[source]
Spring.GetBuildFacing() -> FacingInteger
Returns
FacingIntegerbuildFacing

Spring.GetBuildSpacing (function)

[source]
Spring.GetBuildSpacing() -> number
Returns
numberbuildSpacing

Spring.GetGatherMode (function)

[source]
Spring.GetGatherMode() -> number
Returns
numbergatherMode

Spring.GetActivePage (function)

[source]
Spring.GetActivePage() -> number, number
Returns
numberactivePage
numbermaxPage

Spring.GetMouseState (function)

[source]
Spring.GetMouseState() -> number, number, number, number, number, boolean, boolean
Returns
numberx
numbery
numberlmbPressed
left mouse button pressed
numbermmbPressed
middle mouse button pressed
numberrmbPressed
right mouse button pressed
booleanoffscreen
booleanmmbScroll

Spring.GetMouseCursor (function)

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

Spring.GetMouseStartPosition (function)

[source]
Spring.GetMouseStartPosition(number) -> number, number, number, number, number, number, number, number
Parameters
numberbutton
Returns
numberx
numbery
numbercamPosX
numbercamPosY
numbercamPosZ
numberdirX
numberdirY
numberdirZ

Spring.GetMouseButtonsPressed (function)

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

[source]
Spring.GetClipboard() -> string
Returns
stringtext

Spring.IsUserWriting (function)

[source]
Spring.IsUserWriting() -> boolean
Returns
boolean

Spring.GetLastMessagePositions (function)

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

Spring.GetConsoleBuffer (function)

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

Spring.GetCurrentTooltip (function)

[source]
Spring.GetCurrentTooltip() -> string
Returns
stringtooltip

Spring.GetKeyFromScanSymbol (function)

[source]
Spring.GetKeyFromScanSymbol(string) -> string
Parameters
stringscanSymbol
Returns
stringkeyName

Spring.GetKeyState (function)

[source]
Spring.GetKeyState(number) -> boolean
Parameters
numberkeyCode
Returns
booleanpressed

Spring.GetModKeyState (function)

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

Spring.GetPressedKeys (function)

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

Spring.GetPressedScans (function)

[source]
Spring.GetPressedScans() -> table<(number|string),true>
Returns
table<(number|string),true>where
keys are scanCodes or scan names

Spring.GetInvertQueueKey (function)

[source]
Spring.GetInvertQueueKey() -> number?
Returns
number?queueKey

Spring.GetKeyCode (function)

[source]
Spring.GetKeyCode(string) -> number
Parameters
stringkeySym
Returns
numberkeyCode

Spring.GetKeySymbol (function)

[source]
Spring.GetKeySymbol(number) -> string, string
Parameters
numberkeyCode
Returns
stringkeyCodeName
stringkeyCodeDefaultName
name when there are not aliases

Spring.GetScanSymbol (function)

[source]
Spring.GetScanSymbol(number) -> string, string
Parameters
numberscanCode
Returns
stringscanCodeName
stringscanCodeDefaultName
name when there are not aliases

Spring.GetKeyBindings (function)

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

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

Spring.GetGroupList (function)

[source]
Spring.GetGroupList() -> table<number,number>?
Returns
table<number,number>?where
keys are groupIDs and values are counts

Spring.GetSelectedGroup (function)

[source]
Spring.GetSelectedGroup() -> integer
Returns
integergroupID

Spring.GetUnitGroup (function)

[source]
Spring.GetUnitGroup(integer) -> integer?
Parameters
integerunitID
Returns
integer?groupID

Spring.GetGroupUnits (function)

[source]
Spring.GetGroupUnits(integer) -> number[]?
Parameters
integergroupID
Returns
number[]?unitIDs

Spring.GetGroupUnitsSorted (function)

[source]
Spring.GetGroupUnitsSorted(integer) -> table<number,number[]>?
Parameters
integergroupID
Returns
table<number,number[]>?where
keys are unitDefIDs and values are unitIDs

Spring.GetGroupUnitsCounts (function)

[source]
Spring.GetGroupUnitsCounts(integer) -> table<number,number>?
Parameters
integergroupID
Returns
table<number,number>?where
keys are unitDefIDs and values are counts

Spring.GetGroupUnitsCount (function)

[source]
Spring.GetGroupUnitsCount(integer) -> number?
Parameters
integergroupID
Returns
number?groupSize

Spring.GetPlayerRoster (function)

[source]
Spring.GetPlayerRoster(number?, boolean?) -> Roster[]?
Parameters
number?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)

[source]
Spring.GetPlayerTraffic(integer, integer?) -> number
Parameters
integerplayerID
integer?packetID
Returns
numbertraffic

Spring.GetPlayerStatistics (function)

[source]
Spring.GetPlayerStatistics(integer) -> number?, number, number, number, number
Parameters
integerplayerID
Returns
number?mousePixels
nil when invalid playerID
numbermouseClicks
numberkeyPresses
numbernumCommands
numberunitCommands

Spring.GetConfigParams (function)

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

Spring.GetConfigInt (function)

[source]
Spring.GetConfigInt(string, number?) -> number?
Parameters
stringname
number?default
(Default: 0)
Returns
number?configInt

Spring.GetConfigFloat (function)

[source]
Spring.GetConfigFloat(string, number?) -> number?
Parameters
stringname
number?default
(Default: 0)
Returns
number?configFloat

Spring.GetConfigString (function)

[source]
Spring.GetConfigString(string, string?) -> number?
Parameters
stringname
string?default
(Default: "")
Returns
number?configString

Spring.GetLogSections (function)

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

Spring.GetAllGroundDecals (function)

[source]
Spring.GetAllGroundDecals() -> number[]
Returns
number[]decalIDs

Spring.GetGroundDecalMiddlePos (function)

[source]
Spring.GetGroundDecalMiddlePos(integer) -> number?, number
Parameters
integerdecalID
Returns
number?posX
numberposZ

Spring.GetGroundDecalQuadPos (function)

[source]
Spring.GetGroundDecalQuadPos(integer) -> number?, number, number, number, number, number, number, number
Parameters
integerdecalID
Returns
number?posTL.x
numberposTL.z
numberposTR.x
numberposTR.z
numberposBR.x
numberposBR.z
numberposBL.x
numberposBL.z

Spring.GetGroundDecalSizeAndHeight (function)

[source]
Spring.GetGroundDecalSizeAndHeight(integer) -> number?, number, number
Parameters
integerdecalID
Returns
number?sizeX
numbersizeY
numberprojCubeHeight

Spring.GetGroundDecalRotation (function)

[source]
Spring.GetGroundDecalRotation(integer) -> number?
Parameters
integerdecalID
Returns
number?rotation
Rotation in radians.

Spring.GetGroundDecalTexture (function)

[source]
Spring.GetGroundDecalTexture(integer, boolean?) -> string?
Parameters
integerdecalID
boolean?isMainTex
(Default: true) If false, return the normal/glow map.
Returns
string?texture

Spring.GetGroundDecalTextures (function)

[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.SetGroundDecalTextureParams (function)

[source]
Spring.SetGroundDecalTextureParams(integer) -> number?, number
Parameters
integerdecalID
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.SetGroundDecalTextureParams (function overload 1)

[source]
Spring.SetGroundDecalTextureParams(integer, number?, number?) -> boolean?
Parameters
integerdecalID
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.GetGroundDecalAlpha (function)

[source]
Spring.GetGroundDecalAlpha(integer) -> number?, number
Parameters
integerdecalID
Returns
number?alpha
Between 0 and 1
numberalphaFalloff
Between 0 and 1, per second

Spring.GetGroundDecalNormal (function)

[source]

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

Spring.GetGroundDecalNormal(integer) -> number?, number, number
Parameters
integerdecalID
Returns
number?normal.x
numbernormal.y
numbernormal.z

Spring.GetGroundDecalTint (function)

[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(integer) -> number?, number, number, number
Parameters
integerdecalID
Returns
number?tintR
numbertintG
numbertintB
numbertintA

Spring.GetGroundDecalMisc (function)

[source]

Returns less important parameters of a ground decal

Spring.GetGroundDecalMisc(integer) -> number?, number, number, number, number
Parameters
integerdecalID
Returns
number?dotElimExp
numberrefHeight
numberminHeight
numbermaxHeight
numberforceHeightMode

Spring.GetGroundDecalCreationFrame (function)

[source]

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

Spring.GetGroundDecalCreationFrame(integer) -> number?, number
Parameters
integerdecalID
Returns
number?creationFrameMin
numbercreationFrameMax

Spring.GetGroundDecalOwner (function)

[source]
Spring.GetGroundDecalOwner(integer) -> integer?
Parameters
integerdecalID
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)

[source]

Gets the glow parameters of the ground decal.

Spring.GetGroundDecalGlowParams(integer) -> number?, number
Parameters
integerdecalID
Returns
number?glow
Between 0 and 1
numberglowFalloff
Between 0 and 1, per second

Spring.GetGroundDecalUserData (function)

[source]

Gets the user defined decal data.

Spring.GetGroundDecalUserData(integer, integer) -> number?, number, number, number
Parameters
integerdecalID
integerudQuad
vec4 index, must be within [0;1] for now
Returns
number?x
numbery
numberz
numberw

Spring.GetGroundDecalType (function)

[source]
Spring.GetGroundDecalType(integer) -> ("explosion"|"plate"|"lua"|"track"|"unknown")?
Parameters
integerdecalID
Returns
("explosion"|"plate"|"lua"|"track"|"unknown")?type

Spring.GetSyncedGCInfo (function)

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

Spring.SolveNURBSCurve (function)

[source]
Spring.SolveNURBSCurve(integer) -> number[]?
Parameters
integergroupID
Returns
number[]?unitIDs

Spring.Ping (function)

Send a ping request to the server

[source]

Spring.Ping(number) -> nil
Parameters
numberpingTag
Returns
nil

Spring.SendCommands (function)

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

Spring.SendCommands (function overload 1)

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

Spring.SendPublicChat (function)

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

[source]

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

Spring.SendAllyChat (function)

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

[source]

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

Spring.SendSpectatorChat (function)

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

[source]

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

Spring.SendPrivateChat (function)

Sends a private chat message to a specific player ID.

[source]

Spring.SendPrivateChat(string, integer) -> nil
Parameters
stringmessage
integerplayerID
Returns
nil

Spring.SendMessage (function)

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

Spring.SendMessageToSpectators (function)

[source]
Spring.SendMessageToSpectators(string) -> nil
Parameters
stringmessage

"<PLAYER#>" where # is a player ID.

This will be replaced with the player’s name. e.g. lua Spring.SendMessage(" did something") – “ProRusher did something”

Returns
nil

Spring.SendMessageToPlayer (function)

[source]
Spring.SendMessageToPlayer(integer, string) -> nil
Parameters
integerplayerID
stringmessage
Returns
nil

Spring.SendMessageToTeam (function)

[source]
Spring.SendMessageToTeam(integer, string) -> nil
Parameters
integerteamID
stringmessage
Returns
nil

Spring.SendMessageToAllyTeam (function)

[source]
Spring.SendMessageToAllyTeam(integer, string) -> nil
Parameters
integerallyID
stringmessage
Returns
nil

Spring.RequestStartPosition (function)

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

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

[source]

Spring.LoadSoundDef(string) -> boolean
Parameters
stringsoundfile
Returns
booleansuccess

Spring.PlaySoundFile (function)

[source]
Spring.PlaySoundFile(string, number?, number?, number?, number?, number?, number?, number?, SoundChannel?) -> boolean
Parameters
stringsoundfile
number?volume
(Default: 1.0)
number?posx
number?posy
number?posz
number?speedx
number?speedy
number?speedz
SoundChannel?channel
(Default: 0|“general”)
Returns
booleanplaySound

Spring.PlaySoundStream (function)

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

[source]

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)

Terminates any SoundStream currently running.

[source]

Spring.StopSoundStream() -> nil
Returns
nil

Spring.PauseSoundStream (function)

Pause any SoundStream currently running.

[source]

Spring.PauseSoundStream() -> nil
Returns
nil

Spring.SetSoundStreamVolume (function)

Set volume for SoundStream

[source]

Spring.SetSoundStreamVolume(number) -> nil
Parameters
numbervolume
Returns
nil

Spring.SetSoundEffectParams (function)

[source]
Spring.SetSoundEffectParams() -> nil

Spring.AddWorldIcon (function)

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

Spring.AddWorldText (function)

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

Spring.AddWorldUnit (function)

[source]
Spring.AddWorldUnit(integer, number, number, number, integer, FacingInteger) -> nil
Parameters
integerunitDefID
numberposX
numberposY
numberposZ
integerteamID
FacingIntegerfacing
Returns
nil

Spring.DrawUnitCommands (function)

[source]
Spring.DrawUnitCommands(integer) -> nil
Parameters
integerunitID

Spring.DrawUnitCommands (function overload 1)

[source]
Spring.DrawUnitCommands(integer[], false?) -> nil
Parameters
integer[]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)

[source]
Spring.DrawUnitCommands(table<integer,any>, true) -> nil
Parameters
table<integer,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)

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

[source]

Spring.SetCameraTarget(number, number, number, number?) -> nil
Parameters
numberx
numbery
numberz
number?transTime
Returns
nil

Spring.SetCameraOffset (function)

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

Set camera state.

[source]

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
number?transitionTimeExponent
Returns
booleanset
true when applied without errors, otherwise false.

Spring.RunDollyCamera (function)

Runs Dolly Camera

[source]

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

Spring.PauseDollyCamera (function)

Pause Dolly Camera

[source]

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

Spring.ResumeDollyCamera (function)

Resume Dolly Camera

[source]

Spring.ResumeDollyCamera() -> nil
Returns
nil

Spring.SetDollyCameraPosition (function)

Sets Dolly Camera Position

[source]

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

Spring.SetDollyCameraCurve (function)

Sets Dolly Camera movement Curve

[source]

Spring.SetDollyCameraCurve(number, ControlPoint[], table) -> nil
Parameters
numberdegree
ControlPoint[]cpoints
NURBS control point positions.
tableknots
Returns
nil

Spring.SetDollyCameraMode (function)

Sets Dolly Camera movement mode

[source]

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

Spring.SetDollyCameraRelativeMode (function)

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

[source]

Spring.SetDollyCameraRelativeMode(number) -> nil
Parameters
numberrelativeMode
1 world, 2 look target
Returns
nil

Spring.SetDollyCameraLookCurve (function)

Sets Dolly Camera Look Curve

[source]

Spring.SetDollyCameraLookCurve(number, ControlPoint[], table) -> nil
Parameters
numberdegree
ControlPoint[]cpoints
NURBS control point positions.
tableknots
Returns
nil

Spring.SetDollyCameraLookPosition (function)

Sets Dolly Camera Look Position

[source]

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

Spring.SetDollyCameraLookUnit (function)

Sets target unit for Dolly Camera to look towards

[source]

Spring.SetDollyCameraLookUnit(integer) -> nil
Parameters
integerunitID
The unit to look at.
Returns
nil

Spring.SelectUnit (function)

Selects a single unit

[source]

Spring.SelectUnit(integer?, boolean?) -> nil
Parameters
integer?unitID
boolean?append
(Default: false) Append to current selection.
Returns
nil

Spring.DeselectUnit (function)

[source]
Spring.DeselectUnit(integer) -> nil
Parameters
integerunitID
Returns
nil

Spring.DeselectUnitArray (function)

Deselects multiple units.

[source]

Spring.DeselectUnitArray(integer[]) -> nil
Parameters
integer[]unitIDs
Table with unit IDs as values.
Returns
nil

Spring.DeselectUnitMap (function)

Deselects multiple units.

[source]

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

Spring.SelectUnitArray (function)

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

[source]

Spring.SelectUnitArray(integer[], boolean?) -> nil
Parameters
integer[]unitIDs
Table with unit IDs as values.
boolean?append
(Default: false) append to current selection
Returns
nil

Spring.SelectUnitMap (function)

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

[source]

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

Spring.AddMapLight (function)

[source]

requires MaxDynamicMapLights > 0

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

Spring.AddModelLight (function)

[source]

requires MaxDynamicMapLights > 0

Spring.AddModelLight(LightParams) -> number
Parameters
LightParamslightParams
Returns
numberlightHandle

Spring.UpdateMapLight (function)

[source]
Spring.UpdateMapLight(number, LightParams) -> boolean
Parameters
numberlightHandle
LightParamslightParams
Returns
booleansuccess

Spring.UpdateModelLight (function)

[source]
Spring.UpdateModelLight(number, LightParams) -> boolean
Parameters
numberlightHandle
LightParamslightParams
Returns
booleansuccess

Spring.AddLightTrackingTarget (function)

[source]
Spring.AddLightTrackingTarget() -> nil

Spring.SetMapLightTrackingState (function)

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

[source]

Spring.SetMapLightTrackingState(number, integer, boolean, boolean) -> boolean
Parameters
numberlightHandle
integerunitOrProjectileID
booleanenableTracking
booleanunitOrProjectile
Returns
booleansuccess

Spring.SetModelLightTrackingState (function)

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

[source]

Spring.SetModelLightTrackingState(number, integer, boolean, boolean) -> boolean
Parameters
numberlightHandle
integerunitOrProjectileID
booleanenableTracking
booleanunitOrProjectile
Returns
booleansuccess

Spring.SetMapShader (function)

[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) -> nil
Parameters
integerstandardShaderID
integerdeferredShaderID
Returns
nil

Spring.SetMapSquareTexture (function)

[source]
Spring.SetMapSquareTexture(number, number, string) -> boolean
Parameters
numbertexSqrX
numbertexSqrY
stringluaTexName
Returns
booleansuccess

Spring.SetMapShadingTexture (function)

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

Spring.SetSkyBoxTexture (function)

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

Spring.SetUnitNoDraw (function)

[source]
Spring.SetUnitNoDraw(integer, boolean) -> nil
Parameters
integerunitID
booleannoDraw
Returns
nil

Spring.SetUnitEngineDrawMask (function)

[source]
Spring.SetUnitEngineDrawMask(integer, number) -> nil
Parameters
integerunitID
numberdrawMask
Returns
nil

Spring.SetUnitAlwaysUpdateMatrix (function)

[source]
Spring.SetUnitAlwaysUpdateMatrix(integer, boolean) -> nil
Parameters
integerunitID
booleanalwaysUpdateMatrix
Returns
nil

Spring.SetUnitNoMinimap (function)

[source]
Spring.SetUnitNoMinimap(integer, boolean) -> nil
Parameters
integerunitID
booleanunitNoMinimap
Returns
nil

Spring.SetMiniMapRotation (function)

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

Spring.SetUnitNoGroup (function)

[source]
Spring.SetUnitNoGroup(integer, boolean) -> nil
Parameters
integerunitID
booleanunitNoGroup
Whether unit can be added to selection groups

Spring.SetUnitNoSelect (function)

[source]
Spring.SetUnitNoSelect(integer, boolean) -> nil
Parameters
integerunitID
booleanunitNoSelect
whether unit can be selected or not
Returns
nil

Spring.SetUnitLeaveTracks (function)

[source]
Spring.SetUnitLeaveTracks(integer, boolean) -> nil
Parameters
integerunitID
booleanunitLeaveTracks
whether unit leaves tracks on movement
Returns
nil

Spring.SetUnitSelectionVolumeData (function)

[source]
Spring.SetUnitSelectionVolumeData(integer, integer, number, number, number, number, number, number, number, number, number) -> nil
Parameters
integerunitID
integerfeatureID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numbervType
numbertType
numberAxis
Returns
nil

Spring.SetFeatureNoDraw (function)

[source]
Spring.SetFeatureNoDraw(integer, boolean) -> nil
Parameters
integerfeatureID
booleannoDraw
Returns
nil

Spring.SetFeatureEngineDrawMask (function)

[source]
Spring.SetFeatureEngineDrawMask(integer, number) -> nil
Parameters
integerfeatureID
numberengineDrawMask
Returns
nil

Spring.SetFeatureAlwaysUpdateMatrix (function)

[source]
Spring.SetFeatureAlwaysUpdateMatrix(integer, number) -> nil
Parameters
integerfeatureID
numberalwaysUpdateMat
Returns
nil

Spring.SetFeatureFade (function)

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

[source]

Spring.SetFeatureFade(integer, boolean) -> nil
Parameters
integerfeatureID
booleanallow
Returns
nil

Spring.SetFeatureSelectionVolumeData (function)

[source]
Spring.SetFeatureSelectionVolumeData(integer, number, number, number, number, number, number, number, number, number) -> nil
Parameters
integerfeatureID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numbervType
numbertType
numberAxis
Returns
nil

Spring.AddUnitIcon (function)

[source]
Spring.AddUnitIcon(string, string, 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
Returns
booleanadded

Spring.FreeUnitIcon (function)

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

Spring.UnitIconSetDraw (function)

[source]

Use Spring.SetUnitIconDraw instead.

Deprecated

Spring.UnitIconSetDraw(integer, boolean) -> nil
Parameters
integerunitID
booleandrawIcon
Returns
nil

Spring.SetUnitIconDraw (function)

[source]
Spring.SetUnitIconDraw(integer, boolean) -> nil
Parameters
integerunitID
booleandrawIcon
Returns
nil

Spring.SetUnitDefIcon (function)

[source]
Spring.SetUnitDefIcon(integer, string) -> nil
Parameters
integerunitDefID
stringiconName
Returns
nil

Spring.SetUnitDefImage (function)

[source]
Spring.SetUnitDefImage(integer, string) -> nil
Parameters
integerunitDefID
stringimage
luaTexture|texFile
Returns
nil

Spring.ExtractModArchiveFile (function)

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

Spring.CreateDir (function)

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

Spring.SetActiveCommand (function)

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

Spring.SetActiveCommand (function overload 1)

[source]
Spring.SetActiveCommand(number, number?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?) -> boolean?
Parameters
numbercmdIndex
number?button
(Default: 1)
boolean?leftClick
boolean?rightClick
boolean?alt
boolean?ctrl
boolean?meta
boolean?shift
Returns
boolean?commandSet

Spring.LoadCmdColorsConfig (function)

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

Spring.LoadCtrlPanelConfig (function)

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

Spring.ForceLayoutUpdate (function)

[source]
Spring.ForceLayoutUpdate() -> nil
Returns
nil

Spring.SetDrawSelectionInfo (function)

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

[source]

Spring.SetDrawSelectionInfo(boolean) -> nil
Parameters
booleanenable
Returns
nil

Spring.SetBoxSelectionByEngine (function)

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

Spring.SetTeamColor (function)

[source]
Spring.SetTeamColor(integer, number, number, number) -> nil
Parameters
integerteamID
numberr
numberg
numberb
Returns
nil

Spring.AssignMouseCursor (function)

Changes/creates the cursor of a single CursorCmd.

[source]

Spring.AssignMouseCursor(string, string, boolean?, boolean?) -> boolean?
Parameters
stringcmdName
stringiconFileName
not the full filename, instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack
boolean?overwrite
(Default: true)
boolean?hotSpotTopLeft
(Default: false)
Returns
boolean?assigned

Spring.ReplaceMouseCursor (function)

Mass replace all occurrences of the cursor in all CursorCmds.

[source]

Spring.ReplaceMouseCursor(string, string, boolean?) -> boolean?
Parameters
stringoldFileName
stringnewFileName
boolean?hotSpotTopLeft
(Default: false)
Returns
boolean?assigned

Spring.SetCustomCommandDrawData (function)

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

[source]

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)

[source]
Spring.WarpMouse(number, number) -> nil
Parameters
numberx
numbery
Returns
nil

Spring.SetMouseCursor (function)

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

Spring.SetLosViewColors (function)

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

Spring.SetNanoProjectileParams (function)

[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.SetConfigInt (function)

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

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

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

Closes the application

[source]

Spring.Quit() -> nil
Returns
nil

Spring.SetUnitGroup (function)

[source]
Spring.SetUnitGroup(integer, integer) -> nil
Parameters
integerunitID
integergroupID
the group number to be assigned, or -1 for deassignment
Returns
nil

Spring.GiveOrder (function)

Give order to selected units.

[source]

Spring.GiveOrder((CMD|integer), CreateCommandParams, CreateCommandOptions?, integer?) -> boolean
Parameters
(CMD|integer)cmdID
The command ID.
CreateCommandParamsparams
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)

Give order to specific unit.

[source]

Spring.GiveOrderToUnit(integer, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
integerunitID
(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)

[source]
Spring.GiveOrderToUnit(integer, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
integerunitID
(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)

Give order to multiple units, specified by table keys.

[source]

Spring.GiveOrderToUnitMap(table<integer,any>, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
table<integer,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)

Give order to multiple units, specified by table keys.

[source]

Spring.GiveOrderToUnitMap(table<integer,any>, (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> integer
Parameters
table<integer,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)

Give order to an array of units.

[source]

Spring.GiveOrderToUnitArray(integer[], (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> boolean
Parameters
integer[]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)

[source]
Spring.GiveOrderToUnitArray(integer[], (CMD|integer), CreateCommandParams?, CreateCommandOptions?, integer?) -> integer
Parameters
integer[]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)

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

Spring.GiveOrderArrayToUnit (function overload 1)

[source]
Spring.GiveOrderArrayToUnit(integer, CreateCommand[]) -> boolean
Parameters
integerunitID
CreateCommand[]commands
Returns
booleanordersGiven

Spring.GiveOrderArrayToUnitMap (function)

[source]
Spring.GiveOrderArrayToUnitMap(table<integer,any>, CreateCommand[]) -> boolean
Parameters
table<integer,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)

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

Spring.GiveOrderArrayToUnitArray (function)

[source]
Spring.GiveOrderArrayToUnitArray(integer[], CreateCommand[], boolean?) -> boolean
Parameters
integer[]unitIDs
Array of unit IDs.
CreateCommand[]commands
boolean?pairwise

(Default: false) When false, assign all commands to each unit.

When true, assign commands according to index between units and cmds arrays.

If len(unitArray) < len(cmdArray) only the first len(unitArray) commands will be assigned, and vice-versa.

Returns
booleanordersGiven
true if any orders were sent, otherwise false.

Spring.GiveOrderArrayToUnitArray (function overload 1)

[source]
Spring.GiveOrderArrayToUnitArray(integer[], CreateCommand[], boolean?) -> integer
Parameters
integer[]unitIDs
Array of unit IDs.
CreateCommand[]commands
boolean?pairwise

(Default: false) When false, assign all commands to each unit.

When true, assign commands according to index between units and cmds arrays.

If len(unitArray) < len(cmdArray) only the first len(unitArray) commands will be assigned, and vice-versa.

Returns
integerunitsOrdered
The number of units ordered.

Spring.SetBuildSpacing (function)

[source]
Spring.SetBuildSpacing(number) -> nil
Parameters
numberspacing
Returns
nil

Spring.SetBuildFacing (function)

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

Spring.SendLuaUIMsg (function)

[source]
Spring.SendLuaUIMsg(string, string) -> nil
Parameters
stringmessage
stringmode
“s”/“specs” | “a”/“allies”
Returns
nil

Spring.SendLuaGaiaMsg (function)

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

Spring.SendLuaRulesMsg (function)

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

Spring.SendLuaMenuMsg (function)

[source]
Spring.SendLuaMenuMsg(string) -> nil
Parameters
stringmsg

Spring.SetShareLevel (function)

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

Spring.ShareResources (function)

[source]
Spring.ShareResources(integer, string) -> nil
Parameters
integerteamID
stringunits
Returns
nil

Spring.ShareResources (function overload 1)

[source]
Spring.ShareResources(integer, string, number) -> nil
Parameters
integerteamID
stringresource
metal | energy
numberamount
Returns
nil

Spring.SetLastMessagePosition (function)

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

Spring.MarkerAddPoint (function)

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

Spring.MarkerAddLine (function)

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

Spring.MarkerErasePosition (function)

[source]

Issue an erase command for markers on the map.

Spring.MarkerErasePosition(number, number, number, nil, boolean?, number?, 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
number?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)

Set atmosphere parameters

[source]

Spring.SetAtmosphere(AtmosphereParams) -> nil
Parameters
AtmosphereParamsparams

Spring.SetSunDirection (function)

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

Spring.SetSunLighting (function)

Modify sun lighting parameters.

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

[source]

Spring.SetSunLighting({ groundAmbientColor: rgb, groundDiffuseColor: rgb }) -> nil
Parameters
{ groundAmbientColor: rgb, groundDiffuseColor: rgb }params

Spring.SetMapRenderingParams (function)

Allows to change map rendering params at runtime.

[source]

Spring.SetMapRenderingParams(MapRenderingParams) -> nil
Parameters
MapRenderingParamsparams
Returns
nil

Spring.ForceTesselationUpdate (function)

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

Spring.SendSkirmishAIMessage (function)

[source]
Spring.SendSkirmishAIMessage(number, string) -> boolean?
Parameters
numberaiTeam
stringmessage
Returns
boolean?ai_processed

Spring.SetLogSectionFilterLevel (function)

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

Spring.GarbageCollectCtrl (function)

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

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

Spring.SetDrawSky (function)

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

Spring.SetDrawWater (function)

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

Spring.SetDrawGround (function)

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

Spring.SetDrawGroundDeferred (function)

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

Spring.SetDrawModelsDeferred (function)

[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.SetVideoCapturingMode (function)

This doesn’t actually record the game in any way, it just regulates the framerate and interpolations.

[source]

Spring.SetVideoCapturingMode(boolean) -> nil
Parameters
booleanallowCaptureMode
Returns
nil

Spring.SetVideoCapturingTimeOffset (function)

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

Spring.SetWaterParams (function)

Does not need cheating enabled.

Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your springrc to 1, then you don’t even need to restart BumpWater via /water 4.

[source]

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

Spring.PreloadUnitDefModel (function)

[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(integer) -> nil
Parameters
integerunitDefID
Returns
nil

Spring.PreloadFeatureDefModel (function)

[source]
Spring.PreloadFeatureDefModel(integer) -> nil
Parameters
integerfeatureDefID
Returns
nil

Spring.PreloadSoundItem (function)

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

Spring.LoadModelTextures (function)

[source]
Spring.LoadModelTextures(string) -> boolean?
Parameters
stringmodelName
Returns
boolean?success

Spring.CreateGroundDecal (function)

[source]
Spring.CreateGroundDecal() -> number?
Returns
number?decalID

Spring.DestroyGroundDecal (function)

[source]
Spring.DestroyGroundDecal(integer) -> boolean
Parameters
integerdecalID
Returns
booleandelSuccess

Spring.SetGroundDecalPosAndDims (function)

[source]
Spring.SetGroundDecalPosAndDims(integer, number?, number?, number?, number?, number?) -> boolean
Parameters
integerdecalID
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)

[source]

Use for non-rectangular decals

Spring.SetGroundDecalQuadPosAndHeight(integer, xz?, xz?, xz?, xz?, number?) -> boolean
Parameters
integerdecalID
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)

[source]
Spring.SetGroundDecalRotation(integer, number?) -> boolean
Parameters
integerdecalID
number?rot
(Default: random) in radians
Returns
booleandecalSet

Spring.SetGroundDecalTexture (function)

[source]
Spring.SetGroundDecalTexture(integer, string, boolean?) -> boolean?
Parameters
integerdecalID
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.SetGroundDecalAlpha (function)

[source]
Spring.SetGroundDecalAlpha(integer, number?, number?) -> boolean
Parameters
integerdecalID
number?alpha
(Default: currAlpha) Between 0 and 1
number?alphaFalloff
(Default: currAlphaFalloff) Between 0 and 1, per second
Returns
booleandecalSet

Spring.SetGroundDecalNormal (function)

[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(integer, number?, number?, number?) -> boolean
Parameters
integerdecalID
number?normalX
(Default: 0)
number?normalY
(Default: 0)
number?normalZ
(Default: 0)
Returns
booleandecalSet

Spring.SetGroundDecalTint (function)

[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(integer, number?, number?, number?, number?) -> boolean
Parameters
integerdecalID
number?tintColR
(Default: curTintColR)
number?tintColG
(Default: curTintColG)
number?tintColB
(Default: curTintColB)
number?tintColA
(Default: curTintColA)
Returns
booleandecalSet

Spring.SetGroundDecalMisc (function)

[source]

Sets varios secondary parameters of a decal

Spring.SetGroundDecalMisc(integer, number?, number?, number?, number?, number?) -> boolean
Parameters
integerdecalID
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)

[source]

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

Spring.SetGroundDecalCreationFrame(integer, number?, number?) -> boolean
Parameters
integerdecalID
number?creationFrameMin
(Default: currCreationFrameMin)
number?creationFrameMax
(Default: currCreationFrameMax)
Returns
booleandecalSet

Spring.SetGroundDecalGlowParams (function)

[source]

Set decal glow parameters

Spring.SetGroundDecalGlowParams(integer, number?, number?) -> boolean
Parameters
integerdecalID
number?glow
Between 0 and 1 (Default: currGlow)
number?glowFalloff
Between 0 and 1, per second (Default: currGlowFallOff)
Returns
booleandecalSet

Spring.SetGroundDecalUserData (function)

[source]

Set decal user data. Useful in conjunction with custom decal shaders

Spring.SetGroundDecalUserData(integer, integer, number?, number?, number?, number?) -> boolean
Parameters
integerdecalID
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)

[source]
Spring.SDLSetTextInputRect(number, number, number, number) -> nil
Parameters
numberx
numbery
numberwidth
numberheight
Returns
nil

Spring.SDLStartTextInput (function)

[source]
Spring.SDLStartTextInput() -> nil
Returns
nil

Spring.SDLStopTextInput (function)

[source]
Spring.SDLStopTextInput() -> nil
Returns
nil

Spring.SetWindowGeometry (function)

[source]
Spring.SetWindowGeometry(number, number, number, number, number, boolean, boolean) -> nil
Parameters
numberdisplayIndex
numberwinRelPosX
numberwinRelPosY
numberwinSizeX
numberwinSizeY
booleanfullScreen
booleanborderless
Returns
nil

Spring.SetWindowMinimized (function)

[source]
Spring.SetWindowMinimized() -> boolean
Returns
booleanminimized

Spring.SetWindowMaximized (function)

[source]
Spring.SetWindowMaximized() -> boolean
Returns
booleanmaximized

Spring.Reload (function)

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

Spring.Restart (function)

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

Launches a new Spring instance without terminating the existing one.

[source]

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)

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

[source]

Note: has to be 24bit or 32bit. Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) Note: *.bmp images have to be in BGR format (default for m$ ones). Note: *.ico images are not supported.

Spring.SetWMIcon(string) -> nil
Parameters
stringiconFileName
Returns
nil

Spring.SetWMCaption (function)

Set the window title for the process

[source]

Spring.SetWMCaption(string, string?) -> nil
Parameters
stringtitle
(Default: “Spring <version>")
string?titleShort

(Default: “Spring <version>") displayed in the OS task-bar .

Note

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

Returns
nil

Spring.ClearWatchDogTimer (function)

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

Spring.SetClipboard (function)

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

Spring.Yield (function)

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

[source]

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

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

Spring.GetMetalMapSize (function)

[source]
Spring.GetMetalMapSize() -> integer, integer
Returns
integerx
X coordinate in worldspace / Game.metalMapSquareSize.
integerz
Z coordinate in worldspace / Game.metalMapSquareSize.

Spring.GetMetalAmount (function)

Returns the amount of metal on a single square.

[source]

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)

Sets the amount of metal on a single square.

[source]

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)

[source]
Spring.GetMetalExtraction(integer, integer) -> number
Parameters
integerx
X coordinate in worldspace / Game.metalMapSquareSize.
integerz
Z coordinate in worldspace / Game.metalMapSquareSize.
Returns
numberextraction

Spring.SetAlly (function)

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

[source]

Spring.SetAlly(integer, integer, boolean) -> nil
Parameters
integerfirstAllyTeamID
integersecondAllyTeamID
booleanally
Returns
nil

Spring.SetAllyTeamStartBox (function)

Changes the start box position of an allyTeam.

[source]

Spring.SetAllyTeamStartBox(integer, number, number, number, number) -> nil
Parameters
integerallyTeamID
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)

Assigns a player to a team.

[source]

Spring.AssignPlayerToTeam(integer, integer) -> nil
Parameters
integerplayerID
integerteamID
Returns
nil

Spring.SetTeamStartPosition (function)

Set the starting position of a team.

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

[source]

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

Spring.SetPlayerReadyState (function)

Set the ready state of a player.

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

[source]

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

Spring.SetGlobalLos (function)

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

[source]

Spring.SetGlobalLos(integer, boolean) -> nil
Parameters
integerallyTeamID
booleangloballos
Returns
nil

Spring.SetCheatingEnabled (function)

Changes whether activating cheats is allowed. Note that already activated cheats (e.g. god mode) stay active even if you disallow activating.

[source]

Spring.SetCheatingEnabled(boolean) -> nil
Parameters
booleancheatsEnabled
Returns
nil

Spring.SetGodMode (function)

Toggles ‘god mode’, i.e. whether control of teams other than one’s own is allowed. Affects all teams.

[source]

Spring.SetGodMode(boolean?, boolean?) -> nil
Parameters
boolean?controlAllies
boolean?controlEnemies
Returns
nil

Spring.KillTeam (function)

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

[source]

Gaia team cannot be killed.

Spring.KillTeam(integer) -> nil
Parameters
integerteamID
Returns
nil

Spring.GameOver (function)

Declare game over.

[source]

Spring.GameOver(integer[]) -> integer
Parameters
integer[]winningAllyTeamIDs

A list of winning ally team IDs.

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

Returns
integerNumber
of accepted (valid) ally teams.

Spring.SetTidal (function)

Set tidal strength

[source]

Spring.SetTidal(number) -> nil
Parameters
numberstrength
Returns
nil

Spring.SetWind (function)

Set wind strength

[source]

Spring.SetWind(number, number) -> nil
Parameters
numberminStrength
numbermaxStrength
Returns
nil

Spring.AddTeamResource (function)

Adds metal or energy resources to the specified team. Counts as production in post-game graph statistics.

[source]

Spring.AddTeamResource(integer, ResourceName, number) -> nil
Parameters
integerteamID
ResourceNametype
numberamount
Returns
nil

Spring.UseTeamResource (function)

Consumes metal or energy resources of the specified team. Counts as usage in post-game graph statistics.

[source]

Spring.UseTeamResource(integer, ResourceName, number) -> boolean
Parameters
integerteamID
ResourceNametype
Resource type.
numberamount
Amount of resource to use.
Returns
booleanhadEnough

Spring.UseTeamResource (function overload 1)

Consumes metal and/or energy resources of the specified team. Counts as usage in post-game graph statistics.

[source]

Spring.UseTeamResource(integer, ResourceUsage) -> boolean
Parameters
integerteamID
ResourceUsageamount
Returns
booleanhadEnough

Spring.SetTeamResource (function)

[source]
Spring.SetTeamResource(integer, (ResourceName|StorageName), number) -> nil
Parameters
integerteamID
(ResourceName|StorageName)resource
numberamount
Returns
nil

Spring.SetTeamShareLevel (function)

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

[source]

Spring.SetTeamShareLevel(integer, ResourceName, number) -> nil
Parameters
integerteamID
ResourceNametype
numberamount
Returns
nil

Spring.ShareTeamResource (function)

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.

[source]

Spring.ShareTeamResource(integer, integer, ResourceName, number) -> nil
Parameters
integerteamID_src
integerteamID_recv
ResourceNametype
numberamount
Returns
nil

Spring.SetGameRulesParam (function)

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

Spring.SetTeamRulesParam (function)

[source]
Spring.SetTeamRulesParam(integer, string, (number|string)?, losAccess?) -> nil
Parameters
integerteamID
stringparamName
(number|string)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetPlayerRulesParam (function)

[source]
Spring.SetPlayerRulesParam(integer, string, (number|string)?, losAccess?) -> nil
Parameters
integerplayerID
stringparamName
(number|string)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetUnitRulesParam (function)

[source]
Spring.SetUnitRulesParam(integer, string, (number|string)?, losAccess?) -> nil
Parameters
integerunitID
stringparamName
(number|string)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.SetFeatureRulesParam (function)

[source]
Spring.SetFeatureRulesParam(integer, string, (number|string)?, losAccess?) -> nil
Parameters
integerfeatureID
stringparamName
(number|string)?paramValue
numeric paramValues in quotes will be converted to number.
losAccess?losAccess
Returns
nil

Spring.CallCOBScript (function)

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

Spring.GetCOBScriptID (function)

[source]
Spring.GetCOBScriptID(integer, string) -> integer?
Parameters
integerunitID
stringfuncName
Returns
integer?funcID

Spring.CreateUnit (function)

[source]

See Spring.DestroyUnit

Spring.CreateUnit((string|integer), number, number, number, Facing, integer, boolean?, boolean?, integer?, integer?) -> integer?
Parameters
(string|integer)unitDef
UnitDef name or ID.
numberposX
numberposY
numberposZ
Facingfacing
integerteamID
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.
integer?unitID
Request a specific unitID.
integer?builderID
Returns
integer?unitID
The ID of the created unit, or nil if the unit could not be created.

Spring.DestroyUnit (function)

[source]

See Spring.CreateUnit

Spring.DestroyUnit(integer, boolean?, boolean?, integer?, boolean?) -> nil
Parameters
integerunitID
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!
integer?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)

[source]
Spring.TransferUnit(integer, integer, boolean?, boolean?) -> boolean
Parameters
integerunitID
integernewTeamID
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)

Transfer capacity of units from one team to another

[source]

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(number, number, number) -> boolean
Parameters
numberfromTeamID
numbernewTeamID
numbertransferAmnt
Returns
booleansuccessfulTransfer
Whether the max unit limit was successfully transferred.

Spring.SetUnitCosts (function)

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

Spring.SetUnitResourcing (function)

[source]
Spring.SetUnitResourcing(integer, string, number) -> nil
Parameters
integerunitID
stringres
numberamount
Returns
nil

Spring.SetUnitResourcing (function overload 1)

[source]
Spring.SetUnitResourcing(integer, table<string,number>) -> nil
Parameters
integerunitID
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)

[source]
Spring.SetUnitStorage(integer, string, number) -> nil
Parameters
integerunitID
stringres
numberamount

Spring.SetUnitStorage (function overload 1)

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

Spring.SetUnitTooltip (function)

[source]
Spring.SetUnitTooltip(integer, string) -> nil
Parameters
integerunitID
stringtooltip
Returns
nil

Spring.SetUnitHealth (function)

[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(integer, (number|SetUnitHealthAmounts)) -> nil
Parameters
integerunitID
(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)

[source]
Spring.SetUnitMaxHealth(integer, number) -> nil
Parameters
integerunitID
numbermaxHealth
Returns
nil

Spring.SetUnitStockpile (function)

[source]
Spring.SetUnitStockpile(integer, number?, number?) -> nil
Parameters
integerunitID
number?stockpile
number?buildPercent
Returns
nil

Spring.SetUnitUseWeapons (function)

[source]
Spring.SetUnitUseWeapons(integer, number?, number?) -> nil
Parameters
integerunitID
number?forceUseWeapons
number?allowUseWeapons
Returns
nil

Spring.SetUnitWeaponState (function)

[source]
Spring.SetUnitWeaponState(integer, number, WeaponState) -> nil
Parameters
integerunitID
numberweaponNum
WeaponStatestates
Returns
nil

Spring.SetUnitWeaponState (function overload 1)

[source]
Spring.SetUnitWeaponState(integer, number, string, number) -> nil
Parameters
integerunitID
numberweaponNum
stringkey
numbervalue
Returns
nil

Spring.SetUnitWeaponDamages (function)

[source]
Spring.SetUnitWeaponDamages(integer, (number|"selfDestruct"|"explode"), WeaponDamages) -> nil
Parameters
integerunitID
(number|"selfDestruct"|"explode")weaponNum
WeaponDamagesdamages
Returns
nil

Spring.SetUnitWeaponDamages (function overload 1)

[source]
Spring.SetUnitWeaponDamages(integer, (number|"selfDestruct"|"explode"), string, number) -> nil
Parameters
integerunitID
(number|"selfDestruct"|"explode")weaponNum
stringkey
numbervalue
Returns
nil

Spring.SetUnitMaxRange (function)

[source]
Spring.SetUnitMaxRange(integer, number) -> nil
Parameters
integerunitID
numbermaxRange
Returns
nil

Spring.SetUnitExperience (function)

[source]

See Spring.GetUnitExperience

Spring.SetUnitExperience(integer, number) -> nil
Parameters
integerunitID
numberexperience
Returns
nil

Spring.AddUnitExperience (function)

[source]

See Spring.GetUnitExperience

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

Spring.SetUnitArmored (function)

[source]
Spring.SetUnitArmored(integer, boolean?, number?) -> nil
Parameters
integerunitID
boolean?armored
number?armorMultiple
Returns
nil

Spring.SetUnitLosMask (function)

Set visibility status mask for a unit and team

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

[source]

See Spring.SetUnitLosState

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

Spring.SetUnitLosState (function)

Set current visibility status for a unit and team

Note this state will not be persisted if the visibility state is not masked.

Use it to change visibility state, once you set the unit to not receive engine visibility updates.

A few notes on certain bits:

  • contradar: True when the unit entered los at some point, remains set until radar is lost. Useful for tracking the unit type in radar, if you lost los you still know what unit type that radar dot refers to.
  • prevlos: True when the unit has entered los at least once, useful for tracking building locations (controls whether a ghost appears or not in the location)

[source]

See Spring.SetUnitLosMask

Spring.SetUnitLosState(integer, number, (LosTable|LosMask|integer)) -> nil
Parameters
integerunitID
numberallyTeam
(LosTable|LosMask|integer)losTypes
A bitmask of LosMask bits or a table

Spring.SetUnitCloak (function)

[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(integer, (boolean|number), (boolean|number)) -> nil
Parameters
integerunitID
(boolean|number)cloak
(boolean|number)cloakArg
Returns
nil

Spring.SetUnitStealth (function)

[source]
Spring.SetUnitStealth(integer, boolean) -> nil
Parameters
integerunitID
booleanstealth
Returns
nil

Spring.SetUnitSonarStealth (function)

[source]
Spring.SetUnitSonarStealth(integer, boolean) -> nil
Parameters
integerunitID
booleansonarStealth
Returns
nil

Spring.SetUnitSeismicSignature (function)

[source]
Spring.SetUnitSeismicSignature(integer, number) -> nil
Parameters
integerunitID
numberseismicSignature
Returns
nil

Spring.SetUnitLeavesGhost (function)

Set whether unit leaves static radar ghosts.

[source]

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)

[source]
Spring.SetUnitAlwaysVisible(integer, boolean) -> nil
Parameters
integerunitID
booleanalwaysVisible
Returns
nil

Spring.SetUnitUseAirLos (function)

[source]
Spring.SetUnitUseAirLos(integer, boolean) -> nil
Parameters
integerunitID
booleanuseAirLos
Returns
nil

Spring.SetUnitMetalExtraction (function)

[source]
Spring.SetUnitMetalExtraction(integer, number, number?) -> nil
Parameters
integerunitID
numberdepth
corresponds to metal extraction rate
number?range
similar to “extractsMetal” in unitDefs.
Returns
nil

Spring.SetUnitHarvestStorage (function)

See also harvestStorage UnitDef tag.

[source]

Spring.SetUnitHarvestStorage(integer, number) -> nil
Parameters
integerunitID
numbermetal
Returns
nil

Spring.SetUnitBuildParams (function)

[source]
Spring.SetUnitBuildParams(integer, string, (number|boolean)) -> nil
Parameters
integerunitID
stringparamName
one of buildRange|buildDistance|buildRange3D
(number|boolean)value
boolean when paramName is buildRange3D, otherwise number.
Returns
nil

Spring.SetUnitBuildSpeed (function)

[source]
Spring.SetUnitBuildSpeed(integer, number, number?, number?, number?, number?) -> nil
Parameters
integerbuilderID
numberbuildSpeed
number?repairSpeed
number?reclaimSpeed
number?captureSpeed
number?terraformSpeed
Returns
nil

Spring.SetUnitNanoPieces (function)

[source]

This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!

Spring.SetUnitNanoPieces(integer, table) -> nil
Parameters
integerbuilderID
tablepieces
Returns
nil

Spring.SetUnitBlocking (function)

[source]
Spring.SetUnitBlocking(integer, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?) -> boolean
Parameters
integerunitID
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)

[source]
Spring.SetUnitCrashing(integer, boolean) -> boolean
Parameters
integerunitID
booleancrashing
Returns
booleansuccess

Spring.SetUnitShieldState (function)

[source]
Spring.SetUnitShieldState(integer, integer?, boolean?, number?) -> nil
Parameters
integerunitID
integer?weaponID
(Default: -1)
boolean?enabled
number?power
Returns
nil

Spring.SetUnitShieldRechargeDelay (function)

[source]
Spring.SetUnitShieldRechargeDelay(integer, integer?, number?) -> nil
Parameters
integerunitID
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)

[source]
Spring.SetUnitFlanking(integer, string, number, number?, number?) -> nil
Parameters
integerunitID
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)

[source]
Spring.SetUnitPhysicalStateBit(integer, ) -> nil
Parameters
integerunitID
Physical
Returns
nil

Spring.GetUnitPhysicalState (function)

[source]
Spring.GetUnitPhysicalState(integer) -> number
Parameters
integerunitID
Returns
numberUnit
’s PhysicalState bitmask

Spring.SetUnitNeutral (function)

[source]
Spring.SetUnitNeutral(integer, boolean) -> boolean?
Parameters
integerunitID
booleanneutral
Returns
boolean?setNeutral

Spring.SetUnitTarget (function)

Defines a unit’s target.

[source]

Spring.SetUnitTarget(integer, integer?, boolean?, boolean?, number?) -> boolean
Parameters
integerunitID
integer?enemyUnitID
when nil drops the units current target.
boolean?dgun
(Default: false)
boolean?userTarget
(Default: false)
number?weaponNum
(Default: -1)
Returns
booleansuccess

Spring.SetUnitTarget (function overload 1)

[source]
Spring.SetUnitTarget(integer, number?, number?, number?, boolean?, boolean?, number?) -> boolean
Parameters
integerunitID
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)
number?weaponNum
(Default: -1)
Returns
booleansuccess

Spring.SetUnitMidAndAimPos (function)

[source]
Spring.SetUnitMidAndAimPos(integer, number, number, number, number, number, number, boolean?) -> boolean
Parameters
integerunitID
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)

[source]
Spring.SetUnitRadiusAndHeight(integer, number, number) -> boolean
Parameters
integerunitID
numberradius
numberheight
Returns
booleansuccess

Spring.SetUnitBuildeeRadius (function)

[source]

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

Spring.SetUnitBuildeeRadius(integer, number) -> nil
Parameters
integerunitID
numberbuild
radius for when targeted by build, repair, reclaim-type commands.
Returns
nil

Spring.SetUnitPieceParent (function)

Changes the pieces hierarchy of a unit by attaching a piece to a new parent.

[source]

Spring.SetUnitPieceParent(integer, number, number) -> nil
Parameters
integerunitID
numberAlteredPiece
numberParentPiece
Returns
nil

Spring.SetUnitPieceMatrix (function)

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

[source]

If any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed.

Spring.SetUnitPieceMatrix(integer, number, number[]) -> boolean?
Parameters
integerunitID
numberpieceNum
number[]matrix
an array of 16 floats
Returns
boolean?valid

Spring.SetUnitCollisionVolumeData (function)

[source]
Spring.SetUnitCollisionVolumeData(integer, number, number, number, number, number, number, number, number, number) -> nil
Parameters
integerunitID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numbervType
numbertType
numberAxis
Returns
nilenum
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.SetUnitPieceCollisionVolumeData (function)

[source]
Spring.SetUnitPieceCollisionVolumeData(integer, number, boolean, number, number, number, number, number, number, number?, number?) -> nil
Parameters
integerunitID
numberpieceIndex
booleanenable
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
number?volumeType
number?primaryAxis
Returns
nil

Spring.SetUnitPieceVisible (function)

[source]
Spring.SetUnitPieceVisible(integer, number, boolean) -> nil
Parameters
integerunitID
numberpieceIndex
booleanvisible
Returns
nil

Spring.SetUnitSensorRadius (function)

[source]
Spring.SetUnitSensorRadius(integer, ("los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"...), number) -> number?
Parameters
integerunitID
("los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"...)type
numberradius
Returns
number?New
radius, or nil if unit is invalid.

Spring.SetUnitPosErrorParams (function)

Sets a unit’s radar wobble

Controls how much a unit’s radar dot will wobble. Note that setting this above the allyTeam’s default wobble may result in the edgemost dot positions failing to register in ray traces, i.e. things like native “is under cursor” checks and some Lua interfaces.

[source]

Spring.SetUnitPosErrorParams(integer, number, number, number, number, number, number, number?) -> nil
Parameters
integerunitID
numberposErrorVectorX
numberposErrorVectorY
numberposErrorVectorZ
numberposErrorDeltaX
numberposErrorDeltaY
numberposErrorDeltaZ
number?nextPosErrorUpdate
Returns
nil

Spring.SetUnitMoveGoal (function)

Used by default commands to get in build-, attackrange etc.

[source]

Spring.SetUnitMoveGoal(integer, number, number, number, number?, number?, boolean?) -> nil
Parameters
integerunitID
numbergoalX
numbergoalY
numbergoalZ
number?goalRadius
number?moveSpeed
boolean?moveRaw
Returns
nil

Spring.SetUnitLandGoal (function)

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

[source]

Spring.SetUnitLandGoal(integer, number, number, number, number?) -> nil
Parameters
integerunitID
numbergoalX
numbergoalY
numbergoalZ
number?goalRadius
Returns
nil

Spring.ClearUnitGoal (function)

[source]
Spring.ClearUnitGoal(integer) -> nil
Parameters
integerunitID
Returns
nil

Spring.SetUnitPhysics (function)

[source]
Spring.SetUnitPhysics(integer, number, number, number, number, number, number, number, number, number, number, number, number) -> nil
Parameters
integerunitID
numberposX
numberposY
numberposZ
numbervelX
numbervelY
numbervelZ
numberrotX
numberrotY
numberrotZ
numberdragX
numberdragY
numberdragZ
Returns
nil

Spring.SetUnitMass (function)

[source]
Spring.SetUnitMass(integer, number) -> nil
Parameters
integerunitID
numbermass
Returns
nil

Spring.SetUnitPosition (function)

Set unit position (2D)

[source]

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

Spring.SetUnitPosition(integer, number, number, boolean?) -> nil
Parameters
integerunitID
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)

Set unit position (3D)

[source]

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

Spring.SetUnitPosition(integer, number, number, number) -> nil
Parameters
integerunitID
numberx
numbery
numberz
Returns
nil

Spring.SetUnitRotation (function)

[source]

Note: PYR order

Spring.SetUnitRotation(integer, number, number, number) -> nil
Parameters
integerunitID
numberpitch
Rotation in X axis
numberyaw
Rotation in Y axis
numberroll
Rotation in Z axis
Returns
nil

Spring.SetUnitDirection (function)

[source]

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

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

Spring.SetUnitDirection(integer, number, number, number) -> nil
Parameters
integerunitID
numberfrontx
numberfronty
numberfrontz
Returns
nil

Spring.SetUnitDirection (function overload 1)

[source]

Set unit front and right direction vectors.

Both vectors will be normalized in the engine.

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

Spring.SetUnitHeadingAndUpDir (function)

[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(integer, Heading, number, number, number) -> nil
Parameters
integerunitID
Headingheading
numberupx
numberupy
numberupz
Returns
nil

Spring.SetUnitVelocity (function)

Set the velocity of a Unit

[source]

See Spring.SetUnitMoveCtrl for disabling/enabling this control

Spring.SetUnitVelocity(integer, number, number, number) -> nil
Parameters
integerunitID
numbervelX
in elmos/frame
numbervelY
in elmos/frame
numbervelZ
in elmos/frame

Spring.SetFactoryBuggerOff (function)

[source]
Spring.SetFactoryBuggerOff(integer, boolean?, number?, number?, Heading?, boolean?, boolean?) -> number?
Parameters
integerunitID
boolean?buggerOff
number?offset
number?radius
Heading?relHeading
boolean?spherical
boolean?forced
Returns
number?buggerOff

Spring.BuggerOff (function)

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

Spring.AddFeatureDamage (function)

Apply damage to feature

[source]

Will trigger FeaturePreDamaged and FeatureDamaged callins.

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

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

See SyncedCallins:FeatureDamaged

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

Spring.AddUnitDamage (function)

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

Spring.AddUnitImpulse (function)

[source]
Spring.AddUnitImpulse(integer, number, number, number, number?) -> nil
Parameters
integerunitID
numberx
numbery
numberz
number?decayRate
Returns
nil

Spring.AddUnitSeismicPing (function)

[source]
Spring.AddUnitSeismicPing(integer, number) -> nil
Parameters
integerunitID
numberpindSize
Returns
nil

Spring.AddUnitResource (function)

[source]
Spring.AddUnitResource(integer, string, number) -> nil
Parameters
integerunitID
stringresource
“m” | “e”
numberamount
Returns
nil

Spring.UseUnitResource (function)

[source]
Spring.UseUnitResource(integer, ResourceName, number) -> boolean?
Parameters
integerunitID
ResourceNameresource
numberamount
Returns
boolean?okay

Spring.UseUnitResource (function overload 1)

[source]
Spring.UseUnitResource(integer, ResourceUsage) -> boolean?
Parameters
integerunitID
ResourceUsageresources
Returns
boolean?okay

Spring.AddObjectDecal (function)

[source]
Spring.AddObjectDecal(integer) -> nil
Parameters
integerunitID
Returns
nil

Spring.RemoveObjectDecal (function)

[source]
Spring.RemoveObjectDecal(integer) -> nil
Parameters
integerunitID
Returns
nil

Spring.AddGrass (function)

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

Spring.RemoveGrass (function)

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

Spring.CreateFeature (function)

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

Spring.DestroyFeature (function)

[source]
Spring.DestroyFeature(integer) -> nil
Parameters
integerfeatureID
Returns
nil

Spring.TransferFeature (function)

Feature Control

[source]

Spring.TransferFeature(integer, integer) -> nil
Parameters
integerfeatureID
integerteamID
Returns
nil

Spring.SetFeatureAlwaysVisible (function)

[source]
Spring.SetFeatureAlwaysVisible(integer, boolean) -> nil
Parameters
integerfeatureID
booleanenable
Returns
nil

Spring.SetFeatureUseAirLos (function)

[source]
Spring.SetFeatureUseAirLos(integer, boolean) -> nil
Parameters
integerfeatureID
booleanuseAirLos
Returns
nil

Spring.SetFeatureHealth (function)

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

Spring.SetFeatureMaxHealth (function)

[source]
Spring.SetFeatureMaxHealth(integer, number) -> nil
Parameters
integerfeatureID
numbermaxHealth
minimum 0.1
Returns
nil

Spring.SetFeatureReclaim (function)

[source]
Spring.SetFeatureReclaim(integer, number) -> nil
Parameters
integerfeatureID
numberreclaimLeft
Returns
nil

Spring.SetFeatureResources (function)

[source]
Spring.SetFeatureResources(integer, number, number, number?, number?, number?, number?) -> nil
Parameters
integerfeatureID
numbermetal
numberenergy
number?reclaimTime
number?reclaimLeft
number?featureDefMetal
number?featureDefEnergy
Returns
nil

Spring.SetFeatureResurrect (function)

[source]
Spring.SetFeatureResurrect(integer, (string|integer), Facing?, number?) -> nil
Parameters
integerfeatureID
(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)

Enable feature movement control.

[source]

Spring.SetFeatureMoveCtrl(integer, true, number?, number?, number?, number?, number?, number?) -> nil
Parameters
integerfeatureID
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)

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)

[source]

Spring.SetFeatureMoveCtrl(integer, false, number?, number?, number?, number?, number?, number?, number?, number?, number?) -> nil
Parameters
integerfeatureID
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)

[source]
Spring.SetFeaturePhysics(integer, number, number, number, number, number, number, number, number, number, number, number, number) -> nil
Parameters
integerfeatureID
numberposX
numberposY
numberposZ
numbervelX
numbervelY
numbervelZ
numberrotX
numberrotY
numberrotZ
numberdragX
numberdragY
numberdragZ
Returns
nil

Spring.SetFeatureMass (function)

[source]
Spring.SetFeatureMass(integer, number) -> nil
Parameters
integerfeatureID
numbermass
Returns
nil

Spring.SetFeaturePosition (function)

[source]
Spring.SetFeaturePosition(integer, number, number, number, boolean?) -> nil
Parameters
integerfeatureID
numberx
numbery
numberz
boolean?snapToGround
Returns
nil

Spring.SetFeatureRotation (function)

[source]

Note: PYR order

Spring.SetFeatureRotation(integer, number, number, number) -> nil
Parameters
integerfeatureID
numberpitch
Rotation in X axis
numberyaw
Rotation in Y axis
numberroll
Rotation in Z axis
Returns
nil

Spring.SetFeatureDirection (function)

[source]

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

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

Spring.SetFeatureDirection(integer, number, number, number) -> nil
Parameters
integerfeatureID
numberfrontx
numberfronty
numberfrontz
Returns
nil

Spring.SetFeatureDirection (function overload 1)

[source]

Set feature front and right direction vectors.

Both vectors will be normalized in the engine.

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

Spring.SetFeatureHeadingAndUpDir (function)

[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(integer, Heading, number, number, number) -> nil
Parameters
integerfeatureID
Headingheading
numberupx
numberupy
numberupz
Returns
nil

Spring.SetFeatureVelocity (function)

Set the velocity of a Feature

[source]

See Spring.SetFeatureMoveCtrl for disabling/enabling this control

Spring.SetFeatureVelocity(integer, number, number, number) -> nil
Parameters
integerfeatureID
numbervelX
in elmos/frame
numbervelY
in elmos/frame
numbervelZ
in elmos/frame

Spring.SetFeatureBlocking (function)

[source]
Spring.SetFeatureBlocking(integer, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?) -> boolean
Parameters
integerfeatureID
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)

[source]
Spring.SetFeatureNoSelect(integer, boolean) -> nil
Parameters
integerfeatureID
booleannoSelect
Returns
nil

Spring.SetFeatureMidAndAimPos (function)

[source]

Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.

Spring.SetFeatureMidAndAimPos(integer, number, number, number, number, number, number, boolean?) -> boolean
Parameters
integerfeatureID
numbermpX
numbermpY
numbermpZ
numberapX
numberapY
numberapZ
boolean?relative
Returns
booleansuccess

Spring.SetFeatureRadiusAndHeight (function)

[source]
Spring.SetFeatureRadiusAndHeight(integer, number, number) -> boolean
Parameters
integerfeatureID
numberradius
numberheight
Returns
booleansuccess

Spring.SetFeatureCollisionVolumeData (function)

[source]

Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.

Spring.SetFeatureCollisionVolumeData(integer, number, number, number, number, number, number, number, number, number) -> nil
Parameters
integerfeatureID
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numbervType
numbertType
numberAxis
Returns
nil

Spring.SetFeaturePieceCollisionVolumeData (function)

[source]
Spring.SetFeaturePieceCollisionVolumeData(integer, number, boolean, number, number, number, number, number, number, number, number, number?) -> nil
Parameters
integerfeatureID
numberpieceIndex
booleanenable
numberscaleX
numberscaleY
numberscaleZ
numberoffsetX
numberoffsetY
numberoffsetZ
numberAxis
numbervolumeType
number?primaryAxis
Returns
nil

Spring.SetFeaturePieceVisible (function)

[source]
Spring.SetFeaturePieceVisible(integer, number, boolean) -> nil
Parameters
integerfeatureID
numberpieceIndex
booleanvisible
Returns
nil

Spring.SetFeaturePieceMatrix (function)

Sets the local (i.e. parent-relative) matrix of the given piece, for a feature.

[source]

Spring.SetFeaturePieceMatrix(integer, number, number[]) -> boolean?
Parameters
integerfeatureID
numberpieceIndex
number[]matrix
an array of 16 floats
Returns
boolean?valid

Spring.SetFeatureFireTime (function)

Set the fire timer for a feature.

[source]

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

Spring.SetFeatureFireTime(integer, number) -> nil
Parameters
integerfeatureID
numberfireTime
in seconds

Spring.SetFeatureSmokeTime (function)

Set the smoke timer for a feature.

[source]

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

Setting to zero will stop smoke emission by the feature.

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

Spring.SetFeatureSmokeTime(integer, number) -> nil
Parameters
integerfeatureID
numbersmokeTime
in seconds

Spring.CreateUnitWreck (function)

Create a wreck from a unit

[source]

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

Spring.CreateFeatureWreck (function)

Create a wreck from a feature

[source]

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

Spring.SetProjectileAlwaysVisible (function)

[source]
Spring.SetProjectileAlwaysVisible(integer, boolean) -> nil
Parameters
integerprojectileID
booleanalwaysVisible
Returns
nil

Spring.SetProjectileUseAirLos (function)

[source]
Spring.SetProjectileUseAirLos(integer, boolean) -> nil
Parameters
integerprojectileID
booleanuseAirLos
Returns
nil

Spring.SetProjectileMoveControl (function)

Set whether engine should process position and speed for a projectile

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

Passing true merely skips engine updating velocity and position.

[source]

Spring.SetProjectileMoveControl(integer, boolean) -> nil
Parameters
integerprojectileID
booleanenable

Spring.SetProjectilePosition (function)

Set the position of a projectile

[source]

Spring.SetProjectilePosition(integer, number?, number?, number?) -> nil
Parameters
integerprojectileID
number?posX
(Default: 0)
number?posY
(Default: 0)
number?posZ
(Default: 0)

Spring.SetProjectileVelocity (function)

Set the velocity of a projectile

Note

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

[source]

See Spring.SetProjectileMoveControl

Spring.SetProjectileVelocity(integer, number, number, number) -> nil
Parameters
integerprojectileID
numbervelX
in elmos/frame
numbervelY
in elmos/frame
numbervelZ
in elmos/frame

Spring.SetProjectileCollision (function)

[source]
Spring.SetProjectileCollision(integer) -> nil
Parameters
integerprojectileID

Spring.SetProjectileTarget (function)

Set projectile target (object)

[source]

Spring.SetProjectileTarget(integer, number, ProjectileTargetType) -> boolean?
Parameters
integerprojectileID
numbertargetID
ProjectileTargetTypetargetType
Returns
boolean?validTarget

Spring.SetProjectileTarget (function overload 1)

Set projectile target (position)

[source]

Spring.SetProjectileTarget(integer, number, number, number) -> boolean?
Parameters
integerprojectileID
numberposX
numberposY
numberposZ
Returns
boolean?validTarget

Spring.SetProjectileTimeToLive (function)

Set Time To Live for a projectile

[source]

Spring.SetProjectileTimeToLive(integer, number) -> nil
Parameters
integerprojectileID
numberttl
Remaining time to live in frames

Spring.SetProjectileIsIntercepted (function)

[source]
Spring.SetProjectileIsIntercepted(integer) -> nil
Parameters
integerprojectileID

Spring.SetProjectileDamages (function)

[source]
Spring.SetProjectileDamages(integer, integer, string, number) -> nil
Parameters
integerunitID
integerweaponNum
stringkey
numbervalue

Spring.SetProjectileIgnoreTrackingError (function)

[source]
Spring.SetProjectileIgnoreTrackingError(integer, boolean) -> nil
Parameters
integerprojectileID
booleanignore

Spring.SetProjectileGravity (function)

[source]
Spring.SetProjectileGravity(integer, number?) -> nil
Parameters
integerprojectileID
number?grav
(Default: 0)
Returns
nil

Spring.SetPieceProjectileParams (function)

Set piece projectile params

Non passed or nil args don’t set params.

[source]

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

Spring.SetProjectileCEG (function)

[source]
Spring.SetProjectileCEG(integer, string) -> nil
Parameters
integerprojectileID
stringceg_name
Returns
nil

Spring.UnitFinishCommand (function)

[source]
Spring.UnitFinishCommand(integer) -> nil
Parameters
integerunitID

Spring.LevelHeightMap (function)

Set the height of a point in the world.

[source]

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

Spring.LevelHeightMap (function overload 1)

Set the height of a rectangle area in the world.

[source]

Spring.LevelHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.AdjustHeightMap (function)

Add height to a point in the world.

[source]

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

Spring.AdjustHeightMap (function overload 1)

Add height to a rectangle in the world.

[source]

Spring.AdjustHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.RevertHeightMap (function)

Restore map height at a point in the world.

[source]

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

Spring.RevertHeightMap (function overload 1)

Restore map height of a rectangle area in the world.

[source]

Spring.RevertHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.AddHeightMap (function)

Can only be called in Spring.SetHeightMapFunc

[source]

Spring.AddHeightMap(number, number, number) -> integer?
Parameters
numberx
numberz
numberheight
Returns
integer?newHeight

Spring.SetHeightMap (function)

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

[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, [number, ]*) -> integer?
Parameters
functionluaFunction
numberarg
number...
Returns
integer?absTotalHeightMapAmountChanged

Spring.LevelOriginalHeightMap (function)

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

[source]

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

Spring.LevelOriginalHeightMap (function overload 1)

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

[source]

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

Spring.AdjustOriginalHeightMap (function)

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

[source]

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

Spring.AdjustOriginalHeightMap (function overload 1)

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

[source]

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

Spring.RevertOriginalHeightMap (function)

Restore original map height at a point in the world.

[source]

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

Spring.RevertOriginalHeightMap (function overload 1)

Restore original map height over a rectangle in the world.

[source]

Spring.RevertOriginalHeightMap(number, number, number, number, number?) -> nil
Parameters
numberx1
numberz1
numberx2
numberz2
number?height
Returns
nil

Spring.AddOriginalHeightMap (function)

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

Spring.AddOriginalHeightMap(number, number, number) -> nil
Parameters
numberx
numbery
numberheight
Returns
nil

Spring.SetOriginalHeightMap (function)

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

[source]

Cannot recurse on itself

Spring.SetOriginalHeightMapFunc(function) -> nil
Parameters
functionheightMapFunc
Returns
nil

Spring.RebuildSmoothMesh (function)

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

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

Spring.LevelSmoothMesh (function overload 1)

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

Spring.AdjustSmoothMesh (function)

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

Spring.AdjustSmoothMesh (function overload 1)

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

Spring.RevertSmoothMesh (function)

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

Spring.RevertSmoothMesh (function overload 1)

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

Spring.AddSmoothMesh (function)

Can only be called in Spring.SetSmoothMeshFunc.

[source]

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)

Can only be called in Spring.SetSmoothMeshFunc.

[source]

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

Spring.SetSmoothMeshFunc (function)

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

Spring.SetMapSquareTerrainType (function)

[source]
Spring.SetMapSquareTerrainType(number, number, number) -> integer?
Parameters
numberx
numberz
numbernewType
Returns
integer?oldType

Spring.SetTerrainTypeData (function)

[source]
Spring.SetTerrainTypeData(number, number?, number?, number?, number?) -> boolean?
Parameters
numbertypeIndex
number?speedTanks
(Default: nil)
number?speedKBOts
(Default: nil)
number?speedHovers
(Default: nil)
number?speedShips
(Default: nil)
Returns
boolean?
true

Spring.SetSquareBuildingMask (function)

[source]
Spring.SetSquareBuildingMask(number, number, number) -> nil
Parameters
numberx
numberz
numbermask
Returns
nilSee
also buildingMask unitdef tag.

Spring.UnitWeaponFire (function)

[source]
Spring.UnitWeaponFire(integer, integer) -> nil
Parameters
integerunitID
integerweaponID
Returns
nil

Spring.UnitWeaponHoldFire (function)

[source]
Spring.UnitWeaponHoldFire(integer, integer) -> nil
Parameters
integerunitID
integerweaponID
Returns
nil

Spring.ForceUnitCollisionUpdate (function)

Prevent collision checks from working on outdated data

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

[source]

Spring.ForceUnitCollisionUpdate(integer) -> nil
Parameters
integerunitID
Returns
nil

Spring.UnitAttach (function)

[source]
Spring.UnitAttach(integer, integer, number) -> nil
Parameters
integertransporterID
integerpassengerID
numberpieceNum
Returns
nil

Spring.UnitDetach (function)

[source]
Spring.UnitDetach(integer) -> nil
Parameters
integerpassengerID
Returns
nil

Spring.UnitDetachFromAir (function)

[source]
Spring.UnitDetachFromAir(integer) -> nil
Parameters
integerpassengerID
Returns
nil

Spring.SetUnitLoadingTransport (function)

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

[source]

Spring.SetUnitLoadingTransport(integer, integer) -> nil
Parameters
integerpassengerID
integertransportID
Returns
nil

Spring.SpawnProjectile (function)

[source]
Spring.SpawnProjectile(integer, ProjectileParams) -> integer?
Parameters
integerweaponDefID
ProjectileParamsprojectileParams
Returns
integer?projectileID

Spring.DeleteProjectile (function)

Silently removes projectiles (no explosion).

[source]

Spring.DeleteProjectile(integer) -> nil
Parameters
integerprojectileID
Returns
nil

Spring.SpawnExplosion (function)

[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)
ExplosionParamsexplosionParams
Returns
nil

Spring.SpawnCEG (function)

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

Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

[source]

Spring.SpawnSFX(integer?, integer?, number?, number?, number?, number?, number?, number?, number?, number?, boolean?) -> boolean?
Parameters
integer?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)

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

Spring.SetExperienceGrade (function)

Defines how often Callins.UnitExperience will be called.

[source]

Spring.SetExperienceGrade(number, number?, number?, number?) -> nil
Parameters
numberexpGrade
number?ExpPowerScale
number?ExpHealthScale
number?ExpReloadScale
Returns
nil

Spring.SetRadarErrorParams (function)

[source]
Spring.SetRadarErrorParams(integer, number, number?, number?) -> nil
Parameters
integerallyTeamID
numberallyteamErrorSize
number?baseErrorSize
number?baseErrorMult
Returns
nil

Spring.EditUnitCmdDesc (function)

[source]
Spring.EditUnitCmdDesc(integer, integer, CommandDescription) -> nil
Parameters
integerunitID
integercmdDescID
CommandDescriptioncmdArray

Spring.InsertUnitCmdDesc (function)

Insert a command description at a specific index.

[source]

Spring.InsertUnitCmdDesc(integer, integer, CommandDescription) -> nil
Parameters
integerunitID
integerindex
CommandDescriptioncmdDesc

Spring.InsertUnitCmdDesc (function overload 1)

Insert a command description at the last position.

[source]

Spring.InsertUnitCmdDesc(integer, CommandDescription) -> nil
Parameters
integerunitID
CommandDescriptioncmdDesc

Spring.RemoveUnitCmdDesc (function)

[source]
Spring.RemoveUnitCmdDesc(integer, integer?) -> nil
Parameters
integerunitID
integer?cmdDescID

Spring.IsCheatingEnabled (function)

[source]
Spring.IsCheatingEnabled() -> boolean
Returns
booleanenabled

Spring.IsGodModeEnabled (function)

[source]
Spring.IsGodModeEnabled() -> boolean
Returns
booleanenabled

Spring.IsDevLuaEnabled (function)

[source]
Spring.IsDevLuaEnabled() -> boolean
Returns
booleanenabled

Spring.IsEditDefsEnabled (function)

[source]
Spring.IsEditDefsEnabled() -> boolean
Returns
booleanenabled

Spring.IsNoCostEnabled (function)

[source]
Spring.IsNoCostEnabled() -> boolean
Returns
booleanenabled

Spring.GetGlobalLos (function)

[source]
Spring.GetGlobalLos(integer?) -> boolean
Parameters
integer?teamID
Returns
booleanenabled

Spring.AreHelperAIsEnabled (function)

[source]
Spring.AreHelperAIsEnabled() -> boolean
Returns
booleanenabled

Spring.FixedAllies (function)

[source]
Spring.FixedAllies() -> boolean?
Returns
boolean?enabled

Spring.IsGameOver (function)

[source]
Spring.IsGameOver() -> boolean
Returns
booleanisGameOver

Spring.GetGameFrame (function)

[source]
Spring.GetGameFrame() -> number, number
Returns
numbert1
frameNum % dayFrames
numbert2
frameNum / dayFrames

Spring.GetGameSeconds (function)

[source]
Spring.GetGameSeconds() -> number
Returns
numberseconds

Spring.GetTidal (function)

[source]
Spring.GetTidal() -> number
Returns
numbertidalStrength

Spring.GetWind (function)

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

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

Spring.GetTeamRulesParams (function)

[source]
Spring.GetTeamRulesParams(integer) -> RulesParams
Parameters
integerteamID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetPlayerRulesParams (function)

[source]
Spring.GetPlayerRulesParams(integer) -> RulesParams
Parameters
integerplayerID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetUnitRulesParams (function)

[source]
Spring.GetUnitRulesParams(integer) -> RulesParams
Parameters
integerunitID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetFeatureRulesParams (function)

[source]
Spring.GetFeatureRulesParams(integer) -> RulesParams
Parameters
integerfeatureID
Returns
RulesParamsrulesParams
map with rules names as key and values as values

Spring.GetGameRulesParam (function)

[source]
Spring.GetGameRulesParam((number|string)) -> number?
Parameters
(number|string)ruleRef
the rule index or name
Returns
number?
|string value

Spring.GetTeamRulesParam (function)

[source]
Spring.GetTeamRulesParam(integer, (number|string)) -> (number|string)?
Parameters
integerteamID
(number|string)ruleRef
the rule index or name
Returns
(number|string)?value

Spring.GetPlayerRulesParam (function)

[source]
Spring.GetPlayerRulesParam(integer, (number|string)) -> (number|string)?
Parameters
integerplayerID
(number|string)ruleRef
the rule index or name
Returns
(number|string)?value

Spring.GetUnitRulesParam (function)

[source]
Spring.GetUnitRulesParam(integer, (number|string)) -> (number|string)?
Parameters
integerunitID
(number|string)ruleRef
the rule index or name
Returns
(number|string)?value

Spring.GetFeatureRulesParam (function)

[source]
Spring.GetFeatureRulesParam(integer, (number|string)) -> (number|string)?
Parameters
integerfeatureID
(number|string)ruleRef
the rule index or name
Returns
(number|string)?value

Spring.GetMapOption (function)

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

Spring.GetMapOptions (function)

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

Spring.GetModOption (function)

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

Spring.GetModOptions (function)

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

Spring.GetHeadingFromVector (function)

[source]
Spring.GetHeadingFromVector(number, number) -> number
Parameters
numberx
numberz
Returns
numberheading

Spring.GetVectorFromHeading (function)

[source]
Spring.GetVectorFromHeading(number) -> number, number
Parameters
numberheading
Returns
numberx
numberz

Spring.GetFacingFromHeading (function)

[source]
Spring.GetFacingFromHeading(number) -> FacingInteger
Parameters
numberheading
Returns
FacingIntegerfacing

Spring.GetHeadingFromFacing (function)

[source]
Spring.GetHeadingFromFacing(FacingInteger) -> number
Parameters
FacingIntegerfacing
Returns
numberheading

Spring.GetSideData (function)

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

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

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

Spring.GetGaiaTeamID (function)

[source]
Spring.GetGaiaTeamID() -> integer
Returns
integerteamID

Spring.GetAllyTeamStartBox (function)

[source]
Spring.GetAllyTeamStartBox(integer) -> number?, number?, number?, number?
Parameters
integerallyID
Returns
number?xMin
number?zMin
number?xMax
number?zMax

Spring.GetTeamStartPosition (function)

[source]
Spring.GetTeamStartPosition(integer) -> number?, number?, number?
Parameters
integerteamID
Returns
number?x
number?y
number?x

Spring.GetMapStartPositions (function)

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

Spring.GetAllyTeamList (function)

[source]
Spring.GetAllyTeamList() -> integer[]
Returns
integer[]allyTeamIDs

Spring.GetTeamList (function)

Get all team IDs.

[source]

Spring.GetTeamList(unknown) -> number[]
Parameters
unknownallyTeamID
(Default: -1)
Returns
number[]teamIDs
List of team IDs.

Spring.GetTeamList (function overload 1)

Get team IDs in a specific ally team.

[source]

Spring.GetTeamList(integer) -> number[]?
Parameters
integerallyTeamID
The ally team ID to filter teams by. A value less than 0 will return all teams.
Returns
number[]?teamIDs
List of team IDs or nil if allyTeamID is invalid.

Spring.GetPlayerList (function)

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

Spring.GetTeamInfo (function)

[source]
Spring.GetTeamInfo(integer, boolean?) -> integer?, number, number, number, string, number, number, table<string,string>
Parameters
integerteamID
boolean?getTeamKeys
(Default: true) whether to return the customTeamKeys table
Returns
integer?teamID
numberleader
numberisDead
numberhasAI
stringside
numberallyTeam
numberincomeMultiplier
table<string,string>customTeamKeys
when getTeamKeys is true, otherwise nil

Spring.GetTeamAllyTeamID (function)

[source]
Spring.GetTeamAllyTeamID(integer) -> integer?
Parameters
integerteamID
Returns
integer?allyTeamID

Spring.GetTeamResources (function)

[source]
Spring.GetTeamResources(integer, ResourceName) -> number?, number, number, number, number, number, number, number, number
Parameters
integerteamID
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)

[source]
Spring.GetTeamUnitStats(integer) -> number?, number, number, number, number, number
Parameters
integerteamID
Returns
number?killed
numberdied
numbercapturedBy
numbercapturedFrom
numberreceived
numbersent

Spring.GetTeamResourceStats (function)

[source]
Spring.GetTeamResourceStats(integer, ResourceName) -> number?, number, number, number, number
Parameters
integerteamID
ResourceNameresource
Returns
number?used
numberproduced
numberexcessed
numberreceived
numbersent

Spring.GetTeamDamageStats (function)

Gets team damage dealt/received totals

[source]

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

Spring.GetTeamDamageStats(integer) -> number, number
Parameters
integerteamID
Returns
numberdamageDealt
numberdamageReceived

Spring.GetTeamStatsHistory (function)

Get the number of history entries.

[source]

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

Spring.GetTeamStatsHistory (function overload 1)

Get team stats history.

[source]

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

Spring.GetTeamLuaAI (function)

[source]
Spring.GetTeamLuaAI(integer) -> string
Parameters
integerteamID
Returns
string

Spring.GetTeamMaxUnits (function)

Returns a team’s unit cap.

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

[source]

Spring.GetTeamMaxUnits(integer) -> number, number?
Parameters
integerteamID
Returns
numbermaxUnits
number?currentUnits

Spring.GetPlayerInfo (function)

[source]
Spring.GetPlayerInfo(integer, boolean?) -> string, boolean, boolean, integer, integer, number, number, string, number, boolean, { [string]: string }, boolean
Parameters
integerplayerID
boolean?getPlayerOpts
(Default: true) whether to return custom player options
Returns
stringname
booleanactive
booleanspectator
integerteamID
integerallyTeamID
numberpingTime
numbercpuUsage
stringcountry
numberrank
booleanhasSkirmishAIsInTeam
{ [string]: string }playerOpts
when playerOpts is true
booleandesynced

Spring.GetPlayerControlledUnit (function)

Returns unit controlled by player on FPS mode

[source]

Spring.GetPlayerControlledUnit(integer) -> number?
Parameters
integerplayerID
Returns
number?

Spring.GetAIInfo (function)

[source]
Spring.GetAIInfo(integer) -> integer, string, integer, string, string, table<string,string>
Parameters
integerteamID
Returns
integerskirmishAIID
stringname
integerhostingPlayerID
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)

[source]
Spring.GetAllyTeamInfo(integer) -> table<string,string>?
Parameters
integerallyTeamID
Returns
table<string,string>?

Spring.AreTeamsAllied (function)

[source]
Spring.AreTeamsAllied(number, number) -> boolean?
Parameters
numberteamID1
numberteamID2
Returns
boolean?

Spring.ArePlayersAllied (function)

[source]
Spring.ArePlayersAllied(number, number) -> boolean?
Parameters
numberplayerID1
numberplayerID2
Returns
boolean?

Spring.GetAllUnits (function)

Get a list of all unitIDs

[source]

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

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

See UnsyncedRead.GetVisibleUnits

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

Spring.GetTeamUnits (function)

[source]
Spring.GetTeamUnits(integer) -> number[]?
Parameters
integerteamID
Returns
number[]?unitIDs

Spring.GetTeamUnitsSorted (function)

[source]
Spring.GetTeamUnitsSorted(integer) -> table<integer,integer>
Parameters
integerteamID
Returns
table<integer,integer>unitsByDef
A table where keys are unitDefIDs and values are unitIDs

Spring.GetTeamUnitsCounts (function)

[source]
Spring.GetTeamUnitsCounts(integer) -> table<number,number>?
Parameters
integerteamID
Returns
table<number,number>?countByUnit
A table where keys are unitDefIDs and values are counts.

Spring.GetTeamUnitsByDefs (function)

[source]
Spring.GetTeamUnitsByDefs(integer, (number|number[])) -> number[]?
Parameters
integerteamID
(number|number[])unitDefIDs
Returns
number[]?unitIDs

Spring.GetTeamUnitDefCount (function)

[source]
Spring.GetTeamUnitDefCount(integer, integer) -> number?
Parameters
integerteamID
integerunitDefID
Returns
number?count

Spring.GetTeamUnitCount (function)

[source]
Spring.GetTeamUnitCount(integer) -> number?
Parameters
integerteamID
Returns
number?count

Spring.GetUnitsInRectangle (function)

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

Spring.GetUnitsInBox (function)

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

Spring.GetUnitsInCylinder (function)

[source]
Spring.GetUnitsInCylinder(number, number, number) -> number[]
Parameters
numberx
numberz
numberradius
Returns
number[]unitIDs

Spring.GetUnitsInSphere (function)

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

Spring.GetUnitsInPlanes (function)

[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?) -> integer[]
Parameters
Plane[]planes
integer?allegiance
Returns
integer[]unitIDs

Spring.GetUnitArrayCentroid (function)

Returns the centroid of an array of units

Returns nil for an empty array

[source]

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

Spring.GetUnitMapCentroid (function)

Returns the centroid of a map of units

Returns nil for an empty map

[source]

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

Spring.GetUnitNearestAlly (function)

[source]
Spring.GetUnitNearestAlly(integer, number?) -> integer?
Parameters
integerunitID
number?range
(Default: 1.0e9)
Returns
integer?unitID

Spring.GetUnitNearestEnemy (function)

[source]
Spring.GetUnitNearestEnemy(integer, number?, boolean?) -> integer?
Parameters
integerunitID
number?range
(Default: 1.0e9)
boolean?useLOS
(Default: true)
Returns
integer?unitID

Spring.GetFeaturesInRectangle (function)

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

Spring.GetFeaturesInSphere (function)

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

Spring.GetFeaturesInCylinder (function)

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

Spring.GetAllProjectiles (function)

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

Spring.GetProjectilesInRectangle (function)

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

Spring.GetProjectilesInSphere (function)

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

Spring.ValidUnitID (function)

Get whether a unitID is valid

Dead units are not valid.

[source]

Spring.ValidUnitID(integer) -> boolean
Parameters
integerunitID
Returns
boolean

Spring.GetUnitStates (function)

[source]
Spring.GetUnitStates(integer) -> UnitState
Parameters
integerunitID
Returns
UnitState

Spring.GetUnitArmored (function)

[source]
Spring.GetUnitArmored(integer) -> boolean?, number
Parameters
integerunitID
Returns
boolean?armored
numberarmorMultiple

Spring.GetUnitIsActive (function)

[source]
Spring.GetUnitIsActive(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?isActive

Spring.GetUnitIsCloaked (function)

[source]
Spring.GetUnitIsCloaked(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?isCloaked

Spring.GetUnitSeismicSignature (function)

[source]
Spring.GetUnitSeismicSignature(integer) -> number?
Parameters
integerunitID
Returns
number?seismicSignature

Spring.GetUnitLeavesGhost (function)

Get whether unit leaves static radar ghosts.

[source]

Spring.GetUnitLeavesGhost() -> number?
Returns
number?

Spring.GetUnitSelfDTime (function)

[source]
Spring.GetUnitSelfDTime(integer) -> integer?
Parameters
integerunitID
Returns
integer?selfDTime

Spring.GetUnitStockpile (function)

[source]
Spring.GetUnitStockpile(integer) -> integer?, integer?, number?
Parameters
integerunitID
Returns
integer?numStockpiled
integer?numStockpileQued
number?buildPercent

Spring.GetUnitSensorRadius (function)

[source]
Spring.GetUnitSensorRadius(integer, string) -> number?
Parameters
integerunitID
stringtype
one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
Returns
number?radius

Spring.GetUnitPosErrorParams (function)

[source]
Spring.GetUnitPosErrorParams(integer, integer?) -> number?, number, number, number, number, number, number, boolean
Parameters
integerunitID
integer?allyTeamID
Returns
number?posErrorVectorX
numberposErrorVectorY
numberposErrorVectorZ
numberposErrorDeltaX
numberposErrorDeltaY
numberposErrorDeltaZ
numbernextPosErrorUpdatebaseErrorMult
booleanposErrorBit

Spring.GetUnitTooltip (function)

[source]
Spring.GetUnitTooltip(integer) -> string?
Parameters
integerunitID
Returns
string?

Spring.GetUnitDefID (function)

[source]
Spring.GetUnitDefID(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitTeam (function)

[source]
Spring.GetUnitTeam(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitAllyTeam (function)

[source]
Spring.GetUnitAllyTeam(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitNeutral (function)

Checks if a unit is neutral (NOT Gaia!)

[source]

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

Spring.GetUnitNeutral(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?

Spring.GetUnitHealth (function)

[source]
Spring.GetUnitHealth(integer) -> number?, number, number, number, number
Parameters
integerunitID
Returns
number?health
numbermaxHealth
numberparalyzeDamage
numbercaptureProgress
numberbuildProgress
between 0.0-1.0

Spring.GetUnitIsDead (function)

[source]
Spring.GetUnitIsDead(integer) -> boolean?
Parameters
integerunitID
Returns
boolean?

Spring.GetUnitIsStunned (function)

Checks whether a unit is disabled and can’t act

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

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

[source]

Spring.GetUnitIsStunned(integer) -> boolean?, boolean, boolean
Parameters
integerunitID
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)

[source]
Spring.GetUnitIsBeingBuilt(integer) -> boolean, number
Parameters
integerunitID
Returns
booleanbeingBuilt
numberbuildProgress

Spring.GetUnitResources (function)

[source]
Spring.GetUnitResources(integer) -> number?, number, number, number
Parameters
integerunitID
Returns
number?metalMake
numbermetalUse
numberenergyMake
numberenergyUse

Spring.GetUnitStorage (function)

[source]
Spring.GetUnitStorage(integer) -> number, number
Parameters
integerunitID
Returns
numberUnit
’s metal storage
numberUnit
’s energy storage

Spring.GetUnitCosts (function)

[source]
Spring.GetUnitCosts(integer) -> number?, number, number
Parameters
integerunitID
Returns
number?buildTime
numbermetalCost
numberenergyCost

Spring.GetUnitCostTable (function)

[source]
Spring.GetUnitCostTable(integer) -> ResourceCost?, number?
Parameters
integerunitID
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)

[source]
Spring.GetUnitMetalExtraction(integer) -> number?
Parameters
integerunitID
Returns
number?metalExtraction

Spring.GetUnitExperience (function)

[source]
Spring.GetUnitExperience(integer) -> number, number
Parameters
integerunitID
Returns
numberxp
[0.0; +∞)
numberlimXp
[0.0; 1.0) as experience approaches infinity

Spring.GetUnitHeight (function)

[source]
Spring.GetUnitHeight(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitRadius (function)

[source]
Spring.GetUnitRadius(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitBuildeeRadius (function)

[source]

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

Spring.GetUnitBuildeeRadius(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitMass (function)

[source]
Spring.GetUnitMass(integer) -> number?
Parameters
integerunitID
Returns
number?

Spring.GetUnitPosition (function)

[source]
Spring.GetUnitPosition(integer, boolean?, boolean?) -> number?, number, number, number?, number, number, number?, number, number
Parameters
integerunitID
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)

[source]

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

See Spring.GetUnitPosition

Spring.GetUnitBasePosition(integer) -> number?, number?, number?
Parameters
integerunitID
Returns
number?posX
number?posY
number?posZ

Spring.GetUnitVectors (function)

[source]
Spring.GetUnitVectors(integer) -> float3?, float3, float3
Parameters
integerunitID
Returns
float3?front
float3up
float3right

Spring.GetUnitRotation (function)

[source]

Note: PYR order

Spring.GetUnitRotation(integer) -> number, number, number
Parameters
integerunitID
Returns
numberpitch
Rotation in X axis
numberyaw
Rotation in Y axis
numberroll
Rotation in Z axis

Spring.GetUnitDirection (function)

[source]
Spring.GetUnitDirection(integer) -> number, number, number, number, number, number, number, number, number
Parameters
integerunitID
Returns
numberfrontDirX
numberfrontDirY
numberfrontDirZ
numberrightDirX
numberrightDirY
numberrightDirZ
numberupDirX
numberupDirY
numberupDirZ

Spring.GetUnitHeading (function)

[source]
Spring.GetUnitHeading(integer, boolean?) -> number
Parameters
integerunitID
boolean?convertToRadians
(Default: false)
Returns
numberheading

Spring.GetUnitVelocity (function)

[source]
Spring.GetUnitVelocity(integer) -> nil
Parameters
integerunitID

Spring.GetUnitBuildFacing (function)

[source]
Spring.GetUnitBuildFacing(integer) -> nil
Parameters
integerunitID

Spring.GetUnitIsBuilding (function)

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

[source]

Works for both mobile builders and factories.

Spring.GetUnitIsBuilding(integer) -> integer
Parameters
integerunitID
Returns
integerbuildeeUnitID
or nil

Spring.GetUnitWorkerTask (function)

Checks a builder’s current task

[source]

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

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

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

Spring.GetUnitEffectiveBuildRange (function)

[source]

Useful for setting move goals manually.

Spring.GetUnitEffectiveBuildRange(integer, integer) -> number
Parameters
integerunitID
integerbuildeeDefID
or nil
Returns
numbereffectiveBuildRange
counted to the center of prospective buildee; buildRange if buildee nil

Spring.GetUnitCurrentBuildPower (function)

[source]
Spring.GetUnitCurrentBuildPower(integer) -> nil
Parameters
integerunitID

Spring.GetUnitHarvestStorage (function)

Get a unit’s carried resources

[source]

Checks resources being carried internally by the unit.

Spring.GetUnitHarvestStorage(integer) -> number, number, number, number
Parameters
integerunitID
Returns
numberstoredMetal
numbermaxStoredMetal
numberstoredEnergy
numbermaxStoredEnergy

Spring.GetUnitBuildParams (function)

[source]
Spring.GetUnitBuildParams(integer) -> nil
Parameters
integerunitID

Spring.GetUnitInBuildStance (function)

Is builder in build stance

[source]

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

Spring.GetUnitInBuildStance(integer) -> boolean
Parameters
integerunitID
Returns
booleaninBuildStance

Spring.GetUnitNanoPieces (function)

Get construction FX attachment points

[source]

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

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

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

Spring.GetUnitTransporter (function)

Get the transport carrying the unit

[source]

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

Spring.GetUnitTransporter(integer) -> integer?
Parameters
integerunitID
Returns
integer?transportUnitID

Spring.GetUnitIsTransporting (function)

Get units being transported

[source]

Spring.GetUnitIsTransporting(integer) -> integer[]?
Parameters
integerunitID
Returns
integer[]?transporteeArray

Spring.GetUnitShieldState (function)

[source]
Spring.GetUnitShieldState(integer, number?) -> number, number
Parameters
integerunitID
number?weaponNum
Optional if the unit has just one shield
Returns
numberisEnabled
Warning, number not boolean. 0 or 1
numbercurrentPower

Spring.GetUnitFlanking (function)

[source]
Spring.GetUnitFlanking(integer) -> nil
Parameters
integerunitID

Spring.GetUnitMaxRange (function)

Get a unit’s engagement range

[source]

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

Spring.GetUnitMaxRange(integer) -> number
Parameters
integerunitID
Returns
numbermaxRange

Spring.GetUnitWeaponState (function)

Check the state of a unit’s weapon

[source]

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

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

Spring.GetUnitWeaponState(integer, number, string) -> number
Parameters
integerunitID
numberweaponNum
stringstateName
Returns
numberstateValue

Spring.GetUnitWeaponDamages (function)

[source]
Spring.GetUnitWeaponDamages(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponVectors (function)

[source]
Spring.GetUnitWeaponVectors(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponTryTarget (function)

[source]
Spring.GetUnitWeaponTryTarget(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponTestTarget (function)

[source]
Spring.GetUnitWeaponTestTarget(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponTestRange (function)

[source]
Spring.GetUnitWeaponTestRange(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponHaveFreeLineOfFire (function)

[source]
Spring.GetUnitWeaponHaveFreeLineOfFire(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponCanFire (function)

[source]
Spring.GetUnitWeaponCanFire(integer) -> nil
Parameters
integerunitID

Spring.GetUnitWeaponTarget (function)

Checks a weapon’s target

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

[source]

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

Spring.GetUnitWeaponTarget (function overload 1)

Checks a weapon’s target

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

[source]

Spring.GetUnitWeaponTarget(integer, integer) -> 1, boolean, integer
Parameters
integerunitID
integerweaponNum
Returns
1TargetType
unit
booleanisUserTarget
integertargetUnitID

Spring.GetUnitWeaponTarget (function overload 2)

Checks a weapon’s target

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

[source]

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

Spring.GetUnitWeaponTarget (function overload 3)

Checks a weapon’s target

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

[source]

Spring.GetUnitWeaponTarget(integer, integer) -> 3, boolean, integer
Parameters
integerunitID
integerweaponNum
Returns
3TargetType
projectileID
booleanisUserTarget
integertargetProjectileId

Spring.GetUnitEstimatedPath (function)

[source]
Spring.GetUnitEstimatedPath(integer) -> nil
Parameters
integerunitID

Spring.GetUnitLastAttacker (function)

[source]
Spring.GetUnitLastAttacker(integer) -> nil
Parameters
integerunitID

Spring.GetUnitLastAttackedPiece (function)

[source]
Spring.GetUnitLastAttackedPiece(integer) -> nil
Parameters
integerunitID

Spring.GetUnitCollisionVolumeData (function)

[source]
Spring.GetUnitCollisionVolumeData(integer) -> nil
Parameters
integerunitID

Spring.GetUnitSeparation (function)

[source]
Spring.GetUnitSeparation(number, number, boolean?, boolean?) -> number?
Parameters
numberunitID1
numberunitID2
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)

[source]
Spring.GetUnitFeatureSeparation(integer) -> nil
Parameters
integerunitID

Spring.GetUnitDefDimensions (function)

[source]
Spring.GetUnitDefDimensions(integer) -> UnitDefDimensions?
Parameters
integerunitDefID
Returns
UnitDefDimensions?dimensions

Spring.GetCEGID (function)

[source]
Spring.GetCEGID() -> nil

Spring.GetUnitBlocking (function)

[source]
Spring.GetUnitBlocking(integer) -> boolean?, boolean, boolean, boolean, boolean, boolean, boolean
Parameters
integerunitID
Returns
boolean?isBlocking
booleanisSolidObjectCollidable
booleanisProjectileCollidable
booleanisRaySegmentCollidable
booleancrushable
booleanblockEnemyPushing
booleanblockHeightChanges

Spring.GetUnitMoveTypeData (function)

[source]
Spring.GetUnitMoveTypeData(integer) -> nil
Parameters
integerunitID

Spring.GetUnitCurrentCommand (function)

Get a command from a units command queue.

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

[source]

See Spring.GetFactoryCommands for getting factory build queue commands

Spring.GetUnitCurrentCommand(integer, integer?) -> CMD?, (integer|CommandOptionBit)?, integer?, number? ...
Parameters
integerunitID
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)

Get the commands for a unit.

[source]

Same as Spring.GetCommandQueue

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

Spring.GetUnitCommands (function overload 1)

Get the count of commands for a unit.

[source]

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

Spring.GetUnitCommands(integer, 0) -> integer
Parameters
integerunitID
0count
Returns the number of commands in the units queue.
Returns
integerThe
number of commands in the unit queue.

Spring.GetFactoryCommands (function)

Get the number or list of commands for a factory

[source]

See Spring.GetFactoryCounts to get command counts grouped by cmdID.

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

Spring.GetFactoryCommands (function overload 1)

Get the count of commands for a factory.

[source]

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

See Spring.GetFactoryCommandCount for replacement function.

Spring.GetFactoryCommands(integer, 0) -> integer
Parameters
integerunitID
0count
Returns the number of commands in the factory queue.
Returns
integerThe
number of commands in the factory queue.

Spring.GetUnitCommandCount (function)

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

[source]

Spring.GetUnitCommandCount(integer) -> integer
Parameters
integerunitID
Returns
integerThe
number of commands in the unit’s queue.

Spring.GetFactoryCommandCount (function)

Get the number of commands in a factory queue.

[source]

See Spring.GetFactoryCounts to get command counts grouped by cmdID.

Spring.GetFactoryCommandCount(integer) -> integer
Parameters
integerunitID
Returns
integerThe
number of commands in the factory queue.

Spring.GetFactoryBuggerOff (function)

[source]
Spring.GetFactoryBuggerOff(integer) -> nil
Parameters
integerunitID

Spring.GetFactoryCounts (function)

Gets the build queue of a factory

[source]

Spring.GetFactoryCounts(integer, integer?, boolean?) -> table<number,number>?
Parameters
integerunitID
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)

Get the commands for a unit.

[source]

Same as Spring.GetUnitCommands

Deprecated: Use Spring.GetUnitCommands instead.

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

Spring.GetCommandQueue (function overload 1)

Get the count of commands for a unit.

[source]

Same as Spring.GetUnitCommands

Deprecated: Use Spring.GetUnitCommandCount instead.

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

Spring.GetFullBuildQueue (function)

Returns the build queue

[source]

Spring.GetFullBuildQueue(integer) -> table<number,number>?
Parameters
integerunitID
Returns
table<number,number>?buildqueue
indexed by unitDefID with count values

Spring.GetRealBuildQueue (function)

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

[source]

Spring.GetRealBuildQueue(integer) -> table<number,number>?
Parameters
integerunitID
Returns
table<number,number>?buildqueue
indexed by unitDefID with count values

Spring.GetUnitCmdDescs (function)

[source]
Spring.GetUnitCmdDescs(integer) -> nil
Parameters
integerunitID

Spring.FindUnitCmdDesc (function)

[source]
Spring.FindUnitCmdDesc(integer, integer) -> integer?
Parameters
integerunitID
integercmdID
Returns
integer?

Spring.ValidFeatureID (function)

[source]
Spring.ValidFeatureID(integer) -> boolean
Parameters
integerfeatureID
Returns
boolean

Spring.GetAllFeatures (function)

[source]
Spring.GetAllFeatures() -> integer[]
Returns
integer[]featureIDs

Spring.GetFeatureDefID (function)

[source]
Spring.GetFeatureDefID(integer) -> number?
Parameters
integerfeatureID
Returns
number?

Spring.GetFeatureTeam (function)

[source]
Spring.GetFeatureTeam(integer) -> number?
Parameters
integerfeatureID
Returns
number?

Spring.GetFeatureAllyTeam (function)

[source]
Spring.GetFeatureAllyTeam(integer) -> number?
Parameters
integerfeatureID
Returns
number?

Spring.GetFeatureHealth (function)

[source]
Spring.GetFeatureHealth(integer) -> number?, number, number
Parameters
integerfeatureID
Returns
number?health
numberdefHealth
numberresurrectProgress

Spring.GetFeatureHeight (function)

[source]
Spring.GetFeatureHeight(integer) -> number?
Parameters
integerfeatureID
Returns
number?

Spring.GetFeatureRadius (function)

[source]
Spring.GetFeatureRadius(integer) -> number?
Parameters
integerfeatureID
Returns
number?

Spring.GetFeatureMass (function)

[source]
Spring.GetFeatureMass(integer) -> number?
Parameters
integerfeatureID
Returns
number?

Spring.GetFeaturePosition (function)

[source]
Spring.GetFeaturePosition(integer) -> number?, number?, number?
Parameters
integerfeatureID
Returns
number?x
number?y
number?z

Spring.GetFeatureSeparation (function)

[source]
Spring.GetFeatureSeparation(number, number, boolean?) -> number?
Parameters
numberfeatureID1
numberfeatureID2
boolean?direction
(Default: false) to subtract from, default featureID1 - featureID2
Returns
number?

Spring.GetFeatureRotation (function)

[source]

Note: PYR order

Spring.GetFeatureRotation(integer) -> number?, number?, number?
Parameters
integerfeatureID
Returns
number?pitch
Rotation in X axis
number?yaw
Rotation in Y axis
number?roll
Rotation in Z axis

Spring.GetFeatureDirection (function)

[source]
Spring.GetFeatureDirection(integer) -> number?, number?, number?, number?, number?, number?, number?, number?, number?
Parameters
integerfeatureID
Returns
number?frontDirX
number?frontDirY
number?frontDirZ
number?rightDirX
number?rightDirY
number?rightDirZ
number?upDirX
number?upDirY
number?upDirZ

Spring.GetFeatureVelocity (function)

[source]

Returns nil if no feature found with ID.

Spring.GetFeatureVelocity(integer) -> number?, number?, number?, number?
Parameters
integerfeatureID
Returns
number?x
number?y
number?z
number?w

Spring.GetFeatureHeading (function)

[source]
Spring.GetFeatureHeading(integer) -> nil
Parameters
integerfeatureID

Spring.GetFeatureResources (function)

[source]
Spring.GetFeatureResources(integer) -> number?, number, number, number, number, number
Parameters
integerfeatureID
Returns
number?metal
numberdefMetal
numberenergy
numberdefEnergy
numberreclaimLeft
numberreclaimTime

Spring.GetFeatureBlocking (function)

[source]
Spring.GetFeatureBlocking(integer) -> boolean?, boolean?, boolean?, boolean?, boolean?, boolean?, boolean?
Parameters
integerfeatureID
Returns
boolean?isBlocking
boolean?isSolidObjectCollidable
boolean?isProjectileCollidable
boolean?isRaySegmentCollidable
boolean?crushable
boolean?blockEnemyPushing
boolean?blockHeightChanges

Spring.GetFeatureNoSelect (function)

[source]
Spring.GetFeatureNoSelect(integer) -> boolean?
Parameters
integerfeatureID
Returns
boolean?

Spring.GetFeatureResurrect (function)

[source]

Returns nil if no feature found with ID.

Spring.GetFeatureResurrect(integer) -> (string|"")?, FacingInteger
Parameters
integerfeatureID
Returns
(string|"")?featureDefName
FacingIntegerbuildFacing
facing of footprint, 0 - 3

Spring.GetFeatureLastAttackedPiece (function)

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

Spring.GetFeatureCollisionVolumeData (function)

[source]
Spring.GetFeatureCollisionVolumeData(integer) -> CollisionVolumeData?
Parameters
integerfeatureID
Returns
CollisionVolumeData?

Spring.GetFeaturePieceCollisionVolumeData (function)

[source]
Spring.GetFeaturePieceCollisionVolumeData(integer) -> CollisionVolumeData?
Parameters
integerfeatureID
Returns
CollisionVolumeData?

Spring.GetFeatureFireTime (function)

Get the feature current fire timer.

[source]

Spring.GetFeatureFireTime(integer) -> number?
Parameters
integerfeatureID
Returns
number?fireTime
in seconds, nil when featureID is invalid.

Spring.GetFeatureSmokeTime (function)

Get the feature current smoke timer.

[source]

Spring.GetFeatureSmokeTime(integer) -> number?
Parameters
integerfeatureID
Returns
number?smokeTime
in seconds, nil when featureID is invalid.

Spring.GetProjectilePosition (function)

[source]
Spring.GetProjectilePosition(integer) -> number?, number?, number?
Parameters
integerprojectileID
Returns
number?posX
number?posY
number?posZ

Spring.GetProjectileDirection (function)

[source]
Spring.GetProjectileDirection(integer) -> number?, number?, number?
Parameters
integerprojectileID
Returns
number?dirX
number?dirY
number?dirZ

Spring.GetProjectileVelocity (function)

[source]
Spring.GetProjectileVelocity(integer) -> number?, number?, number?, number?
Parameters
integerprojectileID
Returns
number?velX
number?velY
number?velZ
number?velW

Spring.GetProjectileGravity (function)

[source]
Spring.GetProjectileGravity(integer) -> number?
Parameters
integerprojectileID
Returns
number?

Spring.GetPieceProjectileParams (function)

[source]
Spring.GetPieceProjectileParams(integer) -> number?, number, number, number, number, number
Parameters
integerprojectileID
Returns
number?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)

[source]
Spring.GetProjectileTarget(integer) -> number?, (number|float3)
Parameters
integerprojectileID
Returns
number?targetTypeInt
where string.byte(‘g’) := GROUND string.byte(‘u’) := UNIT string.byte(‘f’) := FEATURE string.byte(‘p’) := PROJECTILE
(number|float3)target
targetID or targetPos when targetTypeInt == string.byte(‘g’)

Spring.GetProjectileIsIntercepted (function)

[source]
Spring.GetProjectileIsIntercepted(integer) -> boolean?
Parameters
integerprojectileID
Returns
boolean?

Spring.GetProjectileTimeToLive (function)

[source]
Spring.GetProjectileTimeToLive(integer) -> number?
Parameters
integerprojectileID
Returns
number?

Spring.GetProjectileOwnerID (function)

[source]
Spring.GetProjectileOwnerID(integer) -> number?
Parameters
integerprojectileID
Returns
number?

Spring.GetProjectileTeamID (function)

[source]
Spring.GetProjectileTeamID(integer) -> number?
Parameters
integerprojectileID
Returns
number?

Spring.GetProjectileAllyTeamID (function)

[source]
Spring.GetProjectileAllyTeamID(integer) -> number?
Parameters
integerprojectileID
Returns
number?

Spring.GetProjectileType (function)

[source]
Spring.GetProjectileType(integer) -> boolean?, boolean
Parameters
integerprojectileID
Returns
boolean?weapon
booleanpiece

Spring.GetProjectileDefID (function)

[source]
Spring.GetProjectileDefID(integer) -> number?
Parameters
integerprojectileID
Returns
number?

Spring.GetPieceProjectileName (function)

Returns the name of the model piece from which a piece projectile was spawned. Returns nil for other projectiles including weapons

[source]

Spring.GetPieceProjectileName(integer) -> string?
Parameters
integerprojectileID
Returns
string?pieceName

Spring.GetProjectileDamages (function)

[source]
Spring.GetProjectileDamages(integer, string) -> number?
Parameters
integerprojectileID
stringtag

one of: “paralyzeDamageTime” “impulseFactor” “impulseBoost” “craterMult” “craterBoost” “dynDamageExp” “dynDamageMin” “dynDamageRange” “dynDamageInverted” “craterAreaOfEffect” “damageAreaOfEffect” “edgeEffectiveness” “explosionSpeed”

  • or - an armor type index to get the damage against it.
Returns
number?

Spring.IsPosInMap (function)

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

Get ground height

On sea, this returns the negative depth of the seafloor

[source]

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

Spring.GetWaterPlaneLevel (function)

Get water plane height

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

[source]

See Spring.GetWaterLevel

Spring.GetWaterPlaneLevel() -> number
Returns
numberwaterPlaneLevel

Spring.GetWaterLevel (function)

Get water level in a specific position

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

[source]

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

Spring.GetGroundOrigHeight (function)

Get ground height as it was at game start

Returns the original height before the ground got deformed

[source]

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

Spring.GetGroundNormal (function)

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

[source]
Spring.GetGroundInfo(number, number) -> number, number, number, string, number, number, number, number, number, number, boolean
Parameters
numberx
numberz
Returns
numberix
numberiz
numberterrainTypeIndex
stringname
numbermetalExtraction
numberhardness
numbertankSpeed
numberkbotSpeed
numberhoverSpeed
numbershipSpeed
booleanreceiveTracks

Spring.GetGroundBlocked (function)

[source]
Spring.GetGroundBlocked() -> nil

Spring.GetGroundExtremes (function)

[source]
Spring.GetGroundExtremes() -> number, number, number, number
Returns
numberinitMinHeight
numberinitMaxHeight
numbercurrMinHeight
numbercurrMaxHeight

Spring.GetTerrainTypeData (function)

[source]
Spring.GetTerrainTypeData(number) -> number, string, number, number, number, number, number, boolean
Parameters
numberterrainTypeInfo
Returns
numberindex
stringname
numberhardness
numbertankSpeed
numberkbotSpeed
numberhoverSpeed
numbershipSpeed
booleanreceiveTracks

Spring.GetGrass (function)

[source]
Spring.GetGrass(number, number) -> number
Parameters
numberx
numberz
Returns
number

Spring.GetSmoothMeshHeight (function)

[source]
Spring.GetSmoothMeshHeight(number, number) -> number
Parameters
numberx
numberz
Returns
numberheight

Spring.TestMoveOrder (function)

[source]
Spring.TestMoveOrder(integer, number, number, number, number?, number?, number?, boolean?, boolean?, boolean?) -> boolean
Parameters
integerunitDefID
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)

[source]
Spring.TestBuildOrder(integer, number, number, number, Facing) -> BuildOrderBlockedStatus, integer?
Parameters
integerunitDefID
numberx
numbery
numberz
Facingfacing
Returns
BuildOrderBlockedStatusblocking
integer?featureID
A reclaimable feature in the way.

Spring.Pos2BuildPos (function)

Snaps a position to the building grid

[source]

Spring.Pos2BuildPos(integer, number, number, number, number?) -> number, number, number
Parameters
integerunitDefID
numberposX
numberposY
numberposZ
number?buildFacing
(Default: 0) one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3
Returns
numberbuildPosX
numberbuildPosY
numberbuildPosZ

Spring.ClosestBuildPos (function)

[source]
Spring.ClosestBuildPos(integer, integer, number, number, number, number, number, number) -> number, number, number
Parameters
integerteamID
integerunitDefID
numberposX
numberposY
numberposZ
numbersearchRadius
numberminDistance
numberbuildFacing
one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3
Returns
numberbuildPosX
numberbuildPosY
numberbuildPosZ

Spring.GetPositionLosState (function)

[source]
Spring.GetPositionLosState(number, number, number, integer?) -> boolean, boolean, boolean, boolean
Parameters
numberposX
numberposY
numberposZ
integer?allyTeamID
Returns
booleaninLosOrRadar
booleaninLos
booleaninRadar
booleaninJammer

Spring.IsPosInLos (function)

[source]
Spring.IsPosInLos(number, number, number, integer?) -> boolean
Parameters
numberposX
numberposY
numberposZ
integer?allyTeamID
Returns
boolean

Spring.IsPosInRadar (function)

[source]
Spring.IsPosInRadar(number, number, number, integer?) -> boolean
Parameters
numberposX
numberposY
numberposZ
integer?allyTeamID
Returns
boolean

Spring.IsPosInAirLos (function)

[source]
Spring.IsPosInAirLos(number, number, number, integer?) -> boolean
Parameters
numberposX
numberposY
numberposZ
integer?allyTeamID
Returns
boolean

Spring.GetUnitLosState (function)

Get unit los state (bitmask)

[source]

Spring.GetUnitLosState(integer, integer?, true) -> (LosMask|integer)?
Parameters
integerunitID
integer?allyTeamID
trueraw
Return a bitmask.
Returns
(LosMask|integer)?bitmask
A bitmask of LosMask bits

Spring.GetUnitLosState (function overload 1)

Get unit los state (table)

[source]

Spring.GetUnitLosState(integer, integer?, false?) -> table<("los"|"radar"...),boolean>?
Parameters
integerunitID
integer?allyTeamID
false?raw
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)

[source]
Spring.IsUnitInLos(integer, integer) -> boolean
Parameters
integerunitID
integerallyTeamID
Returns
booleaninLos

Spring.IsUnitInAirLos (function)

[source]
Spring.IsUnitInAirLos(integer, integer) -> boolean
Parameters
integerunitID
integerallyTeamID
Returns
booleaninAirLos

Spring.IsUnitInRadar (function)

[source]
Spring.IsUnitInRadar(integer, integer) -> boolean
Parameters
integerunitID
integerallyTeamID
Returns
booleaninRadar

Spring.IsUnitInJammer (function)

[source]
Spring.IsUnitInJammer(integer, integer) -> boolean
Parameters
integerunitID
integerallyTeamID
Returns
booleaninJammer

Spring.GetModelRootPiece (function)

[source]
Spring.GetModelRootPiece(string) -> number
Parameters
stringmodelName
Returns
numberindex
of the root piece

Spring.GetModelPieceMap (function)

[source]
Spring.GetModelPieceMap(string) -> table<string,number>?
Parameters
stringmodelName
Returns
table<string,number>?pieceInfos
where keys are piece names and values are indices

Spring.GetModelPieceList (function)

[source]
Spring.GetModelPieceList(string) -> string[]?
Parameters
stringmodelName
Returns
string[]?pieceNames

Spring.GetUnitRootPiece (function)

[source]
Spring.GetUnitRootPiece(integer) -> number
Parameters
integerunitID
Returns
numberindex
of the root piece

Spring.GetUnitPieceMap (function)

[source]
Spring.GetUnitPieceMap(integer) -> table<string,number>?
Parameters
integerunitID
Returns
table<string,number>?pieceInfos
where keys are piece names and values are indices

Spring.GetUnitPieceList (function)

[source]
Spring.GetUnitPieceList(integer) -> string[]
Parameters
integerunitID
Returns
string[]pieceNames

Spring.GetUnitPieceInfo (function)

[source]
Spring.GetUnitPieceInfo(integer, integer) -> PieceInfo?
Parameters
integerunitID
integerpieceIndex
Returns
PieceInfo?pieceInfo

Spring.GetUnitPiecePosDir (function)

[source]
Spring.GetUnitPiecePosDir(integer, integer) -> number?, number, number, number, number, number
Parameters
integerunitID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ

Spring.GetUnitPiecePosition (function)

[source]
Spring.GetUnitPiecePosition(integer, integer) -> number?, number, number
Parameters
integerunitID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ

Spring.GetUnitPieceDirection (function)

[source]
Spring.GetUnitPieceDirection(integer, integer) -> number?, number, number
Parameters
integerunitID
integerpieceIndex
Returns
number?dirX
numberdirY
numberdirZ

Spring.GetUnitPieceMatrix (function)

[source]
Spring.GetUnitPieceMatrix(integer, integer) -> number?, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
integerunitID
integerpieceIndex
Returns
number?m11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.GetFeatureRootPiece (function)

[source]
Spring.GetFeatureRootPiece(integer) -> number
Parameters
integerfeatureID
Returns
numberindex
of the root piece

Spring.GetFeaturePieceMap (function)

[source]
Spring.GetFeaturePieceMap(integer) -> table<string,number>
Parameters
integerfeatureID
Returns
table<string,number>pieceInfos
where keys are piece names and values are indices

Spring.GetFeaturePieceList (function)

[source]
Spring.GetFeaturePieceList(integer) -> string[]
Parameters
integerfeatureID
Returns
string[]pieceNames

Spring.GetFeaturePieceInfo (function)

[source]
Spring.GetFeaturePieceInfo(integer, integer) -> PieceInfo?
Parameters
integerfeatureID
integerpieceIndex
Returns
PieceInfo?pieceInfo

Spring.GetFeaturePiecePosDir (function)

[source]
Spring.GetFeaturePiecePosDir(integer, integer) -> number?, number, number, number, number, number
Parameters
integerfeatureID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ

Spring.GetFeaturePiecePosition (function)

[source]
Spring.GetFeaturePiecePosition(integer, integer) -> number?, number, number
Parameters
integerfeatureID
integerpieceIndex
Returns
number?posX
numberposY
numberposZ

Spring.GetFeaturePieceDirection (function)

[source]
Spring.GetFeaturePieceDirection(integer, integer) -> number?, number, number
Parameters
integerfeatureID
integerpieceIndex
Returns
number?dirX
numberdirY
numberdirZ

Spring.GetFeaturePieceMatrix (function)

[source]
Spring.GetFeaturePieceMatrix(integer, integer) -> number?, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number
Parameters
integerfeatureID
integerpieceIndex
Returns
number?m11
numberm12
numberm13
numberm14
numberm21
numberm22
numberm23
numberm24
numberm31
numberm32
numberm33
numberm34
numberm41
numberm42
numberm43
numberm44

Spring.GetUnitScriptPiece (function)

[source]
Spring.GetUnitScriptPiece(integer) -> integer[]
Parameters
integerunitID
Returns
integer[]pieceIndices

Spring.GetUnitScriptPiece (function overload 1)

[source]
Spring.GetUnitScriptPiece(integer, integer) -> integer
Parameters
integerunitID
integerscriptPiece
Returns
integerpieceIndex

Spring.GetUnitScriptNames (function)

[source]
Spring.GetUnitScriptNames(integer) -> table<string,number>
Parameters
integerunitID
Returns
table<string,number>where
keys are piece names and values are piece indices

Spring.TraceRayGroundInDirection (function)

Checks for a ground collision in given direction

[source]

Checks if there is surface (ground, optionally water) towards a vector and returns the distance to the closest hit and its position, if any.

Spring.TraceRayGroundInDirection(number, number, number, number, number, number, boolean?) -> number, number, number, number
Parameters
numberposX
numberposY
numberposZ
numberdirX
numberdirY
numberdirZ
boolean?testWater
(Default: true)
Returns
numberrayLength
numberposX
numberposY
numberposZ

Spring.TraceRayGroundBetweenPositions (function)

Checks for a ground collision between two positions

[source]

Checks if there is surface (ground, optionally water) between two positions and returns the distance to the closest hit and its position, if any.

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)

[source]
Spring.GetRadarErrorParams(integer) -> number?, number, number
Parameters
integerallyTeamID
Returns
number?radarErrorSize
actual radar error size (when allyTeamID is allied to current team) or base radar error size
numberbaseRadarErrorSize
numberbaseRadarErrorMult

Spring.Echo (function)

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

Hint: the default print() writes to STDOUT.

[source]

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

Spring.Log (function)

Logs a message to the logfile/console.

[source]

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.CallAsTeam (function)

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

[source]

Spring.CallAsTeam(integer, fun(...), [any, ]*) -> any ...
Parameters
integerteamID
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)

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

Fields

MoveCtrl MoveCtrl
[source]

Callins (class)

[source]

Members

Callins:Initialize (function)

Called when the addon is (re)loaded.

[source]

Callins:Initialize() -> nil

Callins:LoadCode (function)

Called when the game is (re)loaded.

[source]

Callins:LoadCode() -> nil

Callins:Shutdown (function)

Called when the addon or the game is shutdown.

[source]

Callins:Shutdown() -> nil
Returns
nil

Callins:GotChatMsg (function)

Called when a player issues a UI command e.g. types /foo or /luarules foo.

[source]

Callins:GotChatMsg(string, integer) -> nil
Parameters
stringmsg
integerplayerID

Callins:Load (function)

Called after GamePreload and before GameStart. See Lua_SaveLoad.

[source]

Callins:Load(table) -> nil
Parameters
tablezipReader

Callins:GamePreload (function)

Called before the 0 gameframe.

Is not called when a saved game is loaded.

[source]

Callins:GamePreload() -> nil

Callins:GameStart (function)

Called upon the start of the game.

[source]

Is not called when a saved game is loaded.

Callins:GameStart() -> nil

Callins:GameOver (function)

Called when the game ends

[source]

Callins:GameOver(number[]) -> nil
Parameters
number[]winningAllyTeams
list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

Callins:GamePaused (function)

Called when the game is paused.

[source]

Callins:GamePaused(integer, boolean) -> nil
Parameters
integerplayerID
booleanpaused

Callins:GameFrame (function)

Called for every game simulation frame (30 per second).

[source]

Callins:GameFrame(number) -> nil
Parameters
numberframe
Starts at frame 1

Callins:GameFramePost (function)

Called at the end of every game simulation frame

[source]

Callins:GameFramePost(number) -> nil
Parameters
numberframe
Starts at frame 1

Callins:GameID (function)

Called once to deliver the gameID

[source]

Callins:GameID(string) -> nil
Parameters
stringgameID
encoded in hex.

Callins:TeamDied (function)

Called when a team dies (see Spring.KillTeam).

[source]

Callins:TeamDied(integer) -> nil
Parameters
integerteamID

Callins:TeamChanged (function)

[source]
Callins:TeamChanged(integer) -> nil
Parameters
integerteamID

Callins:PlayerChanged (function)

Called whenever a player’s status changes e.g. becoming a spectator.

[source]

Callins:PlayerChanged(integer) -> nil
Parameters
integerplayerID

Callins:PlayerAdded (function)

Called whenever a new player joins the game.

[source]

Callins:PlayerAdded(integer) -> nil
Parameters
integerplayerID

Callins:PlayerRemoved (function)

Called whenever a player is removed from the game.

[source]

Callins:PlayerRemoved(integer, string) -> nil
Parameters
integerplayerID
stringreason

Callins:UnitCreated (function)

Called at the moment the unit is created.

[source]

Callins:UnitCreated(integer, integer, integer, integer?) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integer?builderID

Callins:UnitFinished (function)

Called at the moment the unit is completed.

[source]

Callins:UnitFinished(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitFromFactory (function)

Called when a factory finishes construction of a unit.

[source]

Callins:UnitFromFactory(integer, integer, integer, integer, integer, boolean) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integerfactID
integerfactDefID
booleanuserOrders

Callins:UnitReverseBuilt (function)

Called when a living unit becomes a nanoframe again.

[source]

Callins:UnitReverseBuilt(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitConstructionDecayed (function)

Called when a unit being built starts decaying.

[source]

Callins:UnitConstructionDecayed(integer, integer, integer, number, number, number) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
numbertimeSinceLastBuild
numberiterationPeriod
numberpart

Callins:UnitDestroyed (function)

Called when a unit is destroyed.

[source]

Callins:UnitDestroyed(integer, integer, integer, integer, integer, number, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integerattackerID
integerattackerDefID
numberattackerTeam
integerweaponDefID

Callins:UnitTaken (function)

Called when a unit is transferred between teams. This is called before UnitGiven and in that moment unit is still assigned to the oldTeam.

[source]

Callins:UnitTaken(integer, integer, number, number) -> nil
Parameters
integerunitID
integerunitDefID
numberoldTeam
numbernewTeam

Callins:UnitGiven (function)

Called when a unit is transferred between teams. This is called after UnitTaken and in that moment unit is assigned to the newTeam.

[source]

Callins:UnitGiven(integer, integer, number, number) -> nil
Parameters
integerunitID
integerunitDefID
numbernewTeam
numberoldTeam

Callins:UnitIdle (function)

Called when a unit is idle (empty command queue).

[source]

Callins:UnitIdle(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitCommand (function)

Called after when a unit accepts a command, after AllowCommand returns true.

[source]

Callins:UnitCommand(integer, integer, integer, integer, table, CommandOptions, number) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integercmdID
tablecmdParams
CommandOptionsoptions
numbercmdTag

Callins:UnitCmdDone (function)

Called when a unit completes a command.

[source]

Callins:UnitCmdDone(integer, integer, integer, integer, table, CommandOptions, number) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integercmdID
tablecmdParams
CommandOptionsoptions
numbercmdTag

Callins:UnitDamaged (function)

Called when a unit is damaged (after UnitPreDamaged).

[source]

Callins:UnitDamaged(integer, integer, integer, number, number, integer, integer, integer, integer, number) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
numberdamage
numberparalyzer
integerweaponDefID
integerprojectileID
integerattackerID
integerattackerDefID
numberattackerTeam

Callins:UnitStunned (function)

Called when a unit changes its stun status.

[source]

Callins:UnitStunned(integer, integer, integer, boolean) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
booleanstunned

Callins:UnitExperience (function)

Called when a unit gains experience greater or equal to the minimum limit set by calling Spring.SetExperienceGrade.

Should be called more reliably with small values of experience grade.

[source]

Callins:UnitExperience(integer, integer, integer, number, number) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
numberexperience
numberoldExperience

Callins:UnitHarvestStorageFull (function)

Called when a unit’s harvestStorage is full (according to its unitDef’s entry).

[source]

Callins:UnitHarvestStorageFull(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitSeismicPing (function)

Called when a unit emits a seismic ping.

[source]

See seismicSignature.

Callins:UnitSeismicPing(number, number, number, number, integer, integer, integer) -> nil
Parameters
numberx
numbery
numberz
numberstrength
integerallyTeam
integerunitID
integerunitDefID

Callins:UnitEnteredRadar (function)

Called when a unit enters radar of an allyteam.

Also called when a unit enters LOS without any radar coverage.

[source]

Callins:UnitEnteredRadar(integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitTeam
integerallyTeam
integerunitDefID

Callins:UnitEnteredLos (function)

Called when a unit enters LOS of an allyteam.

Its called after the unit is in LOS, so you can query that unit.

[source]

Callins:UnitEnteredLos(integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitTeam
integerallyTeam
who’s LOS the unit entered.
integerunitDefID

Callins:UnitLeftRadar (function)

Called when a unit leaves radar of an allyteam.

Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.

[source]

Callins:UnitLeftRadar(integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitTeam
integerallyTeam
integerunitDefID

Callins:UnitLeftLos (function)

Called when a unit leaves LOS of an allyteam.

For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.

[source]

Callins:UnitLeftLos(integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitTeam
integerallyTeam
integerunitDefID

Callins:UnitLoaded (function)

Called when a unit is loaded by a transport.

[source]

Callins:UnitLoaded(integer, integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integertransportID
integertransportTeam

Callins:UnitUnloaded (function)

Called when a unit is unloaded by a transport.

[source]

Callins:UnitUnloaded(integer, integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integertransportID
integertransportTeam

Callins:UnitEnteredUnderwater (function)

[source]
Callins:UnitEnteredUnderwater(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitEnteredWater (function)

[source]
Callins:UnitEnteredWater(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitLeftAir (function)

[source]
Callins:UnitLeftAir(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitLeftUnderwater (function)

[source]
Callins:UnitLeftUnderwater(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitLeftWater (function)

[source]
Callins:UnitLeftWater(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitEnteredAir (function)

[source]
Callins:UnitEnteredAir(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitCloaked (function)

Called when a unit cloaks.

[source]

Callins:UnitCloaked(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitDecloaked (function)

Called when a unit decloaks.

[source]

Callins:UnitDecloaked(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitUnitCollision (function)

Called when two units collide.

Both units must be registered with Script.SetWatchUnit.

[source]

Callins:UnitUnitCollision(integer, integer) -> nil
Parameters
integercolliderID
integercollideeID

Callins:UnitFeatureCollision (function)

Called when a unit collides with a feature.

[source]

The unit must be registered with Script.SetWatchUnit and the feature registered with Script.SetWatchFeature.

Callins:UnitFeatureCollision(integer, integer) -> nil
Parameters
integercolliderID
integercollideeID

Callins:UnitMoveFailed (function)

[source]
Callins:UnitMoveFailed(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:UnitArrivedAtGoal (function)

[source]
Callins:UnitArrivedAtGoal(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:RenderUnitDestroyed (function)

Called just before a unit is invalid, after it finishes its death animation.

[source]

Callins:RenderUnitDestroyed(integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam

Callins:FeatureCreated (function)

Called when a feature is created.

[source]

Callins:FeatureCreated(integer, integer) -> nil
Parameters
integerfeatureID
integerallyTeamID

Callins:FeatureDestroyed (function)

Called when a feature is destroyed.

[source]

Callins:FeatureDestroyed(integer, integer) -> nil
Parameters
integerfeatureID
integerallyTeamID

Callins:FeatureDamaged (function)

Called when a feature is damaged.

[source]

Callins:FeatureDamaged(integer, integer, number, number, integer, integer, integer, integer, number) -> nil
Parameters
integerfeatureID
integerfeatureDefID
numberfeatureTeam
numberdamage
integerweaponDefID
integerprojectileID
integerattackerID
integerattackerDefID
numberattackerTeam

Callins:ProjectileCreated (function)

Called when the projectile is created.

[source]

Note that weaponDefID is missing if the projectile is spawned as part of a burst, but Spring.GetProjectileDefID and Spring.GetProjectileName still work in callin scope using proID.

See Script.SetWatchWeapon

Callins:ProjectileCreated(integer, integer, integer) -> nil
Parameters
integerproID
integerproOwnerID
integerweaponDefID

Callins:ProjectileDestroyed (function)

Called when the projectile is destroyed.

[source]

See Script.SetWatchWeapon

Callins:ProjectileDestroyed(integer, integer, integer) -> nil
Parameters
integerproID
integerownerID
integerproWeaponDefID

Callins:Explosion (function)

Called when an explosion occurs.

[source]

Only called for weaponDefIDs registered via Script.SetWatchExplosion or Script.SetWatchWeapon.

See Script.SetWatchWeapon

Callins:Explosion(integer, number, number, number, integer, integer) -> boolean
Parameters
integerweaponDefID
numberpx
numberpy
numberpz
integerattackerID
integerprojectileID
Returns
booleannoGfx
if then no graphical effects are drawn by the engine for this explosion.

Callins:StockpileChanged (function)

Called when a units stockpile of weapons increases or decreases.

[source]

Callins:StockpileChanged(integer, integer, integer, integer, integer, integer) -> nil
Parameters
integerunitID
integerunitDefID
integerunitTeam
integerweaponNum
integeroldCount
integernewCount

Callins:RecvLuaMsg (function)

Receives messages from unsynced sent via Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.

[source]

Callins:RecvLuaMsg(string, integer) -> nil
Parameters
stringmsg
integerplayerID

Callins:Save (function)

Called when a chat command ‘/save’ or ‘/savegame’ is received.

[source]

Callins:Save(table) -> nil
Parameters
tablezip
a userdatum representing the savegame zip file. See Lua_SaveLoad.

Callins:UnsyncedHeightMapUpdate (function)

Called when the unsynced copy of the height-map is altered.

[source]

Callins:UnsyncedHeightMapUpdate() -> number, number, number, number
Returns
numberx1
numberz1
numberx2
numberz2

Callins:Update (function)

Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.

[source]

Callins:Update(number) -> nil
Parameters
numberdt
the time since the last update.

Callins:ViewResize (function)

Called whenever the window is resized.

[source]

Callins:ViewResize(number, number) -> nil
Parameters
numberviewSizeX
numberviewSizeY

Callins:FontsChanged (function)

Called whenever fonts are updated. Signals the game display lists and other caches should be discarded.

Gets called before other Update and Draw callins.

[source]

Callins:FontsChanged() -> nil

Callins:SunChanged (function)

[source]
Callins:SunChanged() -> nil

Callins:DefaultCommand (function)

Used to set the default command when a unit is selected.

[source]

Callins:DefaultCommand(("unit"|"feature"), integer) -> nil
Parameters
("unit"|"feature")type
The type of the object pointed at.
integerid
The unitID or featureID.

Callins:DrawGenesis (function)

Use this callin to update textures, shaders, etc.

[source]

Doesn’t render to screen! Also available to LuaMenu.

Callins:DrawGenesis() -> nil

Callins:DrawWorld (function)

Spring draws command queues, ‘map stuff’, and map marks.

[source]

Callins:DrawWorld() -> nil

Callins:DrawWorldPreUnit (function)

Spring draws units, features, some water types, cloaked units, and the sun.

[source]

Callins:DrawWorldPreUnit() -> nil

Callins:DrawPreDecals (function)

Called before decals are drawn

[source]

Callins:DrawPreDecals() -> nil

Callins:DrawWaterPost (function)

[source]
Callins:DrawWaterPost() -> nil

Callins:DrawShadowPassTransparent (function)

Invoked after semi-transparent shadows pass is about to conclude

[source]

This callin has depth and color buffer of shadowmap bound via FBO as well as the FFP state to do “semi-transparent” shadows pass (traditionally only used to draw shadows of shadow casting semi-transparent particles). Can be used to draw nice colored shadows.

Callins:DrawShadowPassTransparent() -> nil

Callins:DrawWorldShadow (function)

[source]
Callins:DrawWorldShadow() -> nil

Callins:DrawWorldReflection (function)

[source]
Callins:DrawWorldReflection() -> nil

Callins:DrawWorldRefraction (function)

[source]
Callins:DrawWorldRefraction() -> nil

Callins:DrawGroundPreForward (function)

Runs at the start of the forward pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

[source]

Callins:DrawGroundPreForward() -> nil

Callins:DrawGroundPostForward (function)

[source]
Callins:DrawGroundPostForward() -> nil

Callins:DrawGroundPreDeferred (function)

Runs at the start of the deferred pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

[source]

Callins:DrawGroundPreDeferred() -> nil

Callins:DrawGroundDeferred (function)

[source]
Callins:DrawGroundDeferred() -> nil

Callins:DrawGroundPostDeferred (function)

This runs at the end of its respective deferred pass.

[source]

Allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and DrawWorldPreUnit) via gl.CopyToTexture.

Callins:DrawGroundPostDeferred() -> nil

Callins:DrawUnitsPostDeferred (function)

Runs at the end of the unit deferred pass.

[source]

Informs Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

Callins:DrawUnitsPostDeferred() -> nil

Callins:DrawFeaturesPostDeferred (function)

Runs at the end of the feature deferred pass to inform Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

[source]

Callins:DrawFeaturesPostDeferred() -> nil

Callins:DrawShadowUnitsLua (function)

[source]
Callins:DrawShadowUnitsLua() -> nil

Callins:DrawShadowFeaturesLua (function)

[source]
Callins:DrawShadowFeaturesLua() -> nil

Callins:DrawWorldPreParticles (function)

DrawWorldPreParticles is called multiples times per draw frame. Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction.

[source]

Callins:DrawWorldPreParticles(boolean, boolean, boolean, boolean) -> nil
Parameters
booleandrawAboveWater
booleandrawBelowWater
booleandrawReflection
booleandrawRefraction

Callins:DrawScreen (function)

Also available to LuaMenu.

[source]

Callins:DrawScreen(number, number) -> nil
Parameters
numberviewSizeX
numberviewSizeY

Callins:DrawScreenEffects (function)

[source]
Callins:DrawScreenEffects(number, number) -> nil
Parameters
numberviewSizeX
numberviewSizeY

Callins:DrawScreenPost (function)

Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).

[source]

Note: This callin is invoked after the software rendered cursor (configuration variable HardwareCursor=0) is drawn.

Callins:DrawScreenPost(number, number) -> nil
Parameters
numberviewSizeX
numberviewSizeY

Callins:DrawInMiniMap (function)

[source]
Callins:DrawInMiniMap(number, number) -> nil
Parameters
numbersx
relative to the minimap’s position and scale.
numbersy
relative to the minimap’s position and scale.

Callins:DrawInMiniMapBackground (function)

[source]
Callins:DrawInMiniMapBackground(number, number) -> nil
Parameters
numbersx
relative to the minimap’s position and scale.
numbersy
relative to the minimap’s position and scale.

Callins:GameProgress (function)

Called every 60 frames, calculating delta between GameFrame and GameProgress.

Can give an ETA about catching up with simulation for mid-game join players.

[source]

Callins:GameProgress(integer) -> nil
Parameters
integerserverFrameNum

Callins:KeyMapChanged (function)

Called when the keymap changes

[source]

Can be caused due to a change in language or keyboard

Callins:KeyMapChanged() -> nil

Callins:KeyPress (function)

Called repeatedly when a key is pressed down.

[source]

Return true if you don’t want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki.

Callins:KeyPress(number, KeyModifiers, boolean, boolean, number, number, table) -> boolean
Parameters
numberkeyCode
KeyModifiersmods
booleanisRepeat
If you want an action to occur only once check for isRepeat == false.
booleanlabel
the name of the key
numberutf32char
(deprecated) always 0
numberscanCode
tableactionList
the list of actions for this keypress
Returns
booleanhalt
whether to halt the chain for consumers of the keypress

Callins:KeyRelease (function)

Called when the key is released.

[source]

Callins:KeyRelease(number, KeyModifiers, boolean, number, number, table) -> boolean
Parameters
numberkeyCode
KeyModifiersmods
booleanlabel
the name of the key
numberutf32char
(deprecated) always 0
numberscanCode
tableactionList
the list of actions for this keyrelease
Returns
boolean

Callins:TextInput (function)

Called whenever a key press results in text input.

[source]

Callins:TextInput(string) -> nil
Parameters
stringutf8char

Callins:TextEditing (function)

[source]
Callins:TextEditing(string, number, number) -> nil
Parameters
stringutf8
numberstart
numberlength

Callins:MousePress (function)

Called when a mouse button is pressed.

The button parameter supports up to 7 buttons. Must return true for MouseRelease and other functions to be called.

[source]

Callins:MousePress(number, number, number) -> boolean
Parameters
numberx
numbery
numberbutton
Returns
booleanbecomeMouseOwner

Callins:MouseRelease (function)

Called when a mouse button is released.

[source]

Please note that in order to have Spring call Spring.MouseRelease, you need to have a Spring.MousePress call-in in the same addon that returns true.

Callins:MouseRelease(number, number, number) -> boolean
Parameters
numberx
numbery
numberbutton
Returns
booleanbecomeMouseOwner

Callins:MouseMove (function)

Called when the mouse is moved.

[source]

Callins:MouseMove(number, number, number, number, number) -> nil
Parameters
numberx
final x position
numbery
final y position
numberdx
distance travelled in x
numberdy
distance travelled in y
numberbutton

Callins:MouseWheel (function)

Called when the mouse wheel is moved.

[source]

Callins:MouseWheel(boolean, number) -> nil
Parameters
booleanup
the direction
numbervalue
the amount travelled

Callins:IsAbove (function)

Called every Update.

[source]

Must return true for Mouse* events and Spring.GetToolTip to be called.

Callins:IsAbove(number, number) -> boolean
Parameters
numberx
numbery
Returns
booleanisAbove

Callins:GetTooltip (function)

Called when Spring.IsAbove returns true.

[source]

Callins:GetTooltip(number, number) -> string
Parameters
numberx
numbery
Returns
stringtooltip

Callins:ActiveCommandChanged (function)

Called when a command is issued.

[source]

Callins:ActiveCommandChanged(integer?, integer?) -> nil
Parameters
integer?cmdId
integer?cmdType

Callins:CameraRotationChanged (function)

Called whenever the camera rotation changes

[source]

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)

Called whenever the camera position changes

[source]

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:CommandNotify (function)

Called when a command is issued.

[source]

Callins:CommandNotify(integer, table, CommandOptions) -> boolean
Parameters
integercmdID
tablecmdParams
CommandOptionsoptions
Returns
booleanReturning
true deletes the command and does not send it through the network.

Callins:AddConsoleLine (function)

Called when text is entered into the console (e.g. Spring.Echo).

[source]

Callins:AddConsoleLine(string, integer) -> nil
Parameters
stringmsg
integerpriority

Callins:GroupChanged (function)

Called when a unit is added to or removed from a control group.

[source]

Callins:GroupChanged(integer) -> nil
Parameters
integergroupID

Callins:WorldTooltip (function)

[source]
Callins:WorldTooltip("unit", integer) -> string
Parameters
"unit"type
integerunitId
Returns
stringtooltip

Callins:WorldTooltip (function overload 1)

[source]
Callins:WorldTooltip("feature", integer) -> string
Parameters
"feature"type
integerfeatureId
Returns
stringtooltip

Callins:WorldTooltip (function overload 2)

[source]
Callins:WorldTooltip("ground", number, number, number) -> string
Parameters
"ground"type
numberposX
numberposY
numberposZ
Returns
stringtooltip

Callins:WorldTooltip (function overload 3)

[source]
Callins:WorldTooltip("selection") -> string
Parameters
"selection"type
Returns
stringtooltip

Callins:MapDrawCmd (function)

[source]
Callins:MapDrawCmd(integer, "point", number, number, number, string) -> nil
Parameters
integerplayerID
"point"type
numberposX
numberposY
numberposZ
stringlabel

Callins:MapDrawCmd (function overload 1)

[source]
Callins:MapDrawCmd(integer, "line", number, number, number, number, number, number) -> nil
Parameters
integerplayerID
"line"type
numberpos1X
numberpos1Y
numberpos1Z
numberpos2X
numberpos2Y
numberpos2Z

Callins:MapDrawCmd (function overload 2)

[source]
Callins:MapDrawCmd(integer, "erase", number, number, number, number) -> nil
Parameters
integerplayerID
"erase"type
numberposX
numberposY
numberposZ
numberradius

Callins:GameSetup (function)

Fired when the pregame stage is reached

Pregame is the stage where player readiness is managed before a game starts. Game only starts once all players are ready.

[source]

Callins:GameSetup(READY_MESSAGE, boolean, table<number,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<number,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)

[source]
Callins:RecvSkirmishAIMessage(integer, string) -> nil
Parameters
integeraiTeam
stringdataStr

Callins:DownloadQueued (function)

Called when a Pr-downloader download is queued

[source]

Callins:DownloadQueued(integer, string, string) -> nil
Parameters
integerid
stringname
stringtype

Callins:DownloadStarted (function)

Called when a Pr-downloader download is started via VFS.DownloadArchive.

[source]

Callins:DownloadStarted(integer) -> nil
Parameters
integerid

Callins:DownloadFinished (function)

Called when a Pr-downloader download finishes successfully.

[source]

Callins:DownloadFinished(integer) -> nil
Parameters
integerid

Callins:DownloadFailed (function)

Called when a Pr-downloader download fails to complete.

[source]

Callins:DownloadFailed(integer, integer) -> nil
Parameters
integerid
integererrorID

Callins:DownloadProgress (function)

Called incrementally during a Pr-downloader download.

[source]

Callins:DownloadProgress(integer, integer, integer) -> nil
Parameters
integerid
integerdownloaded
integertotal

SyncedCallins (class)

[source]

Functions called by the Engine (Synced).

Members

SyncedCallins:CommandFallback (function)

Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine).

[source]

SyncedCallins:CommandFallback(integer, integer, integer, integer, number[], CommandOptions, number) -> boolean
Parameters
integerunitID
integerunitDefID
integerunitTeam
integercmdID
number[]cmdParams
CommandOptionscmdOptions
numbercmdTag
Returns
booleanwhether
to remove the command from the queue

SyncedCallins:AllowCommand (function)

Called when the command is given, before the unit’s queue is altered.

[source]

The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.

SyncedCallins:AllowCommand(integer, integer, integer, integer, number[], CommandOptions, number, boolean, boolean) -> boolean
Parameters
integerunitID
integerunitDefID
integerunitTeam
integercmdID
number[]cmdParams
CommandOptionscmdOptions
numbercmdTag
booleansynced
booleanfromLua
Returns
booleanwhether
it should be let into the queue.

SyncedCallins:AllowUnitCreation (function)

Called just before unit is created.

[source]

SyncedCallins:AllowUnitCreation(integer, integer, integer, number, number, number, FacingInteger) -> boolean, boolean
Parameters
integerunitDefID
integerbuilderID
integerbuilderTeam
numberx
numbery
numberz
FacingIntegerfacing
Returns
booleanallow
booleandropOrder

SyncedCallins:AllowUnitTransfer (function)

Called just before a unit is transferred to a different team.

[source]

SyncedCallins:AllowUnitTransfer(integer, integer, integer, integer, boolean) -> boolean
Parameters
integerunitID
integerunitDefID
integeroldTeam
integernewTeam
booleancapture
Returns
booleanwhether
or not the transfer is permitted.

SyncedCallins:AllowUnitBuildStep (function)

Called just before a unit progresses its build percentage.

[source]

SyncedCallins:AllowUnitBuildStep(integer, integer, integer, integer, number) -> boolean
Parameters
integerbuilderID
integerbuilderTeam
integerunitID
integerunitDefID
numberpart
Returns
booleanwhether
or not the build makes progress.

SyncedCallins:AllowUnitCaptureStep (function)

[source]
SyncedCallins:AllowUnitCaptureStep(integer, integer, integer, integer, number) -> boolean
Parameters
integerbuilderID
integerbuilderTeam
integerunitID
integerunitDefID
numberpart
Returns
booleanwhether
or not the capture makes progress.

SyncedCallins:AllowUnitTransport (function)

[source]
SyncedCallins:AllowUnitTransport(integer, integer, integer, integer, integer, integer) -> boolean
Parameters
integertransporterID
integertransporterUnitDefID
integertransporterTeam
integertransporteeID
integertransporteeUnitDefID
integertransporteeTeam
Returns
booleanwhether
or not the transport is allowed

SyncedCallins:AllowUnitTransportLoad (function)

[source]
SyncedCallins:AllowUnitTransportLoad(integer, integer, integer, integer, integer, integer, number, number, number) -> boolean
Parameters
integertransporterID
integertransporterUnitDefID
integertransporterTeam
integertransporteeID
integertransporteeUnitDefID
integertransporteeTeam
numberx
numbery
numberz
Returns
booleanwhether
or not the transport load is allowed

SyncedCallins:AllowUnitTransportUnload (function)

[source]
SyncedCallins:AllowUnitTransportUnload(integer, integer, integer, integer, integer, integer, number, number, number) -> boolean
Parameters
integertransporterID
integertransporterUnitDefID
integertransporterTeam
integertransporteeID
integertransporteeUnitDefID
integertransporteeTeam
numberx
numbery
numberz
Returns
booleanwhether
or not the transport unload is allowed

SyncedCallins:AllowUnitCloak (function)

[source]
SyncedCallins:AllowUnitCloak(integer, integer?) -> boolean
Parameters
integerunitID
integer?enemyID
Returns
booleanwhether
unit is allowed to cloak

SyncedCallins:AllowUnitCloak (function overload 1)

[source]
SyncedCallins:AllowUnitCloak(integer, integer?, number?) -> boolean
Parameters
integerunitID
integer?objectID
number?weaponNum
Returns
booleanwhether
unit is allowed to decloak

SyncedCallins:AllowUnitKamikaze (function)

[source]
SyncedCallins:AllowUnitKamikaze(integer, integer) -> boolean
Parameters
integerunitID
integertargetID
Returns
booleanwhether
unit is allowed to selfd

SyncedCallins:AllowFeatureCreation (function)

Called just before feature is created.

[source]

SyncedCallins:AllowFeatureCreation(integer, integer, number, number, number) -> boolean
Parameters
integerfeatureDefID
integerteamID
numberx
numbery
numberz
Returns
booleanwhether
or not the creation is permitted

SyncedCallins:AllowFeatureBuildStep (function)

Called just before a feature changes its build percentage.

[source]

Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and resurrect they are positive. Part is the percentage the feature be built or reclaimed per frame. Eg. for a 30 workertime builder, that’s a build power of 1 per frame. For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically.

SyncedCallins:AllowFeatureBuildStep(integer, integer, integer, integer, number) -> boolean
Parameters
integerbuilderID
integerbuilderTeam
integerfeatureID
integerfeatureDefID
numberpart
Returns
booleanwhether
or not the change is permitted

SyncedCallins:AllowResourceLevel (function)

Called when a team sets the sharing level of a resource.

[source]

SyncedCallins:AllowResourceLevel(integer, string, number) -> boolean
Parameters
integerteamID
stringres
numberlevel
Returns
booleanwhether
or not the sharing level is permitted

SyncedCallins:AllowResourceTransfer (function)

Called just before resources are transferred between players.

[source]

SyncedCallins:AllowResourceTransfer(integer, integer, string, number) -> boolean
Parameters
integeroldTeamID
integernewTeamID
stringres
numberamount
Returns
booleanwhether
or not the transfer is permitted.

SyncedCallins:AllowDirectUnitControl (function)

Determines if this unit can be controlled directly in FPS view.

[source]

SyncedCallins:AllowDirectUnitControl(integer, integer, integer, integer) -> boolean
Parameters
integerunitID
integerunitDefID
integerunitTeam
integerplayerID
Returns
booleanallow

SyncedCallins:AllowBuilderHoldFire (function)

Called when a construction unit wants to “use his nano beams”.

[source]

SyncedCallins:AllowBuilderHoldFire(integer, integer, unknown) -> boolean
Parameters
integerunitID
integerunitDefID
unknownaction
Returns
booleanactionAllowed

SyncedCallins:AllowStartPosition (function)

Whether a start position should be allowed

[source]

clamped{X,Y,Z} are the coordinates clamped into start-boxes, raw is where player tried to place their marker.

The readyState can be any one of:

0 - player picked a position, 1 - player clicked ready, 2 - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or 3 - the player failed to load. The default ‘failed to choose’ start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.

SyncedCallins:AllowStartPosition(integer, integer, number, number, number, number, number, number, number) -> boolean
Parameters
integerplayerID
integerteamID
numberreadyState
numberclampedX
numberclampedY
numberclampedZ
numberrawX
numberrawY
numberrawZ
Returns
booleanallow

SyncedCallins:MoveCtrlNotify (function)

Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.

[source]

SyncedCallins:MoveCtrlNotify(integer, integer, integer, number) -> boolean
Parameters
integerunitID
integerunitDefID
integerunitTeam
numberdata
was supposed to indicate the type of notification but currently never has a value other than 1 (“unit hit the ground”).
Returns
booleanwhether
or not the unit should remain script-controlled (false) or return to engine controlled movement (true).

SyncedCallins:TerraformComplete (function)

Called when pre-building terrain levelling terraforms are completed (c.f. levelGround)

[source]

SyncedCallins:TerraformComplete(integer, integer, integer, integer, integer, integer) -> boolean
Parameters
integerunitID
integerunitDefID
integerunitTeam
integerbuildUnitID
integerbuildUnitDefID
integerbuildUnitTeam
Returns
booleanif
true the current build order is terminated

SyncedCallins:UnitPreDamaged (function)

Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.

[source]

Called after every damage modification (even HitByWeaponId) but before the damage is applied

expects two numbers returned by lua code: 1st is stored under *newDamage if newDamage != NULL 2nd is stored under *impulseMult if impulseMult != NULL

SyncedCallins:UnitPreDamaged(integer, integer, integer, number, boolean, integer?, integer?, integer?, integer?, integer?) -> number, number
Parameters
integerunitID
integerunitDefID
integerunitTeam
numberdamage
booleanparalyzer
integer?weaponDefID
Synced Only
integer?projectileID
Synced Only
integer?attackerID
Synced Only
integer?attackerDefID
Synced Only
integer?attackerTeam
Synced Only
Returns
numbernewDamage
numberimpulseMult

SyncedCallins:FeaturePreDamaged (function)

Called before damage is applied to the feature.

[source]

Allows fine control over how much damage and impulse is applied.

SyncedCallins:FeaturePreDamaged(integer, integer, integer, number, integer, integer, integer, integer, integer) -> number, number
Parameters
integerfeatureID
integerfeatureDefID
integerfeatureTeam
numberdamage
integerweaponDefID
integerprojectileID
integerattackerID
integerattackerDefID
integerattackerTeam
Returns
numbernewDamage
numberimpulseMult

SyncedCallins:ShieldPreDamaged (function)

Called before any engine shield-vs-projectile logic executes.

[source]

SyncedCallins:ShieldPreDamaged(integer, integer, integer, integer, boolean, integer?, integer?, number, number, number, number, number, number) -> boolean
Parameters
integerprojectileID
-1 when the weapon type is BeamLaser or LightningCannon
integerprojectileOwnerID
-1 when the weapon type is BeamLaser or LightningCannon
integershieldWeaponNum
integershieldCarrierID
booleanbounceProjectile
integer?beamEmitterWeaponNum
present only when the weapon type is BeamLaser or LightningCannon
integer?beamEmitterUnitID
present only when the weapon type is BeamLaser or LightningCannon
numberstartX
numberstartY
numberstartZ
numberhitX
numberhitY
numberhitZ
Returns
booleanif
true the gadget handles the collision event and the engine does not remove the projectile

SyncedCallins:AllowWeaponTargetCheck (function)

Determines if this weapon can automatically generate targets itself. See also commandFire weaponDef tag.

[source]

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

See Script.SetWatchWeapon

SyncedCallins:AllowWeaponTargetCheck(integer, integer, integer) -> boolean, boolean
Parameters
integerattackerID
integerattackerWeaponNum
integerattackerWeaponDefID
Returns
booleanallowCheck
booleanignoreCheck

SyncedCallins:AllowWeaponTarget (function)

Controls blocking of a specific target from being considered during a weapon’s periodic auto-targeting sweep.

[source]

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

See Script.SetWatchWeapon

SyncedCallins:AllowWeaponTarget(integer, integer, integer, integer, number) -> boolean, number
Parameters
integerattackerID
integertargetID
integerattackerWeaponNum
integerattackerWeaponDefID
numberdefPriority
Returns
booleanallowed
numberthe
new priority for this target (if you don’t want to change it, return defPriority). Lower priority targets are targeted first.

SyncedCallins:AllowWeaponInterceptTarget (function)

Controls blocking of a specific intercept target from being considered during an interceptor weapon’s periodic auto-targeting sweep.

[source]

Only called for weaponDefIDs registered via Script.SetWatchAllowTarget or Script.SetWatchWeapon.

See Script.SetWatchWeapon

SyncedCallins:AllowWeaponInterceptTarget(integer, integer, integer) -> boolean
Parameters
integerinterceptorUnitID
integerinterceptorWeaponID
integertargetProjectileID
Returns
booleanallowed

SyncedCallins.SendToUnsynced (function)

Invoke UnsyncedCallins:RecvFromSynced callin with the given arguments.

[source]

See UnsyncedCallins:RecvFromSynced

SyncedCallins.SendToUnsynced([(boolean|number|string|table)?, ]*) -> nil
Parameters
(boolean|number|string|table)?...

Arguments. Typically the first argument is the name of a function to call.

Argument tables will be recursively copied and stripped of unsupported types and metatables.

UnsyncedCallins (class)

[source]

Functions called by the Engine (Unsynced).

Members

UnsyncedCallins:RecvFromSynced (function)

Receives data sent via SendToUnsynced callout.

[source]

UnsyncedCallins:RecvFromSynced([any, ]*) -> nil
Parameters
any...

UnsyncedCallins:DrawUnit (function)

For custom rendering of units

[source]

Deprecated

UnsyncedCallins:DrawUnit(integer, number) -> boolean
Parameters
integerunitID
numberdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawFeature (function)

For custom rendering of features

[source]

Deprecated

UnsyncedCallins:DrawFeature(integer, number) -> boolean
Parameters
integerfeatureID
numberdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawShield (function)

For custom rendering of shields.

[source]

Deprecated

UnsyncedCallins:DrawShield(integer, integer, number) -> boolean
Parameters
integerfeatureID
integerweaponID
numberdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawProjectile (function)

For custom rendering of weapon (& other) projectiles

[source]

Deprecated

UnsyncedCallins:DrawProjectile(integer, number) -> boolean
Parameters
integerprojectileID
numberdrawMode
Returns
booleansuppressEngineDraw

UnsyncedCallins:DrawMaterial (function)

[source]

Deprecated

UnsyncedCallins:DrawMaterial(integer, number) -> boolean
Parameters
integeruuid
numberdrawMode
Returns
booleansuppressEngineDraw

gl (table)

Callouts for OpenGL API

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

[source]

See GL

Members

gl.AddFallbackFont (function)

Adds a fallback font for the font rendering engine.

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

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

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

[source]

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)

Clears all fallback fonts.

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

[source]

gl.ClearFallbackFonts() -> nil
Returns
nil

gl.GetVAO (function)

Example: local myVAO = gl.GetVAO() if myVAO == nil then Spring.Echo(“Failed to get VAO”) end

[source]

gl.GetVAO() -> VAO?
Returns
VAO?vao
The VAO ref on success, else nil

gl.CreateFBO (function)

[source]
gl.CreateFBO(FBODescription) -> FBO
Parameters
FBODescriptionfboDesc
Returns
FBOfbo

gl.DeleteFBO (function)

This doesn’t delete the attached objects!

[source]

gl.DeleteFBO(FBO) -> nil
Parameters
FBOfbo

gl.IsValidFBO (function)

[source]
gl.IsValidFBO(FBO, GL?) -> boolean, number?
Parameters
FBOfbo
GL?target
Returns
booleanvalid
number?status

gl.ActiveFBO (function)

[source]
gl.ActiveFBO(FBO, fun(...), [any, ]*) -> nil
Parameters
FBOfbo
fun(...)func
any...
args

gl.ActiveFBO (function overload 1)

[source]
gl.ActiveFBO(FBO, GL?, fun(...), [any, ]*) -> nil
Parameters
FBOfbo
GL?target
fun(...)func
any...
args

gl.RawBindFBO (function)

Bind default or specified via rawFboId numeric id of FBO

[source]

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)

[source]
gl.RawBindFBO(FBO, GL?) -> number
Parameters
FBOfbo
GL?target
(Default: fbo.target)
Returns
numberpreviouslyBoundRawFboId

gl.BlitFBO (function)

needs GLAD_GL_EXT_framebuffer_blit

[source]

gl.BlitFBO(number, number, number, number, number, number, number, number, number?, number?) -> nil
Parameters
numberx0Src
numbery0Src
numberx1Src
numbery1Src
numberx0Dst
numbery0Dst
numberx1Dst
numbery1Dst
number?mask
(Default: GL_COLOR_BUFFER_BIT)
number?filter
(Default: GL_NEAREST)

gl.BlitFBO (function overload 1)

needs GLAD_GL_EXT_framebuffer_blit

[source]

gl.BlitFBO(FBO, number, number, number, number, FBO, number, number, number, number, number?, number?) -> nil
Parameters
FBOfboSrc
numberx0Src
numbery0Src
numberx1Src
numbery1Src
FBOfboDst
numberx0Dst
numbery0Dst
numberx1Dst
numbery1Dst
number?mask
(Default: GL_COLOR_BUFFER_BIT)
number?filter
(Default: GL_NEAREST)

gl.ClearAttachmentFBO (function)

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

[source]

gl.ClearAttachmentFBO(number?, (GL|Attachment), number?, number?, number?, number?) -> boolean
Parameters
number?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.HasExtension (function)

[source]
gl.HasExtension(string) -> boolean
Parameters
stringext
Returns
boolean

gl.GetNumber (function)

Get the value or values of a selected parameter.

[source]

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)

Get a string describing the current OpenGL connection.

[source]

gl.GetString(GL) -> nil
Parameters
GLpname

gl.GetScreenViewTrans (function)

[source]
gl.GetScreenViewTrans() -> number, number, number
Returns
numberx
numbery
numberz

gl.GetViewSizes (function)

[source]
gl.GetViewSizes() -> number, number
Returns
numberx
numbery

gl.GetViewRange (function)

[source]
gl.GetViewRange() -> number, number, number, number
Returns
numbernearPlaneDist
numberfarPlaneDist
numberminViewRange
numbermaxViewRange

gl.SlaveMiniMap (function)

[source]
gl.SlaveMiniMap(boolean) -> nil
Parameters
booleannewMode

gl.ConfigMiniMap (function)

[source]
gl.ConfigMiniMap(integer, integer, integer, integer) -> nil
Parameters
integerpx
integerpy
integersx
integersy

gl.DrawMiniMap (function)

[source]
gl.DrawMiniMap(boolean?) -> nil
Parameters
boolean?defaultTransform
(Default: true)

gl.BeginText (function)

Begin a block of text commands.

[source]

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

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

See gl.BlendFuncSeparate

gl.BeginText(boolean?) -> nil
Parameters
boolean?userDefinedBlending
When true doesn’t set the gl.BlendFunc automatically. Defaults to false.

gl.EndText (function)

[source]
gl.EndText() -> nil

gl.Text (function)

[source]
gl.Text(string, number, number, number, string?) -> nil
Parameters
stringtext
numberx
numbery
numbersize
string?options

concatenated string of option characters.

  • horizontal alignment:
  • ‘c’ = center
  • ‘r’ = right
  • vertical alignment:
  • ‘a’ = ascender
  • ’t’ = top
  • ‘v’ = vertical center
  • ‘x’ = baseline
  • ‘b’ = bottom
  • ’d’ = descender
  • decorations:
  • ‘o’ = black outline
  • ‘O’ = white outline
  • ’s’ = shadow
  • other:
  • ’n’ = don’t round vertex coords to nearest integer (font may get blurry)
Returns
nil

gl.GetTextWidth (function)

[source]
gl.GetTextWidth(string) -> number
Parameters
stringtext
Returns
numberwidth

gl.GetTextHeight (function)

[source]
gl.GetTextHeight(string) -> number, number, integer
Parameters
stringtext
Returns
numberheight
numberdescender
integerlines

gl.Unit (function)

Draw the unit, applying transform.

[source]

gl.Unit(integer, boolean?, integer?, boolean?, boolean?) -> nil
Parameters
integerunitID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: false) Skip the DrawUnit callin.
boolean?fullModel
(Default: true)

gl.UnitRaw (function)

Draw the unit without applying transform.

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

[source]

gl.UnitRaw(integer, boolean?, integer?, boolean?, boolean?) -> nil
Parameters
integerunitID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: true) Skip the DrawUnit callin.
boolean?fullModel
(Default: true)

gl.UnitTextures (function)

[source]
gl.UnitTextures(integer, boolean) -> nil
Parameters
integerunitID
booleanpush
If true, push the render state; if false, pop it.

gl.UnitShape (function)

[source]
gl.UnitShape(integer, integer, boolean?, boolean?, boolean?) -> nil
Parameters
integerunitDefID
integerteamID
boolean?rawState
(Default: true)
boolean?toScreen
(Default: false)
boolean?opaque
(Default: true) If true, draw opaque; if false, draw alpha.

gl.UnitShapeTextures (function)

[source]
gl.UnitShapeTextures(integer, boolean) -> nil
Parameters
integerunitDefID
booleanpush
If true, push the render state; if false, pop it.

gl.UnitMultMatrix (function)

[source]
gl.UnitMultMatrix(integer) -> nil
Parameters
integerunitID

gl.UnitPiece (function)

[source]
gl.UnitPiece(integer, integer) -> nil
Parameters
integerunitID
integerpieceID

gl.UnitPieceMatrix (function)

[source]
gl.UnitPieceMatrix(integer, integer) -> nil
Parameters
integerunitID
integerpieceID

gl.UnitPieceMultMatrix (function)

[source]
gl.UnitPieceMultMatrix(integer, integer) -> nil
Parameters
integerunitID
integerpieceID

gl.Feature (function)

Draw the feature, applying transform.

[source]

gl.Feature(integer, boolean?, integer?, boolean?) -> nil
Parameters
integerfeatureID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: false) Skip the DrawFeature callin.

gl.FeatureRaw (function)

Draw the unit without applying transform.

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

[source]

gl.FeatureRaw(integer, boolean?, integer?, boolean?) -> nil
Parameters
integerfeatureID
boolean?doRawDraw
(Default: false)
integer?useLuaMat
boolean?noLuaCall
(Default: true) Skip the DrawFeature callin.

gl.FeatureTextures (function)

[source]
gl.FeatureTextures(integer, boolean) -> nil
Parameters
integerfeatureID
booleanpush
If true, push the render state; if false, pop it.

gl.FeatureShape (function)

[source]
gl.FeatureShape(integer, integer, boolean?, boolean?, boolean?) -> nil
Parameters
integerfeatureDefID
integerteamID
boolean?rawState
(Default: true)
boolean?toScreen
(Default: false)
boolean?opaque
(Default: true) If true, draw opaque; if false, draw alpha.

gl.FeatureShapeTextures (function)

[source]
gl.FeatureShapeTextures(integer, boolean) -> nil
Parameters
integerfeatureDefID
booleanpush
If true, push the render state; if false, pop it.

gl.FeatureMultMatrix (function)

[source]
gl.FeatureMultMatrix(integer) -> nil
Parameters
integerfeatureID

gl.FeaturePiece (function)

[source]
gl.FeaturePiece(integer, integer) -> nil
Parameters
integerfeatureID
integerpieceID

gl.FeaturePieceMatrix (function)

[source]
gl.FeaturePieceMatrix(integer, integer) -> nil
Parameters
integerfeatureID
integerpieceID

gl.FeaturePieceMultMatrix (function)

[source]
gl.FeaturePieceMultMatrix(integer, integer) -> nil
Parameters
integerfeatureID
integerpieceID

gl.DrawListAtUnit (function)

[source]
gl.DrawListAtUnit(integer, integer, boolean?, number?, number?, number?, number?, number?, number?, number?) -> nil
Parameters
integerunitID
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)

[source]
gl.DrawFuncAtUnit(integer, boolean?, unknown, [any, ]*) -> nil
Parameters
integerunitID
boolean?useMidPos
(Default: true)
unknownfun
any...
Arguments passed to function.

gl.DrawGroundCircle (function)

[source]
gl.DrawGroundCircle(number, number, number, number, integer) -> nil
Parameters
numberposX
numberposY
numberposZ
numberradius
integerresolution

gl.DrawGroundCircle (function overload 1)

[source]
gl.DrawGroundCircle(number, number, number, number, integer, number, number, integer) -> nil
Parameters
numberposX
numberposY
numberposZ
numberradius
integerresolution
numberslope
numbergravity
integerweaponDefID

gl.DrawGroundCircle (function overload 2)

[source]
gl.DrawGroundCircle(number, number, number, number, nil, boolean?) -> nil
Parameters
numberx0
numberz0
numberx1
numberz1
niluseNorm
No longer used.
boolean?useTxcd
(Default: false)

gl.DrawGroundCircle (function overload 3)

[source]
gl.DrawGroundCircle(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)

[source]
gl.Shape(GL, VertexData[]) -> nil
Parameters
GLtype
VertexData[]vertices

gl.BeginEnd (function)

[source]
gl.BeginEnd(GL, unknown, [any, ]*) -> nil
Parameters
GLprimMode
unknownfun
any...
Arguments passed to function.

gl.Vertex (function)

[source]
gl.Vertex(xy) -> nil
Parameters
xyv

gl.Vertex (function overload 1)

[source]
gl.Vertex(xyz) -> nil
Parameters
xyzv

gl.Vertex (function overload 2)

[source]
gl.Vertex(xyzw) -> nil
Parameters
xyzwv

gl.Vertex (function overload 3)

[source]
gl.Vertex(number, number, number?, number?) -> nil
Parameters
numberx
numbery
number?z
number?w

gl.Normal (function)

[source]
gl.Normal(xyz) -> nil
Parameters
xyzv

gl.Normal (function overload 1)

[source]
gl.Normal(number, number, number) -> nil
Parameters
numberx
numbery
numberz

gl.TexCoord (function)

[source]
gl.TexCoord((number)) -> nil
Parameters
(number)coord

gl.TexCoord (function overload 1)

[source]
gl.TexCoord(xy) -> nil
Parameters
xycoord

gl.TexCoord (function overload 2)

[source]
gl.TexCoord(xyz) -> nil
Parameters
xyzcoord

gl.TexCoord (function overload 3)

[source]
gl.TexCoord(xyzw) -> nil
Parameters
xyzwcoord

gl.TexCoord (function overload 4)

[source]
gl.TexCoord(number, number?, number?, number?) -> nil
Parameters
numbers
number?t
number?r
number?q

gl.MultiTexCoord (function)

[source]
gl.MultiTexCoord(integer, (number)) -> nil
Parameters
integertexNum
(number)coord

gl.MultiTexCoord (function overload 1)

[source]
gl.MultiTexCoord(integer, xy) -> nil
Parameters
integertexNum
xycoord

gl.MultiTexCoord (function overload 2)

[source]
gl.MultiTexCoord(integer, xyz) -> nil
Parameters
integertexNum
xyzcoord

gl.MultiTexCoord (function overload 3)

[source]
gl.MultiTexCoord(integer, xyzw) -> nil
Parameters
integertexNum
xyzwcoord

gl.MultiTexCoord (function overload 4)

[source]
gl.MultiTexCoord(integer, number, number?, number?, number?) -> nil
Parameters
integertexNum
numbers
number?t
number?r
number?q

gl.SecondaryColor (function)

[source]
gl.SecondaryColor(rgb) -> nil
Parameters
rgbcolor

gl.SecondaryColor (function overload 1)

[source]
gl.SecondaryColor(number, number, number) -> nil
Parameters
numberr
numberg
numberb

gl.FogCoord (function)

[source]
gl.FogCoord(number) -> nil
Parameters
numbercoord

gl.EdgeFlag (function)

[source]
gl.EdgeFlag(boolean) -> nil
Parameters
booleanflag

gl.Rect (function)

[source]
gl.Rect(number, number, number, number) -> nil
Parameters
numberx1
numbery1
numberx2
numbery2

gl.Rect (function overload 1)

[source]
gl.Rect(number, number, number, number, boolean?, boolean?) -> nil
Parameters
numberx1
numbery1
numberx2
numbery2
boolean?flipSCoords
boolean?flipTCoords

gl.Rect (function overload 2)

[source]
gl.Rect(number, number, number, number, number, number, number, number) -> nil
Parameters
numberx1
numbery1
numberx2
numbery2
numbers1
numbert1
numbers2
numbert2

gl.DispatchCompute (function)

[source]
gl.DispatchCompute(integer, integer, integer, integer?) -> nil
Parameters
integernumGroupX
integernumGroupY
integernumGroupZ
integer?barriers
(Default: 4)

gl.MemoryBarrier (function)

[source]
gl.MemoryBarrier(integer?) -> nil
Parameters
integer?barriers
(Default: 4)

gl.Color (function)

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

[source]
gl.Color(rgba) -> nil
Parameters
rgbacolor
Color with alpha.

gl.Color (function overload 2)

[source]
gl.Color(rgb) -> nil
Parameters
rgbcolor
Color.

gl.Material (function)

[source]
gl.Material(Material) -> nil
Parameters
Materialmaterial

gl.ResetState (function)

[source]
gl.ResetState() -> nil

gl.ResetMatrices (function)

[source]
gl.ResetMatrices() -> nil

gl.Lighting (function)

[source]
gl.Lighting(boolean) -> nil
Parameters
booleanenable

gl.ShadeModel (function)

[source]
gl.ShadeModel(GL) -> nil
Parameters
GLmodel

gl.Scissor (function)

[source]
gl.Scissor(boolean) -> nil
Parameters
booleanenable

gl.Scissor (function overload 1)

[source]
gl.Scissor(integer, integer, integer, integer) -> nil
Parameters
integerx
integery
integerw
integerh

gl.Viewport (function)

[source]
gl.Viewport(integer, integer, integer, integer) -> nil
Parameters
integerx
integery
integerw
integerh

gl.ColorMask (function)

Enable or disable writing of frame buffer color components.

[source]

gl.ColorMask(boolean) -> nil
Parameters
booleanrgba

gl.ColorMask (function overload 1)

Enable or disable writing of frame buffer color components.

[source]

gl.ColorMask(boolean, boolean, boolean, boolean) -> nil
Parameters
booleanred
booleangreen
booleanblue
booleanalpha

gl.DepthMask (function)

Enable or disable writing into the depth buffer.

[source]

gl.DepthMask(boolean) -> nil
Parameters
booleanenable

gl.DepthTest (function)

Enable or disable depth test.

[source]

gl.DepthTest(boolean) -> nil
Parameters
booleanenable

gl.DepthTest (function overload 1)

Enable depth test and specify the depth comparison function.

[source]

gl.DepthTest(GL) -> nil
Parameters
GLdepthFunction

gl.DepthClamp (function)

[source]
gl.DepthClamp(boolean) -> nil
Parameters
booleanenable

gl.Culling (function)

[source]
gl.Culling(boolean) -> nil
Parameters
booleanenable

gl.Culling (function overload 1)

Enable culling and set culling mode.

[source]

gl.Culling(GL) -> nil
Parameters
GLmode

gl.LogicOp (function)

[source]
gl.LogicOp(boolean) -> nil
Parameters
booleanenable

gl.LogicOp (function overload 1)

Specify a logical pixel operation for rendering.

[source]

gl.LogicOp(GL) -> nil
Parameters
GLopCode

gl.Fog (function)

[source]
gl.Fog(boolean) -> nil
Parameters
booleanenable

gl.Blending (function)

[source]
gl.Blending(boolean) -> nil
Parameters
booleanenable

gl.Blending (function overload 1)

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

[source]
gl.Blending(GL, GL) -> nil
Parameters
GLsrc
GLdst

gl.BlendEquation (function)

[source]
gl.BlendEquation(GL) -> nil
Parameters
GLmode

gl.BlendFunc (function)

[source]
gl.BlendFunc(GL, GL) -> nil
Parameters
GLsrc
GLdst

gl.BlendEquationSeparate (function)

[source]
gl.BlendEquationSeparate(GL, GL) -> nil
Parameters
GLmodeRGB
GLmodeAlpha

gl.BlendFuncSeparate (function)

[source]
gl.BlendFuncSeparate(GL, GL, GL, GL) -> nil
Parameters
GLsrcRGB
GLdstRGB
GLsrcAlpha
GLdstAlpha

gl.AlphaTest (function)

[source]
gl.AlphaTest(boolean) -> nil
Parameters
booleanenable

gl.AlphaTest (function overload 1)

Specify the alpha test function.

[source]

gl.AlphaTest(GL, number) -> nil
Parameters
GLfunc
numberref

gl.AlphaToCoverage (function)

[source]
gl.AlphaToCoverage(boolean) -> nil
Parameters
booleanenable

gl.PolygonMode (function)

Select polygon rasterization mode.

[source]

gl.PolygonMode(GL, GL) -> nil
Parameters
GLface
GLmode

gl.PolygonOffset (function)

[source]
gl.PolygonOffset(boolean) -> nil
Parameters
booleanenable

gl.PolygonOffset (function overload 1)

[source]
gl.PolygonOffset(number, number) -> nil
Parameters
numberfactor
numberunits

gl.StencilTest (function)

[source]
gl.StencilTest(boolean) -> nil
Parameters
booleanenable

gl.StencilMask (function)

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

[source]

gl.StencilMask(integer) -> nil
Parameters
integermask
Specifies a bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all 1’s.

gl.StencilFunc (function)

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

[source]

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

gl.StencilOp (function)

Set front and back stencil test actions.

[source]

gl.StencilOp(GL, GL, GL) -> nil
Parameters
GLfail
Specifies the action to take when the stencil test fails. Eight symbolic constants are valid: GL.KEEP, GL.ZERO, GL.REPLACE, GL.INCR, GL.INCR_WRAP, GL.DECR, GL.DECR_WRAP, and GL.INVERT. The initial value is GL.KEEP.
GLzfail
Specifies the stencil action when the stencil test passes, but the depth test fails. The initial value is GL.KEEP.
GLzpass
Specifies the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. The initial value is GL.KEEP.

gl.StencilMaskSeparate (function)

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

[source]

gl.StencilMaskSeparate(GL, integer) -> nil
Parameters
GLface
Specifies whether the front and/or back stencil writemask is updated. Three symbolic constants are accepted: GL.FRONT, GL.BACK, and GL.FRONT_AND_BACK. The initial value is GL.FRONT_AND_BACK.
integermask
Specifies a bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all 1’s.

gl.StencilFuncSeparate (function)

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

[source]

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

gl.StencilOpSeparate (function)

Set front and/or back stencil test actions.

[source]

gl.StencilOpSeparate(GL, GL, GL, GL) -> nil
Parameters
GLface
Specifies whether front and/or back stencil state is updated. Three symbolic constants are accepted: GL.FRONT, GL.BACK, and GL.FRONT_AND_BACK. The initial value is GL.FRONT_AND_BACK.
GLfail
Specifies the action to take when the stencil test fails. Eight symbolic constants are valid: GL.KEEP, GL.ZERO, GL.REPLACE, GL.INCR, GL.INCR_WRAP, GL.DECR, GL.DECR_WRAP, and GL.INVERT. The initial value is GL.KEEP.
GLzfail
Specifies the stencil action when the stencil test passes, but the depth test fails. The initial value is GL.KEEP.
GLzpass
Specifies the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. The initial value is GL.KEEP.

gl.LineStipple (function)

[source]
gl.LineStipple(boolean) -> nil
Parameters
booleanenable

gl.LineStipple (function overload 1)

[source]
gl.LineStipple(string) -> nil
Parameters
stringignoredString
The value of this string is ignored, but it still does something.

gl.LineStipple (function overload 2)

[source]
gl.LineStipple(integer, integer, integer?) -> nil
Parameters
integerfactor
integerpattern
integer?shift

gl.LineWidth (function)

[source]
gl.LineWidth(number) -> nil
Parameters
numberwidth

gl.PointSize (function)

[source]
gl.PointSize(number) -> nil
Parameters
numbersize

gl.PointSprite (function)

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

[source]
gl.PointParameter(number, number, number, number?, number?, number?) -> nil
Parameters
numberatten0
numberatten1
numberatten2
number?sizeMin
number?sizeMax
number?sizeFade

gl.Texture (function)

[source]
gl.Texture(integer, boolean?) -> boolean
Parameters
integertexNum
boolean?enable
Returns
boolean

gl.Texture (function overload 1)

[source]
gl.Texture(boolean) -> boolean
Parameters
booleanenable
Returns
boolean

gl.Texture (function overload 2)

[source]
gl.Texture(integer, string) -> boolean
Parameters
integertexNum
stringimage
Returns
boolean

gl.Texture (function overload 3)

[source]
gl.Texture(string) -> boolean
Parameters
stringimage
Returns
boolean

gl.CreateTexture (function)

[source]
gl.CreateTexture(integer, integer, Texture) -> string?
Parameters
integerxsize
integerysize
Texturetexture
Returns
string?texName

gl.CreateTexture (function overload 1)

[source]
gl.CreateTexture(integer, integer, integer, Texture) -> string?
Parameters
integerxsize
integerysize
integerzsize
Texturetexture
Returns
string?texName

gl.ChangeTextureParams (function)

[source]
gl.ChangeTextureParams(string, Texture) -> nil
Parameters
stringtexName
Textureparams

gl.DeleteTexture (function)

[source]
gl.DeleteTexture(string) -> boolean
Parameters
stringtexName
Returns
boolean

gl.DeleteTextureFBO (function)

[source]
gl.DeleteTextureFBO(string) -> boolean
Parameters
stringtexName
Returns
boolean

gl.TextureInfo (function)

[source]
gl.TextureInfo(string) -> TextureInfo
Parameters
stringtexName
Returns
TextureInfotextureInfo

gl.CopyToTexture (function)

[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.RenderToTexture (function)

[source]
gl.RenderToTexture(string, unknown, [any, ]*) -> nil
Parameters
stringtexName
unknownfun
any...
Arguments to the function.

gl.GenerateMipmap (function)

[source]
gl.GenerateMipmap(string) -> nil
Parameters
stringtexName

gl.ActiveTexture (function)

[source]
gl.ActiveTexture(integer, function, [any, ]*) -> nil
Parameters
integertexNum
functionfunc
any...
Arguments to the function.

gl.TextEnv (function)

[source]
gl.TextEnv(GL, GL, number) -> nil
Parameters
GLtarget
GLpname
numbervalue

gl.TextEnv (function overload 1)

[source]
gl.TextEnv(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)

[source]
gl.MultiTexEnv(integer, GL, GL, number) -> nil
Parameters
integertexNum
GLtarget
GLpname
numbervalue

gl.MultiTexEnv (function overload 1)

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

[source]
gl.TexGen(GL, boolean) -> nil
Parameters
GLtarget
booleanstate

gl.TexGen (function overload 1)

[source]
gl.TexGen(GL, GL, number) -> nil
Parameters
GLtarget
GLpname
numbervalue

gl.TexGen (function overload 2)

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

[source]