User:Master-athmos

Development < Lua Scripting < User:Master-athmos

NOTE: Prior to 102.0, 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 in previous versions and removed in 102.0 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

 ( string section, int logLevel | string logLevel,
   arg2 [, arg3 [, ... ] ] ) -> 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 (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)

New arguments since 100.0 (radar2 is the inside of radar edge):

 ( always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b}) -> nil

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" ) -> 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
   [, bool enqueue ]] ) -> 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

Spring.SetUnitSelectionVolumeData New in version 104.0

 ( number featureID, number scaleX, number scaleY, number scaleZ,
   number offsetX, number offsetY, number offsetX,
   number vType, number tType, number Axis
 ) -> 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

Features

Spring.SetFeatureFade New in version 101.0

 ( int featureID, bool allow ) -> nil

Control whether a feature will fade or not when zoomed out.

Spring.SetFeatureNoDraw LuaGadgets only!

 ( number featureID, boolean noDraw ) -> nil

Spring.SetFeatureSelectionVolumeData New in version 104.0

 ( number featureID, number scaleX, number scaleY, number scaleZ,
   number offsetX, number offsetY, number offsetX,
   number vType, number tType, number Axis
 ) -> nil

Developers

Spring.SetDrawSky

 ( boolean drawSky ) -> nil

Spring.SetDrawWater

 ( boolean drawWater ) -> nil

Spring.SetDrawGround

 ( boolean drawGround ) -> nil

Spring.SetWaterParams As of 104.0 no longer 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,
 }

Spring.SetMapRenderingParams New in version 104.0

 ( table params ) -> nil

Allows to change map rendering params at runtime.

 `params` table may contain:
 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 New in version 95.0

  ( string sectionName, string|number logLevel )

see infolog.txt for possible log sections (?)

Spring.SetDrawGroundDeferred New in version 95.0

   ( boolean drawGroundDeferred [, boolean drawGroundForward] ) -> nil

New in version 101.0 drawGroundForward allows disabling of the forward pass

Spring.SetDrawModelsDeferred New in version 95.0

   (     boolean drawUnitsDeferred,
         boolean drawFeaturesDeferred
      [, boolean drawUnitsForward
      [, boolean drawFeaturesForward ]]
    ) -> nil

New in version 101.0 drawFeaturesForward, drawUnitsForward allows disabling of the respective forward passes

Spring.SetVideoCapturingMode New in version 104.0

  ( boolean allowCaptureMode ) -> nil

This doesn't actually record the game in any way, it just regulates the framerate and interpolations.

Spring.SetVideoCapturingTimeOffset New in version 104.0

  ( number timeOffset ) -> nil

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 cmdID_cloneIcon | string iconname,
   { number r, number g, number b, number a } [, boolean showArea ] ) -> nil
 ( number cmdID, nil) -> nil

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.

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. Also see #5028

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)

 ( string path ) -> nil | boolean

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 [, boolean useOverlay = false] ) -> nil

Spring.SetConfigFloat New in version 104.0

 ( string name, number value [, boolean useOverlay = false] ) -> nil

Spring.SetConfigString

 ( 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

Sun

The dynamic Sun must be invoked via /dynamicsun (Dynamic sun was removed in 104.0, use SetSunDirection, SetSunLighting & SetAtmosphere instead).

Spring.SetSunManualControl Removed from version 104.0

 ( boolean setManualControl ) - > nil

Spring.SetSunParameters Removed from version 104.0

 ( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

Spring.SetSunDirection

 ( number dirX, number dirY, number dirZ ) -> nil

Spring.SetSunLighting New in version 101.0

 ( table params ) -> nil

 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 New in version 101.0

 ( table params ) -> nil

 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 New in version 99.0

 ( string startscript )

start-script is the CONTENT of the script.txt spring should use to start.

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

Spring.Start New in version 102.0

 ( string commandline_args, string startscript )
   -> 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 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

Spring.SetClipboard New in version 98.0

 ( string text) -> nil

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 New in version 101.0

 ( number unitDefID ) -> nil

Spring.PreloadFetureDefModel New in version 101.0

 ( number featureDefID ) -> nil

Lighting

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

Map

Spring.SetSkyBoxTexture New in version 101.0

 ( string texName ) -> nil

Spring.SetMapShadingTexture New in version 101.0

 ( string texType, string texName ) -> boolean success

Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")

Spring.SetMapSquareTexture

 ( number texSqrX, number texSqrY, string luaTexName ) -> boolean success

Spring.SetMapShader Template:101.0

 ( number standardShaderID, number deferredShaderID ) -> nil

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.