Module UnsyncedCtrl

Callouts to set state

See also:

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

Give Order

cmdOpts
Command Options params
Spring.GiveOrder
Spring.GiveOrderToUnit
Spring.GiveOrderToUnitMap
Spring.GiveOrderToUnitArray
cmdSpec
Command spec
Spring.GiveOrderArrayToUnit
Spring.GiveOrderArrayToUnitMap
Spring.GiveOrderArrayToUnitArray
Spring.SetBuildSpacing
Spring.SetBuildFacing

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.SetCameraOffset
Spring.SetCameraState
Sets camera state
Spring.RunDollyCamera
Runs Dolly Camera
Spring.PauseDollyCamera
Pause Dolly Camera
Spring.ResumeDollyCamera
Resume Dolly Camera
Spring.SetDollyCameraPosition
Sets Dolly Camera Position
Spring.SetDollyCameraCurve
Sets Dolly Camera movement Curve
Spring.SetDollyCameraMode
Sets Dolly Camera movement mode
Spring.SetDollyCameraRelativeMode
Sets Dolly Camera movement curve to world relative or look target relative
Spring.SetDollyCameraLookCurve
Sets Dolly Camera Look Curve
Spring.SetDollyCameraLookPosition
Sets Dolly Camera Look Position
Spring.SetDollyCameraLookUnit
Sets target unit for Dolly Camera to look towards

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
Spring.AllocateTable

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

Unit Group

Spring.SetUnitGroup

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

AI

Spring.SendSkirmishAIMessage

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:

  1. r number
  2. g number
  3. b number

rgba

Color quadruple (RGBA)

Fields:

  1. r number
  2. g number
  3. b number
  4. a number

Decals

Spring.CreateGroundDecal()

Returns:

  1. nil or number decalID

Spring.DestroyGroundDecal(decalID)

Parameters:

  1. decalID number

Returns:

  1. bool delSuccess

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

Parameters:

  1. decalID number
  2. midPosX number (default currMidPosX)
  3. midPosZ number (default currMidPosZ)
  4. sizeX number (default currSizeX)
  5. sizeZ number (default currSizeZ)
  6. projCubeHeight number (default calculateProjCubeHeight)

Returns:

  1. bool decalSet

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

Use for non-rectangular decals

Parameters:

  1. decalID number
  2. projCubeHeight number (default calculateProjCubeHeight)

Returns:

  1. bool decalSet

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

Parameters:

  1. decalID number
  2. rot number in radians (default random)

Returns:

  1. bool decalSet

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

Parameters:

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

Returns:

  1. nil or bool decalSet

Spring.SetGroundDecalTextureParams(decalID, texWrapDistance, texTraveledDistance)

Parameters:

  1. decalID number
  2. 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
  3. 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:

  1. nil or bool decalSet

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

Parameters:

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

Returns:

  1. 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:

  1. decalID number
  2. normalX number (default 0)
  3. normalY number (default 0)
  4. normalZ number (default 0)

Returns:

  1. 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:

  1. decalID number
  2. tintColR number (default curTintColR)
  3. tintColG number (default curTintColG)
  4. tintColB number (default curTintColB)
  5. tintColA number (default curTintColA)

Returns:

  1. bool decalSet

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

Sets varios secondary parameters of a decal

Parameters:

  1. decalID number
  2. 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)
  3. refHeight number (default curValue)
  4. minHeight number (default curValue)
  5. maxHeight number (default curValue)
  6. 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:

  1. bool decalSet

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

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

Parameters:

  1. decalID number
  2. creationFrameMin number (default currCreationFrameMin)
  3. creationFrameMax number (default currCreationFrameMax)

Returns:

  1. 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:

  1. right bool Right mouse key pressed
  2. alt bool Alt key pressed
  3. ctrl bool Ctrl key pressed
  4. shift bool Shift key pressed
  5. meta bool Meta (windows/mac/mod4) key pressed

Spring.GiveOrder(cmdID, params, options)

Parameters:

  1. cmdID number
  2. params table
  3. options cmdOpts

Returns:

  1. nil or true

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

Parameters:

  1. unitID number
  2. cmdID number
  3. params table
  4. options cmdOpts

Returns:

  1. nil or true

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

Parameters:

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

Returns:

  1. nil or true

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

Parameters:

  1. unitArray {number,...} array of unit ids
  2. cmdID number
  3. params table
  4. options cmdOpts

Returns:

  1. nil or true

cmdSpec

Command spec

Used when assigning multiple commands at once

Fields:

  1. cmdID number
  2. params table
  3. options cmdOpts

Spring.GiveOrderArrayToUnit(unitID, cmdArray)

Parameters:

  1. unitID number
  2. cmdArray {cmdSpec,...}

Returns:

  1. bool ordersGiven

Spring.GiveOrderArrayToUnitMap(unitMap, cmdArray)

Parameters:

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

Returns:

  1. bool ordersGiven

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

Parameters:

  1. unitArray {number,...} array of unit ids
  2. cmdArray {cmdSpec,...}
  3. 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:

  1. nil or bool

Spring.SetBuildSpacing(spacing)

Parameters:

  1. spacing number

Returns:

  1. nil

Spring.SetBuildFacing(facing)

Parameters:

  1. facing number

Returns:

  1. nil

Ingame Console

Spring.Ping(pingTag)

Send a ping request to the server

Parameters:

  1. pingTag number

Returns:

  1. nil

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

Useful for debugging.

Parameters:

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

Returns:

  1. nil

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

Parameters:

  1. section string
  2. 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
  3. logMessage1 string
  4. logMessage2 string (optional)
  5. logMessagen string (optional)

Returns:

  1. nil

Spring.SendCommands(command1, command2)

Parameters:

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

Returns:

  1. 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:

  1. standardShaderID number
  2. deferredShaderID number

Returns:

  1. nil

Spring.SetMapSquareTexture(texSqrX, texSqrY, luaTexName)

Parameters:

  1. texSqrX number
  2. texSqrY number
  3. luaTexName string

Returns:

  1. bool success

Spring.SetMapShadingTexture(texType, texName)

Parameters:

  1. texType string
  2. texName string

Returns:

  1. bool success

Usage:

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

Spring.SetSkyBoxTexture(texName)

Parameters:

  1. texName string

Returns:

  1. nil

Messages

Spring.SendMessage(message)

Parameters:

  1. message string

Returns:

  1. nil

Spring.SendMessageToSpectators(message)

Parameters:

  1. 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:

  1. nil

Spring.SendMessageToPlayer(playerID, message)

Parameters:

  1. playerID number
  2. message string

Returns:

  1. nil

Spring.SendMessageToTeam(teamID, message)

Parameters:

  1. teamID number
  2. message string

Returns:

  1. nil

Spring.SendMessageToAllyTeam(allyID, message)

Parameters:

  1. allyID number
  2. message string

Returns:

  1. nil

Sounds

Spring.LoadSoundDef(soundfile)

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

Parameters:

  1. soundfile string

Returns:

  1. nil or bool success

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

Parameters:

  1. soundfile string
  2. volume number (default 1.0)
  3. posx number (optional)
  4. posy number (optional)
  5. posz number (optional)
  6. speedx number (optional)
  7. speedy number (optional)
  8. speedz number (optional)
  9. channel number or string
    Possible arguments for channel argument:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3
    (optional)

Returns:

  1. 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:

  1. oggfile string
  2. volume number (default 1.0)
  3. enqueue bool (optional)

Returns:

  1. nil or bool success

Spring.StopSoundStream()

Terminates any SoundStream currently running.

Returns:

  1. nil

Spring.PauseSoundStream()

Pause any SoundStream currently running.

Returns:

  1. nil

Spring.SetSoundStreamVolume(volume)

Set volume for SoundStream

Parameters:

  1. volume number

Returns:

  1. nil

Spring.SetSoundEffectParams()

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

Parameters:

  1. cmdID number
  2. posX number
  3. posY number
  4. posZ number

Returns:

  1. nil

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

Parameters:

  1. text string
  2. posX number
  3. posY number
  4. posZ number

Returns:

  1. nil

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

Parameters:

  1. unitDefID number
  2. posX number
  3. posY number
  4. posZ number
  5. teamID number
  6. facing number

Returns:

  1. nil

Spring.DrawUnitCommands(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil

Spring.DrawUnitCommands(units, tableOrArray)

Parameters:

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

Returns:

  1. nil

Camera

camState

Parameters for camera state

Highly dependent on the type of the current camera controller

Fields:

  1. name string "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy"
  2. mode number the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy)
  3. fov number
  4. px number Position X of the ground point in screen center
  5. py number Position Y of the ground point in screen center
  6. pz number Position Z of the ground point in screen center
  7. dx number Camera direction vector X
  8. dy number Camera direction vector Y
  9. dz number Camera direction vector Z
  10. rx number Camera rotation angle on X axis (spring)
  11. ry number Camera rotation angle on Y axis (spring)
  12. rz number Camera rotation angle on Z axis (spring)
  13. angle number Camera rotation angle on X axis (aka tilt/pitch) (ta)
  14. flipped number -1 for when south is down, 1 for when north is down (ta)
  15. dist number Camera distance from the ground (spring)
  16. height number Camera distance from the ground (ta)
  17. 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:

  1. x number
  2. y number
  3. z number
  4. transTime number (optional)

Returns:

  1. nil

Spring.SetCameraOffset([posX=0[, posY=0[, posZ=0[, tiltX=0[, tiltY=0[, tiltZ=0]]]]]])

Parameters:

  1. posX number (default 0)
  2. posY number (default 0)
  3. posZ number (default 0)
  4. tiltX number (default 0)
  5. tiltY number (default 0)
  6. tiltZ number (default 0)

Returns:

  1. 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:

  1. camState camState
  2. transitionTime number in nanoseconds (default 0)
  3. transitionTimeFactor number multiplicative factor applied to this and all subsequent transition times for this camera mode.

    Defaults to "CamTimeFactor" springsetting unless set previously. (optional)

  4. transitionTimeExponent number tween factor applied to this and all subsequent transitions for this camera mode.

    Defaults to "CamTimeExponent" springsetting unless set previously. (optional)

Returns:

  1. bool set

Spring.RunDollyCamera(runtime)

Runs Dolly Camera

Parameters:

  1. runtime number in milliseconds

Returns:

  1. nil

Spring.PauseDollyCamera(fraction)

Pause Dolly Camera

Parameters:

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

Returns:

  1. nil

Spring.ResumeDollyCamera()

Resume Dolly Camera

Returns:

  1. nil

Spring.SetDollyCameraPosition(x, y, z)

Sets Dolly Camera Position

Parameters:

  1. x number
  2. y number
  3. z number

Returns:

  1. nil

Spring.SetDollyCameraCurve(degree, cpoints, knots)

Sets Dolly Camera movement Curve

Parameters:

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

Returns:

  1. nil

Spring.SetDollyCameraMode(mode)

Sets Dolly Camera movement mode

Parameters:

  1. mode number 1 static position, 2 nurbs curve

Returns:

  1. nil

Spring.SetDollyCameraRelativeMode(relativeMode)

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

Parameters:

  1. relativeMode number 1 world, 2 look target

Returns:

  1. nil

Spring.SetDollyCameraLookCurve(degree, cpoints, knots)

Sets Dolly Camera Look Curve

Parameters:

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

Returns:

  1. nil

Spring.SetDollyCameraLookPosition(x, y, z)

Sets Dolly Camera Look Position

Parameters:

  1. x number
  2. y number
  3. z number

Returns:

  1. nil

Spring.SetDollyCameraLookUnit(unitID)

Sets target unit for Dolly Camera to look towards

Parameters:

  1. unitID number the unit to look at

Returns:

  1. nil

Unit Selection

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

Selects a single unit

Parameters:

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

Returns:

  1. nil

Spring.DeselectUnit(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil

Spring.DeselectUnitArray(unitID)

Deselects multiple units.

Accepts a table with unitIDs as values

Parameters:

  1. unitID {[any] , ...} unitIDs

Returns:

  1. nil

Spring.DeselectUnitMap(any)

Deselects multiple units.

Accepts a table with unitIDs as keys

Parameters:

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

Returns:

  1. nil

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

Selects multiple units, or appends to selection.

Accepts a table with unitIDs as values

Parameters:

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

Returns:

  1. nil

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

Selects multiple units, or appends to selection.

Accepts a table with unitIDs as keys

Parameters:

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

Returns:

  1. nil

Lighting

lightParams

Parameters for lighting

Fields:

  1. position
    • px number
    • py number
    • pz number
  2. direction
    • dx number
    • dy number
    • dz number
  3. ambientColor
    • red number
    • green number
    • blue number
  4. diffuseColor
    • red number
    • green number
    • blue number
  5. specularColor
    • red number
    • green number
    • blue number
  6. intensityWeight
    • ambientWeight number
    • diffuseWeight number
    • specularWeight number
  7. ambientDecayRate per-frame decay of ambientColor (spread over TTL frames)
    • ambientRedDecay number
    • ambientGreenDecay number
    • ambientBlueDecay number
  8. diffuseDecayRate per-frame decay of diffuseColor (spread over TTL frames)
    • diffuseRedDecay number
    • diffuseGreenDecay number
    • diffuseBlueDecay number
  9. specularDecayRate per-frame decay of specularColor (spread over TTL frames)
    • specularRedDecay number
    • specularGreenDecay number
    • specularBlueDecay number
  10. decayFunctionType *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
    • ambientDecayType number
    • diffuseDecayType number
    • specularDecayType number
  11. radius number
  12. fov number
  13. ttl number
  14. priority number
  15. ignoreLOS bool

Spring.AddMapLight(lightParams)

requires MaxDynamicMapLights > 0

Parameters:

  1. lightParams lightParams

Returns:

  1. number lightHandle

Spring.AddModelLight(lightParams)

requires MaxDynamicMapLights > 0

Parameters:

  1. lightParams lightParams

Returns:

  1. number lightHandle

Spring.UpdateMapLight(lightHandle, lightParams)

Parameters:

  1. lightHandle number
  2. lightParams lightParams

Returns:

  1. bool success

Spring.UpdateModelLight(lightHandle, lightParams)

Parameters:

  1. lightHandle number
  2. lightParams lightParams

Returns:

  1. 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:

  1. lightHandle number
  2. unitOrProjectileID number
  3. enableTracking bool
  4. unitOrProjectile bool

Returns:

  1. 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:

  1. lightHandle number
  2. unitOrProjectileID number
  3. enableTracking bool
  4. unitOrProjectile bool

Returns:

  1. bool success

Unit custom rendering

Spring.SetUnitNoDraw(unitID, noDraw)

Parameters:

  1. unitID number
  2. noDraw bool

Returns:

  1. nil

Spring.SetUnitEngineDrawMask(unitID, drawMask)

Parameters:

  1. unitID number
  2. drawMask number

Returns:

  1. nil

Spring.SetUnitAlwaysUpdateMatrix(unitID, alwaysUpdateMatrix)

Parameters:

  1. unitID number
  2. alwaysUpdateMatrix bool

Returns:

  1. nil

Spring.SetUnitNoMinimap(unitID, unitNoMinimap)

Parameters:

  1. unitID number
  2. unitNoMinimap bool

Returns:

  1. nil

Spring.SetUnitNoSelect(unitID, unitNoSelect)

Parameters:

  1. unitID number
  2. unitNoSelect bool whether unit can be selected or not

Returns:

  1. nil

Spring.SetUnitLeaveTracks(unitID, unitLeaveTracks)

Parameters:

  1. unitID number
  2. unitLeaveTracks bool whether unit leaves tracks on movement

Returns:

  1. nil

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

Parameters:

  1. unitID number
  2. featureID number
  3. scaleX number
  4. scaleY number
  5. scaleZ number
  6. offsetX number
  7. offsetY number
  8. offsetZ number
  9. vType number
  10. tType number
  11. Axis number

Returns:

  1. nil

Features

Spring.SetFeatureNoDraw(featureID, noDraw)

Parameters:

  1. featureID number
  2. noDraw bool

Returns:

  1. nil

Spring.SetFeatureEngineDrawMask(featureID, engineDrawMask)

Parameters:

  1. featureID number
  2. engineDrawMask number

Returns:

  1. nil

Spring.SetFeatureAlwaysUpdateMatrix(featureID, alwaysUpdateMat)

Parameters:

  1. featureID number
  2. alwaysUpdateMat number

Returns:

  1. nil

Spring.SetFeatureFade(featureID, allow)

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

Parameters:

  1. featureID number
  2. allow bool

Returns:

  1. nil

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

Parameters:

  1. featureID number
  2. scaleX number
  3. scaleY number
  4. scaleZ number
  5. offsetX number
  6. offsetY number
  7. offsetZ number
  8. vType number
  9. tType number
  10. Axis number

Returns:

  1. nil

Unit Icons

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

Parameters:

  1. iconName string
  2. texFile string
  3. size number (optional)
  4. dist number (optional)
  5. radAdjust number (optional)

Returns:

  1. nil or bool added

Spring.FreeUnitIcon(iconName)

Parameters:

  1. iconName string

Returns:

  1. nil or bool freed

Spring.UnitIconSetDraw(unitID, drawIcon)

Parameters:

  1. unitID number
  2. drawIcon bool

Returns:

  1. nil

Spring.SetUnitDefIcon(unitDefID, iconName)

Parameters:

  1. unitDefID number
  2. iconName string

Returns:

  1. nil

Spring.SetUnitDefImage(unitDefID, image)

Parameters:

  1. unitDefID number
  2. image string luaTexture|texFile

Returns:

  1. nil

Virtual File System

Prefer using VFS whenever possible

Spring.ExtractModArchiveFile(modfile)

Parameters:

  1. modfile string

Returns:

  1. bool extracted

Spring.CreateDir(path)

Parameters:

  1. path string

Returns:

  1. nil or bool dirCreated

Spring.AllocateTable(narr, nrec)

Parameters:

  1. narr number hint for count of array elements
  2. nrec number hint for count of record elements

Returns:

  1. table

GUI

Spring.SetActiveCommand(action[, actionExtra])

Parameters:

  1. action string
  2. actionExtra string (optional)

Returns:

  1. nil or bool commandSet

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

Parameters:

  1. cmdIndex number
  2. button number (default 1)
  3. leftClick bool (optional)
  4. rightClick optional bool
  5. alt optional bool
  6. ctrl optional bool
  7. meta optional bool
  8. shift optional bool

Returns:

  1. nil or bool commandSet

Spring.LoadCmdColorsConfig(config)

Parameters:

  1. config string

Returns:

  1. nil

Spring.LoadCtrlPanelConfig(config)

Parameters:

  1. config string

Returns:

  1. nil

Spring.ForceLayoutUpdate()

Returns:

  1. nil

Spring.SetDrawSelectionInfo(enable)

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

Parameters:

  1. enable bool

Returns:

  1. nil

Spring.SetBoxSelectionByEngine(state)

Parameters:

  1. state bool

Returns:

  1. nil

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

Parameters:

  1. teamID number
  2. r number
  3. g number
  4. b number

Returns:

  1. nil

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

Changes/creates the cursor of a single CursorCmd.

Parameters:

  1. cmdName string
  2. iconFileName string

    not the full filename, instead it is like this:

     Wanted filename: Anims/cursorattack_0.bmp
 => iconFileName: cursorattack
  3. overwrite bool (default true)
  4. hotSpotTopLeft bool (default false)

Returns:

  1. nil or bool assigned

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

Mass replace all occurrences of the cursor in all CursorCmds.

Parameters:

  1. oldFileName string
  2. newFileName string
  3. hotSpotTopLeft bool (default false)

Returns:

  1. nil or bool assigned

Spring.SetCustomCommandDrawData(cmdID[, cmdReference])

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

Parameters:

  1. cmdID number
  2. cmdReference string or number iconname | cmdID_cloneIcon (optional)

Returns:

  1. nil or bool assigned

Mouse

Spring.WarpMouse(x, y)

Parameters:

  1. x number
  2. y number

Returns:

  1. nil

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

Parameters:

  1. cursorName string
  2. cursorScale number (default 1.0)

Returns:

  1. nil

LOS Colors

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

Parameters:

  1. always table {r,g,b}
  2. LOS table = {r,g,b}
  3. radar table = {r,g,b}
  4. jam table = {r,g,b}
  5. radar2 table = {r,g,b}

Returns:

  1. nil

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

Parameters:

  1. rotVal number in degrees (default 0)
  2. rotVel number in degrees (default 0)
  3. rotAcc number in degrees (default 0)
  4. rotValRng number in degrees (default 0)
  5. rotVelRng number in degrees (default 0)
  6. rotAccRng number in degrees (default 0)

Returns:

  1. 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:

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

Returns:

  1. nil

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

Parameters:

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

Returns:

  1. nil

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

Parameters:

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

Returns:

  1. nil

Spring.Quit()

Closes the application

Returns:

  1. nil

Unit Group

Spring.SetUnitGroup(unitID, groupID)

Parameters:

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

Returns:

  1. nil

UI

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

Spring.SendLuaUIMsg(message, mode)

Parameters:

  1. message string
  2. mode string "s"/"specs" | "a"/"allies"

Returns:

  1. nil

Spring.SendLuaGaiaMsg(message)

Parameters:

  1. message string

Returns:

  1. nil

Spring.SendLuaRulesMsg(message)

Parameters:

  1. message string

Returns:

  1. nil

Spring.SendLuaMenuMsg(msg)

Parameters:

  1. msg string

Spring.SetLastMessagePosition(x, y, z)

Parameters:

  1. x number
  2. y number
  3. z number

Returns:

  1. nil

Sharing

Spring.SetShareLevel(resource, shareLevel)

Parameters:

  1. resource string metal | energy
  2. shareLevel number

Returns:

  1. nil

Spring.ShareResources(teamID, units)

Parameters:

  1. teamID number
  2. units string

Returns:

  1. nil

Spring.ShareResources(teamID, resource, amount)

Parameters:

  1. teamID number
  2. resource string metal | energy
  3. amount number

Returns:

  1. nil

Markers

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

Parameters:

  1. x number
  2. y number
  3. z number
  4. text string (default "")
  5. localOnly bool (optional)

Returns:

  1. nil

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

Parameters:

  1. x1 number
  2. y1 number
  3. z1 number
  4. x2 number
  5. y2 number
  6. z2 number
  7. localOnly bool (default false)
  8. playerId number (optional)

Returns:

  1. nil

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

Issue an erase command for markers on the map.

Parameters:

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

Returns:

  1. nil

Sun

Spring.SetAtmosphere(params)

It can be used to modify the following atmosphere parameters

Parameters:

  1. params
    • fogStart number
    • fogEnd number
    • sunColor rgb
    • skyColor rgb
    • cloudColor rgb

Returns:

  1. 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:

  1. dirX number
  2. dirY number
  3. dirZ number
  4. intensity number (default true)

Returns:

  1. nil

Spring.SetSunLighting(params)

It can be used to modify the following sun lighting parameters

Parameters:

  1. params
    • groundAmbientColor rgb
    • groundDiffuseColor rgb

Returns:

  1. nil

Usage:

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

mapRenderingParams

Map rendering params

Fields:

  1. splatTexMults rgba
  2. splatTexScales rgba
  3. voidWater bool
  4. voidGround bool
  5. splatDetailNormalDiffuseAlpha bool

Spring.SetMapRenderingParams(params)

Allows to change map rendering params at runtime.

Parameters:

  1. params mapRenderingParams

Returns:

  1. nil

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

Parameters:

  1. normal bool (default true)
  2. shadow bool (default false)

Returns:

  1. bool updated

AI

Spring.SendSkirmishAIMessage(aiTeam, message)

Parameters:

  1. aiTeam number
  2. message string

Returns:

  1. nil or bool ai_processed

Developers

Spring.SetLogSectionFilterLevel(sectionName, logLevel)

Parameters:

  1. sectionName string
  2. logLevel string or number

Returns:

  1. nil

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

Parameters:

  1. itersPerBatch int (optional)
  2. numStepsPerIter int (optional)
  3. minStepsPerIter int (optional)
  4. maxStepsPerIter int (optional)
  5. minLoopRunTime number (optional)
  6. maxLoopRunTime number (optional)
  7. baseRunTimeMult number (optional)
  8. baseMemLoadMult number (optional)

Returns:

  1. nil

Spring.SetDrawSky(drawSky)

Parameters:

  1. drawSky bool

Returns:

  1. nil

Spring.SetDrawWater(drawWater)

Parameters:

  1. drawWater bool

Returns:

  1. nil

Spring.SetDrawGround(drawGround)

Parameters:

  1. drawGround bool

Returns:

  1. nil

Spring.SetDrawGroundDeferred(drawGroundDeferred[, drawGroundForward])

Parameters:

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

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

Parameters:

  1. drawUnitsDeferred bool
  2. drawFeaturesDeferred bool
  3. drawUnitsForward bool allows disabling of the respective forward passes (optional)
  4. drawFeaturesForward bool allows disabling of the respective forward passes (optional)

Returns:

  1. nil

Spring.SetVideoCapturingMode(allowCaptureMode)

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

Parameters:

  1. allowCaptureMode bool

Returns:

  1. nil

Spring.SetVideoCapturingTimeOffset(timeOffset)

Parameters:

  1. timeOffset bool

Returns:

  1. nil

waterParams

Water params

Fields:

  1. absorb rgb
  2. baseColor rgb
  3. minColor rgb
  4. surfaceColor rgb
  5. diffuseColor rgb
  6. specularColor rgb
  7. planeColor rgb
  8. texture string file
  9. foamTexture string file
  10. normalTexture string file
  11. damage number
  12. repeatX number
  13. repeatY number
  14. surfaceAlpha number
  15. ambientFactor number
  16. diffuseFactor number
  17. specularFactor number
  18. specularPower number
  19. fresnelMin number
  20. fresnelMax number
  21. fresnelPower number
  22. reflectionDistortion number
  23. blurBase number
  24. blurExponent number
  25. perlinStartFreq number
  26. perlinLacunarity number
  27. perlinAmplitude number
  28. numTiles number
  29. shoreWaves bool
  30. forceRendering bool
  31. 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:

  1. waterParams waterParams

Returns:

  1. 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:

  1. unitDefID number

Returns:

  1. nil

Spring.PreloadFeatureDefModel(featureDefID)

Parameters:

  1. featureDefID number

Returns:

  1. nil

Spring.PreloadSoundItem(name)

Parameters:

  1. name string

Returns:

  1. nil

Spring.LoadModelTextures(modelName)

Parameters:

  1. modelName string

Returns:

  1. nil or bool success

SDL Text

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

Parameters:

  1. x number
  2. y number
  3. width number
  4. height number

Returns:

  1. nil

Spring.SDLStartTextInput()

Returns:

  1. nil

Spring.SDLStopTextInput()

Returns:

  1. nil

Window Management

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

Parameters:

  1. displayIndex number
  2. winRelPosX number
  3. winRelPosY number
  4. winSizeX number
  5. winSizeY number
  6. fullScreen bool
  7. borderless bool

Returns:

  1. nil

Spring.SetWindowMinimized()

Returns:

  1. bool minimized

Spring.SetWindowMaximized()

Returns:

  1. bool maximized

Misc

Spring.Reload(startScript)

Parameters:

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

Returns:

  1. nil

Spring.Restart(commandline_args, startScript)

If this call returns, something went wrong

Parameters:

  1. commandline_args string commandline arguments passed to spring executable.
  2. startScript string

Returns:

  1. nil

Spring.Start(commandline_args, startScript)

Launches a new Spring instance without terminating the existing one.

If this call returns, something went wrong

Parameters:

  1. commandline_args string commandline arguments passed to spring executable.
  2. 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:

  1. 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:

  1. iconFileName string

Returns:

  1. 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:

  1. title string
  2. titleShort string (default title)

Returns:

  1. nil

Spring.ClearWatchDogTimer([threadName=main])

Parameters:

  1. threadName string (default main)

Returns:

  1. nil

Spring.SetClipboard(text)

Parameters:

  1. text string

Returns:

  1. 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:

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