Lua API

We have recently moved to Lua Language Server for Lua support in IDE. This documentation is generated from its doc export function, which is quite limited. Currently all docs are inluded on a single page, and some information is missing.
In cases where docs seem incomplete (e.g. table and enum definitions), try the “source” link to see if there is more information.
See the Lua Language Server guide for more information.

ActivateGame

function

function ActivateGame()

[source]

Called whenever LuaMenu is on with a game loaded.

ActivateMenu

function

function ActivateMenu()

[source]

Called whenever LuaMenu is on with no game loaded.

ActiveCommandChanged

function

function ActiveCommandChanged(cmdId?: integer, cmdType?: integer)

[source]

Called when a command is issued.

Params

cmdId integer?
cmdType integer?

ActiveUniform

type

[source]

Fields

length integer — The character length of name.
location GL
name string
size integer
type string — String name of GL_* constant.

AddConsoleLine

function

function AddConsoleLine(msg: string, priority: integer)

[source]

Called when text is entered into the console (e.g. Spring.Echo).

Params

msg string
priority integer

AllowBuilderHoldFire

function

function AllowBuilderHoldFire(unitID: integer, unitDefID: integer, action: number)

[source]

Called when a construction unit wants to “use his nano beams”.

-1 Build CMD.REPAIR Repair CMD.RECLAIM Reclaim CMD.RESTORE Restore CMD.RESURRECT Resurrect CMD.CAPTURE Capture

Params

unitID integer
unitDefID integer
action number — one of following:

Returns

boolean actionAllowed

AllowCommand

function

function AllowCommand(unitID: integer, unitDefID: integer, unitTeam: integer, cmdID: integer, cmdParams: number[], cmdOptions: CommandOptions, cmdTag: number, synced: boolean, fromLua: boolean)

[source]

Called when the command is given, before the unit’s queue is altered.

The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.

Params

unitID integer
unitDefID integer
unitTeam integer
cmdID integer
cmdParams number[]
cmdOptions CommandOptions — Parameters for command options
cmdTag number
synced boolean
fromLua boolean

Returns

boolean whether — it should be let into the queue.

AllowDirectUnitControl

function

function AllowDirectUnitControl(unitID: integer, unitDefID: integer, unitTeam: integer, playerID: integer)

[source]

Determines if this unit can be controlled directly in FPS view.

Params

unitID integer
unitDefID integer
unitTeam integer
playerID integer

Returns

boolean allow

AllowDraw

function

function AllowDraw()

[source]

Enables Draw{Genesis,Screen,ScreenPost} callins if true is returned, otherwise they are called once every 30 seconds. Only active when a game isn’t running.

Returns

boolean allowDraw

AllowFeatureBuildStep

function

function AllowFeatureBuildStep(builderID: integer, builderTeam: integer, featureID: integer, featureDefID: integer, part: number)

[source]

Called just before a feature changes its build percentage.

Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and resurrect they are positive. Part is the percentage the feature be built or reclaimed per frame. Eg. for a 30 workertime builder, that’s a build power of 1 per frame. For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically.

Params

builderID integer
builderTeam integer
featureID integer
featureDefID integer
part number

Returns

boolean whether — or not the change is permitted

AllowFeatureCreation

function

function AllowFeatureCreation(featureDefID: integer, teamID: integer, x: number, y: number, z: number)

[source]

Called just before feature is created.

Params

featureDefID integer
teamID integer
x number
y number
z number

Returns

boolean whether — or not the creation is permitted

AllowResourceLevel

function

function AllowResourceLevel(teamID: integer, res: string, level: number)

[source]

Called when a team sets the sharing level of a resource.

Params

teamID integer
res string
level number

Returns

boolean whether — or not the sharing level is permitted

AllowResourceTransfer

function

function AllowResourceTransfer(oldTeamID: integer, newTeamID: integer, res: string, amount: number)

[source]

Called just before resources are transferred between players.

Params

oldTeamID integer
newTeamID integer
res string
amount number

Returns

boolean whether — or not the transfer is permitted.

AllowStartPosition

function

function AllowStartPosition(playerID: integer, teamID: integer, readyState: number, clampedX: number, clampedY: number, clampedZ: number, rawX: number, rawY: number, rawZ: number)

[source]

Whether a start position should be allowed

clamped{X,Y,Z} are the coordinates clamped into start-boxes, raw is where player tried to place their marker.

The readyState can be any one of:

0 - player picked a position, 1 - player clicked ready, 2 - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or 3 - the player failed to load. The default ‘failed to choose’ start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.

Params

playerID integer
teamID integer
readyState number
clampedX number
clampedY number
clampedZ number
rawX number
rawY number
rawZ number

Returns

boolean allow

AllowUnitBuildStep

function

function AllowUnitBuildStep(builderID: integer, builderTeam: integer, unitID: integer, unitDefID: integer, part: number)

[source]

Called just before a unit progresses its build percentage.

Params

builderID integer
builderTeam integer
unitID integer
unitDefID integer
part number

Returns

boolean whether — or not the build makes progress.

AllowUnitCaptureStep

function

function AllowUnitCaptureStep(builderID: integer, builderTeam: integer, unitID: integer, unitDefID: integer, part: number)

[source]

Params

builderID integer
builderTeam integer
unitID integer
unitDefID integer
part number

Returns

boolean whether — or not the capture makes progress.

AllowUnitCloak

function

function AllowUnitCloak(unitID: integer, enemyID?: integer)

[source]

Params

unitID integer
enemyID integer?

Returns

boolean whether — unit is allowed to cloak

AllowUnitCreation

function

function AllowUnitCreation(unitDefID: integer, builderID: integer, builderTeam: integer, x: number, y: number, z: number, facing: number)

[source]

Called just before unit is created.

Params

unitDefID integer
builderID integer
builderTeam integer
x number
y number
z number
facing number

Returns

boolean allow
boolean dropOrder

AllowUnitKamikaze

function

function AllowUnitKamikaze(unitID: integer, targetID: integer)

[source]

Params

unitID integer
targetID integer

Returns

boolean whether — unit is allowed to selfd

AllowUnitTransfer

function

function AllowUnitTransfer(unitID: integer, unitDefID: integer, oldTeam: integer, newTeam: integer, capture: boolean)

[source]

Called just before a unit is transferred to a different team.

Params

unitID integer
unitDefID integer
oldTeam integer
newTeam integer
capture boolean

Returns

boolean whether — or not the transfer is permitted.

AllowUnitTransport

function

function AllowUnitTransport(transporterID: integer, transporterUnitDefID: integer, transporterTeam: integer, transporteeID: integer, transporteeUnitDefID: integer, transporteeTeam: integer)

[source]

Params

transporterID integer
transporterUnitDefID integer
transporterTeam integer
transporteeID integer
transporteeUnitDefID integer
transporteeTeam integer

Returns

boolean whether — or not the transport is allowed

AllowUnitTransportLoad

function

function AllowUnitTransportLoad(transporterID: integer, transporterUnitDefID: integer, transporterTeam: integer, transporteeID: integer, transporteeUnitDefID: integer, transporteeTeam: integer, x: number, y: number, z: number)

[source]

Params

transporterID integer
transporterUnitDefID integer
transporterTeam integer
transporteeID integer
transporteeUnitDefID integer
transporteeTeam integer
x number
y number
z number

Returns

boolean whether — or not the transport load is allowed

AllowUnitTransportUnload

function

function AllowUnitTransportUnload(transporterID: integer, transporterUnitDefID: integer, transporterTeam: integer, transporteeID: integer, transporteeUnitDefID: integer, transporteeTeam: integer, x: number, y: number, z: number)

[source]

Params

transporterID integer
transporterUnitDefID integer
transporterTeam integer
transporteeID integer
transporteeUnitDefID integer
transporteeTeam integer
x number
y number
z number

Returns

boolean whether — or not the transport unload is allowed

AllowWeaponInterceptTarget

function

function AllowWeaponInterceptTarget(interceptorUnitID: integer, interceptorWeaponID: integer, targetProjectileID: integer)

[source]

Controls blocking of a specific intercept target from being considered during an interceptor weapon’s periodic auto-targeting sweep.

Only called for weaponDefIDs registered via Script.SetWatchWeapon.

Params

interceptorUnitID integer
interceptorWeaponID integer
targetProjectileID integer

Returns

boolean allowed

AllowWeaponTarget

function

function AllowWeaponTarget(attackerID: integer, targetID: integer, attackerWeaponNum: integer, attackerWeaponDefID: integer, defPriority: number)

[source]

Controls blocking of a specific target from being considered during a weapon’s periodic auto-targeting sweep.

Params

attackerID integer
targetID integer
attackerWeaponNum integer
attackerWeaponDefID integer
defPriority number

Returns

boolean allowed
number the — new priority for this target (if you don’t want to change it, return defPriority). Lower priority targets are targeted first.

AllowWeaponTargetCheck

function

function AllowWeaponTargetCheck(attackerID: integer, attackerWeaponNum: integer, attackerWeaponDefID: integer)

[source]

Determines if this weapon can automatically generate targets itself. See also commandFire weaponDef tag.

Params

attackerID integer
attackerWeaponNum integer
attackerWeaponDefID integer

Returns

boolean allowCheck
boolean ignoreCheck

AtmosphereParams

type

[source]

Fields

cloudColor rgba — Color quadruple (RGBA)
fogEnd number
fogStart number
skyColor rgba — Color quadruple (RGBA)
sunColor rgba — Color quadruple (RGBA)

BuildOrderBlockedStatus

type

0|1|2|3

[source]

BuildOrderBlockedStatus:
    | 0 -- blocked
    | 1 -- mobile unit on the way
    | 2 -- reclaimable
    | 3 -- open

CMD

table

enum CMD

[source]

CMDTYPE

table

enum CMDTYPE

[source]

COB

table

enum COB

[source]

CameraMode

type

0|1|2|3|4...(+2)

[source]

CameraMode:
    | 0 -- fps
    | 1 -- ta
    | 2 -- spring
    | 3 -- rot
    | 4 -- free
    | 5 -- ov
    | 6 -- dummy

CameraState

type

[source]

Parameters for camera state

Fields

angle number? — Camera rotation angle on X axis (aka tilt/pitch) (ta)
dist number? — Camera distance from the ground (spring)
dx number? — Camera direction vector X
dy number? — Camera direction vector Y
dz number? — Camera direction vector Z
flipped number? — 1 for when south is down, 1 for when north is down (ta)
fov number?
height number? — Camera distance from the ground (ta)
mode 0|1|2|3|4...(+2) — The camera mode
name "dummy"|"fps"|"free"|"ov"|"rot"...(+2) — Highly dependent on the type of the current camera controller
oldHeight number? — Camera distance from the ground, cannot be changed (rot)
px number? — Position X of the ground point in screen center
py number? — Position Y of the ground point in screen center
pz number? — Position Z of the ground point in screen center
rx number? — Camera rotation angle on X axis (spring)
ry number? — Camera rotation angle on Y axis (spring)
rz number? — Camera rotation angle on Z axis (spring)

CameraVectors

type

[source]

Fields

botFrustumPlane xyz — Cartesian triple (XYZ)
forward xyz — Cartesian triple (XYZ)
lftFrustumPlane xyz — Cartesian triple (XYZ)
rgtFrustumPlane xyz — Cartesian triple (XYZ)
right xyz — Cartesian triple (XYZ)
topFrustumPlane xyz — Cartesian triple (XYZ)
up xyz — Cartesian triple (XYZ)

Command

type

[source]

Used when assigning multiple commands at once

Fields

cmdID integer
options CommandOptions? — Parameters for command options
params number[]?

CommandDescription

type

[source]

Command Description

Contains data about a command.

Fields

action string?
cursor string?
disabled boolean?
hidden boolean?
id integer?
name string?
onlyTexture boolean?
params table<string, string>?
queueing boolean?
showUnique boolean?
texture string?
tooltip string?
type integer?

CommandFallback

function

function CommandFallback(unitID: integer, unitDefID: integer, unitTeam: integer, cmdID: integer, cmdParams: number[], cmdOptions: CommandOptions, cmdTag: number)

[source]

Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine).

Params

unitID integer
unitDefID integer
unitTeam integer
cmdID integer
cmdParams number[]
cmdOptions CommandOptions — Parameters for command options
cmdTag number

Returns

boolean whether — to remove the command from the queue

CommandNotify

function

function CommandNotify(cmdID: integer, cmdParams: table, options: CommandOptions)

[source]

Called when a command is issued.

Params

cmdID integer
cmdParams table
options CommandOptions — Parameters for command options

Returns

boolean Returning — true deletes the command and does not send it through the network.

CommandOptions

type

[source]

Parameters for command options

Fields

alt boolean — Alt key pressed
coded integer
ctrl boolean — Ctrl key pressed
internal boolean
meta boolean — Meta key pressed (space)
right boolean — Right mouse key pressed
shift boolean — Shift key pressed

Configuration

type

[source]

Configuration

Contains data about a configuration, only name and type are guaranteed

Fields

declarationFile string
declarationLine string
defaultValue string
description string
maximumValue string
minimumValue string
name string
readOnly boolean
safemodeValue string
type string

ConfigureLayout

function

function ConfigureLayout()

[source]

CreateRBOData

type

[source]

Fields

format GL
samples number? — any number here will result in creation of multisampled RBO
target GL

DefaultCommand

function

function DefaultCommand(type: string, id: integer)

[source]

Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either “unit or “feature”) and the second is its unitID or featureID respectively.

Params

type string — unit
id integer — unitID featureID

DownloadFailed

function

function DownloadFailed(id: number, errorID: number)

[source]

Called when a Pr-downloader download fails to complete.

Params

id number
errorID number

DownloadFinished

function

function DownloadFinished(id: number)

[source]

Called when a Pr-downloader download finishes successfully.

Params

id number

DownloadProgress

function

function DownloadProgress(id: number, downloaded: number, total: number)

[source]

Called incrementally during a Pr-downloader download.

Params

id number
downloaded number
total number

DownloadQueued

function

function DownloadQueued(id: number, name: string, type: string)

[source]

Called when a Pr-downloader download is queued

Params

id number
name string
type string

DownloadStarted

function

function DownloadStarted(id: number)

[source]

Called when a Pr-downloader download is started via VFS.DownloadArchive.

Params

id number

DrawFeature

function

function DrawFeature(featureID: integer, drawMode: number)

[source]

For custom rendering of features

Params

featureID integer
drawMode number

Returns

boolean suppressEngineDraw

DrawFeaturesPostDeferred

function

function DrawFeaturesPostDeferred()

[source]

Runs at the end of the feature deferred pass to inform Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

DrawGenesis

function

function DrawGenesis()

[source]

Use this callin to update textures, shaders, etc.

Doesn’t render to screen! Also available to LuaMenu.

DrawGroundDeferred

function

function DrawGroundDeferred()

[source]

DrawGroundPostDeferred

function

function DrawGroundPostDeferred()

[source]

This runs at the end of its respective deferred pass.

Allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and DrawWorldPreUnit) via gl.CopyToTexture.

DrawGroundPostForward

function

function DrawGroundPostForward()

[source]

DrawGroundPreDeferred

function

function DrawGroundPreDeferred()

[source]

Runs at the start of the deferred pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

DrawGroundPreForward

function

function DrawGroundPreForward()

[source]

Runs at the start of the forward pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

DrawInMiniMap

function

function DrawInMiniMap(sx: number, sy: number)

[source]

Params

sx number — relative to the minimap’s position and scale.
sy number — relative to the minimap’s position and scale.

DrawInMinimapBackground

function

function DrawInMinimapBackground(sx: number, sy: number)

[source]

Params

sx number — relative to the minimap’s position and scale.
sy number — relative to the minimap’s position and scale.

DrawLoadScreen

function

function DrawLoadScreen()

[source]

Draws custom load screens.

DrawMaterial

function

function DrawMaterial(uuid: number, drawMode: number)

[source]

Params

uuid number
drawMode number

Returns

boolean suppressEngineDraw

DrawPreDecals

function

function DrawPreDecals()

[source]

Called before decals are drawn

DrawProjectile

function

function DrawProjectile(projectileID: integer, drawMode: number)

[source]

For custom rendering of weapon (& other) projectiles

Params

projectileID integer
drawMode number

Returns

boolean suppressEngineDraw

DrawScreen

function

function DrawScreen(viewSizeX: number, viewSizeY: number)

[source]

Also available to LuaMenu.

Params

viewSizeX number
viewSizeY number

DrawScreenEffects

function

function DrawScreenEffects(viewSizeX: number, viewSizeY: number)

[source]

Params

viewSizeX number
viewSizeY number

DrawScreenPost

function

function DrawScreenPost(viewSizeX: number, viewSizeY: number)

[source]

Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).

Params

viewSizeX number
viewSizeY number

DrawShadowFeaturesLua

function

function DrawShadowFeaturesLua()

[source]

DrawShadowPassTransparent

function

function DrawShadowPassTransparent()

[source]

Invoked after semi-transparent shadows pass is about to conclude

This callin has depth and color buffer of shadowmap bound via FBO as well as the FFP state to do “semi-transparent” shadows pass (traditionally only used to draw shadows of shadow casting semi-transparent particles). Can be used to draw nice colored shadows.

DrawShadowUnitsLua

function

function DrawShadowUnitsLua()

[source]

DrawShield

function

function DrawShield(featureID: integer, weaponID: integer, drawMode: number)

[source]

For custom rendering of shields.

Params

featureID integer
weaponID integer
drawMode number

Returns

boolean suppressEngineDraw

DrawUnit

function

function DrawUnit(unitID: integer, drawMode: number)

[source]

For custom rendering of units

Params

unitID integer
drawMode number

Returns

boolean suppressEngineDraw

DrawUnitsPostDeferred

function

function DrawUnitsPostDeferred()

[source]

Runs at the end of the unit deferred pass.

Informs Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

DrawWaterPost

function

function DrawWaterPost()

[source]

DrawWorld

function

function DrawWorld()

[source]

Spring draws command queues, ‘map stuff’, and map marks.

DrawWorldPreParticles

function

function DrawWorldPreParticles(drawAboveWater: boolean, drawBelowWater: boolean, drawReflection: boolean, drawRefraction: boolean)

[source]

DrawWorldPreParticles is called multiples times per draw frame. Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction.

Params

drawAboveWater boolean
drawBelowWater boolean
drawReflection boolean
drawRefraction boolean

DrawWorldPreUnit

function

function DrawWorldPreUnit()

[source]

Spring draws units, features, some water types, cloaked units, and the sun.

DrawWorldReflection

function

function DrawWorldReflection()

[source]

DrawWorldRefraction

function

function DrawWorldRefraction()

[source]

DrawWorldShadow

function

function DrawWorldShadow()

[source]

Engine

table

table

[source]

Explosion

function

function Explosion(weaponDefID: number, px: number, py: number, pz: number, attackerID: number, projectileID: number)

[source]

Called when an explosion occurs.

Params

weaponDefID number
px number
py number
pz number
attackerID number
projectileID number

Returns

boolean noGfx — if then no graphical effects are drawn by the engine for this explosion.

ExplosionParams

type

[source]

Parameters for explosion.

Please note the explosion defaults to 1 damage regardless of what it’s defined in the weaponDef. The weapondefID is only used for visuals and for passing into callins like UnitDamaged.

Fields

craterAreaOfEffect number
damageAreaOfEffect number
damageGround boolean
edgeEffectiveness number
explosionSpeed number
gfxMod number
hitFeature number
hitUnit number
ignoreOwner boolean
impactOnly boolean
owner number
weaponDef number

Facing

type

"e"|"east"|"n"|"north"|"s"...(+7)

[source]

Facing:
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | "s" -- South
    | "e" -- East
    | "n" -- North
    | "w" -- West
    | "south" -- South
    | "east" -- East
    | "north" -- North
    | "west" -- West

Fbo

type

[source]

User Data FBO

Fields

color0 attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }
color1 attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }
color15 attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }
color2 attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }
colorn attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }
depth attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }
drawbuffers table — { GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}
readbuffer table — GL_COLOR_ATTACHMENT0_EXT
stencil attachment — attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }

FeatureCreated

function

function FeatureCreated(featureID: number, allyTeamID: number)

[source]

Called when a feature is created.

Params

featureID number
allyTeamID number

FeatureDamaged

function

function FeatureDamaged(featureID: number, featureDefID: number, featureTeam: number, damage: number, weaponDefID: number, projectileID: number, attackerID: number, attackerDefID: number, attackerTeam: number)

[source]

Called when a feature is damaged.

Params

featureID number
featureDefID number
featureTeam number
damage number
weaponDefID number
projectileID number
attackerID number
attackerDefID number
attackerTeam number

FeatureDestroyed

function

function FeatureDestroyed(featureID: number, allyTeamID: number)

[source]

Called when a feature is destroyed.

Params

featureID number
allyTeamID number

FeaturePreDamaged

function

function FeaturePreDamaged(featureID: integer, featureDefID: integer, featureTeam: integer, damage: number, weaponDefID: integer, projectileID: integer, attackerID: integer, attackerDefID: integer, attackerTeam: integer)

[source]

Called before damage is applied to the feature.

Allows fine control over how much damage and impulse is applied.

Params

featureID integer
featureDefID integer
featureTeam integer
damage number
weaponDefID integer
projectileID integer
attackerID integer
attackerDefID integer
attackerTeam integer

Returns

number newDamage
number impulseMult

FeatureSupport

type

[source]

Fields

NegativeGetUnitCurrentCommand boolean
hasExitOnlyYardmaps boolean
rmlUiApiVersion integer

FontsChanged

function

function FontsChanged()

[source]

Called whenever fonts are updated. Signals the game display lists and other caches should be discarded.

Gets called before other Update and Draw callins.

GL

table

enum GL

[source]

GLBufferType

type

GL.ARRAY_BUFFER|GL.ELEMENT_ARRAY_BUFFER|GL.SHADER_STORAGE_BUFFER|GL.UNIFORM_BUFFER

[source]

Game

table

table

[source]

GameFrame

function

function GameFrame(frame: number)

[source]

Called for every game simulation frame (30 per second).

Params

frame number — Starts at frame 1

GameFramePost

function

function GameFramePost(frame: number)

[source]

Called at the end of every game simulation frame

Params

frame number — Starts at frame 1

GameID

function

function GameID(gameID: string)

[source]

Called once to deliver the gameID

Params

gameID string — encoded in hex.

GameOver

function

function GameOver(winningAllyTeams: number[])

[source]

Called when the game ends

Params

winningAllyTeams number[] — list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

GamePaused

function

function GamePaused(playerID: number, paused: boolean)

[source]

Called when the game is paused.

Params

playerID number
paused boolean

GamePreload

function

function GamePreload()

[source]

Called before the 0 gameframe.

Is not called when a saved game is loaded.

GameProgress

function

function GameProgress(serverFrameNum: integer)

[source]

Called every 60 frames, calculating delta between GameFrame and GameProgress.

Can give an ETA about catching up with simulation for mid-game join players.

Params

serverFrameNum integer

GameSetup

function

function GameSetup(state: string, ready: boolean, playerStates: table)

[source]

Params

state string
ready boolean
playerStates table

Returns

boolean success
boolean newReady

GameStart

function

function GameStart()

[source]

Called upon the start of the game.

Is not called when a saved game is loaded.

GetTooltip

function

function GetTooltip(x: number, y: number)

[source]

Called when Spring.IsAbove returns true.

Params

x number
y number

Returns

string tooltip

GotChatMsg

function

function GotChatMsg(msg: string, playerID: number)

[source]

Called when a player issues a UI command e.g. types /foo or /luarules foo.

Params

msg string
playerID number

GroupChanged

function

function GroupChanged(groupID: number)

[source]

Called when a unit is added to or removed from a control group.

Params

groupID number

Initialize

function

function Initialize()

[source]

Called when the addon is (re)loaded.

IsAbove

function

function IsAbove(x: number, y: number)

[source]

Called every Update.

Must return true for Mouse* events and Spring.GetToolTip to be called.

Params

x number
y number

Returns

boolean isAbove

KeyBinding

type

[source]

Keybinding

Contains data about a keybinding

Fields

boundWith string
command string
extra string

KeyMapChanged

function

function KeyMapChanged()

[source]

Called when the keymap changes

Can be caused due to a change in language or keyboard

KeyModifiers

type

[source]

Key Modifier Params

Fields

alt boolean — Alt key pressed
ctrl boolean — Ctrl key pressed
right boolean — Right mouse key pressed
shift boolean — Shift key pressed

KeyPress

function

function KeyPress(keyCode: number, mods: KeyModifiers, isRepeat: boolean, label: boolean, utf32char: number, scanCode: number, actionList: table)

[source]

Called repeatedly when a key is pressed down.

Return true if you don’t want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki.

Params

keyCode number
mods KeyModifiers — Key Modifier Params
isRepeat boolean — If you want an action to occur only once check for isRepeat == false.
label boolean — the name of the key
utf32char number — (deprecated) always 0
scanCode number
actionList table — the list of actions for this keypress

Returns

boolean halt — whether to halt the chain for consumers of the keypress

KeyRelease

function

function KeyRelease(keyCode: number, mods: KeyModifiers, label: boolean, utf32char: number, scanCode: number, actionList: table)

[source]

Called when the key is released.

Params

keyCode number
mods KeyModifiers — Key Modifier Params
label boolean — the name of the key
utf32char number — (deprecated) always 0
scanCode number
actionList table — the list of actions for this keyrelease

Returns

boolean

LightParams

type

[source]

Parameters for lighting

Fields

ambientColor { red: number, green: number, blue: number }
ambientDecayRate { ambientRedDecay: number, ambientGreenDecay: number, ambientBlueDecay: number }
decayFunctionType { ambientDecayType: number, diffuseDecayType: number, specularDecayType: number } — Per-frame decay of specularColor (spread over TTL frames)
diffuseColor { red: number, green: number, blue: number }
diffuseDecayRate { diffuseRedDecay: number, diffuseGreenDecay: number, diffuseBlueDecay: number } — Per-frame decay of ambientColor (spread over TTL frames)
direction { dx: number, dy: number, dz: number }
fov number
ignoreLOS boolean
intensityWeight { ambientWeight: number, diffuseWeight: number, specularWeight: number }
position { px: number, py: number, pz: number }
priority number
radius number — If value is 0.0 then the *DecayRate values will be interpreted as linear, otherwise exponential.
specularColor { red: number, green: number, blue: number }
specularDecayRate { specularRedDecay: number, specularGreenDecay: number, specularBlueDecay: number } — Per-frame decay of diffuseColor (spread over TTL frames)
ttl number

Load

function

function Load(zipReader: table)

[source]

Called after GamePreload and before GameStart. See Lua_SaveLoad.

Params

zipReader table

LoadCode

function

function LoadCode()

[source]

Called when the game is (re)loaded.

LoadProgress

function

function LoadProgress(message: string, replaceLastLine: boolean)

[source]

Params

message string
replaceLastLine boolean

LogLevel

type

integer|"debug"|"deprecated"|"error"|"fatal"...(+3)

[source]

LogLevel:
    | "debug" -- LOG.DEBUG
    | "info" -- LOG.INFO
    | "notice" -- LOG.NOTICE (engine default)
    | "warning" -- LOG.WARNING
    | "deprecated" -- LOG.DEPRECATED
    | "error" -- LOG.ERROR
    | "fatal" -- LOG.FATAL

LuaZipFileReader

type

[source]

LuaZipFileWriter

type

[source]

MapDrawCmd

function

function MapDrawCmd(playerID: number, type: string, posX: number, posY: number, posZ: number, data4: string|number, pos2Y?: number, pos2Z?: number)

[source]

Params

playerID number
type string — point
posX number
posY number
posZ number
data4 string|number — point: label, erase: radius, line: pos2X
pos2Y number? — when type is line
pos2Z number? — when type is line

MapRenderingParams

type

[source]

Map rendering params

Fields

splatDetailNormalDiffuseAlpha boolean
splatTexMults rgba — Color quadruple (RGBA)
splatTexScales rgba — Color quadruple (RGBA)
voidGround boolean
voidWater boolean

MouseMove

function

function MouseMove(x: number, y: number, dx: number, dy: number, button: number)

[source]

Called when the mouse is moved.

Params

x number — final x position
y number — final y position
dx number — distance travelled in x
dy number — distance travelled in y
button number

MousePress

function

function MousePress(x: number, y: number, button: number)

[source]

Called when a mouse button is pressed.

The button parameter supports up to 7 buttons. Must return true for MouseRelease and other functions to be called.

Params

x number
y number
button number

Returns

boolean becomeMouseOwner

MouseRelease

function

function MouseRelease(x: number, y: number, button: number)

[source]

Called when a mouse button is released.

Please note that in order to have Spring call Spring.MouseRelease, you need to have a Spring.MousePress call-in in the same addon that returns true.

Params

x number
y number
button number

Returns

boolean becomeMouseOwner

MouseWheel

function

function MouseWheel(up: boolean, value: number)

[source]

Called when the mouse wheel is moved.

Params

up boolean — the direction
value number — the amount travelled

MoveCtrlNotify

function

function MoveCtrlNotify(unitID: integer, unitDefID: integer, unitTeam: integer, data: number)

[source]

Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.

Params

unitID integer
unitDefID integer
unitTeam integer
data number — was supposed to indicate the type of notification but currently never has a value other than 1 (“unit hit the ground”).

Returns

boolean whether — or not the unit should remain script-controlled (false) or return to engine controlled movement (true).

PieceInfo

type

[source]

Fields

children string[] — names
empty boolean
max [number, number, number] — (x,y,z)
min [number, number, number] — (x,y,z)
name string
offset [number, number, number] — (x,y,z)
parent string

Plane

type

[source]

Fields

d number
normalVecX number
normalVecY number
normalVecZ number

Platform

table

table

[source]

PlayerAdded

function

function PlayerAdded(playerID: number)

[source]

Called whenever a new player joins the game.

Params

playerID number

PlayerChanged

function

function PlayerChanged(playerID: number)

[source]

Called whenever a player’s status changes e.g. becoming a spectator.

Params

playerID number

PlayerRemoved

function

function PlayerRemoved(playerID: number, reason: string)

[source]

Called whenever a player is removed from the game.

Params

playerID number
reason string

ProjectileCreated

function

function ProjectileCreated(proID: number, proOwnerID: number, weaponDefID: number)

[source]

Called when the projectile is created.

Note that weaponDefID is missing if the projectile is spawned as part of a burst, but Spring.GetProjectileDefID and Spring.GetProjectileName still work in callin scope using proID.

Params

proID number
proOwnerID number
weaponDefID number

ProjectileDestroyed

function

function ProjectileDestroyed(proID: number, ownerID: number, proWeaponDefID: number)

[source]

Called when the projectile is destroyed.

Params

proID number
ownerID number
proWeaponDefID number

ProjectileParams

type

[source]

Fields

cegTag string
endAlpha number
error xyz — Cartesian triple (XYZ)
gravity number
maxRange number
model string
owner integer
pos xyz — Cartesian triple (XYZ)
speed xyz — Cartesian triple (XYZ)
spread xyz — Cartesian triple (XYZ)
startAlpha number
team integer
tracking number
ttl number

RBO

type

[source]

User Data RBO

Fields

format GL
samples integer — will return globalRendering->msaaLevel for multisampled RBO or 0 otherwise
target GL
valid boolean
xsize integer
ysize integer

RecvFromSynced

function

function RecvFromSynced(arg1: any, arg2: any, argn: any)

[source]

Receives data sent via SendToUnsynced callout.

Params

arg1 any
arg2 any
argn any

RecvLuaMsg

function

function RecvLuaMsg(msg: string, playerID: number)

[source]

Receives messages from unsynced sent via Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.

Params

msg string
playerID number

RecvSkirmishAIMessage

function

function RecvSkirmishAIMessage(aiTeam: integer, dataStr: string)

[source]

Params

aiTeam integer
dataStr string

RenderUnitDestroyed

function

function RenderUnitDestroyed(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called just before a unit is invalid, after it finishes its death animation.

Params

unitID integer
unitDefID integer
unitTeam integer

ResourceCost

type

[source]

Fields

energy number
metal number

ResourceName

type

"e"|"energy"|"m"|"metal"

[source]

ResourceName:
    | "metal"
    | "energy"
    | "m"
    | "e"

ResourceUsage

type

table<"e"|"energy"|"m"|"metal", number>

[source]

Roster

type

[source]

Roster

Contains data about a player

Fields

allyTeamID integer
cpuUsage number — in order to find the progress, use: cpuUsage&0x1 if it’s PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage»8)*1000 for the progress
name string
pingTime number — if -1, the player is pathfinding
playerID integer
spectator boolean
teamID integer

RulesParams

type

[source]

SFX

table

enum SFX

[source]

Save

function

function Save(zip: table)

[source]

Called when a chat command ‘/save’ or ‘/savegame’ is received.

Params

zip table — a userdatum representing the savegame zip file. See Lua_SaveLoad.

SetWMCaption

function

function SetWMCaption(title: string, titleShort?: string)

[source]

Sets the window title for the process (default: “Spring ").

The shortTitle is displayed in the OS task-bar (default: “Spring ").

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

Params

title string
titleShort string? — (Default: title)

Returns

nil

ShaderParams

type

[source]

Fields

definitions string? — string of shader #defines”
fragment string? — The “Geometry” or Geometry-shader can create new vertices and vertice-stripes from points.
geoInputType integer? — inType
geoOutputType integer? — outType
geoOutputVerts integer? — maxVerts
geometry string? — The “TES” or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader.
tcs string? — The “Vertex” or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc.
tes string? — The “TCS” or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage.
uniform UniformParam<number>? — The “Fragment” or Fragment-shader (sometimes called pixel-Shader) is post processing the already rendered picture (for example drawing stars on the sky).

Remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed.

uniformFloat UniformParam<number>?
uniformInt UniformParam<integer>?
uniformMatrix UniformParam<number>?
vertex string?

ShieldPreDamaged

function

function ShieldPreDamaged(projectileID: integer, projectileOwnerID: integer, shieldWeaponNum: integer, shieldCarrierID: integer, bounceProjectile: boolean, beamEmitterWeaponNum: integer, beamEmitterUnitID: integer, startX: number, startY: number, startZ: number, hitX: number, hitY: number, hitZ: number)

[source]

Called before any engine shield-vs-projectile logic executes.

If the weapon is a hitscan type (BeamLaser or LightningCanon) then proID is nil and beamEmitterWeaponNum and beamEmitterUnitID are populated instead.

Params

projectileID integer
projectileOwnerID integer
shieldWeaponNum integer
shieldCarrierID integer
bounceProjectile boolean
beamEmitterWeaponNum integer
beamEmitterUnitID integer
startX number
startY number
startZ number
hitX number
hitY number
hitZ number

Returns

boolean if — true the gadget handles the collision event and the engine does not remove the projectile

Shutdown

function

function Shutdown()

[source]

Called when the addon or the game is shutdown.

Returns

nil

SideSpec

type

[source]

Side spec

Fields

caseName string
sideName string — Used when returning arrays of side specifications, is itself an array with positional values as below:
startUnit string

SoundChannel

type

"battle"|"general"|"sfx"|"ui"|"unitreply"...(+6)

[source]

SoundChannel:
    | "general" -- 0
    | "battle" -- Same as `"sfx" | 1`
    | "sfx" -- Same as `"battle" | 1`
    | "unitreply" -- Same as `"voice" | 2`
    | "voice" -- Same as `"unitreply" | 2`
    | "userinterface" -- Same as "ui" | 3`
    | "ui" -- Same as "userinterface" | 3`
    | 0 -- General
    | 1 -- SFX
    | 2 -- Voice
    | 3 -- User interface

SoundDeviceSpec

type

[source]

Fields

name string — Contains data about a sound device.

Spring.AddGrass

function

function Spring.AddGrass(x: number, z: number)

[source]

Params

x number
z number

Returns

nil

Spring.AddHeightMap

function

function Spring.AddHeightMap(x: number, z: number, height: number)

[source]

Can only be called in Spring.SetHeightMapFunc

Params

x number
z number
height number

Returns

integer? newHeight

Spring.AddLightTrackingTarget

function

function Spring.AddLightTrackingTarget()

[source]

Spring.AddMapLight

function

function Spring.AddMapLight(lightParams: LightParams)

[source]

requires MaxDynamicMapLights > 0

Params

lightParams LightParams — Parameters for lighting

Returns

integer lightHandle

Spring.AddModelLight

function

function Spring.AddModelLight(lightParams: LightParams)

[source]

requires MaxDynamicMapLights > 0

Params

lightParams LightParams — Parameters for lighting

Returns

number lightHandle

Spring.AddObjectDecal

function

function Spring.AddObjectDecal(unitID: integer)

[source]

Params

unitID integer

Returns

nil

Spring.AddOriginalHeightMap

function

function Spring.AddOriginalHeightMap(x: number, y: number, height: number)

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

Params

x number
y number
height number

Returns

nil

Spring.AddSmoothMesh

function

function Spring.AddSmoothMesh(x: number, z: number, height: number)

[source]

Can only be called in Spring.SetSmoothMeshFunc.

Params

x number
z number
height number

Returns

number? The — new height, or nil if coordinates are invalid.

Spring.AddTeamResource

function

function Spring.AddTeamResource(teamID: integer, type: "e"|"energy"|"m"|"metal", amount: number)

[source]

Adds metal or energy resources to the specified team.

type:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

teamID integer
type "e"|"energy"|"m"|"metal"
amount number

Returns

nil

Spring.AddUnitDamage

function

function Spring.AddUnitDamage(unitID: integer, damage: number, paralyze?: number, attackerID?: integer, weaponID?: integer, impulseX?: number, impulseY?: number, impulseZ?: number)

[source]

Params

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

Returns

nil

Spring.AddUnitExperience

function

function Spring.AddUnitExperience(unitID: integer, deltaExperience: number)

[source]

See:

Params

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

Returns

nil

Spring.AddUnitIcon

function

function Spring.AddUnitIcon(iconName: string, texFile: string, size?: number, dist?: number, radAdjust?: number)

[source]

Params

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

Returns

boolean added

Spring.AddUnitImpulse

function

function Spring.AddUnitImpulse(unitID: integer, x: number, y: number, z: number, decayRate?: number)

[source]

Params

unitID integer
x number
y number
z number
decayRate number?

Returns

nil

Spring.AddUnitResource

function

function Spring.AddUnitResource(unitID: integer, resource: string, amount: number)

[source]

Params

unitID integer
resource string — m
amount number

Returns

nil

Spring.AddUnitSeismicPing

function

function Spring.AddUnitSeismicPing(unitID: integer, pindSize: number)

[source]

Params

unitID integer
pindSize number

Returns

nil

Spring.AddWorldIcon

function

function Spring.AddWorldIcon(cmdID: integer, posX: number, posY: number, posZ: number)

[source]

Params

cmdID integer
posX number
posY number
posZ number

Returns

nil

Spring.AddWorldText

function

function Spring.AddWorldText(text: string, posX: number, posY: number, posZ: number)

[source]

Params

text string
posX number
posY number
posZ number

Returns

nil

Spring.AddWorldUnit

function

function Spring.AddWorldUnit(unitDefID: integer, posX: number, posY: number, posZ: number, teamID: integer, facing: number)

[source]

Params

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

Returns

nil

Spring.AdjustHeightMap

function

function Spring.AdjustHeightMap(x1: number, y1: number, x2_height: number, y2?: number, height?: number)

[source]

Add a certain height to a point or rectangle area on the world

Params

x1 number
y1 number
x2_height number — if y2 and height are nil then this parameter is the height
y2 number?
height number?

Returns

nil

Spring.AdjustOriginalHeightMap

function

function Spring.AdjustOriginalHeightMap(x1: number, y1: number, x2_height: number, y2?: number, height?: number)

[source]

Add height to a point or rectangle area to the original map height cache

Params

x1 number
y1 number
x2_height number — if y2 and height are nil then this parameter is the height
y2 number?
height number?

Returns

nil

Spring.AdjustSmoothMesh

function

function Spring.AdjustSmoothMesh(x1: number, z1: number, x2?: number, z2?: number, height: number)

[source]

Params

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

Returns

nil

Spring.AreHelperAIsEnabled

function

function Spring.AreHelperAIsEnabled()

[source]

Returns

boolean enabled

Spring.ArePlayersAllied

function

function Spring.ArePlayersAllied(playerID1: number, playerID2: number)

[source]

Params

playerID1 number
playerID2 number

Returns

boolean|nil

Spring.AreTeamsAllied

function

function Spring.AreTeamsAllied(teamID1: number, teamID2: number)

[source]

Params

teamID1 number
teamID2 number

Returns

boolean|nil

Spring.AssignMouseCursor

function

function Spring.AssignMouseCursor(cmdName: string, iconFileName: string, overwrite?: boolean, hotSpotTopLeft?: boolean)

[source]

Changes/creates the cursor of a single CursorCmd.

Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack

Params

cmdName string
iconFileName string — not the full filename, instead it is like this:
overwrite boolean? — (Default: true)
hotSpotTopLeft boolean? — (Default: false)

Returns

boolean? assigned

Spring.AssignPlayerToTeam

function

function Spring.AssignPlayerToTeam(playerID: integer, teamID: integer)

[source]

Assigns a player to a team.

Params

playerID integer
teamID integer

Returns

nil

Spring.BuggerOff

function

function Spring.BuggerOff(x: number, y: number, z?: number, radius: number, teamID: integer, spherical?: boolean, forced?: boolean, excludeUnitID?: integer, excludeUnitDefIDs?: number[])

[source]

Params

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

Returns

nil

Spring.CallCOBScript

function

function Spring.CallCOBScript(unitID: integer, funcName?: string|integer, retArgs: integer, ...any)

[source]

Params

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

Returns

number …

Spring.ClearFeaturesPreviousDrawFlag

function

function Spring.ClearFeaturesPreviousDrawFlag()

[source]

Returns

nil

Spring.ClearUnitGoal

function

function Spring.ClearUnitGoal(unitID: integer)

[source]

Params

unitID integer

Returns

nil

Spring.ClearUnitsPreviousDrawFlag

function

function Spring.ClearUnitsPreviousDrawFlag()

[source]

Returns

nil

Spring.ClearWatchDogTimer

function

function Spring.ClearWatchDogTimer(threadName?: string)

[source]

Params

threadName string? — (Default: main)

Returns

nil

Spring.ClosestBuildPos

function

function Spring.ClosestBuildPos(teamID: integer, unitDefID: integer, posX: number, posY: number, posZ: number, searchRadius: number, minDistance: number, buildFacing: number)

[source]

Params

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

Returns

number buildPosX
number buildPosY
number buildPosZ

Spring.CreateDir

function

function Spring.CreateDir(path: string)

[source]

Params

path string

Returns

boolean? dirCreated

Spring.CreateFeature

function

function Spring.CreateFeature(featureDef: string|number, x: number, y: number, z: number, heading?: number, AllyTeamID?: integer, featureID?: integer)

[source]

Params

featureDef string|number — name or id
x number
y number
z number
heading number?
AllyTeamID integer?
featureID integer?

Returns

number featureID

Spring.CreateGroundDecal

function

function Spring.CreateGroundDecal()

[source]

Returns

number|nil decalID

Spring.CreateUnit

function

function Spring.CreateUnit(unitDefName: string|number, x: number, y: number, z: number, facing: "e"|"east"|"n"|"north"|"s"...(+7), teamID: integer, build?: boolean, flattenGround?: boolean, unitID?: integer, builderID?: integer)

[source]

Offmap positions are clamped! Use MoveCtrl to move to such positions.

facing:
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | "s" -- South
    | "e" -- East
    | "n" -- North
    | "w" -- West
    | "south" -- South
    | "east" -- East
    | "north" -- North
    | "west" -- West

See: Spring.DestroyUnit

Params

unitDefName string|number — or unitDefID
x number
y number
z number
facing "e"|"east"|"n"|"north"|"s"...(+7)
teamID integer
build boolean? — (Default: false) the unit is created in “being built” state with buildProgress = 0
flattenGround boolean? — (Default: true) the unit flattens ground, if it normally does so
unitID integer? — requests specific unitID
builderID integer?

Returns

number|nil unitID — meaning unit was created

Spring.DeleteProjectile

function

function Spring.DeleteProjectile(projectileID: integer)

[source]

Silently removes projectiles (no explosion).

Params

projectileID integer

Returns

nil

Spring.DeselectUnit

function

function Spring.DeselectUnit(unitID: integer)

[source]

Params

unitID integer

Returns

nil

Spring.DeselectUnitArray

function

function Spring.DeselectUnitArray(unitIDs: table<any, integer>)

[source]

Deselects multiple units.

Params

unitIDs table<any, integer> — Table with unit IDs as value.

Returns

nil

Spring.DeselectUnitMap

function

function Spring.DeselectUnitMap(unitMap: table<integer, any>)

[source]

Deselects multiple units.

Params

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

Returns

nil

Spring.DestroyFeature

function

function Spring.DestroyFeature(featureDefID: integer)

[source]

Params

featureDefID integer

Returns

nil

Spring.DestroyGroundDecal

function

function Spring.DestroyGroundDecal(decalID: integer)

[source]

Params

decalID integer

Returns

boolean delSuccess

Spring.DestroyUnit

function

function Spring.DestroyUnit(unitID: integer, selfd?: boolean, reclaimed?: boolean, attackerID?: integer, cleanupImmediately?: boolean)

[source]

See: Spring.CreateUnit

Params

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

Returns

nil

Spring.DiffTimers

function

function Spring.DiffTimers(endTimer: integer, startTimer: integer, returnMs?: boolean, fromMicroSecs?: boolean)

[source]

Params

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

Returns

number timeAmount

Spring.DrawUnitCommands

function

function Spring.DrawUnitCommands(unitID: integer)

[source]

Params

unitID integer

Returns

nil

Spring.Echo

function

function Spring.Echo(arg: any, ...any)

[source]

Useful for debugging.

Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

Params

arg any
… any

Returns

nil

Spring.EditUnitCmdDesc

function

function Spring.EditUnitCmdDesc(unitID: integer, cmdDescID: integer, cmdArray: CommandDescription)

[source]

Params

unitID integer
cmdDescID integer
cmdArray CommandDescription — Command Description

Contains data about a command.

Spring.ExtractModArchiveFile

function

function Spring.ExtractModArchiveFile(modfile: string)

[source]

Params

modfile string

Returns

boolean extracted

Spring.FindUnitCmdDesc

function

function Spring.FindUnitCmdDesc(unitID: integer)

[source]

Params

unitID integer

Spring.FixedAllies

function

function Spring.FixedAllies()

[source]

Returns

boolean|nil enabled

Spring.ForceLayoutUpdate

function

function Spring.ForceLayoutUpdate()

[source]

Returns

nil

Spring.ForceTesselationUpdate

function

function Spring.ForceTesselationUpdate(normal?: boolean, shadow?: boolean)

[source]

Params

normal boolean? — (Default: true)
shadow boolean? — (Default: false)

Returns

boolean updated

Spring.ForceUnitCollisionUpdate

function

function Spring.ForceUnitCollisionUpdate(unitID: integer)

[source]

Prevent collision checks from working on outdated data

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

Params

unitID integer

Returns

nil

Spring.FreeUnitIcon

function

function Spring.FreeUnitIcon(iconName: string)

[source]

Params

iconName string

Returns

boolean? freed

Spring.GameOver

function

function Spring.GameOver(allyTeamID1?: number, allyTeamID2?: number, allyTeamIDn?: number)

[source]

Will declare game over.

A list of winning allyteams can be passed, if undecided (like when dropped from the host) it should be empty (no winner), in the case of a draw with multiple winners, all should be listed.

Params

allyTeamID1 number?
allyTeamID2 number?
allyTeamIDn number?

Returns

nil

Spring.GarbageCollectCtrl

function

function Spring.GarbageCollectCtrl(itersPerBatch?: integer, numStepsPerIter?: integer, minStepsPerIter?: integer, maxStepsPerIter?: integer, minLoopRunTime?: number, maxLoopRunTime?: number, baseRunTimeMult?: number, baseMemLoadMult?: number)

[source]

Params

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

Returns

nil

Spring.GetAIInfo

function

function Spring.GetAIInfo(teamID: integer)

[source]

Params

teamID integer

Returns

number skirmishAIID
string name
number hostingPlayerID
string shortName — when synced “SYNCED_NOSHORTNAME”, otherwise the AI shortname or “UNKNOWN”
string version — when synced “SYNCED_NOVERSION”, otherwise the AI version or “UNKNOWN”
table<string, string> options

Spring.GetActionHotKeys

function

function Spring.GetActionHotKeys(actionName: string)

[source]

Params

actionName string

Returns

string[]? hotkeys

Spring.GetActiveCmdDesc

function

function Spring.GetActiveCmdDesc(cmdIndex: integer)

[source]

Params

cmdIndex integer

Returns

CommandDescription?

Spring.GetActiveCmdDescs

function

function Spring.GetActiveCmdDescs()

[source]

Returns

CommandDescription[] cmdDescs

Spring.GetActiveCommand

function

function Spring.GetActiveCommand()

[source]

Returns

number? cmdIndex
number? cmdID
number? cmdType
string|nil cmdName

Spring.GetActivePage

function

function Spring.GetActivePage()

[source]

Returns

number activePage
number maxPage

Spring.GetAllFeatures

function

function Spring.GetAllFeatures()

[source]

Spring.GetAllGroundDecals

function

function Spring.GetAllGroundDecals()

[source]

Returns

number[] decalIDs

Spring.GetAllUnits

function

function Spring.GetAllUnits()

[source]

Get a list of all unitIDs

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

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

See: ~UnsyncedRead.GetVisibleUnits~

Returns

number[] unitIDs

Spring.GetAllyTeamInfo

function

function Spring.GetAllyTeamInfo(allyTeamID: integer)

[source]

Params

allyTeamID integer

Returns

table<string, string>|nil

Spring.GetAllyTeamList

function

function Spring.GetAllyTeamList()

[source]

Returns

number[] list — of allyTeamIDs

Spring.GetAllyTeamStartBox

function

function Spring.GetAllyTeamStartBox(allyID: integer)

[source]

Params

allyID integer

Returns

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

Spring.GetBoxSelectionByEngine

function

function Spring.GetBoxSelectionByEngine()

[source]

Get if selection box is handled by engine

See:

Returns

boolean when — true engine won’t select units inside selection box when released

Spring.GetBuildFacing

function

function Spring.GetBuildFacing()

[source]

buildFacing:
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | "s" -- South
    | "e" -- East
    | "n" -- North
    | "w" -- West
    | "south" -- South
    | "east" -- East
    | "north" -- North
    | "west" -- West

Returns

"e"|"east"|"n"|"north"|"s"...(+7) buildFacing

Spring.GetBuildSpacing

function

function Spring.GetBuildSpacing()

[source]

Returns

number buildSpacing

Spring.GetCEGID

function

function Spring.GetCEGID()

[source]

Spring.GetCOBScriptID

function

function Spring.GetCOBScriptID(unitID: integer, funcName: string)

[source]

Params

unitID integer
funcName string

Returns

integer? funcID

Spring.GetCameraDirection

function

function Spring.GetCameraDirection()

[source]

Returns

number dirX
number dirY
number dirZ

Spring.GetCameraFOV

function

function Spring.GetCameraFOV()

[source]

Returns

number vFOV
number hFOV

Spring.GetCameraNames

function

function Spring.GetCameraNames()

[source]

Get available cameras.

Returns

table<string, number> Table — where where keys are names and values are indices.

Spring.GetCameraPosition

function

function Spring.GetCameraPosition()

[source]

Returns

number posX
number posY
number posZ

Spring.GetCameraRotation

function

function Spring.GetCameraRotation()

[source]

Returns

number rotX — in radians
number rotY — in radians
number rotZ — in radians

Spring.GetCameraState

function

function Spring.GetCameraState(useReturns: false)

[source]

useReturns:
    | false

Params

useReturns false

Returns

CameraState cameraState

Spring.GetCameraVectors

function

function Spring.GetCameraVectors()

[source]

Returns

CameraVectors

Spring.GetClipboard

function

function Spring.GetClipboard()

[source]

Returns

string text

Spring.GetCmdDescIndex

function

function Spring.GetCmdDescIndex(cmdID: integer)

[source]

Params

cmdID integer

Returns

integer? cmdDescIndex

Spring.GetCommandQueue

function

function Spring.GetCommandQueue(unitID: integer, count: integer)

[source]

Get the commands for a unit.

Same as Spring.GetUnitCommands

Params

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

Returns

Command[] commands

Spring.GetConfigFloat

function

function Spring.GetConfigFloat(name: string, default?: number)

[source]

Params

name string
default number? — (Default: 0)

Returns

number? configFloat

Spring.GetConfigInt

function

function Spring.GetConfigInt(name: string, default?: number)

[source]

Params

name string
default number? — (Default: 0)

Returns

number? configInt

Spring.GetConfigParams

function

function Spring.GetConfigParams()

[source]

Returns

Configuration[]

Spring.GetConfigString

function

function Spring.GetConfigString(name: string, default?: string)

[source]

Params

name string
default string? — (Default: "")

Returns

number? configString

Spring.GetConsoleBuffer

function

function Spring.GetConsoleBuffer(maxLines: number)

[source]

Params

maxLines number

Returns

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

Spring.GetCurrentTooltip

function

function Spring.GetCurrentTooltip()

[source]

Returns

string tooltip

Spring.GetDecalQuadPos

function

function Spring.GetDecalQuadPos(decalID: integer)

[source]

Params

decalID integer

Returns

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

Spring.GetDecalTextures

function

function Spring.GetDecalTextures(isMainTex?: boolean)

[source]

Params

isMainTex boolean? — (Default: true) If false, it gets the texture for normals/glow maps

Returns

string[] textureNames — All textures on the atlas and available for use in SetGroundDecalTexture

Spring.GetDefaultCommand

function

function Spring.GetDefaultCommand()

[source]

Returns

number? cmdIndex
number? cmdID
number? cmdType
string|nil cmdName

Spring.GetDrawFrame

function

function Spring.GetDrawFrame()

[source]

Returns

number low_16bit
number high_16bit

Spring.GetDrawSeconds

function

function Spring.GetDrawSeconds()

[source]

Returns

integer Time — in seconds

Spring.GetDrawSelectionInfo

function

function Spring.GetDrawSelectionInfo()

[source]

Returns

boolean

Spring.GetDualViewGeometry

function

function Spring.GetDualViewGeometry()

[source]

Get dual view geometry (minimap when enabled)

Returns

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

Spring.GetFPS

function

function Spring.GetFPS()

[source]

Returns

number fps

Spring.GetFacingFromHeading

function

function Spring.GetFacingFromHeading(heading: number)

[source]

Params

heading number

Returns

number facing

Spring.GetFactoryBuggerOff

function

function Spring.GetFactoryBuggerOff(unitID: integer)

[source]

Params

unitID integer

Spring.GetFactoryCommands

function

function Spring.GetFactoryCommands(unitID: integer, count: number)

[source]

Get the number or list of commands for a factory

Params

unitID integer
count number — when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise

Returns

number|Command[] commands

Spring.GetFactoryCounts

function

function Spring.GetFactoryCounts(unitID: integer, count?: integer, addCmds?: boolean)

[source]

Gets the build queue of a factory

Params

unitID integer
count integer? — (Default: -1) Number of commands to retrieve, -1 for all.
addCmds boolean? — (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.GetFeatureAllyTeam

function

function Spring.GetFeatureAllyTeam(featureID: integer)

[source]

Params

featureID integer

Returns

number?

Spring.GetFeatureAlwaysUpdateMatrix

function

function Spring.GetFeatureAlwaysUpdateMatrix(featureID: integer)

[source]

Params

featureID integer

Returns

boolean? nil — when featureID cannot be parsed

Spring.GetFeatureBlocking

function

function Spring.GetFeatureBlocking(featureID: integer)

[source]

Params

featureID integer

Returns

boolean|nil isBlocking
boolean isSolidObjectCollidable
boolean isProjectileCollidable
boolean isRaySegmentCollidable
boolean crushable
boolean blockEnemyPushing
boolean blockHeightChanges

Spring.GetFeatureCollisionVolumeData

function

function Spring.GetFeatureCollisionVolumeData(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeatureDefID

function

function Spring.GetFeatureDefID(featureID: integer)

[source]

Params

featureID integer

Returns

number?

Spring.GetFeatureDirection

function

function Spring.GetFeatureDirection(featureID: integer)

[source]

Params

featureID integer

Returns

number? dirX
number? dirY
number? dirZ

Spring.GetFeatureDrawFlag

function

function Spring.GetFeatureDrawFlag(featureID: integer)

[source]

Params

featureID integer

Returns

number? nil — when featureID cannot be parsed

Spring.GetFeatureEngineDrawMask

function

function Spring.GetFeatureEngineDrawMask(featureID: integer)

[source]

Params

featureID integer

Returns

boolean? nil — when featureID cannot be parsed

Spring.GetFeatureHeading

function

function Spring.GetFeatureHeading(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeatureHealth

function

function Spring.GetFeatureHealth(featureID: integer)

[source]

Params

featureID integer

Returns

number? health
number defHealth
number resurrectProgress

Spring.GetFeatureHeight

function

function Spring.GetFeatureHeight(featureID: integer)

[source]

Params

featureID integer

Returns

number?

Spring.GetFeatureLastAttackedPiece

function

function Spring.GetFeatureLastAttackedPiece(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeatureLuaDraw

function

function Spring.GetFeatureLuaDraw(featureID: integer)

[source]

Params

featureID integer

Returns

boolean? nil — when featureID cannot be parsed

Spring.GetFeatureMass

function

function Spring.GetFeatureMass(featureID: integer)

[source]

Params

featureID integer

Returns

number?

Spring.GetFeatureNoDraw

function

function Spring.GetFeatureNoDraw(featureID: integer)

[source]

Params

featureID integer

Returns

boolean? nil — when featureID cannot be parsed

Spring.GetFeatureNoSelect

function

function Spring.GetFeatureNoSelect(featureID: integer)

[source]

Params

featureID integer

Returns

boolean|nil

Spring.GetFeaturePieceCollisionVolumeData

function

function Spring.GetFeaturePieceCollisionVolumeData(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeaturePieceDirection

function

function Spring.GetFeaturePieceDirection(featureID: integer, pieceIndex: integer)

[source]

Params

featureID integer
pieceIndex integer

Returns

number|nil dirX
number dirY
number dirZ

Spring.GetFeaturePieceInfo

function

function Spring.GetFeaturePieceInfo(featureID: integer, pieceIndex: integer)

[source]

Params

featureID integer
pieceIndex integer

Returns

PieceInfo? pieceInfo

Spring.GetFeaturePieceList

function

function Spring.GetFeaturePieceList(featureID: integer)

[source]

Params

featureID integer

Returns

string[] pieceNames

Spring.GetFeaturePieceMap

function

function Spring.GetFeaturePieceMap(featureID: integer)

[source]

Params

featureID integer

Returns

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

Spring.GetFeaturePieceMatrix

function

function Spring.GetFeaturePieceMatrix(featureID: integer)

[source]

Params

featureID integer

Returns

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

Spring.GetFeaturePiecePosDir

function

function Spring.GetFeaturePiecePosDir(featureID: integer, pieceIndex: integer)

[source]

Params

featureID integer
pieceIndex integer

Returns

number|nil posX
number posY
number posZ
number dirX
number dirY
number dirZ

Spring.GetFeaturePiecePosition

function

function Spring.GetFeaturePiecePosition(featureID: integer, pieceIndex: integer)

[source]

Params

featureID integer
pieceIndex integer

Returns

number|nil posX
number posY
number posZ

Spring.GetFeaturePosition

function

function Spring.GetFeaturePosition(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeatureRadius

function

function Spring.GetFeatureRadius(featureID: integer)

[source]

Params

featureID integer

Returns

number?

Spring.GetFeatureResources

function

function Spring.GetFeatureResources(featureID: integer)

[source]

Params

featureID integer

Returns

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

Spring.GetFeatureResurrect

function

function Spring.GetFeatureResurrect(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeatureRootPiece

function

function Spring.GetFeatureRootPiece(featureID: integer)

[source]

Params

featureID integer

Returns

number index — of the root piece

Spring.GetFeatureRotation

function

function Spring.GetFeatureRotation(featureID: integer)

[source]

Params

featureID integer

Returns

number? pitch — Rotation in X axis
number? yaw — Rotation in Y axis
number? roll — Rotation in Z axis

Spring.GetFeatureRulesParam

function

function Spring.GetFeatureRulesParam(featureID: integer, ruleRef: string|number)

[source]

Params

featureID integer
ruleRef string|number — the rule index or name

Returns

string|number|nil value

Spring.GetFeatureRulesParams

function

function Spring.GetFeatureRulesParams(featureID: integer)

[source]

Params

featureID integer

Returns

RulesParams rulesParams — map with rules names as key and values as values

Spring.GetFeatureSelectionVolumeData

function

function Spring.GetFeatureSelectionVolumeData(featureID: integer)

[source]

Params

featureID integer

Returns

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

Spring.GetFeatureSeparation

function

function Spring.GetFeatureSeparation(featureID1: number, featureID2: number, direction?: boolean)

[source]

Params

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

Returns

number?

Spring.GetFeatureTeam

function

function Spring.GetFeatureTeam(featureID: integer)

[source]

Params

featureID integer

Returns

number?

Spring.GetFeatureTransformMatrix

function

function Spring.GetFeatureTransformMatrix(featureID: integer)

[source]

Params

featureID integer

Returns

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

Spring.GetFeatureVelocity

function

function Spring.GetFeatureVelocity(featureID: integer)

[source]

Params

featureID integer

Spring.GetFeaturesInCylinder

function

function Spring.GetFeaturesInCylinder(x: number, z: number, radius: number, allegiance?: number)

[source]

Params

x number
z number
radius number
allegiance number?

Returns

number[] featureIDs

Spring.GetFeaturesInRectangle

function

function Spring.GetFeaturesInRectangle(xmin: number, zmin: number, xmax: number, zmax: number)

[source]

Params

xmin number
zmin number
xmax number
zmax number

Returns

number[] featureIDs

Spring.GetFeaturesInScreenRectangle

function

function Spring.GetFeaturesInScreenRectangle(left: number, top: number, right: number, bottom: number)

[source]

Get features inside a rectangle area on the map

Params

left number
top number
right number
bottom number

Returns

number[]|nil featureIDs

Spring.GetFeaturesInSphere

function

function Spring.GetFeaturesInSphere(x: number, y: number, z: number, radius: number)

[source]

Params

x number
y number
z number
radius number

Returns

number[] featureIDs

Spring.GetFrameTimeOffset

function

function Spring.GetFrameTimeOffset()

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

Returns

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

Spring.GetFrameTimer

function

function Spring.GetFrameTimer(lastFrameTime?: boolean)

[source]

Get a timer for the start of the frame

This should give better results for camera interpolations

Params

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

Returns

integer

Spring.GetFullBuildQueue

function

function Spring.GetFullBuildQueue(unitID: integer)

[source]

Returns the build queue

Params

unitID integer

Returns

table<number, number>|nil buildqueue — indexed by unitDefID with count values

Spring.GetGaiaTeamID

function

function Spring.GetGaiaTeamID()

[source]

Returns

number teamID

Spring.GetGameFrame

function

function Spring.GetGameFrame()

[source]

Returns

number t1 — frameNum % dayFrames
number t2 — frameNum / dayFrames

Spring.GetGameName

function

function Spring.GetGameName()

[source]

Returns

string name

Spring.GetGameRulesParam

function

function Spring.GetGameRulesParam(ruleRef: string|number)

[source]

Params

ruleRef string|number — the rule index or name

Returns

number? — string value

Spring.GetGameRulesParams

function

function Spring.GetGameRulesParams()

[source]

Returns

RulesParams rulesParams — map with rules names as key and values as values

Spring.GetGameSeconds

function

function Spring.GetGameSeconds()

[source]

Returns

number seconds

Spring.GetGameSpeed

function

function Spring.GetGameSpeed()

[source]

Returns

number wantedSpeedFactor
number speedFactor
boolean paused

Spring.GetGameState

function

function Spring.GetGameState(maxLatency?: number)

[source]

Params

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

Returns

boolean doneLoading
boolean isSavedGame
boolean isClientPaused
boolean isSimLagging

Spring.GetGatherMode

function

function Spring.GetGatherMode()

[source]

Returns

number gatherMode

Spring.GetGlobalLos

function

function Spring.GetGlobalLos(teamID?: integer)

[source]

Params

teamID integer?

Returns

boolean enabled

Spring.GetGrass

function

function Spring.GetGrass(x: number, z: number)

[source]

Params

x number
z number

Returns

number

Spring.GetGroundBlocked

function

function Spring.GetGroundBlocked()

[source]

Spring.GetGroundDecalAlpha

function

function Spring.GetGroundDecalAlpha(decalID: integer)

[source]

Params

decalID integer

Returns

number? alpha — Between 0 and 1
number alphaFalloff — Between 0 and 1, per second

Spring.GetGroundDecalCreationFrame

function

function Spring.GetGroundDecalCreationFrame(decalID: integer)

[source]

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

Params

decalID integer

Returns

number? creationFrameMin
number creationFrameMax

Spring.GetGroundDecalMiddlePos

function

function Spring.GetGroundDecalMiddlePos(decalID: integer)

[source]

Params

decalID integer

Returns

number? posX
number posZ

Spring.GetGroundDecalMisc

function

function Spring.GetGroundDecalMisc(decalID: integer)

[source]

Returns less important parameters of a ground decal

Params

decalID integer

Returns

number? dotElimExp
number refHeight
number minHeight
number maxHeight
number forceHeightMode

Spring.GetGroundDecalNormal

function

function Spring.GetGroundDecalNormal(decalID: integer)

[source]

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

Params

decalID integer

Returns

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

Spring.GetGroundDecalOwner

function

function Spring.GetGroundDecalOwner(decalID: integer)

[source]

Params

decalID integer

Returns

number? unitID — number featureID(+MAX_UNITS)

Spring.GetGroundDecalRotation

function

function Spring.GetGroundDecalRotation(decalID: integer)

[source]

Params

decalID integer

Returns

number? rotation — in radians

Spring.GetGroundDecalSizeAndHeight

function

function Spring.GetGroundDecalSizeAndHeight(decalID: integer)

[source]

Params

decalID integer

Returns

number? sizeX
number sizeY
number projCubeHeight

Spring.GetGroundDecalTexture

function

function Spring.GetGroundDecalTexture(decalID: integer, isMainTex?: boolean)

[source]

Params

decalID integer
isMainTex boolean? — (Default: true) If false, it gets the normals/glow map

Returns

string|nil texture

Spring.GetGroundDecalTint

function

function Spring.GetGroundDecalTint(decalID: integer)

[source]

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

Params

decalID integer

Returns

number? tintR
number tintG
number tintB
number tintA

Spring.GetGroundDecalType

function

function Spring.GetGroundDecalType(decalID: integer)

[source]

Params

decalID integer

Returns

string|nil type — explosion

Spring.GetGroundExtremes

function

function Spring.GetGroundExtremes()

[source]

Returns

number initMinHeight
number initMaxHeight
number currMinHeight
number currMaxHeight

Spring.GetGroundHeight

function

function Spring.GetGroundHeight(x: number, z: number)

[source]

Get ground height

On sea, this returns the negative depth of the seafloor

Params

x number
z number

Returns

number

Spring.GetGroundInfo

function

function Spring.GetGroundInfo(x: number, z: number)

[source]

Params

x number
z number

Returns

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

Spring.GetGroundNormal

function

function Spring.GetGroundNormal(x: number, z: number, smoothed?: boolean)

[source]

Params

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

Returns

number normalX
number normalY
number normalZ
number slope

Spring.GetGroundOrigHeight

function

function Spring.GetGroundOrigHeight(x: number, z: number)

[source]

Get ground height as it was at game start

Returns the original height before the ground got deformed

Params

x number
z number

Returns

number

Spring.GetGroupList

function

function Spring.GetGroupList()

[source]

Returns

table<number, number>|nil where — keys are groupIDs and values are counts

Spring.GetGroupUnits

function

function Spring.GetGroupUnits(groupID: integer)

[source]

Params

groupID integer

Returns

number[]|nil unitIDs

Spring.GetGroupUnitsCount

function

function Spring.GetGroupUnitsCount(groupID: integer)

[source]

Params

groupID integer

Returns

number? groupSize

Spring.GetGroupUnitsCounts

function

function Spring.GetGroupUnitsCounts(groupID: integer)

[source]

Params

groupID integer

Returns

table<number, number>|nil where — keys are unitDefIDs and values are counts

Spring.GetGroupUnitsSorted

function

function Spring.GetGroupUnitsSorted(groupID: integer)

[source]

Params

groupID integer

Returns

table<number, number[]>|nil where — keys are unitDefIDs and values are unitIDs

Spring.GetHeadingFromFacing

function

function Spring.GetHeadingFromFacing(facing: number)

[source]

Params

facing number

Returns

number heading

Spring.GetHeadingFromVector

function

function Spring.GetHeadingFromVector(x: number, z: number)

[source]

Params

x number
z number

Returns

number heading

Spring.GetInvertQueueKey

function

function Spring.GetInvertQueueKey()

[source]

Returns

number? queueKey

Spring.GetKeyBindings

function

function Spring.GetKeyBindings(keySet1?: string, keySet2?: string)

[source]

Params

keySet1 string? — filters keybindings bound to this keyset
keySet2 string? — OR bound to this keyset

Returns

KeyBinding[]

Spring.GetKeyCode

function

function Spring.GetKeyCode(keySym: string)

[source]

Params

keySym string

Returns

number keyCode

Spring.GetKeyFromScanSymbol

function

function Spring.GetKeyFromScanSymbol(scanSymbol: string)

[source]

Params

scanSymbol string

Returns

string keyName

Spring.GetKeyState

function

function Spring.GetKeyState(keyCode: number)

[source]

Params

keyCode number

Returns

boolean pressed

Spring.GetKeySymbol

function

function Spring.GetKeySymbol(keyCode: number)

[source]

Params

keyCode number

Returns

string keyCodeName
string keyCodeDefaultName — name when there are not aliases

Spring.GetLastMessagePositions

function

function Spring.GetLastMessagePositions()

[source]

Returns

xyz[] message — positions

Spring.GetLastUpdateSeconds

function

function Spring.GetLastUpdateSeconds()

[source]

Returns

number? lastUpdateSeconds

Spring.GetLocalAllyTeamID

function

function Spring.GetLocalAllyTeamID()

[source]

Returns

number allyTeamID

Spring.GetLocalPlayerID

function

function Spring.GetLocalPlayerID()

[source]

Returns

number playerID

Spring.GetLocalTeamID

function

function Spring.GetLocalTeamID()

[source]

Returns

number teamID

Spring.GetLogSections

function

function Spring.GetLogSections()

[source]

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

function

function Spring.GetLosViewColors()

[source]

Returns

rgb always
rgb LOS
rgb radar
rgb jam
rgb radar2

Spring.GetLuaMemUsage

function

function Spring.GetLuaMemUsage()

[source]

Returns

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

Spring.GetMapDrawMode

function

function Spring.GetMapDrawMode()

[source]

return #1:
    | "normal"
    | "height"
    | "metal"
    | "pathTraversability"
    | "los"

Returns

"height"|"los"|"metal"|"normal"|"pathTraversability"

Spring.GetMapOption

function

function Spring.GetMapOption(mapOption: string)

[source]

Params

mapOption string

Returns

string value — Value of modOption.

Spring.GetMapOptions

function

function Spring.GetMapOptions()

[source]

Returns

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

Spring.GetMapSquareTexture

function

function Spring.GetMapSquareTexture(texSquareX: number, texSquareY: number, lodMin: number, luaTexName: string, lodMax?: number)

[source]

Params

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

Returns

boolean? success

Spring.GetMapStartPositions

function

function Spring.GetMapStartPositions()

[source]

Returns

xyz[] array — of positions indexed by teamID

Spring.GetMenuName

function

function Spring.GetMenuName()

[source]

Returns

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

Spring.GetMiniMapDualScreen

function

function Spring.GetMiniMapDualScreen()

[source]

position:
    | false

Returns

string|false position — “left” “right” when dual screen is enabled, false when not

Spring.GetMiniMapGeometry

function

function Spring.GetMiniMapGeometry()

[source]

Get minimap geometry

Returns

number minimapPosX — in px
number minimapPosY — in px
number minimapSizeX — in px
number minimapSizeY — in px
boolean minimized
boolean maximized

Spring.GetMiniMapRotation

function

function Spring.GetMiniMapRotation()

[source]

Get minimap rotation

Returns

number amount — in radians

Spring.GetModKeyState

function

function Spring.GetModKeyState()

[source]

Returns

boolean alt
boolean ctrl
boolean meta
boolean shift

Spring.GetModOption

function

function Spring.GetModOption(modOption: string)

[source]

Params

modOption string

Returns

string value — Value of modOption.

Spring.GetModOptions

function

function Spring.GetModOptions()

[source]

Returns

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

Spring.GetModelPieceList

function

function Spring.GetModelPieceList(modelName: string)

[source]

Params

modelName string

Returns

string[]|nil pieceNames

Spring.GetModelPieceMap

function

function Spring.GetModelPieceMap(modelName: string)

[source]

Params

modelName string

Returns

table<string, number>|nil pieceInfos — where keys are piece names and values are indices

Spring.GetModelRootPiece

function

function Spring.GetModelRootPiece(modelName: string)

[source]

Params

modelName string

Returns

number index — of the root piece

Spring.GetMouseCursor

function

function Spring.GetMouseCursor()

[source]

Returns

string cursorName
number cursorScale

Spring.GetMouseStartPosition

function

function Spring.GetMouseStartPosition(button: number)

[source]

Params

button number

Returns

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

Spring.GetMouseState

function

function Spring.GetMouseState()

[source]

Returns

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

Spring.GetNanoProjectileParams

function

function Spring.GetNanoProjectileParams()

[source]

Returns

number rotVal — in degrees
number rotVel — in degrees
number rotAcc — in degrees
number rotValRng — in degrees
number rotVelRng — in degrees
number rotAccRng — in degrees

Spring.GetNumDisplays

function

function Spring.GetNumDisplays()

[source]

Returns

number numDisplays — as returned by SDL_GetNumVideoDisplays

Spring.GetPieceProjectileParams

function

function Spring.GetPieceProjectileParams(projectileID: integer)

[source]

Params

projectileID integer

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
number spinAngle
number spinSpeed
number spinVectorX
number spinVectorY
number spinVectorZ

Spring.GetPixelDir

function

function Spring.GetPixelDir(x: number, y: number)

[source]

Params

x number
y number

Returns

number dirX
number dirY
number dirZ

Spring.GetPlayerControlledUnit

function

function Spring.GetPlayerControlledUnit(playerID: integer)

[source]

Returns unit controlled by player on FPS mode

Params

playerID integer

Returns

number?

Spring.GetPlayerInfo

function

function Spring.GetPlayerInfo(playerID: integer, getPlayerOpts?: boolean)

[source]

Params

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

Returns

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

Spring.GetPlayerList

function

function Spring.GetPlayerList(teamID?: integer, active?: boolean)

[source]

Params

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

Returns

number[]? list — of playerIDs

Spring.GetPlayerRoster

function

function Spring.GetPlayerRoster(sortType?: number, showPathingPlayers?: boolean)

[source]

Params

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

Returns

Roster[]? playerTable

Spring.GetPlayerRulesParam

function

function Spring.GetPlayerRulesParam(playerID: integer, ruleRef: string|number)

[source]

Params

playerID integer
ruleRef string|number — the rule index or name

Returns

string|number|nil value

Spring.GetPlayerRulesParams

function

function Spring.GetPlayerRulesParams(playerID: integer)

[source]

Params

playerID integer

Returns

RulesParams rulesParams — map with rules names as key and values as values

Spring.GetPlayerStatistics

function

function Spring.GetPlayerStatistics(playerID: integer)

[source]

Params

playerID integer

Returns

number? mousePixels — nil when invalid playerID
number mouseClicks
number keyPresses
number numCommands
number unitCommands

Spring.GetPlayerTraffic

function

function Spring.GetPlayerTraffic(playerID: integer, packetID?: integer)

[source]

Params

playerID integer
packetID integer?

Returns

number traffic

Spring.GetPositionLosState

function

function Spring.GetPositionLosState(posX: number, posY: number, posZ: number, allyTeamID?: integer)

[source]

Params

posX number
posY number
posZ number
allyTeamID integer?

Returns

boolean inLosOrRadar
boolean inLos
boolean inRadar
boolean inJammer

Spring.GetPressedKeys

function

function Spring.GetPressedKeys()

[source]

Returns

table<string|number, true> where — keys are keyCodes or key names

Spring.GetPressedScans

function

function Spring.GetPressedScans()

[source]

Returns

table<string|number, true> where — keys are scanCodes or scan names

Spring.GetProfilerRecordNames

function

function Spring.GetProfilerRecordNames()

[source]

Returns

string[] profilerNames

Spring.GetProfilerTimeRecord

function

function Spring.GetProfilerTimeRecord(profilerName: string, frameData?: boolean)

[source]

Params

profilerName string
frameData boolean? — (Default: false)

Returns

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

Spring.GetProjectileAllyTeamID

function

function Spring.GetProjectileAllyTeamID(projectileID: integer)

[source]

Params

projectileID integer

Returns

number?

Spring.GetProjectileDamages

function

function Spring.GetProjectileDamages(projectileID: integer, tag: string)

[source]

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

or - an armor type index to get the damage against it.

Params

projectileID integer
tag string — one of:

Returns

number?

Spring.GetProjectileDefID

function

function Spring.GetProjectileDefID(projectileID: integer)

[source]

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

Params

projectileID integer

Returns

number?

Spring.GetProjectileDirection

function

function Spring.GetProjectileDirection(projectileID: integer)

[source]

Params

projectileID integer

Returns

number? dirX
number dirY
number dirZ

Spring.GetProjectileGravity

function

function Spring.GetProjectileGravity(projectileID: integer)

[source]

Params

projectileID integer

Returns

number?

Spring.GetProjectileIsIntercepted

function

function Spring.GetProjectileIsIntercepted(projectileID: integer)

[source]

Params

projectileID integer

Returns

boolean|nil

Spring.GetProjectileOwnerID

function

function Spring.GetProjectileOwnerID(projectileID: integer)

[source]

Params

projectileID integer

Returns

number?

Spring.GetProjectilePosition

function

function Spring.GetProjectilePosition(projectileID: integer)

[source]

Params

projectileID integer

Returns

number? posX
number posY
number posZ

Spring.GetProjectileTarget

function

function Spring.GetProjectileTarget(projectileID: integer)

[source]

string.byte(‘g’) := GROUND string.byte(‘u’) := UNIT string.byte(‘f’) := FEATURE string.byte(‘p’) := PROJECTILE

Params

projectileID integer

Returns

number? targetTypeInt — where
number|xyz target — targetID or targetPos when targetTypeInt == string.byte(‘g’)

Spring.GetProjectileTeamID

function

function Spring.GetProjectileTeamID(projectileID: integer)

[source]

Params

projectileID integer

Returns

number?

Spring.GetProjectileTimeToLive

function

function Spring.GetProjectileTimeToLive(projectileID: integer)

[source]

Params

projectileID integer

Returns

number?

Spring.GetProjectileType

function

function Spring.GetProjectileType(projectileID: integer)

[source]

Params

projectileID integer

Returns

boolean|nil weapon
boolean piece

Spring.GetProjectileVelocity

function

function Spring.GetProjectileVelocity(projectileID: integer)

[source]

Params

projectileID integer

Returns

number? velX
number velY
number velZ
number velW

Spring.GetProjectilesInRectangle

function

function Spring.GetProjectilesInRectangle(xmin: number, zmin: number, xmax: number, zmax: number, excludeWeaponProjectiles?: boolean, excludePieceProjectiles?: boolean)

[source]

Params

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

Returns

number[] projectileIDs

Spring.GetRadarErrorParams

function

function Spring.GetRadarErrorParams(allyTeamID: integer)

[source]

Params

allyTeamID integer

Returns

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

Spring.GetRealBuildQueue

function

function Spring.GetRealBuildQueue(unitID: integer)

[source]

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

Params

unitID integer

Returns

table<number, number>|nil buildqueue — indexed by unitDefID with count values

Spring.GetRenderFeatures

function

function Spring.GetRenderFeatures()

[source]

Spring.GetRenderFeaturesDrawFlagChanged

function

function Spring.GetRenderFeaturesDrawFlagChanged()

[source]

Spring.GetRenderUnits

function

function Spring.GetRenderUnits()

[source]

Spring.GetRenderUnitsDrawFlagChanged

function

function Spring.GetRenderUnitsDrawFlagChanged()

[source]

Spring.GetReplayLength

function

function Spring.GetReplayLength()

[source]

Returns

number? timeInSeconds

Spring.GetScanSymbol

function

function Spring.GetScanSymbol(scanCode: number)

[source]

Params

scanCode number

Returns

string scanCodeName
string scanCodeDefaultName — name when there are not aliases

Spring.GetScreenGeometry

function

function Spring.GetScreenGeometry(displayIndex?: number, queryUsable?: boolean)

[source]

Get screen geometry

Params

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

Returns

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

Spring.GetSelectedGroup

function

function Spring.GetSelectedGroup()

[source]

Returns

number groupID — -1 when no group selected

Spring.GetSelectedUnits

function

function Spring.GetSelectedUnits()

[source]

Returns

number[] unitIDs

Spring.GetSelectedUnitsCount

function

function Spring.GetSelectedUnitsCount()

[source]

Returns the amount of selected units

Returns

number selectedUnitsCount

Spring.GetSelectedUnitsCounts

function

function Spring.GetSelectedUnitsCounts()

[source]

Get an aggregate count of selected units per unitDefID

Returns

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

Spring.GetSelectedUnitsSorted

function

function Spring.GetSelectedUnitsSorted()

[source]

Get selected units aggregated by unitDefID

Returns

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

Spring.GetSelectionBox

function

function Spring.GetSelectionBox()

[source]

Get vertices from currently active selection box

Returns nil when selection box is inactive

See: Spring.GetUnitsInScreenRectangle

Returns

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

Spring.GetSideData

function

function Spring.GetSideData(sideName: string)

[source]

Params

sideName string

Returns

string|nil startUnit
string caseSensitiveSideName

Spring.GetSmoothMeshHeight

function

function Spring.GetSmoothMeshHeight(x: number, z: number)

[source]

Params

x number
z number

Returns

number height

Spring.GetSoundDevices

function

function Spring.GetSoundDevices()

[source]

Returns

SoundDeviceSpec[] devices — Sound devices.

Spring.GetSoundEffectParams

function

function Spring.GetSoundEffectParams()

[source]

Spring.GetSoundStreamTime

function

function Spring.GetSoundStreamTime()

[source]

Returns

number playTime
number time

Spring.GetSpectatingState

function

function Spring.GetSpectatingState()

[source]

Returns

boolean spectating
boolean spectatingFullView
boolean spectatingFullSelect

Spring.GetSyncedGCInfo

function

function Spring.GetSyncedGCInfo(collectGC?: boolean)

[source]

Params

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

Returns

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

Spring.GetTeamAllyTeamID

function

function Spring.GetTeamAllyTeamID(teamID: integer)

[source]

Params

teamID integer

Returns

integer? allyTeamID

Spring.GetTeamColor

function

function Spring.GetTeamColor(teamID: integer)

[source]

Params

teamID integer

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

function

function Spring.GetTeamDamageStats(teamID: integer)

[source]

Gets team damage dealt/received totals

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

Params

teamID integer

Returns

number damageDealt
number damageReceived

Spring.GetTeamInfo

function

function Spring.GetTeamInfo(teamID: integer, getTeamKeys?: boolean)

[source]

Params

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

Returns

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

Spring.GetTeamList

function

function Spring.GetTeamList(allyTeamID?: integer)

[source]

Params

allyTeamID integer? — (Default: -1) to filter teams belonging to when >= 0

Returns

number[]? list — of teamIDs

Spring.GetTeamLuaAI

function

function Spring.GetTeamLuaAI(teamID: integer)

[source]

Params

teamID integer

Returns

string

Spring.GetTeamMaxUnits

function

function Spring.GetTeamMaxUnits(teamID: integer)

[source]

Returns a team’s unit cap.

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

Params

teamID integer

Returns

number maxUnits
number? currentUnits

Spring.GetTeamOrigColor

function

function Spring.GetTeamOrigColor(teamID: integer)

[source]

Params

teamID integer

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

function

function Spring.GetTeamResourceStats(teamID: integer, resource: "e"|"energy"|"m"|"metal")

[source]

resource:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

teamID integer
resource "e"|"energy"|"m"|"metal"

Returns

number? used
number produced
number excessed
number received
number sent

Spring.GetTeamResources

function

function Spring.GetTeamResources(teamID: integer, resource: "e"|"energy"|"m"|"metal")

[source]

resource:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

teamID integer
resource "e"|"energy"|"m"|"metal"

Returns

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

Spring.GetTeamRulesParam

function

function Spring.GetTeamRulesParam(teamID: integer, ruleRef: string|number)

[source]

Params

teamID integer
ruleRef string|number — the rule index or name

Returns

string|number|nil value

Spring.GetTeamRulesParams

function

function Spring.GetTeamRulesParams(teamID: integer)

[source]

Params

teamID integer

Returns

RulesParams rulesParams — map with rules names as key and values as values

Spring.GetTeamStartPosition

function

function Spring.GetTeamStartPosition(teamID: integer)

[source]

Params

teamID integer

Returns

number? x
number? y
number? x

Spring.GetTeamStatsHistory

function

function Spring.GetTeamStatsHistory(teamID: integer)

[source]

Get the number of history entries.

Params

teamID integer

Returns

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

Spring.GetTeamUnitCount

function

function Spring.GetTeamUnitCount(teamID: integer)

[source]

Params

teamID integer

Returns

number? count

Spring.GetTeamUnitDefCount

function

function Spring.GetTeamUnitDefCount(teamID: integer, unitDefID: integer)

[source]

Params

teamID integer
unitDefID integer

Returns

number? count

Spring.GetTeamUnitStats

function

function Spring.GetTeamUnitStats(teamID: integer)

[source]

Params

teamID integer

Returns

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

Spring.GetTeamUnits

function

function Spring.GetTeamUnits(teamID: integer)

[source]

Params

teamID integer

Returns

number[]? unitIDs

Spring.GetTeamUnitsByDefs

function

function Spring.GetTeamUnitsByDefs(teamID: integer, unitDefIDs: number|number[])

[source]

Params

teamID integer
unitDefIDs number|number[]

Returns

number[]? unitIDs

Spring.GetTeamUnitsCounts

function

function Spring.GetTeamUnitsCounts(teamID: integer)

[source]

Params

teamID integer

Returns

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

Spring.GetTeamUnitsSorted

function

function Spring.GetTeamUnitsSorted(teamID: integer)

[source]

Params

teamID integer

Returns

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

Spring.GetTerrainTypeData

function

function Spring.GetTerrainTypeData(terrainTypeInfo: number)

[source]

Params

terrainTypeInfo number

Returns

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

Spring.GetTidal

function

function Spring.GetTidal()

[source]

Returns

number tidalStrength

Spring.GetTimer

function

function Spring.GetTimer()

[source]

Get a timer with millisecond resolution

Returns

integer

Spring.GetTimerMicros

function

function Spring.GetTimerMicros()

[source]

Get a timer with microsecond resolution

Returns

integer

Spring.GetUnitAllyTeam

function

function Spring.GetUnitAllyTeam(unitID: integer)

[source]

Params

unitID integer

Returns

number?

Spring.GetUnitAlwaysUpdateMatrix

function

function Spring.GetUnitAlwaysUpdateMatrix(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? nil — when unitID cannot be parsed

Spring.GetUnitArmored

function

function Spring.GetUnitArmored(unitID: integer)

[source]

Params

unitID integer

Returns

boolean|nil armored
number armorMultiple

Spring.GetUnitArrayCentroid

function

function Spring.GetUnitArrayCentroid(units: table)

[source]

Returns the centroid of an array of units

Returns nil for an empty array

Params

units table — { unitID, unitID, … }

Returns

number centerX
number centerY
number centerZ

Spring.GetUnitBasePosition

function

function Spring.GetUnitBasePosition(unitID: integer)

[source]

Params

unitID integer

Returns

number? posX
number posY
number posZ

Spring.GetUnitBlocking

function

function Spring.GetUnitBlocking(unitID: integer)

[source]

Params

unitID integer

Returns

boolean|nil isBlocking
boolean isSolidObjectCollidable
boolean isProjectileCollidable
boolean isRaySegmentCollidable
boolean crushable
boolean blockEnemyPushing
boolean blockHeightChanges

Spring.GetUnitBuildFacing

function

function Spring.GetUnitBuildFacing(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitBuildParams

function

function Spring.GetUnitBuildParams(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitBuildeeRadius

function

function Spring.GetUnitBuildeeRadius(unitID: integer)

[source]

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

Params

unitID integer

Returns

number?

Spring.GetUnitCmdDescs

function

function Spring.GetUnitCmdDescs(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitCollisionVolumeData

function

function Spring.GetUnitCollisionVolumeData(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitCommands

function

function Spring.GetUnitCommands(unitID: integer, count: integer)

[source]

Get the commands for a unit.

Same as Spring.GetCommandQueue

Params

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

Returns

Command[] commands

Spring.GetUnitCostTable

function

function Spring.GetUnitCostTable(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitCosts

function

function Spring.GetUnitCosts(unitID: integer)

[source]

Params

unitID integer

Returns

number? buildTime
number metalCost
number energyCost

Spring.GetUnitCurrentBuildPower

function

function Spring.GetUnitCurrentBuildPower(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitCurrentCommand

function

function Spring.GetUnitCurrentCommand(unitID: integer, cmdIndex: integer)

[source]

for example -1 will be the last command.

Params

unitID integer — Unit id.
cmdIndex integer — Command index to get. If negative will count from the end of the queue,

Spring.GetUnitDefDimensions

function

function Spring.GetUnitDefDimensions(unitDefID: integer)

[source]

Params

unitDefID integer

Spring.GetUnitDefID

function

function Spring.GetUnitDefID(unitID: integer)

[source]

Params

unitID integer

Returns

number?

Spring.GetUnitDirection

function

function Spring.GetUnitDirection(unitID: integer)

[source]

Params

unitID integer

Returns

number? dirX
number? dirY
number? dirZ

Spring.GetUnitDrawFlag

function

function Spring.GetUnitDrawFlag(unitID: integer)

[source]

Params

unitID integer

Returns

number? nil — when unitID cannot be parsed

Spring.GetUnitEffectiveBuildRange

function

function Spring.GetUnitEffectiveBuildRange(unitID: integer, buildeeDefID: integer)

[source]

Useful for setting move goals manually.

Params

unitID integer
buildeeDefID integer — or nil

Returns

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

Spring.GetUnitEngineDrawMask

function

function Spring.GetUnitEngineDrawMask(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? nil — when unitID cannot be parsed

Spring.GetUnitEstimatedPath

function

function Spring.GetUnitEstimatedPath(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitExperience

function

function Spring.GetUnitExperience(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitFeatureSeparation

function

function Spring.GetUnitFeatureSeparation(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitFlanking

function

function Spring.GetUnitFlanking(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitGroup

function

function Spring.GetUnitGroup(unitID: integer)

[source]

Params

unitID integer

Returns

number? groupID

Spring.GetUnitHarvestStorage

function

function Spring.GetUnitHarvestStorage(unitID: integer)

[source]

Get a unit’s carried resources

Checks resources being carried internally by the unit.

Params

unitID integer

Returns

number storedMetal
number maxStoredMetal
number storedEnergy
number maxStoredEnergy

Spring.GetUnitHeading

function

function Spring.GetUnitHeading(unitID: integer, convertToRadians?: boolean)

[source]

Params

unitID integer
convertToRadians boolean? — (Default: false)

Returns

number heading

Spring.GetUnitHealth

function

function Spring.GetUnitHealth(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitHeight

function

function Spring.GetUnitHeight(unitID: integer)

[source]

Params

unitID integer

Returns

number?

Spring.GetUnitInBuildStance

function

function Spring.GetUnitInBuildStance(unitID: integer)

[source]

Is builder in build stance

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

Params

unitID integer

Returns

boolean inBuildStance

Spring.GetUnitIsActive

function

function Spring.GetUnitIsActive(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? isActive

Spring.GetUnitIsBeingBuilt

function

function Spring.GetUnitIsBeingBuilt(unitID: integer)

[source]

Params

unitID integer

Returns

boolean beingBuilt
number buildProgress

Spring.GetUnitIsBuilding

function

function Spring.GetUnitIsBuilding(unitID: integer)

[source]

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

Works for both mobile builders and factories.

Params

unitID integer

Returns

number buildeeUnitID — or nil

Spring.GetUnitIsCloaked

function

function Spring.GetUnitIsCloaked(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? isCloaked

Spring.GetUnitIsDead

function

function Spring.GetUnitIsDead(unitID: integer)

[source]

Params

unitID integer

Returns

boolean|nil

Spring.GetUnitIsStunned

function

function Spring.GetUnitIsStunned(unitID: integer)

[source]

Checks whether a unit is disabled and can’t act

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

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

Params

unitID integer

Returns

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

Spring.GetUnitIsTransporting

function

function Spring.GetUnitIsTransporting(unitID: integer)

[source]

Get units being transported

An array of unitIDs being transported by this unit, or nil if not a transport.

Params

unitID integer

Returns

integer[]? transporteeArray

Spring.GetUnitLastAttackedPiece

function

function Spring.GetUnitLastAttackedPiece(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitLastAttacker

function

function Spring.GetUnitLastAttacker(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitLosState

function

function Spring.GetUnitLosState(unitID: integer, allyTeamID?: integer, raw: true)

[source]

A bitmask integer, or nil if unitID is invalid.

Bitmask bits:

1: LOS_INLOS the unit is currently in the los of the allyteam,
2: LOS_INRADAR the unit is currently in radar from the allyteam,
4: LOS_PREVLOS the unit has previously been in los from the allyteam,
8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam

raw:
    | true

Params

unitID integer
allyTeamID integer?
raw true — Return a bitmask.

Returns

integer? bitmask

Spring.GetUnitLuaDraw

function

function Spring.GetUnitLuaDraw(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? draw — nil when unitID cannot be parsed

Spring.GetUnitMapCentroid

function

function Spring.GetUnitMapCentroid(units: table)

[source]

Returns the centroid of a map of units

Returns nil for an empty map

Params

units table — { [unitID] = true, [unitID] = true, … }

Returns

number centerX
number centerY
number centerZ

Spring.GetUnitMass

function

function Spring.GetUnitMass(unitID: integer)

[source]

Params

unitID integer

Returns

number?

Spring.GetUnitMaxRange

function

function Spring.GetUnitMaxRange(unitID: integer)

[source]

Get a unit’s engagement range

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

Params

unitID integer

Returns

number maxRange

Spring.GetUnitMetalExtraction

function

function Spring.GetUnitMetalExtraction(unitID: integer)

[source]

Params

unitID integer

Returns

number? metalExtraction

Spring.GetUnitMoveTypeData

function

function Spring.GetUnitMoveTypeData(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitNanoPieces

function

function Spring.GetUnitNanoPieces(unitID: integer)

[source]

Get construction FX attachment points

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

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

Params

unitID integer

Returns

integer[] pieceArray

Spring.GetUnitNearestAlly

function

function Spring.GetUnitNearestAlly(unitID: integer, range?: number)

[source]

Params

unitID integer
range number? — (Default: 1.0e9f)

Returns

number? unitID

Spring.GetUnitNearestEnemy

function

function Spring.GetUnitNearestEnemy(unitID: integer, range?: number, useLOS?: boolean)

[source]

Params

unitID integer
range number? — (Default: 1.0e9f)
useLOS boolean? — (Default: true)

Returns

number? unitID

Spring.GetUnitNeutral

function

function Spring.GetUnitNeutral(unitID: integer)

[source]

Checks if a unit is neutral (NOT Gaia!)

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

Params

unitID integer

Returns

boolean|nil

Spring.GetUnitNoDraw

function

function Spring.GetUnitNoDraw(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? nil — when unitID cannot be parsed

Spring.GetUnitNoGroup

function

function Spring.GetUnitNoGroup(unitID: integer)

[source]

Params

unitID integer

Returns

bool|nil noGroup — nil when unitID cannot be parsed.

Spring.GetUnitNoMinimap

function

function Spring.GetUnitNoMinimap(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? nil — when unitID cannot be parsed

Spring.GetUnitNoSelect

function

function Spring.GetUnitNoSelect(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? noSelect — nil when unitID cannot be parsed.

Spring.GetUnitPhysicalState

function

function Spring.GetUnitPhysicalState(unitID: integer)

[source]

Params

unitID integer

Returns

number Unit — ‘s PhysicalState bitmask

Spring.GetUnitPieceDirection

function

function Spring.GetUnitPieceDirection(unitID: integer, pieceIndex: integer)

[source]

Params

unitID integer
pieceIndex integer

Returns

number|nil dirX
number dirY
number dirZ

Spring.GetUnitPieceInfo

function

function Spring.GetUnitPieceInfo(unitID: integer, pieceIndex: integer)

[source]

Params

unitID integer
pieceIndex integer

Returns

PieceInfo? pieceInfo

Spring.GetUnitPieceList

function

function Spring.GetUnitPieceList(unitID: integer)

[source]

Params

unitID integer

Returns

string[] pieceNames

Spring.GetUnitPieceMap

function

function Spring.GetUnitPieceMap(unitID: integer)

[source]

Params

unitID integer

Returns

table<string, number>|nil pieceInfos — where keys are piece names and values are indices

Spring.GetUnitPieceMatrix

function

function Spring.GetUnitPieceMatrix(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitPiecePosDir

function

function Spring.GetUnitPiecePosDir(unitID: integer, pieceIndex: integer)

[source]

Params

unitID integer
pieceIndex integer

Returns

number|nil posX
number posY
number posZ
number dirX
number dirY
number dirZ

Spring.GetUnitPiecePosition

function

function Spring.GetUnitPiecePosition(unitID: integer, pieceIndex: integer)

[source]

Params

unitID integer
pieceIndex integer

Returns

number|nil posX
number posY
number posZ

Spring.GetUnitPosErrorParams

function

function Spring.GetUnitPosErrorParams(unitID: integer, allyTeamID?: integer)

[source]

Params

unitID integer
allyTeamID integer?

Returns

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

Spring.GetUnitPosition

function

function Spring.GetUnitPosition(unitID: integer, midPos?: boolean, aimPos?: boolean)

[source]

Params

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

Returns

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

Spring.GetUnitRadius

function

function Spring.GetUnitRadius(unitID: integer)

[source]

Params

unitID integer

Returns

number?

Spring.GetUnitResources

function

function Spring.GetUnitResources(unitID: integer)

[source]

Params

unitID integer

Returns

number? metalMake
number metalUse
number energyMake
number energyUse

Spring.GetUnitRootPiece

function

function Spring.GetUnitRootPiece(unitID: integer)

[source]

Params

unitID integer

Returns

number index — of the root piece

Spring.GetUnitRotation

function

function Spring.GetUnitRotation(unitID: integer)

[source]

Params

unitID integer

Returns

number? pitch — Rotation in X axis
number? yaw — Rotation in Y axis
number? roll — Rotation in Z axis

Spring.GetUnitRulesParam

function

function Spring.GetUnitRulesParam(unitID: integer, ruleRef: string|number)

[source]

Params

unitID integer
ruleRef string|number — the rule index or name

Returns

string|number|nil value

Spring.GetUnitRulesParams

function

function Spring.GetUnitRulesParams(unitID: integer)

[source]

Params

unitID integer

Returns

RulesParams rulesParams — map with rules names as key and values as values

Spring.GetUnitScriptNames

function

function Spring.GetUnitScriptNames(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitScriptPiece

function

function Spring.GetUnitScriptPiece(unitID: integer)

[source]

Params

unitID integer

Returns

integer[] pieceIndices

Spring.GetUnitSeismicSignature

function

function Spring.GetUnitSeismicSignature(unitID: integer)

[source]

Params

unitID integer

Returns

number? seismicSignature

Spring.GetUnitSelectionVolumeData

function

function Spring.GetUnitSelectionVolumeData(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitSelfDTime

function

function Spring.GetUnitSelfDTime(unitID: integer)

[source]

Params

unitID integer

Returns

integer? selfDTime

Spring.GetUnitSensorRadius

function

function Spring.GetUnitSensorRadius(unitID: integer, type: string)

[source]

Params

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

Returns

number? radius

Spring.GetUnitSeparation

function

function Spring.GetUnitSeparation(unitID1: number, unitID2: number, direction?: boolean, subtractRadii?: boolean)

[source]

Params

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

Returns

number?

Spring.GetUnitShieldState

function

function Spring.GetUnitShieldState(unitID: integer, weaponNum?: number)

[source]

Params

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

Returns

number isEnabled — Warning, number not boolean. 0 or 1
number currentPower

Spring.GetUnitStates

function

function Spring.GetUnitStates(unitID: integer)

[source]

Params

unitID integer

Returns

UnitState

Spring.GetUnitStockpile

function

function Spring.GetUnitStockpile(unitID: integer)

[source]

Params

unitID integer

Returns

integer? numStockpiled
integer? numStockpileQued
number? buildPercent

Spring.GetUnitStorage

function

function Spring.GetUnitStorage(unitID: integer)

[source]

Params

unitID integer

Returns

number Unit — ‘s metal storage
number Unit — ‘s energy storage

Spring.GetUnitTeam

function

function Spring.GetUnitTeam(unitID: integer)

[source]

Params

unitID integer

Returns

number?

Spring.GetUnitTooltip

function

function Spring.GetUnitTooltip(unitID: integer)

[source]

Params

unitID integer

Returns

string|nil

Spring.GetUnitTransformMatrix

function

function Spring.GetUnitTransformMatrix(unitID: integer)

[source]

Params

unitID integer

Returns

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

Spring.GetUnitTransporter

function

function Spring.GetUnitTransporter(unitID: integer)

[source]

Get the transport carrying the unit

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

Params

unitID integer

Returns

number|nil transportUnitID

Spring.GetUnitVectors

function

function Spring.GetUnitVectors(unitID: integer)

[source]

Params

unitID integer

Returns

xyz? front
xyz up
xyz right

Spring.GetUnitVelocity

function

function Spring.GetUnitVelocity(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitViewPosition

function

function Spring.GetUnitViewPosition(unitID: integer, midPos?: boolean)

[source]

Params

unitID integer
midPos boolean? — (Default: false)

Returns

number? x — nil when unitID cannot be parsed
number y
number z

Spring.GetUnitWeaponCanFire

function

function Spring.GetUnitWeaponCanFire(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWeaponDamages

function

function Spring.GetUnitWeaponDamages(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWeaponHaveFreeLineOfFire

function

function Spring.GetUnitWeaponHaveFreeLineOfFire(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWeaponState

function

function Spring.GetUnitWeaponState(unitID: integer, weaponNum: number, stateName: string)

[source]

Check the state of a unit’s weapon

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

Params

unitID integer
weaponNum number
stateName string

Returns

number stateValue

Spring.GetUnitWeaponTarget

function

function Spring.GetUnitWeaponTarget(unitID: integer, weaponNum: integer)

[source]

Checks a weapon’s target

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

TargetType:
    | 0

Params

unitID integer
weaponNum integer

Returns

0 TargetType — none
boolean isUserTarget

Spring.GetUnitWeaponTestRange

function

function Spring.GetUnitWeaponTestRange(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWeaponTestTarget

function

function Spring.GetUnitWeaponTestTarget(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWeaponTryTarget

function

function Spring.GetUnitWeaponTryTarget(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWeaponVectors

function

function Spring.GetUnitWeaponVectors(unitID: integer)

[source]

Params

unitID integer

Spring.GetUnitWorkerTask

function

function Spring.GetUnitWorkerTask(unitID: integer)

[source]

Checks a builder’s current task

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

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

Params

unitID integer

Returns

number cmdID — of the relevant command
number targetID — if applicable (all except RESTORE)

Spring.GetUnitsInBox

function

function Spring.GetUnitsInBox(xmin: number, ymin: number, zmin: number, xmax: number, ymax: number, zmax: number, allegiance?: number)

[source]

Params

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

Returns

number[] unitIDs

Spring.GetUnitsInCylinder

function

function Spring.GetUnitsInCylinder(x: number, z: number, radius: number)

[source]

Params

x number
z number
radius number

Returns

number[] unitIDs

Spring.GetUnitsInPlanes

function

function Spring.GetUnitsInPlanes(planes: Plane[], allegiance?: integer)

[source]

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

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

Params

planes Plane[]
allegiance integer?

Returns

integer[] unitIDs

Spring.GetUnitsInRectangle

function

function Spring.GetUnitsInRectangle(xmin: number, zmin: number, xmax: number, zmax: number, allegiance?: number)

[source]

Params

xmin number
zmin number
xmax number
zmax number
allegiance number?

Returns

number[] unitIDs

Spring.GetUnitsInScreenRectangle

function

function Spring.GetUnitsInScreenRectangle(left: number, top: number, right: number, bottom: number, allegiance?: number)

[source]

Get units inside a rectangle area on the map

Params

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

Returns

number[]|nil unitIDs

Spring.GetUnitsInSphere

function

function Spring.GetUnitsInSphere(x: number, y: number, z: number, radius: number)

[source]

Params

x number
y number
z number
radius number

Returns

number[] unitIDs

Spring.GetVectorFromHeading

function

function Spring.GetVectorFromHeading(heading: number)

[source]

Params

heading number

Returns

number x
number z

Spring.GetVidMemUsage

function

function Spring.GetVidMemUsage()

[source]

Returns

number usedMem — in MB
number availableMem — in MB

Spring.GetVideoCapturingMode

function

function Spring.GetVideoCapturingMode()

[source]

Returns

boolean allowRecord

Spring.GetViewGeometry

function

function Spring.GetViewGeometry()

[source]

Get main view geometry (map and game rendering)

Returns

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

Spring.GetVisibleFeatures

function

function Spring.GetVisibleFeatures(teamID?: integer, radius?: number, icons?: boolean, geos?: boolean)

[source]

Params

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

Returns

number[]|nil featureIDs

Spring.GetVisibleProjectiles

function

function Spring.GetVisibleProjectiles(allyTeamID?: integer, addSyncedProjectiles?: boolean, addWeaponProjectiles?: boolean, addPieceProjectiles?: boolean)

[source]

Params

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

Returns

number[]|nil projectileIDs

Spring.GetVisibleUnits

function

function Spring.GetVisibleUnits(teamID?: integer, radius?: number, icons?: boolean)

[source]

Params

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

Returns

number[]|nil unitIDs

Spring.GetWaterLevel

function

function Spring.GetWaterLevel(x: number, z: number)

[source]

Get water level in a specific position

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

Params

x number
z number

Returns

number waterLevel

Spring.GetWaterMode

function

function Spring.GetWaterMode()

[source]

See: ~rts~ /Rendering/Env/IWater.h

Returns

number waterRendererID
string waterRendererName

Spring.GetWaterPlaneLevel

function

function Spring.GetWaterPlaneLevel()

[source]

Get water plane height

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

See: Spring.GetWaterLevel

Returns

number waterPlaneLevel

Spring.GetWind

function

function Spring.GetWind()

[source]

Returns

number windStrength

Spring.GetWindowDisplayMode

function

function Spring.GetWindowDisplayMode()

[source]

Get main window display mode

Returns

number width — in px
number height — in px
number bits — per pixel
number refresh — rate in Hz

Spring.GetWindowGeometry

function

function Spring.GetWindowGeometry()

[source]

Get main window geometry

Returns

number winSizeX — in px
number winSizeY — in px
number winPosX — in px
number winPosY — in px
number windowBorderTop — in px
number windowBorderLeft — in px
number windowBorderBottom — in px
number windowBorderRight — in px

Spring.GiveOrder

function

function Spring.GiveOrder(cmdID: integer, params: table, options: cmdOpts)

[source]

return #1:
    | true

Params

cmdID integer
params table
options cmdOpts — Command Options params

Returns

true|nil

Spring.GiveOrderArrayToUnit

function

function Spring.GiveOrderArrayToUnit(unitID: integer, cmdArray: Command[])

[source]

Params

unitID integer
cmdArray Command[]

Returns

boolean ordersGiven

Spring.GiveOrderArrayToUnitArray

function

function Spring.GiveOrderArrayToUnitArray(unitArray: number[], commands: Command[])

[source]

Params

unitArray number[] — containing unitIDs
commands Command[]

Returns

nil

Spring.GiveOrderArrayToUnitMap

function

function Spring.GiveOrderArrayToUnitMap(unitMap: { [number]: any }, commands: Command[])

[source]

Params

unitMap { [number]: any } — table with unitIDs as keys
commands Command[]

Returns

number unitsOrdered

Spring.GiveOrderToUnit

function

function Spring.GiveOrderToUnit(unitID: integer, cmdID: integer, params?: number[], options?: CommandOptions)

[source]

Params

unitID integer
cmdID integer
params number[]?
options CommandOptions? — Parameters for command options

Returns

boolean unitOrdered

Spring.GiveOrderToUnitArray

function

function Spring.GiveOrderToUnitArray(unitIDs: number[], cmdID: integer, params?: number[], options?: CommandOptions)

[source]

Params

unitIDs number[]
cmdID integer
params number[]?
options CommandOptions? — Parameters for command options

Returns

number unitsOrdered

Spring.GiveOrderToUnitMap

function

function Spring.GiveOrderToUnitMap(unitMap: table<number, table>, cmdID: integer, params?: number[], options?: CommandOptions)

[source]

Params

unitMap table<number, table> — table with unitIDs as keys
cmdID integer
params number[]?
options CommandOptions? — Parameters for command options

Returns

number unitsOrdered

Spring.HaveAdvShading

function

function Spring.HaveAdvShading()

[source]

Returns

boolean useAdvShading
boolean groundUseAdvShading

Spring.HaveShadows

function

function Spring.HaveShadows()

[source]

Returns

boolean shadowsLoaded

Spring.InsertUnitCmdDesc

function

function Spring.InsertUnitCmdDesc(unitID: integer, cmdDescID?: integer, cmdArray: CommandDescription)

[source]

Params

unitID integer
cmdDescID integer?
cmdArray CommandDescription — Command Description

Contains data about a command.

Spring.IsAABBInView

function

function Spring.IsAABBInView(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number)

[source]

Params

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

Returns

boolean inView

Spring.IsAboveMiniMap

function

function Spring.IsAboveMiniMap(x: number, y: number)

[source]

Params

x number
y number

Returns

boolean isAbove

Spring.IsCheatingEnabled

function

function Spring.IsCheatingEnabled()

[source]

Returns

boolean enabled

Spring.IsDevLuaEnabled

function

function Spring.IsDevLuaEnabled()

[source]

Returns

boolean enabled

Spring.IsEditDefsEnabled

function

function Spring.IsEditDefsEnabled()

[source]

Returns

boolean enabled

Spring.IsGUIHidden

function

function Spring.IsGUIHidden()

[source]

Returns

boolean

Spring.IsGameOver

function

function Spring.IsGameOver()

[source]

Returns

boolean isGameOver

Spring.IsGodModeEnabled

function

function Spring.IsGodModeEnabled()

[source]

Returns

boolean enabled

Spring.IsNoCostEnabled

function

function Spring.IsNoCostEnabled()

[source]

Returns

boolean enabled

Spring.IsPosInAirLos

function

function Spring.IsPosInAirLos(posX: number, posY: number, posZ: number, allyTeamID?: integer)

[source]

Params

posX number
posY number
posZ number
allyTeamID integer?

Returns

boolean

Spring.IsPosInLos

function

function Spring.IsPosInLos(posX: number, posY: number, posZ: number, allyTeamID?: integer)

[source]

Params

posX number
posY number
posZ number
allyTeamID integer?

Returns

boolean

Spring.IsPosInMap

function

function Spring.IsPosInMap(x: number, z: number)

[source]

Params

x number
z number

Returns

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

Spring.IsPosInRadar

function

function Spring.IsPosInRadar(posX: number, posY: number, posZ: number, allyTeamID?: integer)

[source]

Params

posX number
posY number
posZ number
allyTeamID integer?

Returns

boolean

Spring.IsReplay

function

function Spring.IsReplay()

[source]

Returns

boolean? isReplay

Spring.IsSphereInView

function

function Spring.IsSphereInView(posX: number, posY: number, posZ: number, radius?: number)

[source]

Params

posX number
posY number
posZ number
radius number? — (Default: 0)

Returns

boolean inView

Spring.IsUnitAllied

function

function Spring.IsUnitAllied(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? isAllied — nil with unitID cannot be parsed

Spring.IsUnitIcon

function

function Spring.IsUnitIcon(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? isUnitIcon — nil when unitID cannot be parsed

Spring.IsUnitInAirLos

function

function Spring.IsUnitInAirLos(unitID: integer, allyTeamID: integer)

[source]

Params

unitID integer
allyTeamID integer

Returns

boolean inAirLos

Spring.IsUnitInJammer

function

function Spring.IsUnitInJammer(unitID: integer, allyTeamID: integer)

[source]

Params

unitID integer
allyTeamID integer

Returns

boolean inJammer

Spring.IsUnitInLos

function

function Spring.IsUnitInLos(unitID: integer, allyTeamID: integer)

[source]

Params

unitID integer
allyTeamID integer

Returns

boolean inLos

Spring.IsUnitInRadar

function

function Spring.IsUnitInRadar(unitID: integer, allyTeamID: integer)

[source]

Params

unitID integer
allyTeamID integer

Returns

boolean inRadar

Spring.IsUnitInView

function

function Spring.IsUnitInView(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? inView — nil when unitID cannot be parsed

Spring.IsUnitSelected

function

function Spring.IsUnitSelected(unitID: integer)

[source]

Params

unitID integer

Returns

boolean? isSelected — nil when unitID cannot be parsed

Spring.IsUnitVisible

function

function Spring.IsUnitVisible(unitID: integer, radius?: number, checkIcon: boolean)

[source]

Params

unitID integer
radius number? — unitRadius when not specified
checkIcon boolean

Returns

boolean? isVisible — nil when unitID cannot be parsed

Spring.IsUserWriting

function

function Spring.IsUserWriting()

[source]

Returns

boolean

Spring.KillTeam

function

function Spring.KillTeam(teamID: integer)

[source]

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

Gaia team cannot be killed.

Params

teamID integer

Returns

nil

Spring.LevelHeightMap

function

function Spring.LevelHeightMap(x1: number, z1: number, x2_height: number, z2?: number, height?: number)

[source]

Set a certain height to a point or rectangle area on the world

Params

x1 number
z1 number
x2_height number — if y2 and height are nil then this parameter is the height
z2 number?
height number?

Returns

nil

Spring.LevelOriginalHeightMap

function

function Spring.LevelOriginalHeightMap(x1: number, y1: number, x2_height: number, y2?: number, height?: number)

[source]

Set a height to a point or rectangle area to the original map height cache

Params

x1 number
y1 number
x2_height number — if y2 and height are nil then this parameter is the height
y2 number?
height number?

Returns

nil

Spring.LevelSmoothMesh

function

function Spring.LevelSmoothMesh(x1: number, z1: number, x2?: number, z2?: number, height: number)

[source]

Params

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

Returns

nil

Spring.LoadCmdColorsConfig

function

function Spring.LoadCmdColorsConfig(config: string)

[source]

Params

config string

Returns

nil

Spring.LoadCtrlPanelConfig

function

function Spring.LoadCtrlPanelConfig(config: string)

[source]

Params

config string

Returns

nil

Spring.LoadModelTextures

function

function Spring.LoadModelTextures(modelName: string)

[source]

Params

modelName string

Returns

boolean? success

Spring.LoadSoundDef

function

function Spring.LoadSoundDef(soundfile: string)

[source]

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

Params

soundfile string

Returns

boolean success

Spring.Log

function

function Spring.Log(section: string, logLevel?: integer|"debug"|"deprecated"|"error"|"fatal"...(+3), ...string)

[source]

logLevel:
    | "debug" -- LOG.DEBUG
    | "info" -- LOG.INFO
    | "notice" -- LOG.NOTICE (engine default)
    | "warning" -- LOG.WARNING
    | "deprecated" -- LOG.DEPRECATED
    | "error" -- LOG.ERROR
    | "fatal" -- LOG.FATAL

Params

section string
logLevel (integer|"debug"|"deprecated"|"error"|"fatal"...(+3))? — (Default: “notice”)
… string — messages

Spring.MarkerAddLine

function

function Spring.MarkerAddLine(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number, localOnly?: boolean, playerId?: number)

[source]

Params

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

Returns

nil

Spring.MarkerAddPoint

function

function Spring.MarkerAddPoint(x: number, y: number, z: number, text?: string, localOnly?: boolean)

[source]

Params

x number
y number
z number
text string? — (Default: “”)
localOnly boolean?

Returns

nil

Spring.MarkerErasePosition

function

function Spring.MarkerErasePosition(x: number, y: number, z: number, unused: nil, localOnly?: boolean, playerId?: number, alwaysErase?: boolean)

[source]

Issue an erase command for markers on the map.

Params

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

Returns

nil

Spring.PauseDollyCamera

function

function Spring.PauseDollyCamera(fraction: number)

[source]

Pause Dolly Camera

Params

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

Returns

nil

Spring.PauseSoundStream

function

function Spring.PauseSoundStream()

[source]

Pause any SoundStream currently running.

Returns

nil

Spring.Ping

function

function Spring.Ping(pingTag: number)

[source]

Send a ping request to the server

Params

pingTag number

Returns

nil

Spring.PlaySoundFile

function

function Spring.PlaySoundFile(soundfile: string, volume?: number, posx?: number, posy?: number, posz?: number, speedx?: number, speedy?: number, speedz?: number, channel?: "battle"|"general"|"sfx"|"ui"|"unitreply"...(+6))

[source]

channel:
    | "general" -- 0
    | "battle" -- Same as `"sfx" | 1`
    | "sfx" -- Same as `"battle" | 1`
    | "unitreply" -- Same as `"voice" | 2`
    | "voice" -- Same as `"unitreply" | 2`
    | "userinterface" -- Same as "ui" | 3`
    | "ui" -- Same as "userinterface" | 3`
    | 0 -- General
    | 1 -- SFX
    | 2 -- Voice
    | 3 -- User interface

Params

soundfile string
volume number? — (Default: 1.0)
posx number?
posy number?
posz number?
speedx number?
speedy number?
speedz number?
channel ("battle"|"general"|"sfx"|"ui"|"unitreply"...(+6))? — (Default: 0|"general")

Returns

boolean playSound

Spring.PlaySoundStream

function

function Spring.PlaySoundStream(oggfile: string, volume?: number, enqueue?: boolean)

[source]

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

Multiple sound streams may be played at once.

Params

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

Returns

boolean success

Spring.Pos2BuildPos

function

function Spring.Pos2BuildPos(unitDefID: integer, posX: number, posY: number, posZ: number, buildFacing?: number)

[source]

Snaps a position to the building grid

Params

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

Returns

number buildPosX
number buildPosY
number buildPosZ

Spring.PreloadFeatureDefModel

function

function Spring.PreloadFeatureDefModel(featureDefID: integer)

[source]

Params

featureDefID integer

Returns

nil

Spring.PreloadSoundItem

function

function Spring.PreloadSoundItem(name: string)

[source]

Params

name string

Returns

nil

Spring.PreloadUnitDefModel

function

function Spring.PreloadUnitDefModel(unitDefID: integer)

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

Params

unitDefID integer

Returns

nil

Spring.Quit

function

function Spring.Quit()

[source]

Closes the application

Returns

nil

Spring.RebuildSmoothMesh

function

function Spring.RebuildSmoothMesh()

[source]

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

Returns

nil

Spring.Reload

function

function Spring.Reload(startScript: string)

[source]

Params

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

Returns

nil

Spring.RemoveGrass

function

function Spring.RemoveGrass(x: number, z: number)

[source]

Params

x number
z number

Returns

nil

Spring.RemoveObjectDecal

function

function Spring.RemoveObjectDecal(unitID: integer)

[source]

Params

unitID integer

Returns

nil

Spring.RemoveUnitCmdDesc

function

function Spring.RemoveUnitCmdDesc(unitID: integer, cmdDescID?: integer)

[source]

Params

unitID integer
cmdDescID integer?

Spring.ReplaceMouseCursor

function

function Spring.ReplaceMouseCursor(oldFileName: string, newFileName: string, hotSpotTopLeft?: boolean)

[source]

Mass replace all occurrences of the cursor in all CursorCmds.

Params

oldFileName string
newFileName string
hotSpotTopLeft boolean? — (Default: false)

Returns

boolean? assigned

Spring.Restart

function

function Spring.Restart(commandline_args: string, startScript: string)

[source]

If this call returns, something went wrong

Params

commandline_args string — commandline arguments passed to spring executable.
startScript string

Returns

nil

Spring.ResumeDollyCamera

function

function Spring.ResumeDollyCamera()

[source]

Resume Dolly Camera

Returns

nil

Spring.RevertHeightMap

function

function Spring.RevertHeightMap(x1: number, y1: number, x2_factor: number, y2?: number, factor?: number)

[source]

Restore original map height to a point or rectangle area on the world

Params

x1 number
y1 number
x2_factor number — if y2 and factor are nil then this parameter is the factor
y2 number?
factor number?

Returns

nil

Spring.RevertOriginalHeightMap

function

function Spring.RevertOriginalHeightMap(x1: number, y1: number, x2_factor: number, y2?: number, factor?: number)

[source]

Restore original map height cache to a point or rectangle area on the world

Params

x1 number
y1 number
x2_factor number — if y2 and factor are nil then this parameter is the factor
y2 number?
factor number?

Returns

nil

Spring.RevertSmoothMesh

function

function Spring.RevertSmoothMesh(x1: number, z1: number, x2?: number, z2?: number, origFactor: number)

[source]

Params

x1 number
z1 number
x2 number?
z2 number?
origFactor number

Returns

nil

Spring.RunDollyCamera

function

function Spring.RunDollyCamera(runtime: number)

[source]

Runs Dolly Camera

Params

runtime number — Runtime in milliseconds.

Returns

nil

Spring.SDLSetTextInputRect

function

function Spring.SDLSetTextInputRect(x: number, y: number, width: number, height: number)

[source]

Params

x number
y number
width number
height number

Returns

nil

Spring.SDLStartTextInput

function

function Spring.SDLStartTextInput()

[source]

Returns

nil

Spring.SDLStopTextInput

function

function Spring.SDLStopTextInput()

[source]

Returns

nil

Spring.SelectUnit

function

function Spring.SelectUnit(unitID?: integer, append?: boolean)

[source]

Selects a single unit

Params

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

Returns

nil

Spring.SelectUnitArray

function

function Spring.SelectUnitArray(unitMap: table<any, integer>, append?: boolean)

[source]

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

Params

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

Returns

nil

Spring.SelectUnitMap

function

function Spring.SelectUnitMap(unitMap: table<integer, any>, append?: boolean)

[source]

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

Params

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

Returns

nil

Spring.SendCommands

function

function Spring.SendCommands(commands: string[])

[source]

Params

commands string[]

Spring.SendLuaGaiaMsg

function

function Spring.SendLuaGaiaMsg(message: string)

[source]

Params

message string

Returns

nil

Spring.SendLuaMenuMsg

function

function Spring.SendLuaMenuMsg(msg: string)

[source]

Params

msg string

Spring.SendLuaRulesMsg

function

function Spring.SendLuaRulesMsg(message: string)

[source]

Params

message string

Returns

nil

Spring.SendLuaUIMsg

function

function Spring.SendLuaUIMsg(message: string, mode: string)

[source]

Params

message string
mode string — s

Returns

nil

Spring.SendMessage

function

function Spring.SendMessage(message: string)

[source]

Params

message string

Returns

nil

Spring.SendMessageToAllyTeam

function

function Spring.SendMessageToAllyTeam(allyID: integer, message: string)

[source]

Params

allyID integer
message string

Returns

nil

Spring.SendMessageToPlayer

function

function Spring.SendMessageToPlayer(playerID: integer, message: string)

[source]

Params

playerID integer
message string

Returns

nil

Spring.SendMessageToSpectators

function

function Spring.SendMessageToSpectators(message: string)

[source]

Params

message string — <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage (“<PLAYER1> did something”) might display as “ProRusher did something”

Returns

nil

Spring.SendMessageToTeam

function

function Spring.SendMessageToTeam(teamID: integer, message: string)

[source]

Params

teamID integer
message string

Returns

nil

Spring.SendSkirmishAIMessage

function

function Spring.SendSkirmishAIMessage(aiTeam: number, message: string)

[source]

Params

aiTeam number
message string

Returns

boolean? ai_processed

Spring.SetActiveCommand

function

function Spring.SetActiveCommand(action: string, actionExtra?: string)

[source]

Params

action string
actionExtra string?

Returns

boolean? commandSet

Spring.SetAlly

function

function Spring.SetAlly(firstAllyTeamID: integer, secondAllyTeamID: integer, ally: boolean)

[source]

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

Params

firstAllyTeamID integer
secondAllyTeamID integer
ally boolean

Returns

nil

Spring.SetAllyTeamStartBox

function

function Spring.SetAllyTeamStartBox(allyTeamID: integer, xMin: number, zMin: number, xMax: number, zMax: number)

[source]

Changes the start box position of an allyTeam.

Params

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

Returns

nil

Spring.SetAtmosphere

function

function Spring.SetAtmosphere(params: AtmosphereParams)

[source]

It can be used to modify the following atmosphere parameters

Usage:

Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})

Params

params AtmosphereParams

Spring.SetAutoShowMetal

function

function Spring.SetAutoShowMetal(autoShow: boolean)

[source]

Params

autoShow boolean

Returns

nil

Spring.SetBoxSelectionByEngine

function

function Spring.SetBoxSelectionByEngine(state: boolean)

[source]

Params

state boolean

Returns

nil

Spring.SetBuildFacing

function

function Spring.SetBuildFacing(facing: number)

[source]

Params

facing number

Returns

nil

Spring.SetBuildSpacing

function

function Spring.SetBuildSpacing(spacing: number)

[source]

Params

spacing number

Returns

nil

Spring.SetCameraOffset

function

function Spring.SetCameraOffset(posX?: number, posY?: number, posZ?: number, tiltX?: number, tiltY?: number, tiltZ?: number)

[source]

Params

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

Returns

nil

Spring.SetCameraState

function

function Spring.SetCameraState(camState: camState, transitionTime?: number, transitionTimeFactor?: number, transitionTimeExponent?: number)

[source]

Sets camera state

The fields in camState must be consistent with the name/mode and current/new camera mode

multiplicative factor applied to this and all subsequent transition times for this camera mode.

Defaults to “CamTimeFactor” springsetting unless set previously. tween factor applied to this and all subsequent transitions for this camera mode.

Defaults to “CamTimeExponent” springsetting unless set previously.

Params

camState camState — Parameters for camera state

Highly dependent on the type of the current camera controller

transitionTime number? — (Default: 0) in nanoseconds
transitionTimeFactor number?
transitionTimeExponent number?

Returns

boolean set

Spring.SetCameraTarget

function

function Spring.SetCameraTarget(x: number, y: number, z: number, transTime?: number)

[source]

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

Params

x number
y number
z number
transTime number?

Returns

nil

Spring.SetClipboard

function

function Spring.SetClipboard(text: string)

[source]

Params

text string

Returns

nil

Spring.SetConfigFloat

function

function Spring.SetConfigFloat(name: string, value: number, useOverla?: boolean)

[source]

Params

name string
value number
useOverla boolean? — (Default: false) the value will only be set in memory, and not be restored for the next game.y

Returns

nil

Spring.SetConfigInt

function

function Spring.SetConfigInt(name: string, value: number, useOverlay?: boolean)

[source]

Params

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

Returns

nil

Spring.SetConfigString

function

function Spring.SetConfigString(name: string, value: number, useOverlay?: boolean)

[source]

Params

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

Returns

nil

Spring.SetCustomCommandDrawData

function

function Spring.SetCustomCommandDrawData(cmdID: integer, string: any, number: any)

[source]

Params

cmdID integer
string any
number any

Returns

boolean? assigned

Spring.SetDollyCameraCurve

function

function Spring.SetDollyCameraCurve(degree: number, cpoints: table, knots: table)

[source]

Sets Dolly Camera movement Curve

Params

degree number
cpoints table — NURBS control point positions {{x,y,z,weight}, ...}
knots table

Returns

nil

Spring.SetDollyCameraLookCurve

function

function Spring.SetDollyCameraLookCurve(degree: number, cpoints: table, knots: table)

[source]

Sets Dolly Camera Look Curve

Params

degree number
cpoints table — NURBS control point positions {{x,y,z,weight}, ...}
knots table

Returns

nil

Spring.SetDollyCameraLookPosition

function

function Spring.SetDollyCameraLookPosition(x: number, y: number, z: number)

[source]

Sets Dolly Camera Look Position

Params

x number
y number
z number

Returns

nil

Spring.SetDollyCameraLookUnit

function

function Spring.SetDollyCameraLookUnit(unitID: integer)

[source]

Sets target unit for Dolly Camera to look towards

Params

unitID integer — The unit to look at.

Returns

nil

Spring.SetDollyCameraMode

function

function Spring.SetDollyCameraMode(mode: 1|2)

[source]

Sets Dolly Camera movement mode

mode:
    | 1
    | 2

Params

mode 1|2 — 1 static position, 2 nurbs curve

Returns

nil

Spring.SetDollyCameraPosition

function

function Spring.SetDollyCameraPosition(x: number, y: number, z: number)

[source]

Sets Dolly Camera Position

Params

x number
y number
z number

Returns

nil

Spring.SetDollyCameraRelativeMode

function

function Spring.SetDollyCameraRelativeMode(relativeMode: number)

[source]

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

Params

relativeMode number — 1 world, 2 look target

Returns

nil

Spring.SetDrawGround

function

function Spring.SetDrawGround(drawGround: boolean)

[source]

Params

drawGround boolean

Returns

nil

Spring.SetDrawGroundDeferred

function

function Spring.SetDrawGroundDeferred(drawGroundDeferred: boolean, drawGroundForward?: boolean)

[source]

Params

drawGroundDeferred boolean
drawGroundForward boolean? — allows disabling of the forward pass

Returns

nil

Spring.SetDrawModelsDeferred

function

function Spring.SetDrawModelsDeferred(drawUnitsDeferred: boolean, drawFeaturesDeferred: boolean, drawUnitsForward?: boolean, drawFeaturesForward?: boolean)

[source]

Params

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

Returns

nil

Spring.SetDrawSelectionInfo

function

function Spring.SetDrawSelectionInfo(enable: boolean)

[source]

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

Params

enable boolean

Returns

nil

Spring.SetDrawSky

function

function Spring.SetDrawSky(drawSky: boolean)

[source]

Params

drawSky boolean

Returns

nil

Spring.SetDrawWater

function

function Spring.SetDrawWater(drawWater: boolean)

[source]

Params

drawWater boolean

Returns

nil

Spring.SetExperienceGrade

function

function Spring.SetExperienceGrade(expGrade: number, ExpPowerScale?: number, ExpHealthScale?: number, ExpReloadScale?: number)

[source]

Defines how often Callins.UnitExperience will be called.

Params

expGrade number
ExpPowerScale number?
ExpHealthScale number?
ExpReloadScale number?

Returns

nil

Spring.SetFactoryBuggerOff

function

function Spring.SetFactoryBuggerOff(unitID: integer, buggerOff?: boolean, offset?: number, radius?: number, relHeading?: number, spherical?: boolean, forced?: boolean)

[source]

Params

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

Returns

number|nil buggerOff

Spring.SetFeatureAlwaysUpdateMatrix

function

function Spring.SetFeatureAlwaysUpdateMatrix(featureID: integer, alwaysUpdateMat: number)

[source]

Params

featureID integer
alwaysUpdateMat number

Returns

nil

Spring.SetFeatureAlwaysVisible

function

function Spring.SetFeatureAlwaysVisible(featureID: integer, enable: boolean)

[source]

Params

featureID integer
enable boolean

Returns

nil

Spring.SetFeatureBlocking

function

function Spring.SetFeatureBlocking(featureID: integer, isBlocking: boolean, isSolidObjectCollidable: boolean, isProjectileCollidable: boolean, isRaySegmentCollidable: boolean, crushable: boolean, blockEnemyPushing: boolean, blockHeightChanges: boolean)

[source]

Params

featureID integer
isBlocking boolean
isSolidObjectCollidable boolean
isProjectileCollidable boolean
isRaySegmentCollidable boolean
crushable boolean
blockEnemyPushing boolean
blockHeightChanges boolean

Returns

nil

Spring.SetFeatureCollisionVolumeData

function

function Spring.SetFeatureCollisionVolumeData(featureID: integer, scaleX: number, scaleY: number, scaleZ: number, offsetX: number, offsetY: number, offsetZ: number, vType: number, tType: number, Axis: number)

[source]

Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.

Params

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

Returns

nil

Spring.SetFeatureDirection

function

function Spring.SetFeatureDirection(featureID: integer, dirX: number, dirY: number, dirZ: number)

[source]

Params

featureID integer
dirX number
dirY number
dirZ number

Returns

nil

Spring.SetFeatureEngineDrawMask

function

function Spring.SetFeatureEngineDrawMask(featureID: integer, engineDrawMask: number)

[source]

Params

featureID integer
engineDrawMask number

Returns

nil

Spring.SetFeatureFade

function

function Spring.SetFeatureFade(featureID: integer, allow: boolean)

[source]

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

Params

featureID integer
allow boolean

Returns

nil

Spring.SetFeatureHeadingAndUpDir

function

function Spring.SetFeatureHeadingAndUpDir(featureID: integer, heading: number, upx: number, upy: number, upz: number)

[source]

Use this call to set up feature direction in a robust way. Heading (-32768 to 32767) represents a 2D (xz plane) feature orientation 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.

Params

featureID integer
heading number
upx number
upy number
upz number

Returns

nil

Spring.SetFeatureHealth

function

function Spring.SetFeatureHealth(featureID: integer, health: number)

[source]

Params

featureID integer
health number

Returns

nil

Spring.SetFeatureMass

function

function Spring.SetFeatureMass(featureID: integer, mass: number)

[source]

Params

featureID integer
mass number

Returns

nil

Spring.SetFeatureMaxHealth

function

function Spring.SetFeatureMaxHealth(featureID: integer, maxHealth: number)

[source]

Params

featureID integer
maxHealth number — minimum 0.1

Returns

nil

Spring.SetFeatureMidAndAimPos

function

function Spring.SetFeatureMidAndAimPos(featureID: integer, mpX: number, mpY: number, mpZ: number, apX: number, apY: number, apZ: number, relative?: boolean)

[source]

Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.

Params

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

Returns

boolean success

Spring.SetFeatureMoveCtrl

function

function Spring.SetFeatureMoveCtrl(featureID: integer, enable?: boolean, arg1?: number, arg2?: number, argn?: number)

[source]

Use this callout to control feature movement. The arg* arguments are parsed as follows and all optional:

If enable is true: [, velVector(x,y,z) * initial velocity for feature [, accVector(x,y,z) * acceleration added every frame]]

If enable is false: [, velocityMask(x,y,z) * dimensions in which velocity is allowed to build when not using MoveCtrl [, impulseMask(x,y,z) * dimensions in which impulse is allowed to apply when not using MoveCtrl [, movementMask(x,y,z) * dimensions in which feature is allowed to move when not using MoveCtrl]]]

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

For example use Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1) to unlock all movement prior to making Spring.SetFeatureVelocity calls.

Params

featureID integer
enable boolean?
arg1 number?
arg2 number?
argn number?

Returns

nil

Spring.SetFeatureNoDraw

function

function Spring.SetFeatureNoDraw(featureID: integer, noDraw: boolean)

[source]

Params

featureID integer
noDraw boolean

Returns

nil

Spring.SetFeatureNoSelect

function

function Spring.SetFeatureNoSelect(featureID: integer, noSelect: boolean)

[source]

Params

featureID integer
noSelect boolean

Returns

nil

Spring.SetFeaturePhysics

function

function Spring.SetFeaturePhysics(featureID: integer, posX: number, posY: number, posZ: number, velX: number, velY: number, velZ: number, rotX: number, rotY: number, rotZ: number, dragX: number, dragY: number, dragZ: number)

[source]

Params

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

Returns

nil

Spring.SetFeaturePieceCollisionVolumeData

function

function Spring.SetFeaturePieceCollisionVolumeData(featureID: integer, pieceIndex: number, enable: boolean, scaleX: number, scaleY: number, scaleZ: number, offsetX: number, offsetY: number, offsetZ: number, Axis: number, volumeType: number, primaryAxis?: number)

[source]

Params

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

Returns

nil

Spring.SetFeaturePieceVisible

function

function Spring.SetFeaturePieceVisible(featureID: integer, pieceIndex: number, visible: boolean)

[source]

Params

featureID integer
pieceIndex number
visible boolean

Returns

nil

Spring.SetFeaturePosition

function

function Spring.SetFeaturePosition(featureID: integer, x: number, y: number, z: number, snapToGround?: boolean)

[source]

Params

featureID integer
x number
y number
z number
snapToGround boolean?

Returns

nil

Spring.SetFeatureRadiusAndHeight

function

function Spring.SetFeatureRadiusAndHeight(featureID: integer, radius: number, height: number)

[source]

Params

featureID integer
radius number
height number

Returns

boolean success

Spring.SetFeatureReclaim

function

function Spring.SetFeatureReclaim(featureID: integer, reclaimLeft: number)

[source]

Params

featureID integer
reclaimLeft number

Returns

nil

Spring.SetFeatureResources

function

function Spring.SetFeatureResources(featureID: integer, metal: number, energy: number, reclaimTime?: number, reclaimLeft?: number, featureDefMetal?: number, featureDefEnergy?: number)

[source]

Params

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

Returns

nil

Spring.SetFeatureResurrect

function

function Spring.SetFeatureResurrect(featureID: integer, unitDef: string|integer, facing?: "e"|"east"|"n"|"north"|"s"...(+7), progress?: number)

[source]

facing:
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | "s" -- South
    | "e" -- East
    | "n" -- North
    | "w" -- West
    | "south" -- South
    | "east" -- East
    | "north" -- North
    | "west" -- West

Params

featureID integer
unitDef string|integer — Can be a number id or a string name, this allows cancelling resurrection by passing -1.
facing ("e"|"east"|"n"|"north"|"s"...(+7))? — (Default: "south")
progress number? — Set the level of progress.

Returns

nil

Spring.SetFeatureRotation

function

function Spring.SetFeatureRotation(featureID: integer, rotX: number, rotY: number, rotZ: number)

[source]

Params

featureID integer
rotX number
rotY number
rotZ number

Returns

nil

Spring.SetFeatureRulesParam

function

function Spring.SetFeatureRulesParam(featureID: integer, paramName: string, paramValue?: string|number, losAccess?: losAccess)

[source]

Params

featureID integer
paramName string
paramValue (string|number)? — numeric paramValues in quotes will be converted to number.
losAccess losAccess? — Parameters for los access

If one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with inradar=true even if the param has inlos=false) All GameRulesParam are public, TeamRulesParams can just be private,allied and/or public You can read RulesParams from any Lua environments! With those losAccess policies you can limit their access.

All GameRulesParam are public, TeamRulesParams can just be private,allied and/or public You can read RulesParams from any Lua environments! With those losAccess policies you can limit their access.

Returns

nil

Spring.SetFeatureSelectionVolumeData

function

function Spring.SetFeatureSelectionVolumeData(featureID: integer, scaleX: number, scaleY: number, scaleZ: number, offsetX: number, offsetY: number, offsetZ: number, vType: number, tType: number, Axis: number)

[source]

Params

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

Returns

nil

Spring.SetFeatureUseAirLos

function

function Spring.SetFeatureUseAirLos(featureID: integer, useAirLos: boolean)

[source]

Params

featureID integer
useAirLos boolean

Returns

nil

Spring.SetFeatureVelocity

function

function Spring.SetFeatureVelocity(featureID: integer, velX: number, velY: number, velZ: number)

[source]

Params

featureID integer
velX number
velY number
velZ number

Returns

nil

Spring.SetGameRulesParam

function

function Spring.SetGameRulesParam(paramName: string, paramValue?: string|number, losAccess?: losAccess)

[source]

Params

paramName string
paramValue (string|number)? — numeric paramValues in quotes will be converted to number.
losAccess losAccess? — Parameters for los access

Returns

nil

Spring.SetGlobalLos

function

function Spring.SetGlobalLos(allyTeamID: integer, globallos: boolean)

[source]

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

Params

allyTeamID integer
globallos boolean

Returns

nil

Spring.SetGroundDecalAlpha

function

function Spring.SetGroundDecalAlpha(decalID: integer, alpha?: number, alphaFalloff?: number)

[source]

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalCreationFrame

function

function Spring.SetGroundDecalCreationFrame(decalID: integer, creationFrameMin?: number, creationFrameMax?: number)

[source]

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

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalMisc

function

function Spring.SetGroundDecalMisc(decalID: integer, dotElimExp?: number, refHeight?: number, minHeight?: number, maxHeight?: number, forceHeightMode?: number)

[source]

Sets varios secondary parameters of a decal

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalNormal

function

function Spring.SetGroundDecalNormal(decalID: integer, normalX?: number, normalY?: number, normalZ?: number)

[source]

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

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalPosAndDims

function

function Spring.SetGroundDecalPosAndDims(decalID: integer, midPosX?: number, midPosZ?: number, sizeX?: number, sizeZ?: number, projCubeHeight?: number)

[source]

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalQuadPosAndHeight

function

function Spring.SetGroundDecalQuadPosAndHeight(decalID: integer, posTL?: xz, posTR?: xz, posBR?: xz, posBL?: xz, projCubeHeight?: number)

[source]

Use for non-rectangular decals

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalRotation

function

function Spring.SetGroundDecalRotation(decalID: integer, rot?: number)

[source]

Params

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

Returns

boolean decalSet

Spring.SetGroundDecalTexture

function

function Spring.SetGroundDecalTexture(decalID: integer, textureName: string, isMainTex?: boolean)

[source]

Params

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

Returns

boolean|nil decalSet

Spring.SetGroundDecalTextureParams

function

function Spring.SetGroundDecalTextureParams(decalID: integer, texWrapDistance?: number, texTraveledDistance?: number)

[source]

Params

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

Returns

boolean|nil decalSet

Spring.SetGroundDecalTint

function

function Spring.SetGroundDecalTint(decalID: integer, tintColR?: number, tintColG?: number, tintColB?: number, tintColA?: number)

[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

Params

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

Returns

boolean decalSet

Spring.SetHeightMap

function

function Spring.SetHeightMap(x: number, z: number, height: number, terraform?: number)

[source]

Can only be called in Spring.SetHeightMapFunc. The terraform argument is

Params

x number
z number
height number
terraform number? — (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

function Spring.SetHeightMapFunc(luaFunction: function, arg: number, ...number)

[source]

Example code:

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

Params

luaFunction function
arg number
… number

Returns

integer? absTotalHeightMapAmountChanged

Spring.SetLastMessagePosition

function

function Spring.SetLastMessagePosition(x: number, y: number, z: number)

[source]

Params

x number
y number
z number

Returns

nil

Spring.SetLogSectionFilterLevel

function

function Spring.SetLogSectionFilterLevel(sectionName: string, logLevel?: string|number)

[source]

Params

sectionName string
logLevel (string|number)?

Returns

nil

Spring.SetLosViewColors

function

function Spring.SetLosViewColors(always: rgb, LOS: rgb, radar: rgb, jam: rgb, radar2: rgb)

[source]

Params

always rgb — Color triple (RGB)
LOS rgb — Color triple (RGB)
radar rgb — Color triple (RGB)
jam rgb — Color triple (RGB)
radar2 rgb — Color triple (RGB)

Returns

nil

Spring.SetMapLightTrackingState

function

function Spring.SetMapLightTrackingState(lightHandle: number, unitOrProjectileID: integer, enableTracking: boolean, unitOrProjectile: boolean)

[source]

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

Params

lightHandle number
unitOrProjectileID integer
enableTracking boolean
unitOrProjectile boolean

Returns

boolean success

Spring.SetMapRenderingParams

function

function Spring.SetMapRenderingParams(params: MapRenderingParams)

[source]

Allows to change map rendering params at runtime.

Params

params MapRenderingParams — Map rendering params

Returns

nil

Spring.SetMapShader

function

function Spring.SetMapShader(standardShaderID: integer, deferredShaderID: integer)

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

Params

standardShaderID integer
deferredShaderID integer

Returns

nil

Spring.SetMapShadingTexture

function

function Spring.SetMapShadingTexture(texType: string, texName: string)

[source]

Params

texType string
texName string

Returns

boolean success

Spring.SetMapSquareTerrainType

function

function Spring.SetMapSquareTerrainType(x: number, z: number, newType: number)

[source]

Params

x number
z number
newType number

Returns

integer? oldType

Spring.SetMapSquareTexture

function

function Spring.SetMapSquareTexture(texSqrX: number, texSqrY: number, luaTexName: string)

[source]

Params

texSqrX number
texSqrY number
luaTexName string

Returns

boolean success

Spring.SetMetalAmount

function

function Spring.SetMetalAmount(x: integer, z: integer, metalAmount: number)

[source]

Params

x integer — in worldspace/16.
z integer — in worldspace/16.
metalAmount number — must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).

Returns

nil

Spring.SetModelLightTrackingState

function

function Spring.SetModelLightTrackingState(lightHandle: number, unitOrProjectileID: integer, enableTracking: boolean, unitOrProjectile: boolean)

[source]

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

Params

lightHandle number
unitOrProjectileID integer
enableTracking boolean
unitOrProjectile boolean

Returns

boolean success

Spring.SetMouseCursor

function

function Spring.SetMouseCursor(cursorName: string, cursorScale?: number)

[source]

Params

cursorName string
cursorScale number? — (Default: 1.0)

Returns

nil

Spring.SetNanoProjectileParams

function

function Spring.SetNanoProjectileParams(rotVal?: number, rotVel?: number, rotAcc?: number, rotValRng?: number, rotVelRng?: number, rotAccRng?: number)

[source]

Params

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

Returns

nil

Spring.SetNoPause

function

function Spring.SetNoPause(noPause: boolean)

[source]

Params

noPause boolean

Returns

nil

Spring.SetOriginalHeightMap

function

function Spring.SetOriginalHeightMap(x: number, y: number, height: number, factor?: number)

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

Params

x number
y number
height number
factor number?

Returns

nil

Spring.SetOriginalHeightMapFunc

function

function Spring.SetOriginalHeightMapFunc(heightMapFunc: function)

[source]

Cannot recurse on itself

Params

heightMapFunc function

Returns

nil

Spring.SetPieceProjectileParams

function

function Spring.SetPieceProjectileParams(projectileID: integer, explosionFlags?: number, spinAngle?: number, spinSpeed?: number, spinVectorX?: number, spinVectorY?: number, spinVectorZ?: number)

[source]

Params

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

Returns

nil

Spring.SetPlayerRulesParam

function

function Spring.SetPlayerRulesParam(playerID: integer, paramName: string, paramValue?: string|number, losAccess?: losAccess)

[source]

Params

playerID integer
paramName string
paramValue (string|number)? — numeric paramValues in quotes will be converted to number.
losAccess losAccess? — Parameters for los access

Returns

nil

Spring.SetProjectileAlwaysVisible

function

function Spring.SetProjectileAlwaysVisible(projectileID: integer, alwaysVisible: boolean)

[source]

Params

projectileID integer
alwaysVisible boolean

Returns

nil

Spring.SetProjectileCEG

function

function Spring.SetProjectileCEG(projectileID: integer, ceg_name: string)

[source]

Params

projectileID integer
ceg_name string

Returns

nil

Spring.SetProjectileCollision

function

function Spring.SetProjectileCollision(projectileID: integer)

[source]

Params

projectileID integer

Returns

nil

Spring.SetProjectileDamages

function

function Spring.SetProjectileDamages(unitID: integer, weaponNum: number, key: string, value: number)

[source]

Params

unitID integer
weaponNum number
key string
value number

Returns

nil

Spring.SetProjectileGravity

function

function Spring.SetProjectileGravity(projectileID: integer, grav?: number)

[source]

Params

projectileID integer
grav number? — (Default: 0)

Returns

nil

Spring.SetProjectileIgnoreTrackingError

function

function Spring.SetProjectileIgnoreTrackingError(projectileID: integer, ignore: boolean)

[source]

Params

projectileID integer
ignore boolean

Returns

nil

Spring.SetProjectileIsIntercepted

function

function Spring.SetProjectileIsIntercepted(projectileID: integer)

[source]

Params

projectileID integer

Returns

nil

Spring.SetProjectileMoveControl

function

function Spring.SetProjectileMoveControl(projectileID: integer, enable: boolean)

[source]

Disables engine movecontrol, so lua can fully control the physics.

Params

projectileID integer
enable boolean

Returns

nil

Spring.SetProjectilePosition

function

function Spring.SetProjectilePosition(projectileID: integer, posX?: number, posY?: number, posZ?: number)

[source]

Params

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

Returns

nil

Spring.SetProjectileTarget

function

function Spring.SetProjectileTarget(projectileID: integer, arg1?: number, arg2?: number, posZ?: number)

[source]

targetTypeStr can be one of: ‘u’ - unit ‘f’ - feature ‘p’ - projectile while targetTypeInt is one of: string.byte(‘g’) := GROUND string.byte(‘u’) := UNIT string.byte(‘f’) := FEATURE string.byte(‘p’) := PROJECTILE

Params

projectileID integer
arg1 number? — (Default: 0) targetID or posX
arg2 number? — (Default: 0) targetType or posY
posZ number? — (Default: 0)

Returns

boolean? validTarget

Spring.SetProjectileTimeToLive

function

function Spring.SetProjectileTimeToLive(projectileID: integer, ttl: number)

[source]

Params

projectileID integer
ttl number — Remaining time to live in frames

Returns

nil

Spring.SetProjectileUseAirLos

function

function Spring.SetProjectileUseAirLos(projectileID: integer, useAirLos: boolean)

[source]

Params

projectileID integer
useAirLos boolean

Returns

nil

Spring.SetProjectileVelocity

function

function Spring.SetProjectileVelocity(projectileID: integer, velX?: number, velY?: number, velZ?: number)

[source]

Params

projectileID integer
velX number? — (Default: 0)
velY number? — (Default: 0)
velZ number? — (Default: 0)

Returns

nil

Spring.SetRadarErrorParams

function

function Spring.SetRadarErrorParams(allyTeamID: integer, allyteamErrorSize: number, baseErrorSize?: number, baseErrorMult?: number)

[source]

Params

allyTeamID integer
allyteamErrorSize number
baseErrorSize number?
baseErrorMult number?

Returns

nil

Spring.SetShareLevel

function

function Spring.SetShareLevel(resource: string, shareLevel: number)

[source]

Params

resource string — metal energy
shareLevel number

Returns

nil

Spring.SetSkyBoxTexture

function

function Spring.SetSkyBoxTexture(texName: string)

[source]

Params

texName string

Returns

nil

Spring.SetSmoothMesh

function

function Spring.SetSmoothMesh(x: number, z: number, height: number, terraform?: number)

[source]

Can only be called in Spring.SetSmoothMeshFunc.

Params

x number
z number
height number
terraform number? — (Default: 1)

Returns

number? The — absolute height difference, or nil if coordinates are invalid.

Spring.SetSmoothMeshFunc

function

function Spring.SetSmoothMeshFunc(luaFunction: function, arg?: any, ...any)

[source]

Params

luaFunction function
arg any
… any

Returns

number? absTotalHeightMapAmountChanged

Spring.SetSoundEffectParams

function

function Spring.SetSoundEffectParams()

[source]

Spring.SetSoundStreamVolume

function

function Spring.SetSoundStreamVolume(volume: number)

[source]

Set volume for SoundStream

Params

volume number

Returns

nil

Spring.SetSquareBuildingMask

function

function Spring.SetSquareBuildingMask(x: number, z: number, mask: number)

[source]

Params

x number
z number
mask number

Returns

nil

Spring.SetSunDirection

function

function Spring.SetSunDirection(dirX: number, dirY: number, dirZ: number, intensity?: number)

[source]

Params

dirX number
dirY number
dirZ number
intensity number? — (Default: 1.0)

Returns

nil

Spring.SetSunLighting

function

function Spring.SetSunLighting(params: { groundAmbientColor: rgb, groundDiffuseColor: rgb })

[source]

Modify sun lighting parameters.

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

Params

params { groundAmbientColor: rgb, groundDiffuseColor: rgb }

Spring.SetTeamColor

function

function Spring.SetTeamColor(teamID: integer, r: number, g: number, b: number)

[source]

Params

teamID integer
r number
g number
b number

Returns

nil

Spring.SetTeamResource

function

function Spring.SetTeamResource(teamID: integer, resource: "e"|"energy"|"energyStorage"|"es"|"m"...(+3), amount: number)

[source]

resource:
    | "metal"
    | "energy"
    | "m"
    | "e"
    | "metalStorage"
    | "energyStorage"
    | "ms"
    | "es"

Params

teamID integer
resource "e"|"energy"|"energyStorage"|"es"|"m"...(+3)
amount number

Returns

nil

Spring.SetTeamRulesParam

function

function Spring.SetTeamRulesParam(teamID: integer, paramName: string, paramValue?: string|number, losAccess?: losAccess)

[source]

Params

teamID integer
paramName string
paramValue (string|number)? — numeric paramValues in quotes will be converted to number.
losAccess losAccess? — Parameters for los access

Returns

nil

Spring.SetTeamShareLevel

function

function Spring.SetTeamShareLevel(teamID: integer, type: "e"|"energy"|"m"|"metal", amount: number)

[source]

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

type:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

teamID integer
type "e"|"energy"|"m"|"metal"
amount number

Returns

nil

Spring.SetTerrainTypeData

function

function Spring.SetTerrainTypeData(typeIndex: number, speedTanks?: number, speedKBOts?: number, speedHovers?: number, speedShips?: number)

[source]

Params

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

Returns

boolean? true

Spring.SetTidal

function

function Spring.SetTidal(strength: number)

[source]

Set tidal strength

Params

strength number

Returns

nil

Spring.SetUnitAlwaysUpdateMatrix

function

function Spring.SetUnitAlwaysUpdateMatrix(unitID: integer, alwaysUpdateMatrix: boolean)

[source]

Params

unitID integer
alwaysUpdateMatrix boolean

Returns

nil

Spring.SetUnitAlwaysVisible

function

function Spring.SetUnitAlwaysVisible(unitID: integer, alwaysVisible: boolean)

[source]

Params

unitID integer
alwaysVisible boolean

Returns

nil

Spring.SetUnitArmored

function

function Spring.SetUnitArmored(unitID: integer, armored?: boolean, armorMultiple?: number)

[source]

Params

unitID integer
armored boolean?
armorMultiple number?

Returns

nil

Spring.SetUnitBlocking

function

function Spring.SetUnitBlocking(unitID: integer, isblocking: boolean, isSolidObjectCollidable: boolean, isProjectileCollidable: boolean, isRaySegmentCollidable: boolean, crushable: boolean, blockEnemyPushing: boolean, blockHeightChanges: boolean)

[source]

Params

unitID integer
isblocking boolean
isSolidObjectCollidable boolean
isProjectileCollidable boolean
isRaySegmentCollidable boolean
crushable boolean
blockEnemyPushing boolean
blockHeightChanges boolean

Returns

nil

Spring.SetUnitBuildParams

function

function Spring.SetUnitBuildParams(unitID: integer, paramName: string, value: boolean|number)

[source]

Params

unitID integer
paramName string — one of buildRange buildDistance buildRange3D
value boolean|number — boolean when paramName is buildRange3D, otherwise number.

Returns

nil

Spring.SetUnitBuildSpeed

function

function Spring.SetUnitBuildSpeed(builderID: integer, buildSpeed: number, repairSpeed?: number, reclaimSpeed?: number, captureSpeed?: number, terraformSpeed?: number)

[source]

Params

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

Returns

nil

Spring.SetUnitBuildeeRadius

function

function Spring.SetUnitBuildeeRadius(unitID: integer, build: number)

[source]

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

Params

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

Returns

nil

Spring.SetUnitCloak

function

function Spring.SetUnitCloak(unitID: integer, cloak: boolean|number, cloakArg: boolean|number)

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

Params

unitID integer
cloak boolean|number
cloakArg boolean|number

Returns

nil

Spring.SetUnitCollisionVolumeData

function

function Spring.SetUnitCollisionVolumeData(unitID: integer, scaleX: number, scaleY: number, scaleZ: number, offsetX: number, offsetY: number, offsetZ: number, vType: number, tType: number, Axis: number)

[source]

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

Params

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

Returns

nil

Spring.SetUnitCosts

function

function Spring.SetUnitCosts(unitID: integer, where: table<number, number>)

[source]

Params

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

Returns

nil

Spring.SetUnitCrashing

function

function Spring.SetUnitCrashing(unitID: integer, crashing: boolean)

[source]

Params

unitID integer
crashing boolean

Returns

boolean success

Spring.SetUnitDefIcon

function

function Spring.SetUnitDefIcon(unitDefID: integer, iconName: string)

[source]

Params

unitDefID integer
iconName string

Returns

nil

Spring.SetUnitDefImage

function

function Spring.SetUnitDefImage(unitDefID: integer, image: string)

[source]

Params

unitDefID integer
image string — luaTexture texFile

Returns

nil

Spring.SetUnitDirection

function

function Spring.SetUnitDirection(unitID: integer, x: number, y: number, z: number)

[source]

Params

unitID integer
x number
y number
z number

Returns

nil

Spring.SetUnitEngineDrawMask

function

function Spring.SetUnitEngineDrawMask(unitID: integer, drawMask: number)

[source]

Params

unitID integer
drawMask number

Returns

nil

Spring.SetUnitExperience

function

function Spring.SetUnitExperience(unitID: integer, experience: number)

[source]

See:

Params

unitID integer
experience number

Returns

nil

Spring.SetUnitFlanking

function

function Spring.SetUnitFlanking(unitID: integer, type: string, arg1: number, y?: number, z?: number)

[source]

Params

unitID integer
type string — dir
arg1 number — x minDamage maxDamage moveFactor mode
y number? — only when type is “dir”
z number? — only when type is “dir”

Returns

nil

Spring.SetUnitGroup

function

function Spring.SetUnitGroup(unitID: integer, groupID: number)

[source]

Params

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

Returns

nil

Spring.SetUnitHarvestStorage

function

function Spring.SetUnitHarvestStorage(unitID: integer, metal: number)

[source]

Params

unitID integer
metal number

Returns

nil

Spring.SetUnitHeadingAndUpDir

function

function Spring.SetUnitHeadingAndUpDir(unitID: integer, heading: number, upx: number, upy: number, upz: number)

[source]

Use this call to set up unit direction in a robust way. Heading (-32768 to 32767) represents a 2D (xz plane) unit orientation 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.

Params

unitID integer
heading number
upx number
upy number
upz number

Returns

nil

Spring.SetUnitHealth

function

function Spring.SetUnitHealth(unitID: integer, health: number|table<string, number>)

[source]

Params

unitID integer
health number|table<string, number> — where keys can be one of health capture paralyze build and values are amounts

Returns

nil

Spring.SetUnitIconDraw

function

function Spring.SetUnitIconDraw(unitID: integer, drawIcon: boolean)

[source]

Params

unitID integer
drawIcon boolean

Returns

nil

Spring.SetUnitLandGoal

function

function Spring.SetUnitLandGoal(unitID: integer, goalX: number, goalY: number, goalZ: number, goalRadius?: number)

[source]

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

Params

unitID integer
goalX number
goalY number
goalZ number
goalRadius number?

Returns

nil

Spring.SetUnitLeaveTracks

function

function Spring.SetUnitLeaveTracks(unitID: integer, unitLeaveTracks: boolean)

[source]

Params

unitID integer
unitLeaveTracks boolean — whether unit leaves tracks on movement

Returns

nil

Spring.SetUnitLoadingTransport

function

function Spring.SetUnitLoadingTransport(passengerID: integer, transportID: integer)

[source]

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

Params

passengerID integer
transportID integer

Returns

nil

Spring.SetUnitLosMask

function

function Spring.SetUnitLosMask(unitID: integer, allyTeam: number, losTypes: number|table)

[source]

The 3rd argument is either the bit-and combination of the following numbers:

LOS_INLOS = 1 LOS_INRADAR = 2 LOS_PREVLOS = 4 LOS_CONTRADAR = 8

or a table of the following form:

losTypes = { [los = boolean,] [radar = boolean,] [prevLos = boolean,] [contRadar = boolean] }

Params

unitID integer
allyTeam number
losTypes number|table

Returns

nil

Spring.SetUnitLosState

function

function Spring.SetUnitLosState(unitID: integer, allyTeam: number, los: number|table)

[source]

Params

unitID integer
allyTeam number
los number|table

Returns

nil

Spring.SetUnitMass

function

function Spring.SetUnitMass(unitID: integer, mass: number)

[source]

Params

unitID integer
mass number

Returns

nil

Spring.SetUnitMaxHealth

function

function Spring.SetUnitMaxHealth(unitID: integer, maxHealth: number)

[source]

Params

unitID integer
maxHealth number

Returns

nil

Spring.SetUnitMaxRange

function

function Spring.SetUnitMaxRange(unitID: integer, maxRange: number)

[source]

Params

unitID integer
maxRange number

Returns

nil

Spring.SetUnitMetalExtraction

function

function Spring.SetUnitMetalExtraction(unitID: integer, depth: number, range?: number)

[source]

Params

unitID integer
depth number — corresponds to metal extraction rate
range number? — similar to “extractsMetal” in unitDefs.

Returns

nil

Spring.SetUnitMidAndAimPos

function

function Spring.SetUnitMidAndAimPos(unitID: integer, mpX: number, mpY: number, mpZ: number, apX: number, apY: number, apZ: number, relative?: boolean)

[source]

Params

unitID integer
mpX number — new middle positionX of unit
mpY number — new middle positionY of unit
mpZ number — new middle positionZ of unit
apX number — new positionX that enemies aim at on this unit
apY number — new positionY that enemies aim at on this unit
apZ number — new positionZ that enemies aim at on this unit
relative boolean? — (Default: false) are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!

Returns

boolean success

Spring.SetUnitMoveGoal

function

function Spring.SetUnitMoveGoal(unitID: integer, goalX: number, goalY: number, goalZ: number, goalRadius?: number, moveSpeed?: number, moveRaw?: boolean)

[source]

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

Params

unitID integer
goalX number
goalY number
goalZ number
goalRadius number?
moveSpeed number?
moveRaw boolean?

Returns

nil

Spring.SetUnitNanoPieces

function

function Spring.SetUnitNanoPieces(builderID: integer, pieces: table)

[source]

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

Params

builderID integer
pieces table

Returns

nil

Spring.SetUnitNeutral

function

function Spring.SetUnitNeutral(unitID: integer, neutral: boolean)

[source]

Params

unitID integer
neutral boolean

Returns

boolean|nil setNeutral

Spring.SetUnitNoDraw

function

function Spring.SetUnitNoDraw(unitID: integer, noDraw: boolean)

[source]

Params

unitID integer
noDraw boolean

Returns

nil

Spring.SetUnitNoGroup

function

function Spring.SetUnitNoGroup(unitID: integer, unitNoGroup: boolean)

[source]

Params

unitID integer
unitNoGroup boolean — Whether unit can be added to selection groups

Spring.SetUnitNoMinimap

function

function Spring.SetUnitNoMinimap(unitID: integer, unitNoMinimap: boolean)

[source]

Params

unitID integer
unitNoMinimap boolean

Returns

nil

Spring.SetUnitNoSelect

function

function Spring.SetUnitNoSelect(unitID: integer, unitNoSelect: boolean)

[source]

Params

unitID integer
unitNoSelect boolean — whether unit can be selected or not

Returns

nil

Spring.SetUnitPhysicalStateBit

function

function Spring.SetUnitPhysicalStateBit(unitID: integer, Physical: number)

[source]

Params

unitID integer
Physical number — [bit] state bit

Returns

nil

Spring.SetUnitPhysics

function

function Spring.SetUnitPhysics(unitID: integer, posX: number, posY: number, posZ: number, velX: number, velY: number, velZ: number, rotX: number, rotY: number, rotZ: number, dragX: number, dragY: number, dragZ: number)

[source]

Params

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

Returns

nil

Spring.SetUnitPieceCollisionVolumeData

function

function Spring.SetUnitPieceCollisionVolumeData(unitID: integer, pieceIndex: number, enable: boolean, scaleX: number, scaleY: number, scaleZ: number, offsetX: number, offsetY: number, offsetZ: number, volumeType?: number, primaryAxis?: number)

[source]

Params

unitID integer
pieceIndex number
enable boolean
scaleX number
scaleY number
scaleZ number
offsetX number
offsetY number
offsetZ number
volumeType number?
primaryAxis number?

Returns

nil

Spring.SetUnitPieceMatrix

function

function Spring.SetUnitPieceMatrix(unitID: integer, pieceNum: number, matrix: number[])

[source]

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

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

Params

unitID integer
pieceNum number
matrix number[] — an array of 16 floats

Returns

nil

Spring.SetUnitPieceParent

function

function Spring.SetUnitPieceParent(unitID: integer, AlteredPiece: number, ParentPiece: number)

[source]

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

Params

unitID integer
AlteredPiece number
ParentPiece number

Returns

nil

Spring.SetUnitPieceVisible

function

function Spring.SetUnitPieceVisible(unitID: integer, pieceIndex: number, visible: boolean)

[source]

Params

unitID integer
pieceIndex number
visible boolean

Returns

nil

Spring.SetUnitPosErrorParams

function

function Spring.SetUnitPosErrorParams(unitID: integer, posErrorVectorX: number, posErrorVectorY: number, posErrorVectorZ: number, posErrorDeltaX: number, posErrorDeltaY: number, posErrorDeltaZ: number, nextPosErrorUpdate?: number)

[source]

Sets a unit’s radar wobble

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

Params

unitID integer
posErrorVectorX number
posErrorVectorY number
posErrorVectorZ number
posErrorDeltaX number
posErrorDeltaY number
posErrorDeltaZ number
nextPosErrorUpdate number?

Returns

nil

Spring.SetUnitPosition

function

function Spring.SetUnitPosition(unitID: integer, x: number, z: number, floating?: boolean)

[source]

Set unit position (2D)

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

Params

unitID integer
x number
z number
floating boolean? — (Default: false) If true, over water the position is on surface. If false, on seafloor.

Returns

nil

Spring.SetUnitRadiusAndHeight

function

function Spring.SetUnitRadiusAndHeight(unitID: integer, radius: number, height: number)

[source]

Params

unitID integer
radius number
height number

Returns

boolean success

Spring.SetUnitResourcing

function

function Spring.SetUnitResourcing(unitID: integer, res: string, amount: number)

[source]

Params

unitID integer
res string
amount number

Returns

nil

Spring.SetUnitRotation

function

function Spring.SetUnitRotation(unitID: integer, yaw: number, pitch: number, roll: number)

[source]

Params

unitID integer
yaw number
pitch number
roll number

Returns

nil

Spring.SetUnitRulesParam

function

function Spring.SetUnitRulesParam(unitID: integer, paramName: string, paramValue?: string|number, losAccess?: losAccess)

[source]

Params

unitID integer
paramName string
paramValue (string|number)? — numeric paramValues in quotes will be converted to number.
losAccess losAccess? — Parameters for los access

Returns

nil

Spring.SetUnitSeismicSignature

function

function Spring.SetUnitSeismicSignature(unitID: integer, seismicSignature: number)

[source]

Params

unitID integer
seismicSignature number

Returns

nil

Spring.SetUnitSelectionVolumeData

function

function Spring.SetUnitSelectionVolumeData(unitID: integer, featureID: integer, scaleX: number, scaleY: number, scaleZ: number, offsetX: number, offsetY: number, offsetZ: number, vType: number, tType: number, Axis: number)

[source]

Params

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

Returns

nil

Spring.SetUnitSensorRadius

function

function Spring.SetUnitSensorRadius(unitID: integer, type: "airLos"|"los"|"radar"|"radarJammer"|"seismic"...(+2), radius: number)

[source]

type:
    | "los"
    | "airLos"
    | "radar"
    | "sonar"
    | "seismic"
    | "radarJammer"
    | "sonarJammer"

Params

unitID integer
type "airLos"|"los"|"radar"|"radarJammer"|"seismic"...(+2)
radius number

Returns

number? New — radius, or nil if unit is invalid.

Spring.SetUnitShieldRechargeDelay

function

function Spring.SetUnitShieldRechargeDelay(unitID: integer, weaponID?: integer, rechargeTime?: number)

[source]

Params

unitID integer
weaponID integer? — (optional if the unit only has one shield)
rechargeTime number? — (in seconds; emulates a regular hit if nil)

Returns

nil

Spring.SetUnitShieldState

function

function Spring.SetUnitShieldState(unitID: integer, weaponID?: integer, enabled?: boolean, power?: number)

[source]

Params

unitID integer
weaponID integer? — (Default: -1)
enabled boolean?
power number?

Returns

nil

Spring.SetUnitSonarStealth

function

function Spring.SetUnitSonarStealth(unitID: integer, sonarStealth: boolean)

[source]

Params

unitID integer
sonarStealth boolean

Returns

nil

Spring.SetUnitStealth

function

function Spring.SetUnitStealth(unitID: integer, stealth: boolean)

[source]

Params

unitID integer
stealth boolean

Returns

nil

Spring.SetUnitStockpile

function

function Spring.SetUnitStockpile(unitID: integer, stockpile?: number, buildPercent?: number)

[source]

Params

unitID integer
stockpile number?
buildPercent number?

Returns

nil

Spring.SetUnitStorage

function

function Spring.SetUnitStorage(unitID: number, res: string, amount: number)

[source]

Params

unitID number
res string
amount number

Spring.SetUnitTarget

function

function Spring.SetUnitTarget(unitID: integer, enemyUnitID?: integer, dgun?: boolean, userTarget?: boolean, weaponNum?: number)

[source]

Defines a unit’s target.

Params

unitID integer
enemyUnitID integer? — when nil drops the units current target.
dgun boolean? — (Default: false)
userTarget boolean? — (Default: false)
weaponNum number? — (Default: -1)

Returns

boolean success

Spring.SetUnitTooltip

function

function Spring.SetUnitTooltip(unitID: integer, tooltip: string)

[source]

Params

unitID integer
tooltip string

Returns

nil

Spring.SetUnitUseAirLos

function

function Spring.SetUnitUseAirLos(unitID: integer, useAirLos: boolean)

[source]

Params

unitID integer
useAirLos boolean

Returns

nil

Spring.SetUnitUseWeapons

function

function Spring.SetUnitUseWeapons(unitID: integer, forceUseWeapons?: number, allowUseWeapons?: number)

[source]

Params

unitID integer
forceUseWeapons number?
allowUseWeapons number?

Returns

nil

Spring.SetUnitVelocity

function

function Spring.SetUnitVelocity(unitID: integer, velX: number, velY: number, velZ: number)

[source]

Params

unitID integer
velX number
velY number
velZ number

Returns

nil

Spring.SetUnitWeaponDamages

function

function Spring.SetUnitWeaponDamages(unitID: integer, weaponNum: number|"explode"|"selfDestruct", damages: WeaponDamages)

[source]

weaponNum:
    | "selfDestruct"
    | "explode"

Params

unitID integer
weaponNum number|"explode"|"selfDestruct"
damages WeaponDamages — Parameters for damage

Returns

nil

Spring.SetUnitWeaponState

function

function Spring.SetUnitWeaponState(unitID: integer, weaponNum: number, states: WeaponState)

[source]

Params

unitID integer
weaponNum number
states WeaponState — Parameter for weapon states

Returns

nil

Spring.SetVideoCapturingMode

function

function Spring.SetVideoCapturingMode(allowCaptureMode: boolean)

[source]

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

Params

allowCaptureMode boolean

Returns

nil

Spring.SetVideoCapturingTimeOffset

function

function Spring.SetVideoCapturingTimeOffset(timeOffset: boolean)

[source]

Params

timeOffset boolean

Returns

nil

Spring.SetWMIcon

function

function Spring.SetWMIcon(iconFileName: string)

[source]

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

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

Params

iconFileName string

Returns

nil

Spring.SetWaterParams

function

function Spring.SetWaterParams(waterParams: WaterParams)

[source]

Does not need cheating enabled.

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

Params

waterParams WaterParams — Water params

Returns

nil

Spring.SetWind

function

function Spring.SetWind(minStrength: number, maxStrength: number)

[source]

Set wind strength

Params

minStrength number
maxStrength number

Returns

nil

Spring.SetWindowGeometry

function

function Spring.SetWindowGeometry(displayIndex: number, winRelPosX: number, winRelPosY: number, winSizeX: number, winSizeY: number, fullScreen: boolean, borderless: boolean)

[source]

Params

displayIndex number
winRelPosX number
winRelPosY number
winSizeX number
winSizeY number
fullScreen boolean
borderless boolean

Returns

nil

Spring.SetWindowMaximized

function

function Spring.SetWindowMaximized()

[source]

Returns

boolean maximized

Spring.SetWindowMinimized

function

function Spring.SetWindowMinimized()

[source]

Returns

boolean minimized

Spring.ShareResources

function

function Spring.ShareResources(teamID: integer, units: string)

[source]

Params

teamID integer
units string

Returns

nil

Spring.ShareTeamResource

function

function Spring.ShareTeamResource(teamID_src: integer, teamID_recv: integer, type: "e"|"energy"|"m"|"metal", amount: number)

[source]

Transfers resources between two teams.

type:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

teamID_src integer
teamID_recv integer
type "e"|"energy"|"m"|"metal"
amount number

Returns

nil

Spring.SolveNURBSCurve

function

function Spring.SolveNURBSCurve(groupID: integer)

[source]

Params

groupID integer

Returns

number[]? unitIDs

Spring.SpawnCEG

function

function Spring.SpawnCEG(cegname: string, posX?: number, posY?: number, posZ?: number, dirX?: number, dirY?: number, dirZ?: number, radius?: number, damage?: number)

[source]

Params

cegname string
posX number? — (Default: 0)
posY number? — (Default: 0)
posZ number? — (Default: 0)
dirX number? — (Default: 0)
dirY number? — (Default: 0)
dirZ number? — (Default: 0)
radius number? — (Default: 0)
damage number? — (Default: 0)

Returns

boolean? success
number cegID

Spring.SpawnExplosion

function

function Spring.SpawnExplosion(posX?: number, posY?: number, posZ?: number, dirX?: number, dirY?: number, dirZ?: number, explosionParams: ExplosionParams)

[source]

Params

posX number? — (Default: 0)
posY number? — (Default: 0)
posZ number? — (Default: 0)
dirX number? — (Default: 0)
dirY number? — (Default: 0)
dirZ number? — (Default: 0)
explosionParams ExplosionParams — Parameters for explosion.

Please note the explosion defaults to 1 damage regardless of what it’s defined in the weaponDef. The weapondefID is only used for visuals and for passing into callins like UnitDamaged.

Returns

nil

Spring.SpawnProjectile

function

function Spring.SpawnProjectile(weaponDefID: integer, projectileParams: ProjectileParams)

[source]

Params

weaponDefID integer
projectileParams ProjectileParams

Returns

integer? projectileID

Spring.SpawnSFX

function

function Spring.SpawnSFX(unitID?: integer, sfxID?: integer, posX?: number, posY?: number, posZ?: number, dirX?: number, dirY?: number, dirZ?: number, radius?: number, damage?: number, absolute?: boolean)

[source]

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

Params

unitID integer? — (Default: 0)
sfxID integer? — (Default: 0)
posX number? — (Default: 0)
posY number? — (Default: 0)
posZ number? — (Default: 0)
dirX number? — (Default: 0)
dirY number? — (Default: 0)
dirZ number? — (Default: 0)
radius number? — (Default: 0)
damage number? — (Default: 0)
absolute boolean?

Returns

boolean? success

Spring.Start

function

function Spring.Start(commandline_args: string, startScript: string)

[source]

Launches a new Spring instance without terminating the existing one.

If this call returns, something went wrong

Params

commandline_args string — commandline arguments passed to spring executable.
startScript string — the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args.

Returns

nil

Spring.StopSoundStream

function

function Spring.StopSoundStream()

[source]

Terminates any SoundStream currently running.

Returns

nil

Spring.TestBuildOrder

function

function Spring.TestBuildOrder(unitDefID: integer, x: number, y: number, z: number, facing: "e"|"east"|"n"|"north"|"s"...(+7))

[source]

facing:
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | 0 -- South
    | 1 -- East
    | 2 -- North
    | 3 -- West
    | "s" -- South
    | "e" -- East
    | "n" -- North
    | "w" -- West
    | "south" -- South
    | "east" -- East
    | "north" -- North
    | "west" -- West

blocking:
    | 0 -- blocked
    | 1 -- mobile unit on the way
    | 2 -- reclaimable
    | 3 -- open

Params

unitDefID integer
x number
y number
z number
facing "e"|"east"|"n"|"north"|"s"...(+7)

Returns

0|1|2|3 blocking
integer? featureID — A reclaimable feature in the way.

Spring.TestMoveOrder

function

function Spring.TestMoveOrder(unitDefID: integer, pos: xyz, dir?: xyz, testTerrain?: boolean, testObjects?: boolean, centerOnly?: boolean)

[source]

Params

unitDefID integer
pos xyz — Cartesian triple (XYZ)
dir xyz? — (Default: { x: 0, y: 0, z: 0 })
testTerrain boolean? — (Default: true)
testObjects boolean? — (Default: true)
centerOnly boolean? — (Default: false)

Returns

boolean

Spring.TraceRayGroundBetweenPositions

function

function Spring.TraceRayGroundBetweenPositions(startX: number, startY: number, startZ: number, endX: number, endY: number, endZ: number, testWater?: boolean)

[source]

Checks for a ground collision between two positions

Checks if there is surface (ground, optionally water) between two positions and returns the distance to the closest hit and its position, if any.

Params

startX number
startY number
startZ number
endX number
endY number
endZ number
testWater boolean? — (Default: true)

Returns

number rayLength
number posX
number posY
number posZ

Spring.TraceRayGroundInDirection

function

function Spring.TraceRayGroundInDirection(posX: number, posY: number, posZ: number, dirX: number, dirY: number, dirZ: number, testWater?: boolean)

[source]

Checks for a ground collision in given direction

Checks if there is surface (ground, optionally water) towards a vector and returns the distance to the closest hit and its position, if any.

Params

posX number
posY number
posZ number
dirX number
dirY number
dirZ number
testWater boolean? — (Default: true)

Returns

number rayLength
number posX
number posY
number posZ

Spring.TraceScreenRay

function

function Spring.TraceScreenRay(screenX: number, screenY: number, onlyCoords?: boolean, useMinimap?: boolean, includeSky?: boolean, ignoreWater?: boolean, heightOffset?: number)

[source]

Get information about a ray traced from screen to world position

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

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

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

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

Params

screenX number — position on x axis in mouse coordinates (origin on left border of view)
screenY number — position on y axis in mouse coordinates (origin on top border of view)
onlyCoords boolean? — (Default: false) return only description (1st return value) and coordinates (2nd return value)
useMinimap boolean? — (Default: false) if position arguments are contained by minimap, use the minimap corresponding world position
includeSky boolean? — (Default: false)
ignoreWater boolean? — (Default: false)
heightOffset number? — (Default: 0)

Returns

string|nil description — of traced position
string|number|xyz|nil unitID — or feature, position triple when onlyCoords=true
string|number|nil featureID — or ground
xyz|nil coords

Spring.TransferFeature

function

function Spring.TransferFeature(featureDefID: integer, teamID: integer)

[source]

Feature Control

Params

featureDefID integer
teamID integer

Returns

nil

Spring.TransferUnit

function

function Spring.TransferUnit(unitID: integer, newTeamID: integer, given?: boolean)

[source]

Params

unitID integer
newTeamID integer
given boolean? — (Default: true) if false, the unit is captured.

Returns

nil

Spring.UnitAttach

function

function Spring.UnitAttach(transporterID: integer, passengerID: integer, pieceNum: number)

[source]

Params

transporterID integer
passengerID integer
pieceNum number

Returns

nil

Spring.UnitDetach

function

function Spring.UnitDetach(passengerID: integer)

[source]

Params

passengerID integer

Returns

nil

Spring.UnitDetachFromAir

function

function Spring.UnitDetachFromAir(passengerID: integer)

[source]

Params

passengerID integer

Returns

nil

Spring.UnitFinishCommand

function

function Spring.UnitFinishCommand(unitID: integer)

[source]

Params

unitID integer

Spring.UnitIconGetDraw

function

function Spring.UnitIconGetDraw(unitID: integer)

[source]

true if icon is being drawn, nil when unitID is invalid, otherwise false.

Params

unitID integer

Returns

boolean? drawIcon

Spring.UnitIconSetDraw

function

function Spring.UnitIconSetDraw(unitID: integer, drawIcon: boolean)

[source]

Use Spring.SetUnitIconDraw instead.

Params

unitID integer
drawIcon boolean

Returns

nil

Spring.UnitWeaponFire

function

function Spring.UnitWeaponFire(unitID: integer, weaponID: integer)

[source]

Params

unitID integer
weaponID integer

Returns

nil

Spring.UnitWeaponHoldFire

function

function Spring.UnitWeaponHoldFire(unitID: integer, weaponID: integer)

[source]

Params

unitID integer
weaponID integer

Returns

nil

Spring.UpdateMapLight

function

function Spring.UpdateMapLight(lightHandle: number, lightParams: LightParams)

[source]

Params

lightHandle number
lightParams LightParams — Parameters for lighting

Returns

boolean success

Spring.UpdateModelLight

function

function Spring.UpdateModelLight(lightHandle: number, lightParams: LightParams)

[source]

Params

lightHandle number
lightParams LightParams — Parameters for lighting

Returns

boolean success

Spring.UseTeamResource

function

function Spring.UseTeamResource(teamID: integer, type: "e"|"energy"|"m"|"metal", amount: number)

[source]

Consumes metal or energy resources of the specified team.

True if enough of the resource type was available and was consumed, otherwise false.

type:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

teamID integer
type "e"|"energy"|"m"|"metal" — Resource type.
amount number — Amount of resource to use.

Returns

boolean hadEnough

Spring.UseUnitResource

function

function Spring.UseUnitResource(unitID: integer, resource: "e"|"energy"|"m"|"metal", amount: number)

[source]

resource:
    | "metal"
    | "energy"
    | "m"
    | "e"

Params

unitID integer
resource "e"|"energy"|"m"|"metal"
amount number

Returns

boolean? okay

Spring.ValidFeatureID

function

function Spring.ValidFeatureID(featureID: integer)

[source]

Params

featureID integer

Returns

boolean

Spring.ValidUnitID

function

function Spring.ValidUnitID(unitID: integer)

[source]

Params

unitID integer

Returns

boolean

Spring.WarpMouse

function

function Spring.WarpMouse(x: number, y: number)

[source]

Params

x number
y number

Returns

nil

Spring.WorldToScreenCoords

function

function Spring.WorldToScreenCoords(x: number, y: number, z: number)

[source]

Params

x number
y number
z number

Returns

number viewPortX
number viewPortY
number viewPortZ

Spring.Yield

function

function Spring.Yield()

[source]

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

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

for wupget in pairs(wupgetsToLoad) do loadWupget(wupget) wantYield = wantYield and Spring.Yield() end

Returns

boolean when — true caller should continue calling Spring.Yield during the widgets/gadgets load, when false it shouldn’t call it any longer.

StockpileChanged

function

function StockpileChanged(unitID: integer, unitDefID: integer, unitTeam: integer, weaponNum: integer, oldCount: integer, newCount: integer)

[source]

Called when a units stockpile of weapons increases or decreases.

Params

unitID integer
unitDefID integer
unitTeam integer
weaponNum integer
oldCount integer
newCount integer

StorageName

type

"energyStorage"|"es"|"metalStorage"|"ms"

[source]

StorageName:
    | "metalStorage"
    | "energyStorage"
    | "ms"
    | "es"

SunChanged

function

function SunChanged()

[source]

TargetType

type

0|1|2|3

[source]

TargetType:
    | 0 -- none
    | 1 -- unit
    | 2 -- position
    | 3 -- projectile

TeamChanged

function

function TeamChanged(teamID: number)

[source]

Params

teamID number

TeamDied

function

function TeamDied(teamID: number)

[source]

Called when a team dies (see Spring.KillTeam).

Params

teamID number

TeamStats

type

[source]

Fields

damageDealt number
damageReceived number
energyExcess number
energyProduced number
energyReceived number
energySent number
energyUsed number
frame number
metalExcess number
metalProduced number
metalReceived number
metalSent number
metalUsed number
time number
unitsCaptured integer
unitsDied integer
unitsOutCaptured integer
unitsProduced integer
unitsReceived integer
unitsSent integer

TerraformComplete

function

function TerraformComplete(unitID: integer, unitDefID: integer, unitTeam: integer, buildUnitID: integer, buildUnitDefID: integer, buildUnitTeam: integer)

[source]

Called when pre-building terrain levelling terraforms are completed (c.f. levelGround)

Params

unitID integer
unitDefID integer
unitTeam integer
buildUnitID integer
buildUnitDefID integer
buildUnitTeam integer

Returns

boolean if — true the current build order is terminated

TextEditing

function

function TextEditing(utf8: string, start: number, length: number)

[source]

Params

utf8 string
start number
length number

TextInput

function

function TextInput(utf8char: string)

[source]

Called whenever a key press results in text input.

Params

utf8char string

UniformArrayType

type

1|2|3

[source]

UniformArrayType:
    | 1 -- int
    | 2 -- float
    | 3 -- float matrix

UniformParam

type

[source]

UnitArrivedAtGoal

function

function UnitArrivedAtGoal(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitCloaked

function

function UnitCloaked(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called when a unit cloaks.

Params

unitID integer
unitDefID integer
unitTeam integer

UnitCmdDone

function

function UnitCmdDone(unitID: integer, unitDefID: integer, unitTeam: integer, cmdID: number, cmdParams: table, options: CommandOptions, cmdTag: number)

[source]

Called when a unit completes a command.

Params

unitID integer
unitDefID integer
unitTeam integer
cmdID number
cmdParams table
options CommandOptions — Parameters for command options
cmdTag number

UnitCommand

function

function UnitCommand(unitID: integer, unitDefID: integer, unitTeam: integer, cmdID: number, cmdParams: table, options: CommandOptions, cmdTag: number)

[source]

Called after when a unit accepts a command, after AllowCommand returns true.

Params

unitID integer
unitDefID integer
unitTeam integer
cmdID number
cmdParams table
options CommandOptions — Parameters for command options
cmdTag number

UnitConstructionDecayed

function

function UnitConstructionDecayed(unitID: integer, unitDefID: integer, unitTeam: integer, timeSinceLastBuild: number, iterationPeriod: number, part: number)

[source]

Called when a unit being built starts decaying.

Params

unitID integer
unitDefID integer
unitTeam integer
timeSinceLastBuild number
iterationPeriod number
part number

UnitCreated

function

function UnitCreated(unitID: integer, unitDefID: integer, unitTeam: integer, builderID?: number)

[source]

Called at the moment the unit is created.

Params

unitID integer
unitDefID integer
unitTeam integer
builderID number?

UnitDamaged

function

function UnitDamaged(unitID: integer, unitDefID: integer, unitTeam: integer, damage: number, paralyzer: number, weaponDefID: number, projectileID: number, attackerID: number, attackerDefID: number, attackerTeam: number)

[source]

Called when a unit is damaged (after UnitPreDamaged).

Params

unitID integer
unitDefID integer
unitTeam integer
damage number
paralyzer number
weaponDefID number
projectileID number
attackerID number
attackerDefID number
attackerTeam number

UnitDecloaked

function

function UnitDecloaked(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called when a unit decloaks.

Params

unitID integer
unitDefID integer
unitTeam integer

UnitDestroyed

function

function UnitDestroyed(unitID: integer, unitDefID: integer, unitTeam: integer, attackerID: number, attackerDefID: number, attackerTeam: number, weaponDefID: number)

[source]

Called when a unit is destroyed.

Params

unitID integer
unitDefID integer
unitTeam integer
attackerID number
attackerDefID number
attackerTeam number
weaponDefID number

UnitEnteredAir

function

function UnitEnteredAir(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitEnteredLos

function

function UnitEnteredLos(unitID: integer, unitTeam: integer, allyTeam: integer, unitDefID: integer)

[source]

Called when a unit enters LOS of an allyteam.

Its called after the unit is in LOS, so you can query that unit.

Params

unitID integer
unitTeam integer
allyTeam integer — who’s LOS the unit entered.
unitDefID integer

UnitEnteredRadar

function

function UnitEnteredRadar(unitID: integer, unitTeam: integer, allyTeam: integer, unitDefID: integer)

[source]

Called when a unit enters radar of an allyteam.

Also called when a unit enters LOS without any radar coverage.

Params

unitID integer
unitTeam integer
allyTeam integer
unitDefID integer

UnitEnteredUnderwater

function

function UnitEnteredUnderwater(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitEnteredWater

function

function UnitEnteredWater(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitExperience

function

function UnitExperience(unitID: integer, unitDefID: integer, unitTeam: integer, experience: number, oldExperience: number)

[source]

Called when a unit gains experience greater or equal to the minimum limit set by calling Spring.SetExperienceGrade.

Should be called more reliably with small values of experience grade.

Params

unitID integer
unitDefID integer
unitTeam integer
experience number
oldExperience number

UnitFeatureCollision

function

function UnitFeatureCollision(colliderID: number, collideeID: number)

[source]

Called when a unit collides with a feature.

The unit must be registered with Script.SetWatchUnit and the feature registered with Script.SetWatchFeature.

Params

colliderID number
collideeID number

UnitFinished

function

function UnitFinished(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called at the moment the unit is completed.

Params

unitID integer
unitDefID integer
unitTeam integer

UnitFromFactory

function

function UnitFromFactory(unitID: integer, unitDefID: integer, unitTeam: integer, factID: number, factDefID: number, userOrders: boolean)

[source]

Called when a factory finishes construction of a unit.

Params

unitID integer
unitDefID integer
unitTeam integer
factID number
factDefID number
userOrders boolean

UnitGiven

function

function UnitGiven(unitID: integer, unitDefID: integer, newTeam: number, oldTeam: number)

[source]

Called when a unit is transferred between teams. This is called after UnitTaken and in that moment unit is assigned to the newTeam.

Params

unitID integer
unitDefID integer
newTeam number
oldTeam number

UnitHarvestStorageFull

function

function UnitHarvestStorageFull(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called when a unit’s harvestStorage is full (according to its unitDef’s entry).

Params

unitID integer
unitDefID integer
unitTeam integer

UnitIdle

function

function UnitIdle(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called when a unit is idle (empty command queue).

Params

unitID integer
unitDefID integer
unitTeam integer

UnitLeftAir

function

function UnitLeftAir(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitLeftLos

function

function UnitLeftLos(unitID: integer, unitTeam: integer, allyTeam: integer, unitDefID: integer)

[source]

Called when a unit leaves LOS of an allyteam.

For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.

Params

unitID integer
unitTeam integer
allyTeam integer
unitDefID integer

UnitLeftRadar

function

function UnitLeftRadar(unitID: integer, unitTeam: integer, allyTeam: integer, unitDefID: integer)

[source]

Called when a unit leaves radar of an allyteam.

Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.

Params

unitID integer
unitTeam integer
allyTeam integer
unitDefID integer

UnitLeftUnderwater

function

function UnitLeftUnderwater(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitLeftWater

function

function UnitLeftWater(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitLoaded

function

function UnitLoaded(unitID: integer, unitDefID: integer, unitTeam: integer, transportID: integer, transportTeam: integer)

[source]

Called when a unit is loaded by a transport.

Params

unitID integer
unitDefID integer
unitTeam integer
transportID integer
transportTeam integer

UnitMoveFailed

function

function UnitMoveFailed(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Params

unitID integer
unitDefID integer
unitTeam integer

UnitPreDamaged

function

function UnitPreDamaged(unitID: integer, unitDefID: integer, unitTeam: integer, damage: number, paralyzer: boolean, weaponDefID?: integer, projectileID?: integer, attackerID?: integer, attackerDefID?: integer, attackerTeam?: integer)

[source]

Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.

Called after every damage modification (even HitByWeaponId) but before the damage is applied

expects two numbers returned by lua code: 1st is stored under *newDamage if newDamage != NULL 2nd is stored under *impulseMult if impulseMult != NULL

Params

unitID integer
unitDefID integer
unitTeam integer
damage number
paralyzer boolean
weaponDefID integer? — Synced Only
projectileID integer? — Synced Only
attackerID integer? — Synced Only
attackerDefID integer? — Synced Only
attackerTeam integer? — Synced Only

Returns

number newDamage
number impulseMult

UnitReverseBuilt

function

function UnitReverseBuilt(unitID: integer, unitDefID: integer, unitTeam: integer)

[source]

Called when a living unit becomes a nanoframe again.

Params

unitID integer
unitDefID integer
unitTeam integer

UnitSeismicPing

function

function UnitSeismicPing(x: number, y: number, z: number, strength: number, allyTeam: integer, unitID: integer, unitDefID: integer)

[source]

Called when a unit emits a seismic ping.

See seismicSignature.

Params

x number
y number
z number
strength number
allyTeam integer
unitID integer
unitDefID integer

UnitState

type

[source]

Fields

active boolean
autoland boolean?
autorepairlevel number?
cloak boolean
firestate number
loopbackattack boolean?
movestate number
repeat boolean
trajectory boolean

UnitStunned

function

function UnitStunned(unitID: integer, unitDefID: integer, unitTeam: integer, stunned: boolean)

[source]

Called when a unit changes its stun status.

Params

unitID integer
unitDefID integer
unitTeam integer
stunned boolean

UnitTaken

function

function UnitTaken(unitID: integer, unitDefID: integer, oldTeam: number, newTeam: number)

[source]

Called when a unit is transferred between teams. This is called before UnitGiven and in that moment unit is still assigned to the oldTeam.

Params

unitID integer
unitDefID integer
oldTeam number
newTeam number

UnitUnitCollision

function

function UnitUnitCollision(colliderID: number, collideeID: number)

[source]

Called when two units collide.

Both units must be registered with Script.SetWatchUnit.

Params

colliderID number
collideeID number

UnitUnloaded

function

function UnitUnloaded(unitID: integer, unitDefID: integer, unitTeam: integer, transportID: integer, transportTeam: integer)

[source]

Called when a unit is unloaded by a transport.

Params

unitID integer
unitDefID integer
unitTeam integer
transportID integer
transportTeam integer

UnsyncedHeightMapUpdate

function

function UnsyncedHeightMapUpdate()

[source]

Called when the unsynced copy of the height-map is altered.

Returns

number x1
number z1
number x2
number z2

Update

function

function Update(dt: number)

[source]

Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.

Params

dt number — the time since the last update.

VAO

table

table

[source]

VAO

type

[source]

Vertex Array Object

VAO.AddFeatureDefsToSubmission

function

(method) VAO:AddFeatureDefsToSubmission(featureDefIDs: number|number[])

[source]

Params

self table
featureDefIDs number|number[]

Returns

number submittedCount

VAO.AddFeaturesToSubmission

function

(method) VAO:AddFeaturesToSubmission(featureIDs: number|number[])

[source]

Params

self table
featureIDs number|number[]

Returns

number submittedCount

VAO.AddUnitDefsToSubmission

function

(method) VAO:AddUnitDefsToSubmission(unitDefIDs: number|number[])

[source]

Params

self table
unitDefIDs number|number[]

Returns

number submittedCount

VAO.AddUnitsToSubmission

function

(method) VAO:AddUnitsToSubmission(unitIDs: number|number[])

[source]

Params

self table
unitIDs number|number[]

Returns

number submittedCount

VAO.AttachIndexBuffer

function

(method) VAO:AttachIndexBuffer(vbo: VBO)

[source]

Attaches a VBO to be used as an index buffer

Params

self table
vbo VBO — Vertex Buffer Object

Returns

nil

VAO.AttachInstanceBuffer

function

(method) VAO:AttachInstanceBuffer(vbo: VBO)

[source]

Attaches a VBO to be used as an instance buffer

Params

self table
vbo VBO — Vertex Buffer Object

Returns

nil

VAO.AttachVertexBuffer

function

(method) VAO:AttachVertexBuffer(vbo: VBO)

[source]

Attaches a VBO to be used as a vertex buffer

Params

self table
vbo VBO — Vertex Buffer Object

Returns

nil

VAO.Delete

function

(method) VAO:Delete()

[source]

Params

self table

Returns

nil

VAO.DrawArrays

function

(method) VAO:DrawArrays(glEnum: number, vertexCount?: number, vertexFirst?: number, instanceCount?: number, instanceFirst?: number)

[source]

Params

self table
glEnum number — primitivesMode
vertexCount number?
vertexFirst number?
instanceCount number?
instanceFirst number?

Returns

nil

VAO.DrawElements

function

(method) VAO:DrawElements(glEnum: number, drawCount?: number, baseIndex?: number, instanceCount?: number, baseVertex?: number, baseInstance?: number)

[source]

Params

self table
glEnum number — primitivesMode
drawCount number?
baseIndex number?
instanceCount number?
baseVertex number?
baseInstance number?

Returns

nil

VAO.RemoveFromSubmission

function

(method) VAO:RemoveFromSubmission(index: number)

[source]

Params

self table
index number

Returns

nil

VAO.Submit

function

(method) VAO:Submit()

[source]

Params

self table

Returns

nil

VBO

type

[source]

Vertex Buffer Object

VBOAttributeDef

type

[source]

Fields

id integer
name string — The location in the vertex shader layout e.g.: layout (location = 0) in vec2 aPos. optional attrib, specifies location in the vertex shader. If not specified the implementation will increment the counter starting from 0. There can be maximum 16 attributes (so id of 15 is max).
normalized boolean? — (Defaults: false)
size integer? — The name for this VBO, only used for debugging.
type GL.BYTE|GL.FLOAT|GL.INT|GL.SHORT|GL.UNSIGNED_BYTE...(+2) — (Default: GL.FLOAT)

VBODataType

type

GL.BYTE|GL.FLOAT|GL.INT|GL.SHORT|GL.UNSIGNED_BYTE...(+2)

[source]

ViewResize

function

function ViewResize(viewSizeX: number, viewSizeY: number)

[source]

Called whenever the window is resized.

Params

viewSizeX number
viewSizeY number

WaterParams

type

[source]

Water params

Fields

absorb rgb — Color triple (RGB)
ambientFactor number
baseColor rgb — Color triple (RGB)
blurBase number
blurExponent number
causticsResolution number
causticsStrength number
damage number
diffuseColor rgb — Color triple (RGB)
diffuseFactor number
foamTexture string — file
forceRendering boolean
fresnelMax number
fresnelMin number
fresnelPower number
hasWaterPlane boolean
minColor rgb — Color triple (RGB)
normalTexture string — file
numTiles integer
perlinAmplitude number
perlinLacunarity number
perlinStartFreq number
planeColor rgb — Color triple (RGB)
reflectionDistortion number
repeatX number
repeatY number
shoreWaves boolean
specularColor rgb — Color triple (RGB)
specularFactor number
specularPower number
surfaceAlpha number
surfaceColor rgb — Color triple (RGB)
texture string — file
waveFoamDistortion number
waveFoamIntensity number
waveLength number
waveOffsetFactor number
windSpeed number

WeaponDamages

type

[source]

Parameters for damage

Fields

craterAreaOfEffect number — Set to true if a non-zero value is passed, false is zero is passed.
craterBoost number
craterMult number
damageAreaOfEffect number
dynDamageExp number
dynDamageInverted number
dynDamageMin number
dynDamageRange number
edgeEffectiveness number
explosionSpeed number
impulseBoost number
impulseFactor number
paralyzeDamageTime integer

WeaponState

type

[source]

Parameter for weapon states

Fields

accuracy number?
aimReady number?
avoidFlags integer?
burst integer?
burstRate number?
collisionFlags integer?
forceAim integer? — Set to true if a non-zero value is passed, false is zero is passed.
nextSalvo integer?
projectileSpeed number? — If you change the range of a weapon with dynamic damage make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
projectiles integer?
range number?
reaimTime integer?
reloadFrame integer? — Alias for reloadState.
reloadState integer?
reloadTime number?
salvoLeft integer?
sprayAngle number?

WorldTooltip

function

function WorldTooltip(ttType: string, data1: number, data2?: number, data3?: number)

[source]

Params

ttType string — unit
data1 number — unitID featureID posX
data2 number? — posY
data3 number? — posZ

Returns

string newTooltip

attachment

type

[source]

attachment ::= luaTex or RBO.rbo or nil or { luaTex [, num target [, num level ] ] }

camState

type

[source]

Parameters for camera state

Highly dependent on the type of the current camera controller

Fields

angle number — Camera rotation angle on X axis (aka tilt/pitch) (ta)
dist number — Camera distance from the ground (spring)
dx number — Camera direction vector X
dy number — Camera direction vector Y
dz number — Camera direction vector Z
flipped number — 1 for when south is down, 1 for when north is down (ta)
fov number
height number — Camera distance from the ground (ta)
mode number — the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy)
name "dummy"|"fps"|"free"|"ov"|"rot"...(+2)
oldHeight number — Camera distance from the ground, cannot be changed (rot)
px number — Position X of the ground point in screen center
py number — Position Y of the ground point in screen center
pz number — Position Z of the ground point in screen center
rx number — Camera rotation angle on X axis (spring)
ry number — Camera rotation angle on Y axis (spring)
rz number — Camera rotation angle on Z axis (spring)

cmdOpts

type

[source]

Command Options params

Fields

alt boolean — Alt key pressed
ctrl boolean — Ctrl key pressed
meta boolean — Meta (windows/mac/mod4) key pressed
right boolean — Right mouse key pressed
shift boolean — Shift key pressed

float3

type

xyz

[source]

Cartesian triple (XYZ)

gl

table

table

[source]

gl.ActiveFBO

function

function gl.ActiveFBO(fbo: Fbo, target?: GL, identities?: boolean, lua_function?: function, arg1?: any, arg2?: any, argn?: any)

[source]

Params

fbo Fbo — User Data FBO
target GL?
identities boolean?
lua_function function?
arg1 any
arg2 any
argn any

gl.ActiveShader

function

function gl.ActiveShader(shaderID: integer, func: function, ...any)

[source]

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

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

Params

shaderID integer
func function
… any — Arguments

gl.AddFallbackFont

function

function gl.AddFallbackFont(filePath: string)

[source]

Adds a fallback font for the font rendering engine.

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

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

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

Params

filePath string — VFS path to the file, for example “fonts/myfont.ttf”. Uses VFS.RAW_FIRST access mode.

Returns

bool success

gl.BlitFBO

function

function gl.BlitFBO(x0Src: number, y0Src: number, x1Src: number, y1Src: number, x0Dst: number, y0Dst: number, x1Dst: number, y1Dst: number, mask?: number, filter?: number)

[source]

needs GLAD_GL_EXT_framebuffer_blit

Params

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

gl.ClearAttachmentFBO

function

function gl.ClearAttachmentFBO(target?: number, attachment: string|GL, clearValue0: number, clearValue1: number, clearValue2: number, clearValue3: number)

[source]

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

Params

target number? — (Default: GL.FRAMEBUFFER)
attachment string|GL — (e.g. "color0" or GL.COLOR_ATTACHMENT0)
clearValue0 number
clearValue1 number
clearValue2 number
clearValue3 number

gl.ClearFallbackFonts

function

function gl.ClearFallbackFonts()

[source]

Clears all fallback fonts.

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

Returns

nil

gl.Color

function

function gl.Color(r: number, g: number, b: number, a?: number)

[source]

Params

r number — Red
g number — Green
b number — Blue
a number? — Alpha (Default: 1.0f)

gl.CreateFBO

function

function gl.CreateFBO(fbo: Fbo)

[source]

Params

fbo Fbo — User Data FBO

gl.CreateRBO

function

function gl.CreateRBO(xsize: integer, ysize: integer, data: CreateRBOData)

[source]

Params

xsize integer
ysize integer
data CreateRBOData

Returns

RBO

gl.CreateShader

function

function gl.CreateShader(shaderParams: ShaderParams)

[source]

Create a shader.

Params

shaderParams ShaderParams

Returns

integer shaderID

gl.DeleteFBO

function

function gl.DeleteFBO(fbo: Fbo)

[source]

This doesn’t delete the attached objects!

Params

fbo Fbo — User Data FBO

gl.DeleteRBO

function

function gl.DeleteRBO(rbo: RBO)

[source]

Params

rbo RBO — User Data RBO

gl.DeleteShader

function

function gl.DeleteShader(shaderID: integer)

[source]

Deletes a shader identified by shaderID

Params

shaderID integer

gl.GetActiveUniforms

function

function gl.GetActiveUniforms(shaderID: integer)

[source]

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

Params

shaderID integer

Returns

ActiveUniform[] activeUniforms

gl.GetEngineModelUniformDataDef

function

function gl.GetEngineModelUniformDataDef(index: number)

[source]

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

Params

index number

Returns

string glslDefinition

gl.GetEngineUniformBufferDef

function

function gl.GetEngineUniformBufferDef(index: number)

[source]

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

Params

index number

Returns

string glslDefinition

gl.GetShaderLog

function

function gl.GetShaderLog()

[source]

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

Returns

string infoLog

gl.GetUniformLocation

function

function gl.GetUniformLocation(shaderID: integer, name: string)

[source]

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

Params

shaderID integer
name string

Returns

GL locationID

gl.GetVAO

function

function gl.GetVAO()

[source]

Example:

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

Returns

VAO? vao — The VAO ref on success, else nil

gl.GetVBO

function

function gl.GetVBO(bufferType?: GL.ARRAY_BUFFER|GL.ELEMENT_ARRAY_BUFFER|GL.SHADER_STORAGE_BUFFER|GL.UNIFORM_BUFFER, freqUpdated?: boolean)

[source]

Example:

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

Use GL.ARRAY_BUFFER for vertex data and GL.ELEMENT_ARRAY_BUFFER for vertex indices.

true to updated frequently, false to update only once.

The VBO ref on success, or nil if not supported or an error occurred. See: ~GL.OpenGL_Buffer_Types~

Params

bufferType (GL.ARRAY_BUFFER|GL.ELEMENT_ARRAY_BUFFER|GL.SHADER_STORAGE_BUFFER|GL.UNIFORM_BUFFER)? — (Default: GL.ARRAY_BUFFER)
freqUpdated boolean? — (Default: true)

Returns

VBO? VBO

gl.IsValidFBO

function

function gl.IsValidFBO(fbo: Fbo, target?: GL)

[source]

Params

fbo Fbo — User Data FBO
target GL?

Returns

boolean valid
number? status

gl.ObjectLabel

function

function gl.ObjectLabel(objectTypeIdentifier: GLenum, objectID: GLuint, label: string)

[source]

labels an object for use with debugging tools

Params

objectTypeIdentifier GLenum — Specifies the type of object being labeled.
objectID GLuint — Specifies the name or ID of the object to label.
label string — A string containing the label to be assigned to the object.

Returns

nil

gl.PopDebugGroup

function

function gl.PopDebugGroup()

[source]

Returns

nil

gl.PushDebugGroup

function

function gl.PushDebugGroup(id: GLuint, message: string, sourceIsThirdParty: boolean)

[source]

pushes a debug marker for nVidia nSight 2024.04, does not seem to work when FBO’s are raw bound

Params

id GLuint — A numeric identifier for the group.
message string — A human-readable string describing the debug group.
sourceIsThirdParty boolean — Set the source tag, true for GL_DEBUG_SOURCE_THIRD_PARTY, false for GL_DEBUG_SOURCE_APPLICATION. default false

Returns

nil

gl.RawBindFBO

function

function gl.RawBindFBO(fbo: nil, target?: GL, rawFboId?: integer)

[source]

Bind default or specified via rawFboId numeric id of FBO

Params

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

Returns

nil

gl.SetGeometryShaderParameter

function

function gl.SetGeometryShaderParameter(shaderID: integer, param: number, number: number)

[source]

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

Params

shaderID integer
param number
number number

Returns

nil

gl.SetTesselationShaderParameter

function

function gl.SetTesselationShaderParameter(param: integer, value: integer)

[source]

Sets the tesselation shader parameters for shaderID.

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

Params

param integer
value integer

Returns

nil

gl.Text

function

function gl.Text(text: string, x: number, y: number, size: number, options?: string)

[source]

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)

Params

text string
x number
y number
size number
options string? — concatenated string of option characters.

Returns

nil

gl.Uniform

function

function gl.Uniform(locationID: string|GL, f1: number, f2?: number, f3?: number, f4?: number)

[source]

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

Params

locationID string|GL — uniformName
f1 number
f2 number?
f3 number?
f4 number?

gl.UniformArray

function

function gl.UniformArray(locationID: string|integer, type: 1|2|3, uniforms: number[])

[source]

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

Shader must be activated before setting uniforms.

type:
    | 1 -- int
    | 2 -- float
    | 3 -- float matrix

Params

locationID string|integer — uniformName
type 1|2|3
uniforms number[] — Array up to 1024 elements

gl.UniformInt

function

function gl.UniformInt(locationID: string|integer, int1: integer, int2?: integer, int3?: integer, int4?: integer)

[source]

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

Params

locationID string|integer — uniformName
int1 integer
int2 integer?
int3 integer?
int4 integer?

gl.UniformMatrix

function

function gl.UniformMatrix(locationID: string|integer, matrix: "camera"|"caminv"|"camprj"|"shadows")

[source]

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

Shader must be activated before setting uniforms.

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

matrix:
    | "shadows"
    | "camera"
    | "caminv"
    | "camprj"

Params

locationID string|integer — uniformName
matrix "camera"|"caminv"|"camprj"|"shadows" — Name of common matrix.

gl.UseShader

function

function gl.UseShader(shaderID: integer)

[source]

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

Params

shaderID integer

Returns

boolean linked

losAccess

type

[source]

Parameters for los access

Fields

allied boolean? — readable by ally + ingame allied
inlos boolean? — readable if the unit is in LOS
inradar boolean? — readable if the unit is in AirLOS
private boolean? — only readable by the ally (default)
public boolean? — readable by all

math.bit_and

function

function math.bit_and(...integer)

[source]

Returns the bitwise AND of all arguments. Only use up to 24 bit integers.

Params

… integer

Returns

integer result

math.bit_bits

function

function math.bit_bits(...integer)

[source]

Set each of the bits of a 24 bit integer. Returns result = result OR (1 « a1) OR (1 « a2) OR …;)

Params

… integer

Returns

integer result

math.bit_inv

function

function math.bit_inv(value: integer)

[source]

Returns the bitwise NOT of the 24 bit integer argument.

Params

value integer

Returns

integer result

math.bit_or

function

function math.bit_or(...integer)

[source]

Returns the bitwise OR of all arguments. Only use up to 24 bit integers.

Params

… integer

Returns

integer result

math.bit_xor

function

function math.bit_xor(...integer)

[source]

Returns the bitwise XOR of all arguments. Only use up to 24 bit integers.

Params

… integer

Returns

integer result

math.clamp

function

function math.clamp(value: number, min: number, max: number)

[source]

Returns x clamped to min and max boundaries.

Params

value number
min number
max number

Returns

number clamped

math.diag

function

function math.diag(x: number, ...number)

[source]

Returns the length of the diagonal of an n-dimensional box (or the length of an n-component vector). Rather quick method that does not handle intermediate overflows/underflows nor is made for numerical stability.

Params

x number
… number

Returns

number diagonal

math.erf

function

function math.erf(x: number)

[source]

Returns erf(x), the Gauss error function, between -1 and 1.

Params

x number

Returns

number erf

math.hypot

function

function math.hypot(x: number, y: number)

[source]

Returns the length of hypotenuse of right angle triangle with sides x and y, equivalent to sqrt(x*x + y*y), but has better numerical stability and internally handles intermediate overflows/underflows, but is also slower.

Params

x number
y number

Returns

number — sqrt(x*x+y*y)

math.mix

function

function math.mix(x: number, y: number, a: number)

[source]

Returns linear interpolation between x and y with ratio a (x+(y-x)*a).

Params

x number
y number
a number

Returns

number — (x+(y-x)*a)

math.normalize

function

function math.normalize(x: number, ...number)

[source]

Returns the normalize vector of an given vector.

Params

x number
… number

Returns

number … — normalized

math.round

function

function math.round(x: number, decimals: number)

[source]

Returns x rounded to n decimals, if n is omitted or <=0, rounds to nearest integer. Note that Spring’s Lua interpreter uses 32-bit floats for all numbers so max. precision is ~7 decimal digits.

Params

x number
decimals number

Returns

number rounded

math.sgn

function

function math.sgn(x: number)

[source]

Returns 0 if x == 0, 1 if x > 0, -1 if x < 0

Params

x number

Returns

number sign

math.smoothstep

function

function math.smoothstep(edge0: number, edge1: number, v: number)

[source]

Applies the smoothstep function

Clamps and rescales v to a value between [0; 1] based on the edges and then applies the smoothstep function. For example math.smoothstep(10, 25, 15) is 0.259, because 15 is 0.333 of the way from 10 to 25, and smoothstep(0.333) is 0.259

Params

edge0 number
edge1 number
v number

Returns

number smoothstep

rgb

type

[source]

Color triple (RGB)

Fields

b number
g number
r number

rgba

type

[source]

Color quadruple (RGBA)

Fields

a number
b number
g number
r number

table.new

function

function table.new(nArray: number, nHashed: number)

[source]

Returns a table with preallocated memory

Returns an empty table with more memory allocated. This lets you microoptimize cases where a table receives a lot of elements and you know the number beforehand, such as one for each UnitDef, by avoiding reallocation.

Params

nArray number — hint for count of array elements
nHashed number — hint for count of hashtable elements

Returns

table

tracy

table

table

[source]

tracy.LuaTracyPlot

function

function tracy.LuaTracyPlot(plotName: string, plotValue: number)

[source]

Update a Tracy plot with a value

Params

plotName string — Which LuaPlot should be updated
plotValue number — the number to show on the Tracy plot

tracy.LuaTracyPlotConfig

function

function tracy.LuaTracyPlotConfig(plotName: string, plotFormatType: "Memory"|"Number"|"Percentage"|nil, stepwise?: boolean, fill?: boolean, color?: integer)

[source]

Configure custom appearance for a Tracy plot for use in debugging or profiling

plotFormatType:
    | "Number"
    | "Percentage"
    | "Memory"

Params

plotName string — name of the plot to customize
plotFormatType "Memory"|"Number"|"Percentage"|nil — (Default: "Number")
stepwise boolean? — (Default: true) stepwise chart
fill boolean? — (Default: false) whether to fill color
color integer? — (Default: 0xFFFFFF) uint32 number as BGR color

xyz

type

[source]

Cartesian triple (XYZ)

Fields

x number
y number
z number

xz

type

[source]

Fields

x number
y number