Development < Lua Scripting < Lua UnsyncedCtrl

NOTE: Entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users springrc, if you want to use them in unsynced LuaRules/LuaGaia. It is enabled by default so you generally don't need to care.

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

Contents

UI