Lua UnsyncedCtrl

Development < Lua Scripting < Lua UnsyncedCtrl

NOTE: Entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users springsettings.cfg, 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.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.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 = ""] ) -> 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.
 Note: you may only play _ONE_ stream at a time. If another stream is playing and
 you try to start a second one the call will fail, and silence will result.
 

Spring.StopSoundStream

 ( ) -> nil
 Terminates any SoundStream is running.
 Since only one may play at any time (see above), this can be used as an interrupt.

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

Units

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"}
     }, ..
   }
 ) -> nil | boolean true

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 springsettings.cfg/.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:

 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 z, number y [,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 ${HOME}/.springrc (Unix, Linux, BSD), springsettings.cfg (Windows), 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 (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 (0.83+)

 ( string iconFileName ) -> nil

iconFileName has to point to a windows BMP file!

Sets the icon for the process which is seen in the OS task-bar, for example (default: spring-logo). Note: When loading a 24-bit Windows BMP file, pixel data points are loaded as blue, green, red, and NOT red, green, blue (as one might expect).

Spring.SetWMCaption (0.83+)

 ( string caption ) -> nil

Sets the title for the process which is seen in the OS task-bar, for example (default: "Spring <version>").

Rendering

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 unitID | projectileID,
  boolean enableTracking, boolean unitOrProjectile) -> boolean success

Spring.SetModelLightTrackingState

 (number lightHandle, number unitID | projectileID,
  boolean enableTracking, boolean unitOrProjectile) -> boolean success

lightParams is a table with the following recognized keys:

   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,
   }