Lua UnsyncedCtrl
Development < Lua Scripting < Lua UnsyncedCtrl
UI
Spring.SetLastMessagePosition
( number x,
number y,
number z )
return: nil
Ingame Console
Spring.Echo
( arg1 [,
arg2 [,
... ]] )
return: nil
- Useful for debugging.
Prints values in the spring chat console.
Hint: the default print() writes to STDOUT.
Spring.Log
( string section,
number logLevel | string logLevel,
string LogMessage1 [,
string LogMessage2[,
... ]] )
return: nil
Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) (new in Version 97)
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL
Spring.SendCommands
( string command1 [,
string command2 [,
... ]] )
return: nil
- Needs ModUICtrl.
or
Spring.SendCommands
( { string command1, string command2, ... } )
return: nil
- Needs ModUICtrl.
GUI
Spring.SetActiveCommand
( string action [,
string actionExtra ] )
return: nil | bool commandSet
- Needs ModUICtrl.
or
Spring.SetActiveCommand
( number cmdIndex [,
number button = 1 [,
bool leftClick [,
bool rightClick [,
bool alt [,
bool ctrl [,
bool meta [,
bool shift ]]]]]]] )
return: nil | bool commandSet
- Needs ModUICtrl.
Spring.LoadCmdColorsConfig
( string config )
return: nil
- Needs ModUICtrl.
Spring.LoadCtrlPanelConfig
( string config )
return: nil
- Needs ModUICtrl.
Spring.ForceLayoutUpdate
( )
return: nil
- Needs ModUICtrl.
Spring.SetDrawSelectionInfo
( bool enable )
return: nil
- Needs ModUICtrl.
Disables the "Selected Units x" box in the GUI.
Mouse
Spring.SetMouseCursor
( string cursorName [,
number scale ] )
return: nil
- Needs ModUICtrl.
Spring.WarpMouse
( number x,
number y )
return: nil
- Needs ModUICtrl.
LOS Colors
Spring.SetLosViewColors
( table always = {r,g,b},
table LOS = {r,g,b},
table radar = {r,g,b},
table jam = {r,g,b},
table radar2 = {r,g,b} )
return: nil
- Needs ModUICtrl.
New arguments since 100.0 (radar2 is the inside of radar edge). Arguments for 99.0 and before:
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil
SendMessage
Spring.SendMessage
( string message )
return: nil
Spring.SendMessageToPlayer
( number playerID,
string message )
return: nil
Spring.SendMessageToTeam
( number teamID,
string message )
return: nil
Spring.SendMessageToAllyTeam
( number allyID,
string message )
return: nil
Spring.SendMessageToSpectators
( string message )
return: nil
- <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"
Markers
Spring.MarkerAddPoint
( number x,
number y,
number z [,
string text = "" [,
bool localOnly ]] )
return: nil
- Needs ModUICtrl.
Spring.MarkerAddLine
( number x1,
number y1,
number z1,
number x2,
number y2,
number z2 )
return: nil
- Needs ModUICtrl.
Spring.MarkerErasePosition
( number x,
number y,
number z )
return: nil
- Needs ModUICtrl.
Sounds
Spring.LoadSoundDef
( string soundfile )
return: nil | bool success
- Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
Spring.PlaySoundFile
( string soundfile [,
number volume = 1.0 [,
number posx [,
number posy [,
number posz [,
number speedx[,
number speedy[,
number speedz[,
number | string channel ]]]]]]]] )
return: nil | bool playSound
- Possible arguments for channel argument:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3
Spring.PlaySoundStream
( string oggfile [,
number volume = 1.0 [,
bool enqueue ]] )
return: nil | bool true
- Allows to play an Ogg Vorbis (.OGG) compressed sound file.
In 83.0 and up multiple sound streams may be played at once.
Spring.StopSoundStream
( )
return: nil
- Terminates any SoundStream currently running.
Spring.PauseSoundStream
( )
return: nil
Spring.SetSoundStreamVolume
( number volume )
return: nil
SendLuaMessage
Very important! (allows synced inter-lua-enviroment communications)
Spring.SendLuaUIMsg
( string message,
string mode )
return: nil
- Needs ModUICtrl.
Possible modes are:
"s"/"specs" & "a"/"allies"
Spring.SendLuaGaiaMsg
( string message )
return: nil
- Needs ModUICtrl.
Spring.SendLuaRulesMsg
( string message )
return: nil
- Needs ModUICtrl.
AI
Spring.SendSkirmishAIMessage
( number aiTeam,
string message )
return: nil | bool ai_processed, { [1] = string response1, ... }
- New in version 83.0
Note there is nothing in this table due to "limitations" of the AI interface.
Units
Spring.SetUnitLeaveTracks
( number unitID,
bool leavetracks )
return: nil
- New in version 83.0
Spring.SetUnitSelectionVolumeData
( number featureID,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number vType,
number tType,
number Axis )
return: nil
- New in version 104.0
Unit Selection
Spring.SelectUnitMap
( { [unitID] = anything, ... } [,
bool append ] )
return: nil
Spring.SelectUnitArray
( { [1] = unitID1, [2] = unitID2, ... } [,
bool append ] )
return: nil
Spring.SetDrawSelectionInfo
( bool drawSelectionInfo )
return: nil
Unit Group
Spring.SetUnitGroup
( number unitID,
number groupID )
return: nil
- Needs ModUICtrl.
Give Order
Spring.GiveOrder
( number cmdID,
table params = {number, etc...},
table options = {"alt", "ctrl", "shift", "right"} )
return: nil | bool true
- Needs ModUICtrl.
Gives order to all selected units.
Spring.GiveOrderToUnit
( number unitID,
number cmdID,
table params = {number, etc...},
table options = {"alt", "ctrl", "shift", "right"} )
return: nil | bool true
- Needs ModUICtrl.
Spring.GiveOrderToUnitMap
( table unitMap = { [unitID] = arg1, etc... },
number cmdID,
table params = {number, etc...},
table options = {"alt", "ctrl", "shift", "right"} )
return: nil | bool true
- Needs ModUICtrl.
Spring.GiveOrderToUnitArray
( table unitArray = { [1] = number unitID, etc... },
number cmdID,
table params = {number, etc...},
table options = {"alt", "ctrl", "shift", "right"} )
return: nil | bool true
- Needs ModUICtrl.
Spring.GiveOrderArrayToUnitMap
( table unitMap = { [unitID] = arg1, etc... },
table orderArray = { number cmdID, table params = {number, etc...}, table options = {"alt", "ctrl", "shift", "right"} } )
return: nil | bool true
- Needs ModUICtrl.
Spring.GiveOrderArrayToUnitArray
( table unitArray = { [11] = number unitID, etc... },
table orderArray = { number cmdID, table params = {number, etc...}, table options = {"alt", "ctrl", "shift", "right"} } [,
bool pairwise ] )
return: nil | bool true
- Needs ModUICtrl.
"pairwise" paramater (New in version 89.0) is used to send multiple units a single individual command.
Spring.SetBuildFacing
( number facing )
return: nil
Spring.SetBuildSpacing
( number spacing )
return: nil
Unit NoDraw,NoSelect,NoMinimap
Spring.SetUnitNoDraw
( number unitID,
bool noDraw )
return: nil
- LuaGadgets only!
Spring.SetUnitNoSelect
( number unitID,
bool noSelect )
return: nil
- LuaGadgets only!
Spring.SetUnitNoMinimap
( number unitID,
bool noMinimap )
return: nil
- LuaGadgets only!
Features
Spring.SetFeatureFade
( number featureID,
bool allow )
return: nil
- New in version 101.0
Control whether a feature will fade or not when zoomed out.
Spring.SetFeatureNoDraw
( number featureID,
bool noDraw )
return: nil
- LuaGadgets only!
Spring.SetFeatureSelectionVolumeData
( number featureID,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number vType,
number tType,
number Axis )
return: nil
- New in version 104.0
Developers
Spring.SetDrawSky
( bool drawSky )
return: nil
Spring.SetDrawWater
( bool drawWater )
return: nil
Spring.SetDrawGround
( bool drawGround )
return: nil
Spring.SetWaterParams
( table params )
return: nil
- As of 104.0 no longer needs cheating enabled.
Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your springrc to 1, then you don't even need to restart BumpWater via `/water 4`. "Params" table contains:
params = {
absorb = {number r, number g, number b},
baseColor = {number r, number g, number b},
minColor = {number r, number g, number b},
surfaceColor = {number r, number g, number b},
diffuseColor = {number r, number g, number b},
specularColor = {number r, number g, number b},
planeColor = {number r, number g, number b},
texture = string file,
foamTexture = string file,
normalTexture = string file,
damage = number value,
repeatX = number value,
repeatY = number value,
surfaceAlpha = number value,
ambientFactor = number value,
diffuseFactor = number value,
specularFactor = number value,
specularPower = number value,
fresnelMin = number value,
fresnelMax = number value,
fresnelPower = number value,
reflectionDistortion = number value,
blurBase = number value,
blurExponent = number value,
perlinStartFreq = number value,
perlinLacunarity = number value,
perlinAmplitude = number value,
numTiles = number value,
shoreWaves = boolean value,
forceRendering = boolean value,
hasWaterPlane = boolean value,
}
Spring.SetMapRenderingParams
( table params )
return: nil
- New in version 104.0
Allows to change map rendering params at runtime.
"Params" table contains:
params = {
splatTexMults = {number r, number g, number b, number a},
splatTexScales = {number r, number g, number b, number a},
voidWater = boolean value,
voidGround = boolean value,
splatDetailNormalDiffuseAlpha = boolean value,
}
Spring.SetLogSectionFilterLevel
( string sectionName,
string | number logLevel )
return: nil
- New in version 95.0
See infolog.txt for possible log sections.
Spring.SetDrawGroundDeferred
( bool drawGroundDeferred [,
bool drawGroundForward ] )
return: nil
- New in version 101.0 drawGroundForward allows disabling of the forward pass
Spring.SetDrawModelsDeferred
( bool drawUnitsDeferred,
bool drawFeaturesDeferred [,
bool drawUnitsForward [,
bool drawFeaturesForward ]] )
return: nil
- New in version 101.0 drawFeaturesForward, drawUnitsForward allows disabling of the respective forward passes
Spring.SetVideoCapturingMode
( bool allowCaptureMode )
return: nil
- New in version 104.0
This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
Spring.SetVideoCapturingTimeOffset
( bool timeOffset )
return: nil
- New in version 104.0
GUI
Spring.DrawUnitCommands
( number unitID )
return: nil
- New in version 104.0
or
Spring.DrawUnitCommands
( table units = { [1] = unitID, ... } [,
bool false )
return: nil
or
Spring.DrawUnitCommands
( table units = { [unitID] = arg1, ... },
bool true )
return: nil
Spring.SetTeamColor
( number teamID,
number r,
number g,
number b )
return: nil
Spring.AssignMouseCursor ( string cmdName, string iconFileName [, bool overwrite = true [, bool hotSpotTopLeft = false ]{rbracket, {{{arg5}}}, {{{arg6}}}, {{{arg7}}}, {{{arg8}}}, {{{arg9}}} )
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = nil | bool assigned
|info = Changes/creates the cursor of a single CursorCmd. Note, that iconFileName is not the full filename instead it is like this:
Wanted filename: Anims/cursorattack_0.bmp
=> iconFileName: cursorattack
}}
Spring.ReplaceMouseCursor
( string oldFileName,
string newFileName [,
bool hotSpotTopLeft = false ] )
return: nil | bool assigned
- Mass replace all occurrence of the cursor in all CursorCmds.
Spring.SetCustomCommandDrawData
( number cmdID,
number cmdID_cloneIcon | string iconname,
table RGBA = { number r, number g, number b, number a } [,
bool showArea ] )
return: nil | bool assigned
- Register your custom cmd so it gets visible in the unit's cmd queue
or
Spring.SetCustomCommandDrawData
( number cmdID,
nil )
return: nil | bool assigned
- Register your custom cmd so it gets visible in the unit's cmd queue
Sharing
Spring.SetShareLevel
( string metal | string energy,
number shareLevel )
return: nil
- LuaGadgets only!
Note: shareLevel is 0<= x <= 1 .
Spring.ShareResources
( number teamID,
string units )
return: nil
- LuaGadgets only!
or
Spring.ShareResources
( number teamID,
string metal | string energy,
number amount )
return: nil
- LuaGadgets only!
UnitDef RadarIcons & BuildPics
Spring.AddUnitIcon
( string iconName,
string texFile [,
number size [,
number dist [,
bool radAdjust ]]] )
return: nil | bool added
Spring.FreeUnitIcon
( string iconName )
return: nil | bool freed
Spring.SetUnitDefIcon
( number unitDefID,
string iconName )
return: nil
- Needs ModUICtrl.
Sets radar icon.
Spring.SetUnitDefImage
( number unitDefID,
string luaTexture | string texFile )
return: nil
- Needs ModUICtrl.
Sets buildpic.
Camera
Spring.SetCameraState
( table camState,
number camTime )
return: nil | bool stateSet
- camState has the same format as the output of Spring.GetCameraState(). See Lua_camState for details about camState.
The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [1] Also see #5028]
Spring.SetCameraTarget
( number x, number y, number z [,
number transTime ] )
return: nil
- For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
Spring.SetCameraOffset
( number px = 0 [,
number py = 0 [,
number pz = 0 [,
number tx = 0 [,
number ty = 0 [,
number tz = 0 ]]]]] )
return: nil
- Needs ModUICtrl.
(Virtual-)FileSystem
Spring.ExtractModArchiveFile
( string modfile )
return: bool extracted
Spring.CreateDir
( string path )
return: nil | bool dirCreated
- Needs ModUICtrl.
The full VFS API is available at link.
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. If *Overlay is true, the value will only be set in memory, and not be restored for the next game.
Spring.SetConfigInt
( string name,
number value [,
bool useOverlay = false ] )
return: nil
Spring.SetConfigFloat
( string name,
number value [,
bool useOverlay = false ] )
return: nil
- New in version 104.0
Spring.SetConfigString
( string name,
number value [,
bool useOverlay = false ] )
return: nil
- New in version 104.0
World Primitives
outdated! use opengl api instead!
Spring.AddWorldIcon
( number cmdID,
number x, number y, number z )
return: nil
Spring.AddWorldText
( string text,
number x, number y, number z )
return: nil
Spring.AddWorldUnit
( number unitDefID,
number x, number y, number z,
number team,
number facing )
return: nil
Sun
The dynamic Sun must be invoked via /dynamicsun (Dynamic sun was removed in 104.0, use SetSunDirection, SetSunLighting & SetAtmosphere instead).
Spring.SetSunManualControl
( bool setManualControl )
return: nil
- Removed from version 104.0
Spring.SetSunParameters
( number dirX,
number dirY,
number dirZ,
number dist,
number startTime,
number orbitTime )
return: nil
- Removed from version 104.0
Spring.SetSunDirection
( number dirX,
number dirY,
number dirZ )
return: nil
Spring.SetSunLighting
( table params )
return: nil
- New in version 101.0
It can be used to modify the following sun lighting parameters:
{ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
All Colourvalues have to in the Range from 0.0 to 1.0 for all colors and the alpha
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })
Spring.SetAtmosphere
( table params )
return: nil
- New in version 101.0
It can be used to modify the following atmosphere parameters:
fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})
Misc
Spring.Reload
( string startscript )
return: -
- New in version 99.0
start-script is the CONTENT of the script.txt spring should use to start.
Spring.Restart
( string commandline_args,
string startscript )
return: -
- New in version 0.79
If this call returns, something went wrong.
commandline_args are commandline arguments passed to spring executable.
Spring.Start
( string commandline_args,
string startscript )
return: -
- New in version 102.0
If this call returns, something went wrong.
Launches a new Spring instance without terminating the existing one.
start-script is 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.
Spring.SetWMIcon
( string iconFileName )
return: nil
- New in version 83.0
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.
Spring.SetWMCaption
( string title [,
string titleShort = title ] )
return: nil
- New in version 83.0
Sets the window title for the process (default: "Spring <version>").
The shortTitle is displayed in the OS task-bar (default: "Spring <version>").
NOTE: shortTitle is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See this site for more details.
Spring.ClearWatchDogTimer
( [ string threadName = main ] )
return: nil
- New in version 83.0
Spring.SetClipboard
( string text )
return: nil
- New in version 98.0
Rendering
Preload
Allow the engine to load the unit's model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.
Spring.PreloadUnitDefModel
( number unitDefID )
return: nil
- {New in version 101.0
Spring.PreloadFetureDefModel
( number featureDefID )
return: nil
- {New in version 101.0
Lighting
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!
Spring.AddMapLight
( table lightParams )
return: number lightHandle
- (requires MaxDynamicMapLights > 0)
Spring.AddModelLight
( table lightParams )
return: number lightHandle
- (requires MaxDynamicMapLights > 0)
Spring.UpdateMapLight
( number lightHandle,
table lightParams )
return: bool success
Spring.UpdateModelLight
( number lightHandle,
table lightParams )
return: bool success
Spring.SetMapLightTrackingState
( number lightHandle,
number unitOrProjectileID,
bool enableTracking,
bool unitOrProjectile )
return: bool success
Spring.SetModelLightTrackingState
( number lightHandle,
number unitOrProjectileID,
bool enableTracking,
bool unitOrProjectile )
return: bool success
lightParams is a table that should contain at least one of the following recognized key/value pairs:
lightParams = {
position = {px, py, pz},
direction = {dx, dy, dz},
ambientColor = {red, green, blue},
diffuseColor = {red, green, blue},
specularColor = {red, green, blue},
intensityWeight = {ambientWeight, diffuseWeight, specularWeight},
-- per-frame decay of ambientColor (spread over TTL frames)
ambientDecayRate = {ambientRedDecay, ambientGreenDecay, ambientBlueDecay},
-- per-frame decay of diffuseColor (spread over TTL frames)
diffuseDecayRate = {diffuseRedDecay, diffuseGreenDecay, diffuseBlueDecay},
-- per-frame decay of specularColor (spread over TTL frames)
specularDecayRate = {specularRedDecay, specularGreenDecay, specularBlueDecay},
-- *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
decayFunctionType = {ambientDecayType, diffuseDecayType, specularDecayType},
radius = number elmos,
fov = number degrees,
ttl = number frames,
priority = number,
ignoreLOS = boolean,
}
Map
Spring.SetSkyBoxTexture
( string texName )
return: nil
- New in version 101.0
Spring.SetMapShadingTexture
( string texType,
string texName )
return: bool success
- New in version 101.0
Spring.SetMapSquareTexture
( number texSqrX,
number texSqrY,
string luaTexName )
return: bool success
Spring.SetMapShader
( number standardShaderID,
number deferredShaderID )
return: nil
- New in version 101.0
