Development < Lua Scripting < Lua UnsyncedCtrl
Contents |
UI
Spring.SetLastMessagePosition
( number x, number y, number z ) -> nil
Ingame Console
Spring.Echo
( arg1 [, arg2 [, ... ] ] ) -> nil
Useful for debugging.
Prints values in the spring chat console.
Hint: the default print() writes to STDOUT.
Spring.Log
( int logLevel | string logLevel, string section, arg2 [, arg3 [, ... ] ] ) -> nil
Possible values for logLevel are: "debug" | LOG.DEBUG "info" | LOG.INFO "warning" | LOG.WARNING "error" | LOG.ERROR "fatal" | LOG.FATAL
Spring.SendCommands (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil
GUI
Spring.SetActiveCommand (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
Spring.LoadCmdColorsConfig (needs ModUICtrl)
( string config ) -> nil
Spring.LoadCtrlPanelConfig (needs ModUICtrl)
( string config ) -> nil
Spring.ForceLayoutUpdate (needs ModUICtrl)
( ) -> nil
Spring.SetDrawSelectionInfo disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil
Mouse
Spring.SetMouseCursor (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
Spring.WarpMouse (needs ModUICtrl)
( number x, number y ) -> nil
LOS Colors
Spring.SetLosViewColors (needs ModUICtrl)
( 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" ) -> nil
Spring.SendMessageToPlayer
( number playerID, string "message" ) -> nil
Spring.SendMessageToTeam
( number teamID, string "message" ) -> nil
Spring.SendMessageToAllyTeam
( number allyID, string "message" ) -> nil
Spring.SendMessageToSpectators
( string "message" ) -> nil
Funfact: <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name. ie Spring.SendMessage ("<PLAYER1> did something") might display as "ProRusher did something"
Markers
Spring.MarkerAddPoint (needs ModUICtrl)
( number x, number y, number z [, string text = "" [, bool localOnly] ] ) -> nil
Spring.MarkerAddLine (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
Spring.MarkerErasePosition (needs ModUICtrl)
( number x, number y, number z ) -> nil
Sounds
Spring.LoadSoundDef
( string "soundfile" ) -> nil | boolean success
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
Spring.PlaySoundFile Plays WAV or OGG sounds.
( string "soundfile" [, number volume = 1.0 [, number posx, number posy, number posz [, number speedx, number speedy, number speedz ] ] ], [string/number channel ] ) -> nil | boolean `channel` is new in Spring0.83, and can be one of those: "general" || 0 || nil (default) "battle" || "sfx" | 1 "unitreply" || "voice" || 2 "userinterface" || "ui" || 3
Spring.PlaySoundStream
( string "oggfile" [, number volume = 1.0
[, number x, number y, number z ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file.
In 83.0 and up multiple sound streams may be played at once
Spring.StopSoundStream
( ) -> nil
Terminates any SoundStream currently running.
Spring.PauseSoundStream
( ) -> nil
Spring.SetSoundStreamVolume
( number volume ) -> nil
SendLuaMessage
Very important! (allows synced inter-lua-enviroment communications)
Spring.SendLuaUIMsg (needs ModUICtrl)
( string message, string mode ) -> nil possible modes are:
"s"/"specs" & "a"/"allies"
Spring.SendLuaGaiaMsg (needs ModUICtrl)
( string message ) -> nil
Spring.SendLuaRulesMsg (needs ModUICtrl)
( string message ) -> nil
AI
Spring.SendSkirmishAIMessage New in version 83.0
( number aiTeam, string message )
-> nil | boolean ai_processed, { [1] = string response1, etc... }
Note there is nothing in this table due to "limitations" of the AI interface.
Units
Spring.SetUnitLeaveTracks New in version 83.0
( number unitID, boolean leavetracks ) -> nil
Unit Selection
Spring.SelectUnitMap
( { [unitID] = anything, ...} [,boolean append] ) -> nil
Spring.SelectUnitArray
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil
Spring.SetDrawSelectionInfo
( boolean drawSelectionInfo ) -> nil
Unit Group
Spring.SetUnitGroup (needs ModUICtrl)
( number unitID, number groupID ) -> nil
Give Order
Spring.GiveOrder gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
Spring.GiveOrderToUnit (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
Spring.GiveOrderToUnitMap (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
Spring.GiveOrderToUnitArray (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
Spring.GiveOrderArrayToUnitMap (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
Spring.GiveOrderArrayToUnitArray (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
},
[boolean pairwise]
) -> nil | boolean true
pairwise param (New in version 89.0) is used to send multiple units a single individual command
Spring.SetBuildFacing
( int Facing ) -> nil
Spring.SetBuildSpacing
( int Spacing ) -> nil
Unit NoDraw,NoSelect,NoMinimap
Spring.SetUnitNoDraw LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
Spring.SetUnitNoSelect LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
Spring.SetUnitNoMinimap LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil
Developers
Spring.SetDrawSky
( boolean drawSky ) -> nil
Spring.SetDrawWater
( boolean drawWater ) -> nil
Spring.SetDrawGround
( boolean drawGround ) -> nil
Spring.SetWaterParams needs cheating enabled!
( table params ) -> nil
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 may contain:
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,
}
GUI
Spring.DrawUnitCommands
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil
Spring.SetTeamColor
( number teamID, number r, number g, number b ) -> nil
Spring.AssignMouseCursor changes/creates the cursor of a single CursorCmd
( string "cmdName", string "iconFileName" [, boolean overwrite = true [, boolean hotSpotTopLeft = false] ] ) -> nil | boolean
Note, that iconFileName is not the full filename instead it is like this:
wanted filename: Anims/cursorattack_0.bmp
=> iconFileName: cursorattack
Spring.ReplaceMouseCursor mass replace all occurrence of the cursor in all CursorCmds
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft = false] ) -> nil | boolean
Spring.SetCustomCommandDrawData register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdIconID | string iconname | nil,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil | true
Sharing
Spring.SetShareLevel note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
Spring.ShareResources (needs ModUICtrl)
( number teamID, string "units" ) -> nil ( number teamID, string "metal" | "energy", number amount ) -> nil
UnitDef RadarIcons & BuildPics
Spring.AddUnitIcon
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] ) -> nil | boolean
Spring.FreeUnitIcon
( string iconName ) -> nil | boolean
Spring.SetUnitDefIcon (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
Spring.SetUnitDefImage (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil
Camera
Spring.SetCameraState
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See Lua_camState for details about camState.
Spring.SetCameraTarget
( number x, number y, number z [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
Spring.SetCameraOffset (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil
(Virtual-)FileSystem
Spring.ExtractModArchiveFile
( string modfile ) -> boolean
Spring.CreateDir (needs ModUICtrl)
( number path ) -> nil | boolean
Engine Config
The following functions read the engine configs saved in springrc, 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.GetConfigInt (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
Spring.SetConfigInt (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
Spring.GetConfigString (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
Spring.SetConfigString (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil
World Primitives
outdated! use opengl api instead!
Spring.AddWorldIcon
( number cmdID, number x, number y, number z ) -> nil
Spring.AddWorldText
( string "text", number x, number y, number z ) -> nil
Spring.AddWorldUnit
( number unitDefID, number x, number y, number z, number team, number facing) -> nil
Misc
Spring.Restart New in version 0.79
( string commandline_args, string startscript ) -> if this call returns, something went wrong
commandline_args are commandline arguments passed to spring executable
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 New in version 83.0
( string iconFileName ) -> nil
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 New in version 83.0
( string title [, string titleShort = title ] ) -> nil
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 New in version 83.0
( [ string threadName = main ] ) -> nil
Rendering
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!
Spring.AddMapLight (requires MaxDynamicMapLights > 0)
(table lightParams) -> number lightHandle
Spring.AddModelLight (requires MaxDynamicModelLights > 0)
(table lightParams) -> number lightHandle
Spring.UpdateMapLight
(number lightHandle, table lightParams) -> boolean success
Spring.UpdateModelLight
(number lightHandle, table lightParams) -> boolean success
Spring.SetMapLightTrackingState
(number lightHandle, number unitOrProjectileID, boolean enableTracking, boolean unitOrProjectile) -> boolean success
Spring.SetModelLightTrackingState
(number lightHandle, number unitOrProjectileID, boolean enableTracking, boolean unitOrProjectile) -> boolean 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,
}
Spring.SetMapSquareTexture
(number texSqrX, number texSqrY, string luaTexName) -> boolean success