Module `UnsyncedCtrl`

Callouts to set state

Tables

rgb: Color triple (RGB)
rgba: Color quadruple (RGBA)

Decals

Spring.CreateGroundDecal
Spring.DestroyGroundDecal
Spring.SetGroundDecalPosAndDims
Spring.SetGroundDecalQuadPosAndHeight
Spring.SetGroundDecalRotation
Spring.SetGroundDecalTexture
Spring.SetGroundDecalTextureParams
Spring.SetGroundDecalAlpha
Spring.SetGroundDecalNormal
Spring.SetGroundDecalTint
Spring.SetGroundDecalMisc
Spring.SetGroundDecalCreationFrame

Ingame Console

Spring.Ping: Send a ping request to the server
Spring.Echo: Useful for debugging.
Spring.Log
Spring.SendCommands
Spring.SetMapShader
Spring.SetMapSquareTexture
Spring.SetMapShadingTexture
Spring.SetSkyBoxTexture

Messages

Spring.SendMessage
Spring.SendMessageToSpectators
Spring.SendMessageToPlayer
Spring.SendMessageToTeam
Spring.SendMessageToAllyTeam

Sounds

Spring.LoadSoundDef: Loads a SoundDefs file, the format is the same as in gamedata/sounds.lua.
Spring.PlaySoundFile
Spring.PlaySoundStream: Allows to play an Ogg Vorbis (.OGG) and mp3 compressed sound file.
Spring.StopSoundStream: Terminates any SoundStream currently running.
Spring.PauseSoundStream: Pause any SoundStream currently running.
Spring.SetSoundStreamVolume: Set volume for SoundStream
Spring.SetSoundEffectParams
Spring.AddWorldIcon
Spring.AddWorldText
Spring.AddWorldUnit
Spring.DrawUnitCommands
Spring.DrawUnitCommands

Camera

camState: Parameters for camera state
Spring.SetCameraTarget: For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
Spring.SetCameraTarget
Spring.SetCameraState: Sets camera state

Unit Selection

Spring.SelectUnit: Selects a single unit
Spring.DeselectUnit
Spring.DeselectUnitArray: Deselects multiple units.
Spring.DeselectUnitMap: Deselects multiple units.
Spring.SelectUnitArray: Selects multiple units, or appends to selection.
Spring.SelectUnitMap: Selects multiple units, or appends to selection.

Lighting

lightParams: Parameters for lighting
Spring.AddMapLight
Spring.AddModelLight
Spring.UpdateMapLight
Spring.UpdateModelLight
Spring.AddLightTrackingTarget
Spring.SetMapLightTrackingState: Set a map-illuminating light to start/stop tracking the position of a moving object (unit or projectile)
Spring.SetModelLightTrackingState: Set a model-illuminating light to start/stop tracking the position of a moving object (unit or projectile)

Unit custom rendering

Spring.SetUnitNoDraw
Spring.SetUnitEngineDrawMask
Spring.SetUnitAlwaysUpdateMatrix
Spring.SetUnitNoMinimap
Spring.SetUnitNoSelect
Spring.SetUnitLeaveTracks
Spring.SetUnitSelectionVolumeData

Features

Spring.SetFeatureNoDraw
Spring.SetFeatureEngineDrawMask
Spring.SetFeatureAlwaysUpdateMatrix
Spring.SetFeatureFade: Control whether a feature will fade or not when zoomed out.
Spring.SetFeatureSelectionVolumeData

Unit Icons

Spring.AddUnitIcon
Spring.FreeUnitIcon
Spring.UnitIconSetDraw
Spring.SetUnitDefIcon
Spring.SetUnitDefImage

Virtual File System

Spring.ExtractModArchiveFile
Spring.CreateDir

GUI

Spring.SetActiveCommand
Spring.SetActiveCommand
Spring.LoadCmdColorsConfig
Spring.LoadCtrlPanelConfig
Spring.ForceLayoutUpdate
Spring.SetDrawSelectionInfo: Disables the "Selected Units x" box in the GUI.
Spring.SetBoxSelectionByEngine
Spring.SetTeamColor
Spring.AssignMouseCursor: Changes/creates the cursor of a single CursorCmd.
Spring.ReplaceMouseCursor: Mass replace all occurrences of the cursor in all CursorCmds.
Spring.SetCustomCommandDrawData: Register your custom cmd so it gets visible in the unit's cmd queue

Mouse

Spring.WarpMouse
Spring.SetMouseCursor

LOS Colors

Spring.SetLosViewColors
Spring.SetNanoProjectileParams

Engine Config

Spring.SetConfigInt
Spring.SetConfigFloat
Spring.SetConfigString
Spring.Quit: Closes the application

UI

Spring.SendLuaUIMsg
Spring.SendLuaGaiaMsg
Spring.SendLuaRulesMsg
Spring.SendLuaMenuMsg
Spring.SetLastMessagePosition

Sharing

Spring.SetShareLevel
Spring.ShareResources
Spring.ShareResources

Markers

Spring.MarkerAddPoint
Spring.MarkerAddLine
Spring.MarkerErasePosition

Sun

Spring.SetAtmosphere: It can be used to modify the following atmosphere parameters
Spring.SetSunDirection
Spring.SetSunLighting: It can be used to modify the following sun lighting parameters
mapRenderingParams: Map rendering params
Spring.SetMapRenderingParams: Allows to change map rendering params at runtime.
Spring.ForceTesselationUpdate

Developers

Spring.SetLogSectionFilterLevel
Spring.GarbageCollectCtrl
Spring.SetDrawSky
Spring.SetDrawWater
Spring.SetDrawGround
Spring.SetDrawGroundDeferred
Spring.SetDrawModelsDeferred
Spring.SetVideoCapturingMode: This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
Spring.SetVideoCapturingTimeOffset
waterParams: Water params
Spring.SetWaterParams

Preload

Spring.PreloadUnitDefModel
Spring.PreloadFeatureDefModel
Spring.PreloadSoundItem
Spring.LoadModelTextures

SDL Text

Spring.SDLSetTextInputRect
Spring.SDLStartTextInput
Spring.SDLStopTextInput

Window Management

Spring.SetWindowGeometry
Spring.SetWindowMinimized
Spring.SetWindowMaximized

Misc

Spring.Reload
Spring.Restart
Spring.Start: Launches a new Spring instance without terminating the existing one.
Spring.SetWMIcon: Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo).
SetWMCaption: Sets the window title for the process (default: "Spring ").
Spring.ClearWatchDogTimer
Spring.SetClipboard
Spring.Yield: Relinquish control of the game loading thread and OpenGL context back to the UI (LuaIntro).

Tables

rgb

Color triple (RGB)

Fields:

r number
g number
b number

rgba

Color quadruple (RGBA)

Fields:

r number
g number
b number
a number

Decals

Spring.CreateGroundDecal()

Returns:

nil or number decalID

Spring.DestroyGroundDecal(decalID)

Parameters:

decalID number

Returns:

bool delSuccess

Spring.SetGroundDecalPosAndDims(decalID[, midPosX=currMidPosX[, midPosZ=currMidPosZ[, sizeX=currSizeX[, sizeZ=currSizeZ[, projCubeHeight=calculateProjCubeHeight]]]]])

Parameters:

decalID number
midPosX number (default currMidPosX)
midPosZ number (default currMidPosZ)
sizeX number (default currSizeX)
sizeZ number (default currSizeZ)
projCubeHeight number (default calculateProjCubeHeight)

Returns:

bool decalSet

Spring.SetGroundDecalQuadPosAndHeight(decalID[, projCubeHeight=currPosTL.x])

Use for non-rectangular decals

Parameters:

decalID number
projCubeHeight number (default calculateProjCubeHeight)

Returns:

bool decalSet

Spring.SetGroundDecalRotation(decalID[, rot=random])

Parameters:

decalID number
rot number in radians (default random)

Returns:

bool decalSet

Spring.SetGroundDecalTexture(decalID, textureName[, isMainTex=true])

Parameters:

decalID number
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 bool If false, it sets the normals/glow map (default true)

Returns:

nil or bool decalSet

Spring.SetGroundDecalTextureParams(decalID, texWrapDistance, texTraveledDistance)

Parameters:

decalID number
texWrapDistance number [opt=currTexWrapDistance] if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos
texTraveledDistance number [opt=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:

nil or bool decalSet

Spring.SetGroundDecalAlpha(decalID[, alpha=currAlpha[, alphaFalloff=currAlphaFalloff]])

Parameters:

decalID number
alpha number Between 0 and 1 (default currAlpha)
alphaFalloff number Between 0 and 1, per second (default currAlphaFalloff)

Returns:

bool decalSet

Spring.SetGroundDecalNormal(decalID[, normalX=0[, normalY=0[, normalZ=0]]])

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

Parameters:

decalID number
normalX number (default 0)
normalY number (default 0)
normalZ number (default 0)

Returns:

bool decalSet

Spring.SetGroundDecalTint(decalID[, tintColR=curTintColR[, tintColG=curTintColG[, tintColB=curTintColB[, tintColA=curTintColA]]]])

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

Parameters:

decalID number
tintColR number (default curTintColR)
tintColG number (default curTintColG)
tintColB number (default curTintColB)
tintColA number (default curTintColA)

Returns:

bool decalSet

Spring.SetGroundDecalMisc(decalID[, dotElimExp=curValue[, refHeight=curValue[, minHeight=curValue[, maxHeight=curValue[, forceHeightMode=curValue]]]]])

Sets varios secondary parameters of a decal

Parameters:

decalID number
dotElimExp number pow(max(dot(decalProjVector, SurfaceNormal), 0.0), dotElimExp), used to reduce decal artifacts on surfaces non-collinear with the projection vector (default curValue)
refHeight number (default curValue)
minHeight number (default curValue)
maxHeight number (default curValue)
forceHeightMode number 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 (default curValue)

Returns:

bool decalSet

Spring.SetGroundDecalCreationFrame(decalID[, creationFrameMin=currCreationFrameMin[, creationFrameMax=currCreationFrameMax]])

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

Parameters:

decalID number
creationFrameMin number (default currCreationFrameMin)
creationFrameMax number (default currCreationFrameMax)

Returns:

bool decalSet

Give Order

Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) See Constants.CMD for relevant constants.

cmdOpts

Command Options params

Can be specified as a table, or as an array containing any of the keys below.

Fields:

right bool Right mouse key pressed
alt bool Alt key pressed
ctrl bool Ctrl key pressed
shift bool Shift key pressed
meta bool Meta (windows/mac/mod4) key pressed

Spring.GiveOrder(cmdID, params, options)

Parameters:

cmdID number
params table
options cmdOpts

Returns:

nil or true

Spring.GiveOrderToUnit(unitID, cmdID, params, options)

Parameters:

unitID number
cmdID number
params table
options cmdOpts

Returns:

nil or true

Spring.GiveOrderToUnitMap(unitMap, cmdID, params, options)

Parameters:

unitMap table { [unitID] = arg1, ... }
cmdID number
params table
options cmdOpts

Returns:

nil or true

Spring.GiveOrderToUnitArray(unitArray, cmdID, params, options)

Parameters:

unitArray {number,...} array of unit ids
cmdID number
params table
options cmdOpts

Returns:

nil or true

cmdSpec

Command spec

Used when assigning multiple commands at once

Fields:

cmdID number
params table
options cmdOpts

Spring.GiveOrderArrayToUnit(unitID, cmdArray)

Parameters:

unitID number
cmdArray {cmdSpec,...}

Returns:

bool ordersGiven

Spring.GiveOrderArrayToUnitMap(unitMap, cmdArray)

Parameters:

unitMap table { [unitID] = arg1, ... }
cmdArray {cmdSpec,...}

Returns:

bool ordersGiven

Spring.GiveOrderArrayToUnitArray(unitArray, cmdArray[, pairwise=false])

Parameters:

unitArray {number,...} array of unit ids
cmdArray {cmdSpec,...}
pairwise bool When false, assign all commands to each unit.
When true, assign commands according to index between units and cmds arrays.
If len(unitArray) < len(cmdArray) only the first len(unitArray) commands will be assigned, and vice-versa. (default false)

Returns:

nil or bool

Spring.SetBuildSpacing(spacing)

Parameters:

spacing number

Returns:

nil

Spring.SetBuildFacing(facing)

Parameters:

facing number

Returns:

nil

Ingame Console

Spring.Ping(pingTag)

Send a ping request to the server

Parameters:

pingTag number

Returns:

nil

Spring.Echo(arg1[, arg2[, argn]])

Useful for debugging.

Parameters:

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

Returns:

nil

Spring.Log(section, logLevel, logMessage1[, logMessage2[, logMessagen]])

Parameters:

section string

logLevel number or string

Possible values for logLevel are:

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

logMessage1 string
logMessage2 string (optional)
logMessagen string (optional)

Returns:

nil

Spring.SendCommands(command1, command2)

Parameters:

command1 string or table | { command1, command 2, ...}
command2 string

Returns:

nil

Spring.SetMapShader(standardShaderID, deferredShaderID)

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.

Parameters:

standardShaderID number
deferredShaderID number

Returns:

nil

Spring.SetMapSquareTexture(texSqrX, texSqrY, luaTexName)

Parameters:

texSqrX number
texSqrY number
luaTexName string

Returns:

bool success

Spring.SetMapShadingTexture(texType, texName)

Parameters:

texType string
texName string

Returns:

bool success

Usage:

Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")

Spring.SetSkyBoxTexture(texName)

Parameters:

texName string

Returns:

nil

Messages

Spring.SendMessage(message)

Parameters:

message string

Returns:

nil

Spring.SendMessageToSpectators(message)

Parameters:

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.SendMessageToPlayer(playerID, message)

Parameters:

playerID number
message string

Returns:

nil

Spring.SendMessageToTeam(teamID, message)

Parameters:

teamID number
message string

Returns:

nil

Spring.SendMessageToAllyTeam(allyID, message)

Parameters:

allyID number
message string

Returns:

nil

Sounds

Spring.LoadSoundDef(soundfile)

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

Parameters:

soundfile string

Returns:

nil or bool success

Spring.PlaySoundFile(soundfile[, volume=1.0[, posx[, posy[, posz[, speedx[, speedy[, speedz[, channel]]]]]]]])

Parameters:

soundfile string
volume number (default 1.0)
posx number (optional)
posy number (optional)
posz number (optional)
speedx number (optional)
speedy number (optional)
speedz number (optional)

channel number or string

Possible arguments for channel argument:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3

(optional)

Returns:

nil or bool playSound

Spring.PlaySoundStream(oggfile[, volume=1.0[, enqueue]])

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

Multiple sound streams may be played at once.

Parameters:

oggfile string
volume number (default 1.0)
enqueue bool (optional)

Returns:

nil or bool success

Spring.StopSoundStream()

Terminates any SoundStream currently running.

Returns:

nil

Spring.PauseSoundStream()

Pause any SoundStream currently running.

Returns:

nil

Spring.SetSoundStreamVolume(volume)

Set volume for SoundStream

Parameters:

volume number

Returns:

nil

Spring.SetSoundEffectParams()

Spring.AddWorldIcon(cmdID, posX, posY, posZ)

Parameters:

cmdID number
posX number
posY number
posZ number

Returns:

nil

Spring.AddWorldText(text, posX, posY, posZ)

Parameters:

text string
posX number
posY number
posZ number

Returns:

nil

Spring.AddWorldUnit(unitDefID, posX, posY, posZ, teamID, facing)

Parameters:

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

Returns:

nil

Spring.DrawUnitCommands(unitID)

Parameters:

unitID number

Returns:

nil

Spring.DrawUnitCommands(units, tableOrArray)

Parameters:

units table array of unit ids
tableOrArray bool [opt=false] when true units is interpreted as a table in the format { [unitID] = arg1, ... }

Returns:

nil

Camera

camState

Parameters for camera state

Highly dependent on the type of the current camera controller

Fields:

name string "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy"
mode number the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy)
fov number
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
dx number Camera direction vector X
dy number Camera direction vector Y
dz number Camera direction vector Z
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)
angle number Camera rotation angle on X axis (aka tilt/pitch) (ta)
flipped number -1 for when south is down, 1 for when north is down (ta)
dist number Camera distance from the ground (spring)
height number Camera distance from the ground (ta)
oldHeight number Camera distance from the ground, cannot be changed (rot)

Spring.SetCameraTarget(x, y, z[, transTime])

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

Parameters:

x number
y number
z number
transTime number (optional)

Returns:

nil

Spring.SetCameraTarget(px, py, pz, tx, ty, tz)

Parameters:

px number [opt=0]
py number [opt=0]
pz number [opt=0]
tx number [opt=0]
ty number [opt=0]
tz number [opt=0]

Returns:

nil

Spring.SetCameraState(camState[, transitionTime=0[, transitionTimeFactor[, transitionTimeExponent]]])

Sets camera state

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

Parameters:

camState camState
transitionTime number in nanoseconds (default 0)
transitionTimeFactor number multiplicative factor applied to this and all subsequent transition times for this camera mode.
Defaults to "CamTimeFactor" springsetting unless set previously. (optional)
transitionTimeExponent number tween factor applied to this and all subsequent transitions for this camera mode.
Defaults to "CamTimeExponent" springsetting unless set previously. (optional)

Returns:

bool set

Unit Selection

Spring.SelectUnit(unitID[, append=false])

Selects a single unit

Parameters:

unitID number or nil
append bool append to current selection (default false)

Returns:

nil

Spring.DeselectUnit(unitID)

Parameters:

unitID number

Returns:

nil

Spring.DeselectUnitArray(unitID)

Deselects multiple units.

Accepts a table with unitIDs as values

Parameters:

unitID {[any] , ...} unitIDs

Returns:

nil

Spring.DeselectUnitMap(any)

Deselects multiple units.

Accepts a table with unitIDs as keys

Parameters:

any {[unitID] , ...} unitMap where keys are unitIDs

Returns:

nil

Spring.SelectUnitArray(unitID[, append=false])

Selects multiple units, or appends to selection.

Accepts a table with unitIDs as values

Parameters:

unitID {[any] , ...} unitIDs
append bool append to current selection (default false)

Returns:

nil

Spring.SelectUnitMap(any[, append=false])

Selects multiple units, or appends to selection.

Accepts a table with unitIDs as keys

Parameters:

any {[unitID] , ...} unitMap where keys are unitIDs
append bool append to current selection (default false)

Returns:

nil

Lighting

lightParams

Parameters for lighting

Fields:

position
- px number
- py number
- pz number
direction
- dx number
- dy number
- dz number
ambientColor
- red number
- green number
- blue number
diffuseColor
- red number
- green number
- blue number
specularColor
- red number
- green number
- blue number
intensityWeight
- ambientWeight number
- diffuseWeight number
- specularWeight number
ambientDecayRate per-frame decay of ambientColor (spread over TTL frames)
- ambientRedDecay number
- ambientGreenDecay number
- ambientBlueDecay number
diffuseDecayRate per-frame decay of diffuseColor (spread over TTL frames)
- diffuseRedDecay number
- diffuseGreenDecay number
- diffuseBlueDecay number
specularDecayRate per-frame decay of specularColor (spread over TTL frames)
- specularRedDecay number
- specularGreenDecay number
- specularBlueDecay number
decayFunctionType *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
- ambientDecayType number
- diffuseDecayType number
- specularDecayType number
radius number
fov number
ttl number
priority number
ignoreLOS bool

Spring.AddMapLight(lightParams)

requires MaxDynamicMapLights > 0

Parameters:

lightParams lightParams

Returns:

number lightHandle

Spring.AddModelLight(lightParams)

requires MaxDynamicMapLights > 0

Parameters:

lightParams lightParams

Returns:

number lightHandle

Spring.UpdateMapLight(lightHandle, lightParams)

Parameters:

lightHandle number
lightParams lightParams

Returns:

bool success

Spring.UpdateModelLight(lightHandle, lightParams)

Parameters:

lightHandle number
lightParams lightParams

Returns:

bool success

Spring.AddLightTrackingTarget()

Spring.SetMapLightTrackingState(lightHandle, unitOrProjectileID, enableTracking, unitOrProjectile)

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

Parameters:

lightHandle number
unitOrProjectileID number
enableTracking bool
unitOrProjectile bool

Returns:

bool success

Spring.SetModelLightTrackingState(lightHandle, unitOrProjectileID, enableTracking, unitOrProjectile)

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

Parameters:

lightHandle number
unitOrProjectileID number
enableTracking bool
unitOrProjectile bool

Returns:

bool success

Unit custom rendering

Spring.SetUnitNoDraw(unitID, noDraw)

Parameters:

unitID number
noDraw bool

Returns:

nil

Spring.SetUnitEngineDrawMask(unitID, drawMask)

Parameters:

unitID number
drawMask number

Returns:

nil

Spring.SetUnitAlwaysUpdateMatrix(unitID, alwaysUpdateMatrix)

Parameters:

unitID number
alwaysUpdateMatrix bool

Returns:

nil

Spring.SetUnitNoMinimap(unitID, unitNoMinimap)

Parameters:

unitID number
unitNoMinimap bool

Returns:

nil

Spring.SetUnitNoSelect(unitID, unitNoSelect)

Parameters:

unitID number
unitNoSelect bool whether unit can be selected or not

Returns:

nil

Spring.SetUnitLeaveTracks(unitID, unitLeaveTracks)

Parameters:

unitID number
unitLeaveTracks bool whether unit leaves tracks on movement

Returns:

nil

Spring.SetUnitSelectionVolumeData(unitID, featureID, scaleX, scaleY, scaleZ, offsetX, offsetY, offsetZ, vType, tType, Axis)

Parameters:

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

Returns:

nil

Features

Spring.SetFeatureNoDraw(featureID, noDraw)

Parameters:

featureID number
noDraw bool

Returns:

nil

Spring.SetFeatureEngineDrawMask(featureID, engineDrawMask)

Parameters:

featureID number
engineDrawMask number

Returns:

nil

Spring.SetFeatureAlwaysUpdateMatrix(featureID, alwaysUpdateMat)

Parameters:

featureID number
alwaysUpdateMat number

Returns:

nil

Spring.SetFeatureFade(featureID, allow)

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

Parameters:

featureID number
allow bool

Returns:

nil

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

Parameters:

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

Returns:

nil

Unit Icons

Spring.AddUnitIcon(iconName, texFile[, size[, dist[, radAdjust]]])

Parameters:

iconName string
texFile string
size number (optional)
dist number (optional)
radAdjust number (optional)

Returns:

nil or bool added

Spring.FreeUnitIcon(iconName)

Parameters:

iconName string

Returns:

nil or bool freed

Spring.UnitIconSetDraw(unitID, drawIcon)

Parameters:

unitID number
drawIcon bool

Returns:

nil

Spring.SetUnitDefIcon(unitDefID, iconName)

Parameters:

unitDefID number
iconName string

Returns:

nil

Spring.SetUnitDefImage(unitDefID, image)

Parameters:

unitDefID number
image string luaTexture|texFile

Returns:

nil

Virtual File System

Prefer using VFS whenever possible

Spring.ExtractModArchiveFile(modfile)

Parameters:

modfile string

Returns:

bool extracted

Spring.CreateDir(path)

Parameters:

path string

Returns:

nil or bool dirCreated

GUI

Spring.SetActiveCommand(action[, actionExtra])

Parameters:

action string
actionExtra string (optional)

Returns:

nil or bool commandSet

Spring.SetActiveCommand(cmdIndex[, button=1][, leftClick], rightClick, alt, ctrl, meta, shift)

Parameters:

cmdIndex number
button number (default 1)
leftClick bool (optional)
rightClick optional bool
alt optional bool
ctrl optional bool
meta optional bool
shift optional bool

Returns:

nil or bool commandSet

Spring.LoadCmdColorsConfig(config)

Parameters:

config string

Returns:

nil

Spring.LoadCtrlPanelConfig(config)

Parameters:

config string

Returns:

nil

Spring.ForceLayoutUpdate()

Returns:

nil

Spring.SetDrawSelectionInfo(enable)

Disables the "Selected Units x" box in the GUI.

Parameters:

enable bool

Returns:

nil

Spring.SetBoxSelectionByEngine(state)

Parameters:

state bool

Returns:

nil

Spring.SetTeamColor(teamID, r, g, b)

Parameters:

teamID number
r number
g number
b number

Returns:

nil

Spring.AssignMouseCursor(cmdName, iconFileName[, overwrite=true[, hotSpotTopLeft=false]])

Changes/creates the cursor of a single CursorCmd.

Parameters:

cmdName string

iconFileName string

not the full filename, instead it is like this:

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

overwrite bool (default true)
hotSpotTopLeft bool (default false)

Returns:

nil or bool assigned

Spring.ReplaceMouseCursor(oldFileName, newFileName[, hotSpotTopLeft=false])

Mass replace all occurrences of the cursor in all CursorCmds.

Parameters:

oldFileName string
newFileName string
hotSpotTopLeft bool (default false)

Returns:

nil or bool assigned

Spring.SetCustomCommandDrawData(cmdID[, cmdReference])

Parameters:

cmdID number
cmdReference string or number iconname | cmdID_cloneIcon (optional)

Returns:

nil or bool assigned

Mouse

Spring.WarpMouse(x, y)

Parameters:

x number
y number

Returns:

nil

Spring.SetMouseCursor(cursorName[, cursorScale=1.0])

Parameters:

cursorName string
cursorScale number (default 1.0)

Returns:

nil

LOS Colors

Spring.SetLosViewColors(always, LOS, radar, jam, radar2)

Parameters:

always table {r,g,b}
LOS table = {r,g,b}
radar table = {r,g,b}
jam table = {r,g,b}
radar2 table = {r,g,b}

Returns:

nil

Spring.SetNanoProjectileParams([rotVal=0[, rotVel=0[, rotAcc=0[, rotValRng=0[, rotVelRng=0[, rotAccRng=0]]]]]])

Parameters:

rotVal number in degrees (default 0)
rotVel number in degrees (default 0)
rotAcc number in degrees (default 0)
rotValRng number in degrees (default 0)
rotVelRng number in degrees (default 0)
rotAccRng number in degrees (default 0)

Returns:

nil

Engine Config

The following functions read the engine configs saved in Springsettings.cfg, a version-ed instance of these or a custom file supplied on the command line.

Spring.SetConfigInt(name, value[, useOverlay=false])

Parameters:

name string
value number
useOverlay bool the value will only be set in memory, and not be restored for the next game. (default false)

Returns:

nil

Spring.SetConfigFloat(name, value[, useOverla=false])

Parameters:

name string
value number
useOverla bool the value will only be set in memory, and not be restored for the next game.y (default false)

Returns:

nil

Spring.SetConfigString(name, value[, useOverlay=false])

Parameters:

name string
value number
useOverlay bool the value will only be set in memory, and not be restored for the next game. (default false)

Returns:

nil

Spring.Quit()

Closes the application

Returns:

nil

Unit Group

Spring.SetUnitGroup(unitID, groupID)

Parameters:

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

Returns:

nil

UI

Very important! (allows synced inter-lua-enviroment communications)

Spring.SendLuaUIMsg(message, mode)

Parameters:

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

Returns:

nil

Spring.SendLuaGaiaMsg(message)

Parameters:

message string

Returns:

nil

Spring.SendLuaRulesMsg(message)

Parameters:

message string

Returns:

nil

Spring.SendLuaMenuMsg(msg)

Parameters:

msg string

Spring.SetLastMessagePosition(x, y, z)

Parameters:

x number
y number
z number

Returns:

nil

Spring.SetShareLevel(resource, shareLevel)

Parameters:

resource string metal | energy
shareLevel number

Returns:

nil

Spring.ShareResources(teamID, units)

Parameters:

teamID number
units string

Returns:

nil

Spring.ShareResources(teamID, resource, amount)

Parameters:

teamID number
resource string metal | energy
amount number

Returns:

nil

Markers

Spring.MarkerAddPoint(x, y, z[, text=""[, localOnly]])

Parameters:

x number
y number
z number
text string (default "")
localOnly bool (optional)

Returns:

nil

Spring.MarkerAddLine(x1, y1, z1, x2, y2, z2[, localOnly=false[, playerId]])

Parameters:

x1 number
y1 number
z1 number
x2 number
y2 number
z2 number
localOnly bool (default false)
playerId number (optional)

Returns:

nil

Spring.MarkerErasePosition(x, y, z, noop[, localOnly=false[, playerId[, alwaysErase=false]]])

Issue an erase command for markers on the map.

Parameters:

x number
y number
z number
noop
localOnly bool do not issue a network message, erase only for the current player (default false)
playerId number when not specified it uses the issuer playerId (optional)
alwaysErase bool erase any marker when localOnly and current player is spectating. Allows spectators to erase players markers locally (default false)

Returns:

nil

Sun

Spring.SetAtmosphere(params)

It can be used to modify the following atmosphere parameters

Parameters:

params
- fogStart number
- fogEnd number
- sunColor rgb
- skyColor rgb
- cloudColor rgb

Returns:

nil

Usage:

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

Spring.SetSunDirection(dirX, dirY, dirZ[, intensity=true])

Parameters:

dirX number
dirY number
dirZ number
intensity number (default true)

Returns:

nil

Spring.SetSunLighting(params)

It can be used to modify the following sun lighting parameters

Parameters:

params
- groundAmbientColor rgb
- groundDiffuseColor rgb

Returns:

nil

Usage:

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

mapRenderingParams

Map rendering params

Fields:

splatTexMults rgba
splatTexScales rgba
voidWater bool
voidGround bool
splatDetailNormalDiffuseAlpha bool

Spring.SetMapRenderingParams(params)

Allows to change map rendering params at runtime.

Parameters:

params mapRenderingParams

Returns:

nil

Spring.ForceTesselationUpdate([normal=true[, shadow=false]])

Parameters:

normal bool (default true)
shadow bool (default false)

Returns:

bool updated

AI

Spring.SendSkirmishAIMessage(aiTeam, message)

Parameters:

aiTeam number
message string

Returns:

nil or bool ai_processed

Developers

Spring.SetLogSectionFilterLevel(sectionName, logLevel)

Parameters:

sectionName string
logLevel string or number

Returns:

nil

Spring.GarbageCollectCtrl([itersPerBatch[, numStepsPerIter[, minStepsPerIter[, maxStepsPerIter[, minLoopRunTime[, maxLoopRunTime[, baseRunTimeMult[, baseMemLoadMult]]]]]]]])

Parameters:

itersPerBatch int (optional)
numStepsPerIter int (optional)
minStepsPerIter int (optional)
maxStepsPerIter int (optional)
minLoopRunTime number (optional)
maxLoopRunTime number (optional)
baseRunTimeMult number (optional)
baseMemLoadMult number (optional)

Returns:

nil

Spring.SetDrawSky(drawSky)

Parameters:

drawSky bool

Returns:

nil

Spring.SetDrawWater(drawWater)

Parameters:

drawWater bool

Returns:

nil

Spring.SetDrawGround(drawGround)

Parameters:

drawGround bool

Returns:

nil

Spring.SetDrawGroundDeferred(drawGroundDeferred[, drawGroundForward])

Parameters:

drawGroundDeferred bool
drawGroundForward bool allows disabling of the forward pass treturn nil (optional)

Spring.SetDrawModelsDeferred(drawUnitsDeferred, drawFeaturesDeferred[, drawUnitsForward[, drawFeaturesForward]])

Parameters:

drawUnitsDeferred bool
drawFeaturesDeferred bool
drawUnitsForward bool allows disabling of the respective forward passes (optional)
drawFeaturesForward bool allows disabling of the respective forward passes (optional)

Returns:

nil

Spring.SetVideoCapturingMode(allowCaptureMode)

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

Parameters:

allowCaptureMode bool

Returns:

nil

Spring.SetVideoCapturingTimeOffset(timeOffset)

Parameters:

timeOffset bool

Returns:

nil

waterParams

Water params

Fields:

absorb rgb
baseColor rgb
minColor rgb
surfaceColor rgb
diffuseColor rgb
specularColor rgb
planeColor rgb
texture string file
foamTexture string file
normalTexture string file
damage number
repeatX number
repeatY number
surfaceAlpha number
ambientFactor number
diffuseFactor number
specularFactor number
specularPower number
fresnelMin number
fresnelMax number
fresnelPower number
reflectionDistortion number
blurBase number
blurExponent number
perlinStartFreq number
perlinLacunarity number
perlinAmplitude number
numTiles number
shoreWaves bool
forceRendering bool
hasWaterPlane bool

Spring.SetWaterParams(waterParams)

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

Parameters:

waterParams waterParams

Returns:

nil

Preload

Spring.PreloadUnitDefModel(unitDefID)

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

Parameters:

unitDefID number

Returns:

nil

Spring.PreloadFeatureDefModel(featureDefID)

Parameters:

featureDefID number

Returns:

nil

Spring.PreloadSoundItem(name)

Parameters:

name string

Returns:

nil

Spring.LoadModelTextures(modelName)

Parameters:

modelName string

Returns:

nil or bool success

SDL Text

Spring.SDLSetTextInputRect(x, y, width, height)

Parameters:

x number
y number
width number
height number

Returns:

nil

Spring.SDLStartTextInput()

Returns:

nil

Spring.SDLStopTextInput()

Returns:

nil

Window Management

Spring.SetWindowGeometry(displayIndex, winRelPosX, winRelPosY, winSizeX, winSizeY, fullScreen, borderless)

Parameters:

displayIndex number
winRelPosX number
winRelPosY number
winSizeX number
winSizeY number
fullScreen bool
borderless bool

Returns:

nil

Spring.SetWindowMinimized()

Returns:

bool minimized

Spring.SetWindowMaximized()

Returns:

bool maximized

Misc

Spring.Reload(startScript)

Parameters:

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

Returns:

nil

Spring.Restart(commandline_args, startScript)

If this call returns, something went wrong

Parameters:

commandline_args string commandline arguments passed to spring executable.
startScript string

Returns:

nil

Spring.Start(commandline_args, startScript)

Launches a new Spring instance without terminating the existing one.

If this call returns, something went wrong

Parameters:

commandline_args string commandline arguments passed to spring executable.
startScript string the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args.

Returns:

nil

Spring.SetWMIcon(iconFileName)

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.

Parameters:

iconFileName string

Returns:

nil

SetWMCaption(title[, titleShort=title])

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.

Parameters:

title string
titleShort string (default title)

Returns:

nil

Spring.ClearWatchDogTimer([threadName=main])

Parameters:

threadName string (default main)

Returns:

nil

Spring.SetClipboard(text)

Parameters:

text string

Returns:

nil

Spring.Yield()

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.

Returns:

bool when true caller should continue calling Spring.Yield during the widgets/gadgets load, when false it shouldn't call it any longer.

Usage:

local wantYield = Spring.Yield and Spring.Yield() -- nil check: not present in synced
for wupget in pairs(wupgetsToLoad) do
  loadWupget(wupget)
  wantYield = wantYield and Spring.Yield()
end

Module UnsyncedCtrl

See also:

Tables

rgb

Fields:

rgba

Fields:

Decals

Spring.CreateGroundDecal()

Returns:

Spring.DestroyGroundDecal(decalID)

Parameters:

Returns:

Spring.SetGroundDecalPosAndDims(decalID[, midPosX=currMidPosX[, midPosZ=currMidPosZ[, sizeX=currSizeX[, sizeZ=currSizeZ[, projCubeHeight=calculateProjCubeHeight]]]]])

Parameters:

Returns:

Spring.SetGroundDecalQuadPosAndHeight(decalID[, projCubeHeight=currPosTL.x])

Parameters:

Returns:

Spring.SetGroundDecalRotation(decalID[, rot=random])

Parameters:

Returns:

Spring.SetGroundDecalTexture(decalID, textureName[, isMainTex=true])

Parameters:

Returns:

Spring.SetGroundDecalTextureParams(decalID, texWrapDistance, texTraveledDistance)

Parameters:

Returns:

Spring.SetGroundDecalAlpha(decalID[, alpha=currAlpha[, alphaFalloff=currAlphaFalloff]])

Parameters:

Returns:

Spring.SetGroundDecalNormal(decalID[, normalX=0[, normalY=0[, normalZ=0]]])

Parameters:

Returns:

Spring.SetGroundDecalTint(decalID[, tintColR=curTintColR[, tintColG=curTintColG[, tintColB=curTintColB[, tintColA=curTintColA]]]])

Parameters:

Returns:

Spring.SetGroundDecalMisc(decalID[, dotElimExp=curValue[, refHeight=curValue[, minHeight=curValue[, maxHeight=curValue[, forceHeightMode=curValue]]]]])

Parameters:

Returns:

Spring.SetGroundDecalCreationFrame(decalID[, creationFrameMin=currCreationFrameMin[, creationFrameMax=currCreationFrameMax]])

Parameters:

Returns:

Give Order

cmdOpts

Fields:

Spring.GiveOrder(cmdID, params, options)

Parameters:

Returns:

Spring.GiveOrderToUnit(unitID, cmdID, params, options)

Parameters:

Returns:

Spring.GiveOrderToUnitMap(unitMap, cmdID, params, options)

Parameters:

Returns:

Spring.GiveOrderToUnitArray(unitArray, cmdID, params, options)

Parameters:

Returns:

cmdSpec

Fields:

Spring.GiveOrderArrayToUnit(unitID, cmdArray)

Parameters:

Returns:

Spring.GiveOrderArrayToUnitMap(unitMap, cmdArray)

Parameters:

Returns:

Spring.GiveOrderArrayToUnitArray(unitArray, cmdArray[, pairwise=false])

Parameters:

Returns:

Spring.SetBuildSpacing(spacing)

Parameters:

Returns:

Spring.SetBuildFacing(facing)

Parameters:

Returns:

Ingame Console

Spring.Ping(pingTag)

Parameters:

Returns:

Spring.Echo(arg1[, arg2[, argn]])

Module `UnsyncedCtrl`