Lua UnsyncedCtrl

From Spring
Revision as of 02:30, 16 September 2011 by Abma (talk | contribs) (→Engine Config)
Jump to navigationJump to search

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.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 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 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 (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

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 (0.83+) 

 ( 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.

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


Spring.SetMapSquareTexture 

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

Spring.GetMapSquareTexture 

 (number texSqrX, number texSqrY, number texMipLvl, string luaTexName) -> boolean success
Retrieved from "https://springrts-wiki.p2004a.com/mediawiki/index.php?title=Lua_UnsyncedCtrl&oldid=12262"