Module UnsyncedCtrl
Callouts to set state
See also:
Tables
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.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
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
LOS Colors
Engine Config
- Spring.SetConfigInt
- Spring.SetConfigFloat
- Spring.SetConfigString
- Spring.Quit
- Closes the application
Unit Group
UI
- Spring.SendLuaUIMsg
- Spring.SendLuaGaiaMsg
- Spring.SendLuaRulesMsg
- Spring.SendLuaMenuMsg
- Spring.SetLastMessagePosition
Sharing
Markers
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
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
Window Management
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)
Spring.GiveOrderToUnit(unitID, cmdID, params, options)
Spring.GiveOrderToUnitMap(unitMap, cmdID, params, options)
Parameters:
Returns:
- nil or true
Spring.GiveOrderToUnitArray(unitArray, cmdID, params, options)
Parameters:
Returns:
- nil or true
cmdSpec
Command spec
Spring.GiveOrderArrayToUnit(unitID, cmdArray)
Spring.GiveOrderArrayToUnitMap(unitMap, cmdArray)
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 stringPossible 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)
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)
Spring.SetMapShadingTexture(texType, texName)
Parameters:
Returns:
- bool success
Usage:
Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")
Spring.SetSkyBoxTexture(texName)
Messages
Spring.SendMessage(message)
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)
Spring.SendMessageToTeam(teamID, message)
Spring.SendMessageToAllyTeam(allyID, message)
Sounds
Spring.LoadSoundDef(soundfile)
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
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
(optional)Possible arguments for channel argument: "general" || 0 || nil (default) "battle" || "sfx" | 1 "unitreply" || "voice" || 2 "userinterface" || "ui" || 3
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)
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 trueunits
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)
Spring.AddModelLight(lightParams)
Spring.UpdateMapLight(lightHandle, lightParams)
Spring.UpdateModelLight(lightHandle, lightParams)
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)
Spring.UnitIconSetDraw(unitID, drawIcon)
Parameters:
-
unitID
number -
drawIcon
bool
Returns:
- nil
Spring.SetUnitDefIcon(unitDefID, iconName)
Spring.SetUnitDefImage(unitDefID, image)
Virtual File System
Prefer using VFS whenever possible
Spring.ExtractModArchiveFile(modfile)
Spring.CreateDir(path)
Spring.AllocateTable(narr, nrec)
Parameters:
-
narr
number hint for count of array elements -
nrec
number hint for count of record elements
Returns:
GUI
Spring.SetActiveCommand(action[, actionExtra])
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)
Spring.LoadCtrlPanelConfig(config)
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
stringnot 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:
Returns:
- nil or bool assigned
Spring.SetCustomCommandDrawData(cmdID[, cmdReference])
Register your custom cmd so it gets visible in the unit's cmd queue
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])
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)
Spring.SendLuaGaiaMsg(message)
Spring.SendLuaRulesMsg(message)
Spring.SendLuaMenuMsg(msg)
Parameters:
-
msg
string
Spring.SetLastMessagePosition(x, y, z)
Parameters:
-
x
number -
y
number -
z
number
Returns:
- nil
Sharing
Spring.SetShareLevel(resource, shareLevel)
Spring.ShareResources(teamID, units)
Spring.ShareResources(teamID, resource, amount)
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 whenlocalOnly
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:
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:
Returns:
- nil
Usage:
Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })
mapRenderingParams
Map rendering params
Fields:
Spring.SetMapRenderingParams(params)
Allows to change map rendering params at runtime.
Spring.ForceTesselationUpdate([normal=true[, shadow=false]])
Parameters:
-
normal
bool (default true) -
shadow
bool (default false)
Returns:
- bool updated
AI
Spring.SendSkirmishAIMessage(aiTeam, message)
Developers
Spring.SetLogSectionFilterLevel(sectionName, logLevel)
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)
Spring.LoadModelTextures(modelName)
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:
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
Parameters:
Returns:
- nil
Spring.ClearWatchDogTimer([threadName=main])
Spring.SetClipboard(text)
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