Spring - User contributions [en]

Lua OpenGL Api

2012-05-09T16:33:49Z

Ledz: Reworded a warning while I'm here

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

= Spring =
'''gl.GetSun'''
() -> number sunPosX, number sunPosY, number sunPosZ
( "pos" ) -> number sunPosX, number sunPosY, number sunPosZ
( "shadowDensity" [, "unit"] ) -> number shadowDensity
( "diffuse" [, "unit"] ) -> nil | number r, number g, number b
( "ambient" [, "unit"] ) -> nil | number r, number g, number b
( "specular" ) -> nil | number r, number g, number b

'''gl.ConfigScreen''' used for Unit LODs
( number screenWidth, number screenDistance ) -> nil

'''gl.DrawMiniMap''' argument new in 0.82+
( boolean tansform = true ) -> nil

'''gl.SlaveMiniMap'''
( boolean mode ) -> nil

'''gl.ConfigMiniMap'''
( int px, int py, int sx, int sy ) -> nil

'''gl.GetViewSizes'''
( ) -> number x, number y

= Matrices & Viewport =
'''gl.Viewport'''
( number x, number y, number w, number h ) -> nil

'''gl.PushMatrix'''
() -> nil

'''gl.PopMatrix'''
() -> nil

'''gl.Translate'''
(number x, number y, number z) -> nil

'''gl.Scale'''
( number x, number y, number z ) -> nil

'''gl.Rotate'''
( number angle, number x, number y, number z ) -> nil

'''gl.Billboard'''
( ) -> nil
Use this to draw 2d primitives in DrawWorld().
To render a 2D billboarded quad in the gameworld at world position x,y,z, you do the following (at a minimum; I am skipping blending / depthtesting) here:
gl.PushMatrix()
gl.Texture(read what you need here)
gl.Translate(x,y,z)
gl.Billboard()
gl.TexRect(x1,y1,x2,y2)
gl.PopMatrix()

'''gl.MatrixMode'''
( number [[Lua_ConstGL#MatrixMode|mode]] ) -> nil

'''gl.LoadIdentity'''
( ) -> nil

'''gl.LoadMatrix'''
( ) -> nil

'''gl.MultMatrix'''
( ?? ) -> ??

'''gl.Ortho'''
( number left, number right, number bottom, number top, number near, number far ) -> nil

'''gl.Frustum'''
( number left, number right, number bottom, number top, number near, number far ) -> nil

'''gl.PushPopMatrix'''
( ?? ) -> ??

'''gl.ClipPlane'''
( int plane, note: $plane can only be 1 or 2
boolean enable |
number A, number B, number C, number D ) -> nil

= Clear =
'''gl.Clear'''
( GL.DEPTH_BUFFER_BIT [, number cleardepth] ) -> nil
( GL.STENCIL_BUFFER_BIT [, int clearstencil] ) -> nil
( GL.COLOR_BUFFER_BIT | GL.ACCUM_BUFFER_BIT [, number r, number g, number b, number a] ) -> nil

= ResetState/Matrices =
'''gl.ResetState''' DON'T USE IT UNLESS YOU KNOW WHAT YOU ARE DOING! Each call-in has different default states, but this function resets all states to the states below no matter what!
() -> nil

ShadeModel = GL.SMOOTH
Scissor = false
Texture = false
Lighting = false,
ColorMask = true, true, true, true
DepthMask = false
DepthTest = false (GL.LEQUAL)
Culling = false (GL.BACK)
LogicOp = false (GL.INVERT)
AlphaTest = false (GL.GREATER, 0.5f)
Blending = true (GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)


'''gl.ResetMatrices'''
() -> nil

Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack


= Draw Basics =
'''gl.BeginEnd'''
( number [[Lua_ConstGL#Drawing_Primitives|GLType]], function [, arg1,... ] ) -> nil

'''gl.Color'''
( { number r, number g, number b[, number a] } |
number r, number g, number b[, number a] ) -> nil

'''gl.Vertex'''
( { number x, number y [, number z [, number w ]] } |
number x, number y |
number x, number y, number z |
number x, number y, number z, number w ) -> nil

'''gl.Normal'''
( number x, number y, number z |
{ number x, number y, number z } ) -> nil

'''gl.EdgeFlag'''
( boolean enable ) -> nil

'''gl.Rect'''
( number x1, number y1, number x2, number y2 ) -> nil

'''gl.TexRect''' texture rect
( number x1, number y1, number x2, number y2,
[ boolean flip_s, boolean flip_t | number s1, number t1, number s2, number t2 ] ) -> nil

'''gl.Shape'''
( number [[Lua_ConstGL#Drawing_Primitives|GLtype]],
elements = {
[1] = { v | vertex = { number x, number y, number z }, required
n | normal = { number x, number y, number z }, optional
t | texcoord = { number x, number y }, optional
c | color = { number r, number g, number b, number a } optional
},
etc ...
}
) -> nil

'''gl.SecondaryColor'''
( { number r, number g, number b } |
number r, number g, number b ) -> nil

'''gl.FogCoord'''
( number value ) -> nil

= Display Lists =
Display Lists save given vertex attributes in a static buffer, so the GPU can directly read them (without the CPU). Display Lists are a lot faster (10-60x) than standard drawing with glShape/glBeginEnd, so try to use them when ever you can. If you want to learn more about them, g00gle is your friend ;)

'''gl.CreateList'''
( function [,arg1 [,arg2...]] ) -> number listID

'''gl.CallList'''
( number listID ) -> nil

'''gl.DeleteList'''
( number listID ) -> nil

= Text =
'''gl.Text'''
(string "text", number x, number y, number size [, string "options"] )

options are:
horizontal alignment:
'c' = center
'r' = right
vertical alignment:
'a' = ascender
't' = top
'v' = vertical center
'x' = baseline
'b' = bottom
'd' = descender
decorations:
'o' = black outline
'O' = white outline
's' = shadow
other:
'n' = don't round vertex coords to nearest integer (font may get blurry)

http://home.arcor.de/jkei/fontlines.png

'''gl.GetTextWidth'''
(string "text") -> number width (in pixels, with a font size of 1.0)

'''gl.GetTextHeight'''
( string "text" ) -> nil | number height, number descender, number numlines (in pixels, with a font size of 1.0)
further descriptions here: [[GetTextHeight]]

If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering. 
'''gl.BeginText'''
( ) -> nil
'''gl.EndText'''
( ) -> nil

= Unit/Feature Draw Functions =
'''gl.Unit''' (draws an unit; on default it uses LOD, with lod<0 it is turned off, else it defines a specific level)
( number unitID, [ boolean rawdraw, int lod ] ) -> nil

'''gl.UnitRaw''' (doesn't apply worldspace->unit transformation! only works if rawdraw is true )
( number unitID, [ boolean rawdraw, int lod ] ) -> nil

'''gl.UnitShape'''
( number unitDefID, number teamID ) -> nil

'''gl.Feature'''
( number featureID ) -> nil

'''gl.FeatureShape'''
( number featureDefID, number teamID ) -> nil

'''gl.UnitMultMatrix''' (world space -> unit space)
( number unitID ) -> nil

'''gl.UnitPieceMultMatrix''' (unit space -> piece space)
( number unitID, int piece ) -> nil

'''gl.UnitPiece''' (draws the unit piece)
( number unitID, int piece ) -> nil

'''gl.UnitPieceMatrix''' (use gl.UnitPieceMultMatrix instead!)
( number unitID, int piece ) -> nil

'''gl.DrawListAtUnit'''
( number unitID, number listID, [ boolean midPos,
number scaleX, number scaleY, number scaleZ,
number degrees, number rotX, number rotX, number rotZ ] ) -> nil

'''gl.DrawFuncAtUnit'''
( number unitID, boolean midPos, function [, arg1,... ]) -> nil

= States (Blending,AlphaTest...) =
'''gl.Blending'''
( boolean enable | number [[Lua_ConstGL#BlendingFactorSrc|srcmode]], number [[Lua_ConstGL#BlendingFactorDest|dstmode]] ) -> nil
( string mode ) -> nil
{| cellpadding="0" cellspacing="0" style="margin-top: -5px; margin-left:5px"
! style="color:#55ee99" | mode maybe:
|-
| style="color:#55ee99" | "add"
| style="color:#55ee99" | = GL.ONE, GL.ONE
|-
| style="color:#55ee99" | "alpha_add"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE
|-
| style="color:#55ee99" | "alpha"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
|-
| style="color:#55ee99" | "reset"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
|-
| style="color:#55ee99" | "color"
| style="color:#55ee99" | = GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA
|-
| style="color:#55ee99" | "modulate"
| style="color:#55ee99" | = GL.DST_COLOR, GL.ZERO
|-
| style="color:#55ee99" | "disable"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
|}

'''gl.BlendEquation'''
( number mode ) -> nil

'''gl.BlendFunc'''
( number [[Lua_ConstGL#BlendingFactorSrc|srcmode]], number [[Lua_ConstGL#BlendingFactorDest|dstmode]] ) -> nil

'''gl.BlendEquationSeparate''' (needs openGL2.0!)
( number modeRGB, number modeAlpha ) -> nil

'''gl.BlendFuncSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#BlendingFactorSrc|srcRGB]], number [[Lua_ConstGL#BlendingFactorDest|dstRGB]], number [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]], number [[Lua_ConstGL#BlendingFactorDest|dstAlpha]] ) -> nil

'''gl.AlphaTest'''
( boolean enable | number [[Lua_ConstGL#AlphaFunction and DepthFunction|func]], number threshold ) -> nil

'''gl.DepthTest'''
( boolean enable | number [[Lua_ConstGL#AlphaFunction and DepthFunction|func]] ) -> nil

'''gl.Culling'''
( boolean enable | number [[Lua_ConstGL#Culling|face]] ) -> nil

'''gl.DepthClamp''' not always available, needs GL.NV_depth_clamp!
( boolean enable ) -> nil

'''gl.DepthMask'''
( boolean enable ) -> nil

'''gl.ColorMask'''
( boolean ) -> nil
( boolean r, boolean g, boolean b, boolean a ) -> nil

'''gl.LogicOp'''
( boolean enable | number [[Lua_ConstGL#LogicOp|func]] ) -> nil

'''gl.Fog'''
( boolean enable ) -> nil

'''gl.Smoothing'''
( (boolean enable | number POINT),
(boolean enable | number LINE),
(boolean enable | number POLYGON) ) -> nil

'''gl.EdgeFlag'''
( boolean enable ) -> nil

'''gl.Scissor'''
( boolean ) -> nil
( int x, int y, int w, int h ) -> nil

'''gl.LineStipple'''
( string any ) -> nil (use springs default line stipple)
( boolean enable ) -> nil
( int factor, number pattern ) -> nil

'''gl.PolygonMode'''
( number [[Lua_ConstGL#Culling|face]], number [[Lua_ConstGL#PolygonMode|mode]] ) -> nil

'''gl.PolygonOffset'''
( boolean enable | number factor, number units ) -> nil

'''gl.PushAttrib'''
( [ number [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] ] ) -> nil

'''gl.PopAttrib'''
() -> nil

= Stencil =
'''gl.StencilTest'''
( boolean enable ) -> nil
'''gl.StencilMask'''
( number mask ) -> nil
'''gl.StencilFunc'''
( number func, number ref, number mask ) -> nil
'''gl.StencilOp'''
( number fail, number zfail, number zpass ) -> nil

'''gl.StencilMaskSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#Culling|face]], number mask ) -> nil
'''gl.StencilFuncSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#Culling|face]], number func, number ref, number mask ) -> nil
'''gl.StencilOpSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#Culling|face]], number fail, number zfail, number zpass ) -> nil

= LineWidth & PointSize =
'''gl.LineWidth'''
( number width ) -> nil

'''gl.PointSize''' (values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390)
( number size ) -> nil

'''gl.PointSprite''' (needs openGL2.0!)
( boolean enable, [boolean coord_replace, boolean coord_origin_upper] ) -> nil

'''gl.PointParameter''' (needs openGL2.0!)
( number v1, number v2, number v3,
[ number sizeMin, number sizeMax, number sizeFade ] ) -> nil

= Textures =
'''gl.Texture'''
( [ number texNum, ] boolean enable | string name ) -> nil | boolean loaded
This is the only call-out that is needed to load and draw any texture in a Lua script. All you have to do is pass it a valid path to a valid png and it will use that image for drawing any subsequent textured rectangles. This is shown in the last line of the following list of valid strings for the name parameter.


{| cellpadding="0" cellspacing="0" style="margin-top: -5px; margin-left:5px"
! style="color:#55ee99; text-align:left" |`name` maybe:
|-
| style="color:#55ee99" | #12
| style="color:#55ee99" | = unitDef 12 buildpic
|-
| style="color:#55ee99" | %34:1
| style="color:#55ee99" | = unitDef 34 s3o tex2 (:0->tex1,:1->tex2)
|-
| style="color:#55ee99" | %-102:0
| style="color:#55ee99" | = featureDef 102 s3o tex1
|-
| style="color:#55ee99" | !56
| style="color:#55ee99" | = lua generated texture 56 (= return value of gl.CreateTexture)
|-
| style="color:#55ee99" | $units
| style="color:#55ee99" | = 3do textureatlas tex1
|-
| style="color:#55ee99" | $units1
| style="color:#55ee99" | = 3do textureatlas tex1
|-
| style="color:#55ee99" | $units2
| style="color:#55ee99" | = 3do textureatlas tex2
|-
| style="color:#55ee99" | $shadow
| style="color:#55ee99" | = shadowmap
|-
| style="color:#55ee99" | $specular
| style="color:#55ee99" | = specular cube map
|-
| style="color:#55ee99" | $reflection
| style="color:#55ee99" | = reflection cube map
|-
| style="color:#55ee99" | $shading
| style="color:#55ee99" | = ground shading texture
|-
| style="color:#55ee99" | $grass
| style="color:#55ee99" | = grass shading texture
|-
| style="color:#55ee99" | $heightmap
| style="color:#55ee99" | = heightmap (needs HeightMapTexture=1 set in spring config)
|-
| style="color:#55ee99" | ${opt}:/LuaUI/images/image.png
| style="color:#55ee99" | = load a texture from the VFS
|}

possible ${opt}'s are:
'n' = nearest
'l' = linear
'a' = aniso
'i' = invert
'g' = greyed
'c' = clamped
'b' = border
't%r,%g,%b' = tint
'r%width,%height' = resize

example: ":iac:/LuaUI/images/image.png"
example: ":cr16,16:/LuaUI/images/image.png"
example2: ":t1.0,0.5,0:/LuaUI/images/image.png" (orange tint)


'''gl.CreateTexture'''
( int xsize, int ysize,
[ {
[target = number,] (like GL.TEXTURE_1D,GL.TEXTURE_2D,...)
[format = number,]
[min_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[mag_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[wrap_s = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_t = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_r = [[Lua_ConstGL#Texture_Clamping|number]],]
[aniso = number,]
[border = boolean,]
[fbo = boolean,] (needs GLEW_EXT_framebuffer_object!)
[fboDepth = boolean] (needs GLEW_EXT_framebuffer_object!)
} ]
) -> string

'''gl.DeleteTexture'''
( string texture ) -> boolean

'''gl.DeleteTextureFBO''' (needs GLEW_EXT_framebuffer_object!)
( string texture ) -> boolean

'''gl.TextureInfo'''
( string texture ) -> nil | {
xsize = number,
ysize = number,
alpha = boolean, //not used yet
type = number, //not used yet
}

the format of the texture string is the same as in gl.Texture()


'''gl.TexCoord'''
( number x |
number x, number y |
number x, number y, number z |
number x, number y, number z, number w |
{ number x [, number y [, number z [, number w ]]] } ) -> nil

'''gl.MultiTexCoord'''
( int texNum,
number x |
number x, number y |
number x, number y, number z |
number x, number y, number z, number w |
{ number x [, number y [, number z [, number w ]]] } ) -> nil

'''gl.TexEnv'''
( number [[Lua_ConstGL#Texture_Environment|target]], number [[Lua_ConstGL#Texture_Environment|pname]],
number [[Lua_ConstGL#Texture_Environment|value]] |
number var1, number var2, number var3 ) -> nil

'''gl.MultiTexEnv'''
( int texNum, number [[Lua_ConstGL#Texture_Environment|target]], number [[Lua_ConstGL#Texture_Environment|pname]],
number [[Lua_ConstGL#Texture_Environment|value]] |
number var1, number var2, number var3 ) -> nil

'''gl.TexGen'''
( number [[Lua_ConstGL#Texture_Generation|target]],
boolean state |
number [[Lua_ConstGL#Texture_Generation|pname]], number value |
number [[Lua_ConstGL#Texture_Generation|pname]], number var1, number var2, number var3 ) -> nil

'''gl.MultiTexGen'''
( int texNum, number [[Lua_ConstGL#Texture_Generation|target]],
boolean state |
number [[Lua_ConstGL#Texture_Generation|pname]], number value |
number [[Lua_ConstGL#Texture_Generation|pname]], number var1, number var2, number var3 ) -> nil

'''gl.CopyToTexture'''
(string texture, int xoff, int yoff, int x, int y, int w, int h
[,number target,number level])->nil

'''gl.RenderToTexture''' (needs GLEW_EXT_framebuffer_object!)
( string fbotexture, lua_func ) -> nil

'''gl.GenerateMipmap''' (needs glGenerateMipmapEXT!)
( string texture ) -> boolean

= PixelReadback =
'''gl.SaveImage'''
( number x, number y, number w, number h,
string filename [, table {alpha=boolean, yflip=boolean} ] ) -> nil | boolean success

'''gl.ReadPixels'''
( number x, number y, number w, number h [, number format = GL.RGBA ] )
-> nil | number r,[g,[b,[a]]] | table { { {1 = number r, 2 = number g, 3 = number b, 4 = number a}, ... }, ... }

= Lights =
'''gl.Lighting'''
( boolean enable ) -> nil

'''gl.ShadeModel'''
( number [[Lua_ConstGL#ShadeModel|mode]] ) -> nil

'''gl.Light'''
( int light,
boolean enable |
number [[Lua_ConstGL#Light_Specification|pname]], number param |
number [[Lua_ConstGL#Light_Specification|pname]], number param1, number param2, number param3 ) -> nil

'''gl.Material'''
({
ambient = {number r, number g, number b[, number a]},
diffuse = {number r, number g, number b[, number a]},
ambidiff = {number r, number g, number b[, number a]},
emission = {number r, number g, number b[, number a]},
specular = {number r, number g, number b[, number a]},
shininess = number specularExponent
}) -> nil

= Hardware relevant =
'''gl.HasExtension'''
( string extname ) -> boolean

'''gl.GetNumber'''
( number ext, int count ) -> number [, number, number, ... #count ]

'''gl.GetString'''
( number ext ) -> string

= DrawGroundPrimitives =
'''gl.DrawGroundCircle'''
( number x, number y, number z, number radius, number divs [, number slope ] ) -> nil
Note: number divs is the number of sides the circle will have. the higher the smoother the circle (and more GPU intensive) 

'''gl.DrawGroundQuad''' Note: x1,z1,x2 & z2 are rounded, so don't use it for very small or moving objects. x and z are correspond to the coordinates displayed by the tooltip 
( number x1, number z1, number x2, number z2,
[ boolean useNorm, (does nothing!)
[ number tu1, number tv1, number tu2, number tv2 |
boolean useTextureCoord ] ] ) -> nil

= Queries =
'''gl.CreateQuery''' needs >=OpengGL2.0!
( ) -> nil | userdata query
'''gl.DeleteQuery''' needs >=OpengGL2.0!
( userdata query ) -> nil
'''gl.RunQuery''' needs >=OpengGL2.0!
( userdata query, function, arg1, arg2, ... ) -> nil
'''gl.GetQuery''' needs >=OpengGL2.0!
( userdata query ) -> nil | number renderedFragments

= Extended =
'''gl.ActiveTexture'''
( int texNum, function [, arg1,... ] ) -> nil

'''gl.GetGlobalTexNames'''
() -> { [1] = string texture, etc ... }

'''gl.GetGlobalTexCoords''' gets the texcoord of a 3do texture in the 3do texture atlas
( string 3doTextureName ) -> number xstart, number ystart, number xend, number yend

'''gl.UnsafeState'''
( number state [, boolean disable_state ], function, arg1, arg2, ... ) -> nil
Calls glEnable(state) or glDisable(state) (if disable_state==true) and then calls the lua_function and afterwards reverts the state.

'''gl.GetShadowMapParams'''
() -> number xmid, number ymid, number p17, number p18

'''gl.GetMatrixData'''
( GL.PROJECTION [, int i] ) -> nil | number, etc.. | number Matrix[i]
( GL.MODELVIEW [, int i] ) -> nil | number, etc.. | number Matrix[i]
( GL.TEXTURE [, int i] ) -> nil | number, etc.. | number Matrix[i]
( "shadow" ) -> nil | number, etc..
( "camera" ) -> nil | number, etc..
( "caminv" ) -> nil | number, etc..
( "camprj" ) -> nil | number, etc..
( "billboard" ) -> nil | number, etc..

'''gl.Flush'''
() -> nil

'''gl.Finish'''
() -> nil

= Shaders (GLSL) =
[[Lua_GLSL_Api]]

[[category: Lua]]

Lua UnsyncedCtrl

2012-05-07T15:15:09Z

Ledz: Added argument to MarkerAddPoint

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

<div class="note">
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.</div>

= 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,
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.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 = "", number localOnly (0/1)] ) -> 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|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|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"}
}, ..
}
) -> 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''' {{new|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|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|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 [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.

'''Spring.ClearWatchdogTimer''' {{new|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,
}

'''Spring.SetMapSquareTexture'''
(number texSqrX, number texSqrY, string luaTexName) -> boolean success
'''Spring.GetMapSquareTexture'''
(number texSqrX, number texSqrY, number texMipLvl, string luaTexName) -> boolean success

[[category: Lua]]