Spring - User contributions [en]

User:Master-athmos

2021-04-21T20:51:35Z

Master-athmos: Replaced content with "Development < Lua Scripting < {{FULLPAGENAME}} These functions are ONLY available if the graphic board supp..."

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

These functions are ONLY available if the graphic board supports GLSL. Please test in your scripts if one of them exists before you use them!

'''gl.CreateShader'''
({[ vertex = "glsl code" ,]
[ tcs = "glsl code" ,]
[ tes = "glsl code" ,]
[ geometry = "glsl code" ,]
[ fragment = "glsl code" ,]
[ uniform = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformInt = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformFloat = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformMatrix = { uniformName = number value, ...} ,]
[ geoInputType = number inType,]
[ geoOutputType = number outType,]
[ geoOutputVerts = number maxVerts,]
[ definitions = "string of shader #defines", ]
}) -> number shaderID

* The "Vertex" or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc.

* The "Geometry" or Geometry-shader can create new vertices and vertice-stripes from points.

* The "TCS" or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage. TCS shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

* The "TES" or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader. TES shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

* The "Fragment" or Fragment-shader (sometimes called pixel-Shader) is post processing the allready rendered picture (for example drawing stars on the sky)- remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed.

* The Uniforms are the values, you send along with the shader-program. To use them in the shader-program declare them like this:
<syntaxhighlight lang="c">uniform float frame;</syntaxhighlight>

* From 101.0 onwards, the engine will automatically fill in an appropriately named uniform for team colour if it is declared;
<syntaxhighlight lang="c">uniform vec4 teamColor;</syntaxhighlight>

'''gl.DeleteShader'''
( number shaderID ) -> nil

'''gl.ActiveShader''' can be used in NON-drawing events (to update uniforms etc.)!
( number shaderID, function [, arg1 [, arg2, ..]] ) -> nil

'''gl.UseShader'''
( number shaderID ) -> boolean linked

'''gl.GetShaderLog'''
( ) -> string "infoLog"

'''gl.SetShaderParameter'''
Renamed to SetGeometryShaderParameter in spring version >= 104.0.1-596 (maintenance).
needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri)
( number shaderID, number param, number value ) -> nil

'''gl.SetTesselationShaderParameter'''
Available for spring versions >= 104.0.1-596 (maintenance).
needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri)
( number param, number value ) -> nil

'''gl.GetActiveUniforms'''
( number shaderID ) -> {
[1] = { name = "name", type = "type", length = number length, size = number size },
...
}

'''gl.GetUniformLocation'''
( number shaderID, name uniformName ) -> number locationID

'''gl.Uniform'''
( number locationID, number f1 [,number f2 [,number f3 [,number f4]]] ) -> nil

'''gl.UniformInt'''
( number locationID, number int1 [,number int2 [,number int3 [,number int4]]] ) -> nil

'''gl.UniformArray''' {{new|95.0}}
( number locationID, number type, table uniforms ) -> nil
type can be one of {1 = int, 2 = float, 3 = float matrix}. In 104.0 the maximum length of the uniforms table increased from 32 entries to 1024.

'''gl.UniformMatrix'''
( number locationID,
"shadow" |
"camera" |
"caminv" |
"camprj" |
number m1, number m2, number m3, number m4 |
number m1, ... , number m9 |
number m1, ... , number m16
) -> nil

[[category: Lua]]

Lua OpenGL Api

2021-04-21T20:48:24Z

Master-athmos: Updated page with new anchorable templates

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>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()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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!
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> 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 ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= 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 ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= Text =

{{LuaCallout
|prefix = gl.
|name = Text
|arg1 = {{type|string}} "text"
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} size {{bracket}}
|arg5 = {{type|string}} "options" {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = GetTextWidth
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} width
|info = Width in pixels, with a font size of 1.0.
}}

{{LuaCallout
|prefix = gl.
|name = GetTextHeight
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height, {{type|number}} descender, {{type|number}} numlines
|info = Height in pixels, with a font size of 1.0. Further descriptions here: [[GetTextHeight]]
}}

{{LuaCallout
|prefix = gl.
|name = BeginText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
}}

{{LuaCallout
|prefix = gl.
|name = EndText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Unit/Feature Draw Functions =

{{LuaCallout
|prefix = gl.
|name = Unit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws a unit - on default it uses LOD, with lod<0 it is turned off, else it defines a specific level.
}}

{{LuaCallout
|prefix = gl.
|name = UnitRaw
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Doesn't apply worldspace->unit transformation! only works if rawdraw is true.
}}

{{LuaCallout
|prefix = gl.
|name = UnitShape
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} rawState
|arg4 = {{type|bool}} toScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.
}}

{{LuaCallout
|prefix = gl.
|name = UnitMultMatrix
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = world space -> unit space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMultMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = unit space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPiece
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws the unit piece.
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use gl.UnitPieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = Feature
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureRaw
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShape
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} custom
|arg4 = {{type|bool}} drawScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureMultMatrix
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} world space -> feature space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMultMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} feature space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePiece
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Draws the Feature piece.
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Use gl.FeaturePieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = DrawListAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} listID {{bracket}}
|arg3 = {{type|bool}} midPos
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} degrees
|arg6 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DrawFuncAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} midPos
|arg3 = {{type|function}} {{bracket}}, arg1, ... {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= States (Blending,AlphaTest...) =

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|string}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Mode can be set to:
}}
<pre>"add"
= GL.ONE, GL.ONE

"alpha_add"
= GL.SRC_ALPHA, GL.ONE

"alpha"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"reset"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"color"
= GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA

"modulate"
= GL.DST_COLOR, GL.ZERO

"disable"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA</pre>

{{LuaCallout
|prefix = gl.
|name = BlendEquation
|arg1 = {{type|number}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendFunc
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendEquationSeparate
|arg1 = {{type|number}} modeRGB
|arg2 = {{type|number}} modeAlpha
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = BlendFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcRGB]]
|arg2 = {{type|number}} [Lua_ConstGL#BlendingFactorDest|dstRGB]]
|arg3 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]]
|arg4 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstAlpha]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = AlphaTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 = {{type|number}} threshold
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Culling
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthClamp
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Not always available, needs GL.NV_depth_clamp!
}}

{{LuaCallout
|prefix = gl.
|name = DepthMask
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} masked
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} r, {{type|bool}} g, {{type|bool}} b, {{type|bool}} a
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LogicOp
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#LogicOp|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Fog
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Smoothing
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} point
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} line
|arg3 = {{type|bool}} enable {{pipe}} {{type|number}} polygon
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|number}} intX, {{type|number}} intY, {{type|number}} intW, {{type|number}} intH
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|string}} any
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use springs default line stipple.
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|number}} intFactor
|arg2 = {{type|number}} pattern
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonMode
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} [[Lua_ConstGL#PolygonMode|mode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonOffset
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} factor
|arg2 = {{type|number}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushAttrib
|arg1 = {{bracket}} {{type|number}} [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopAttrib
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Stencil =

{{LuaCallout
|prefix = gl.
|name = StencilTest
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMask
|arg1 = {{type|number}} mask
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilFunc
|arg1 = {{type|number}} func
|arg2 = {{type|number}} ref
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilOp
|arg1 = {{type|number}} fail
|arg2 = {{type|number}} zfail
|arg3 = {{type|number}} zpass
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMaskSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} mask
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} func
|arg3 = {{type|number}} ref
|arg4 = {{type|number}} mask
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilOpSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} fail
|arg3 = {{type|number}} zfail
|arg4 = {{type|number}} zpass
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= LineWidth & PointSize =

{{LuaCallout
|prefix = gl.
|name = LineWidth
|arg1 = {{type|number}} width
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PointSize
|arg1 = {{type|number}} size
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390
}}

{{LuaCallout
|prefix = gl.
|name = PointSprite
|arg1 = {{type|bool}} enable {{bracket}}
|arg2 = {{type|bool}} coord_replace
|arg3 = {{type|bool}} coord_origin_upper {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = PointParameter
|arg1 = {{type|number}} v1, {{type|number}} v2, {{type|number}} v3 {{bracket}}
|arg2 = {{type|number}} sizeMin
|arg3 = {{type|number}} sizeMax
|arg4 = {{type|number}} sizeFade {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= Textures =

{{LuaCallout
|prefix = gl.
|name = Texture
|arg1 = {{bracket}} {{type|number}} texNum, {{rbracket}} {{type|bool}} enable {{pipe}} {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} loaded
|info = 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.
}}
name may be:

#12
= unitDef 12 buildpic

%34:1
= unitDef 34 s3o tex2 (:0->tex1,:1->tex2)

%-102:0
= featureDef 102 s3o tex1

!56
= lua generated texture 56 (= return value of gl.CreateTexture)

$units
= 3do textureatlas tex1

$units1
= 3do textureatlas tex1

$units2
= 3do textureatlas tex2

$shadow
= shadowmap

$specular
= specular cube map (removed in the latest develop)

$reflection
= reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)

$shading
= ground shading texture

$grass
= grass shading texture

$heightmap
= heightmap (needs HeightMapTexture=1 set in spring config)

$minimap
= minimap texture

$map_reflection
= same as "$reflection" {{new|101.0}}

$sky_reflection
= defined for SSMF maps that have a skyReflectModTex {{new|101.0}}

$detail
= detail texture {{new|101.0}}

$normals
= auto generated normals texture {{new|101.0}}

$ssmf_normals
= SSMF normals texture {{new|101.0}}

$ssmf_specular
= SSMF specular texture {{new|101.0}}

$ssmf_splat_distr
= SSMF splat distribution texture {{new|101.0}}

$ssmf_splat_detail
= SSMF splat detail texture {{new|101.0}}

$ssmf_splat_normals
= SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted

$ssmf_emission
= SSMF emission texture {{new|101.0}}

$ssmf_parallax
= SSMF parallax texture {{new|101.0}}

$info
= currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale

$info_losmap
= los texture (L-view)

$info_mtlmap
= metal map texture (F4-view)

$info_hgtmap
= height map texture (F1-view)

$info_blkmap
= blocking map texture (F2-view)

$map_gbuffer_normtex
= contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$map_gbuffer_difftex
= contains the diffuse texture buffer of the map in view {{new|95}}

$map_gbuffer_spectex
= contains the specular textures of the map in view {{new|95}}

$map_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$map_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$map_gbuffer_zvaltex
= contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use:

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;

$model_gbuffer_normtex
= contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$model_gbuffer_difftex
= contains the diffuse texture buffer of the models in view {{new|95}}

$model_gbuffer_spectex
= contains the specular textures of the models in view {{new|95}}

$model_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$model_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$model_gbuffer_zvaltex
= contains the depth values (z-buffer) of the models in view. {{new|95}}

${opt}:/LuaUI/images/image.png
= 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
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

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)


{{LuaCallout
|prefix = gl.
|name = CreateTexture
|arg1 = {{type|number}} intXSize
|arg2 = {{type|number}} intYSize {{bracket}}
|arg3 = {{type|table}} texProps {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} texture
|info = texProps contains:
}}
<pre>texProps = {
[target = number,](like GL.TEXTURE_1D,GL.TEXTURE_2D,...)(Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[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!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
}</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteTexture
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteTextureFBO
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = TextureInfo
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} texInfo
|info = texInfo contains:
}}
<pre> texInfo = {
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().</pre>

{{LuaCallout
|prefix = gl.
|name = MultiTexCoord
|arg1 = {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} {{pipe}} {{type|table}} texCoords = { {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} state
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|bool}} state
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CopyToTexture
|arg1 = {{type|string}} texture
|arg2 = {{type|number}} intXOff
|arg3 = {{type|number}} intYOff
|arg4 = {{type|number}} intX
|arg5 = {{type|number}} intY
|arg6 = {{type|number}} intW
|arg7 = {{type|number}} intH {{bracket}}
|arg8 = {{type|number}} target
|arg9 = {{type|number}} level {{rbracket}}
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = RenderToTexture
|arg1 = {{type|string}} fbotexture
|arg2 = {{type|function}} lua_func
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = GenerateMipmap
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} created
|info = Needs glGenerateMipmapEXT!
}}
<pre>The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")</pre>

{{LuaCallout
|prefix = gl.
|name = UnitTextures
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = UnitShapeTextures
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureTextures
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShapeTextures
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

= PixelReadback =

{{LuaCallout
|prefix = gl.
|name = SaveImage
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 = {{type|string}} filename {{bracket}}
|arg6 = {{type|table}} imgProps = { alpha={{type|bool}}, yflip={{type|bool}}, grayscale16bit={{type|bool}}, readbuffer={{type|number}} } {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index
}}

{{LuaCallout
|prefix = gl.
|name = ReadPixels
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h {{bracket}}
|arg5 = {{type|number}} format = GL.RGBA {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r {{bracket}}, g {{bracket}}, b {{bracket}}, a {rbracket}}{rbracket}}{rbracket}} {{pipe}} {{type|table}} readPixels = { { { 1 = {{type|number}} r, 2 = {{type|number}} g, 3 = {{type|number}} b, 4 = {{type|number}} a}, ... }, ... }
|info = This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.
}}

= Lights =

{{LuaCallout
|prefix = gl.
|name = Lighting
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ShadeModel
|arg1 = {{type|number}} [[Lua_ConstGL#ShadeModel|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|number}} [[Lua_ConstGL#Light_Specification|pname]]
|arg3 = {{type|number}} param
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|number}} [[Lua_ConstGL#Light_Specification|pname]]
|arg3 = {{type|number}} param1
|arg4 = {{type|number}} param2
|arg5 = {{type|number}} param3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Material
|arg1 = {{type|table}} material
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = material contains:
}}
<pre>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
}</pre>

= Hardware relevant =

{{LuaCallout
|prefix = gl.
|name = HasExtension
|arg1 = {{type|string}} extname
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasExtension
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetNumber
|arg1 = {{type|number}} ext
|arg2 = {{type|number}} intCount
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} number1 {{bracket}}, {{type|number}} number2, {{type|number}} number3, ... #count {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetString
|arg1 = {{type|number}} ext
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} extString
|info =
}}

= DrawGroundPrimitives =

{{LuaCallout
|prefix = gl.
|name = DrawGroundCircle
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 = {{type|number}} divs {{bracket}}
|arg6 = {{type|number}} slope {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Number divs is the number of sides the circle will have. The higher the smoother the circle (and more GPU intensive).
}}

{{LuaCallout
|prefix = gl.
|name = DrawGroundQuad
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{bracket}}
|arg5 = {{type|bool}} useNorm {{bracket}}
|arg6 = {{type|number}} tu1, {{type|number}} tv1
|arg7 = {{type|number}} tu2, {{type|number}} tv2 {{rbracket}} {{pipe}} {{bracket}} {{type|bool}} useTextureCoord {{rbracket}} {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: x1, z1, x2 & z2 are rounded, so don't use it for very small or moving objects. x and z correspond to the coordinates displayed by the tooltip. Also note: useNorm does nothing!
}}

= Queries =

{{LuaCallout
|prefix = gl.
|name = CreateQuery
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|userdata}} query
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = DeleteQuery
|arg1 = {{type|userdata}} query
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = RunQuery
|arg1 = {{type|userdata}} query
|arg2 = {{type|function}} func
|arg3 = {{type|arg1}}
|arg4 = {{type|arg2}}
|arg5 = ...
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = GetQuery
|arg1 = {{type|userdata}} query
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} renderedFragments
|info =
}}

= Extended =

{{LuaCallout
|prefix = gl.
|name = ActiveTexture
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|function}} func {{bracket}}
|arg3 = {{type|arg1}}
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetGlobalTexNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} texNames = { {{bracket|1}} = {{type|string}} texture, etc ... }
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetGlobalTexCoords
|arg1 = {{type|string}} 3doTextureName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} xstart, {{type|number}} ystart, {{type|number}} xend, {{type|number}} yend
|info = Gets the texcoord of a 3do texture in the 3do texture atlas.
}}

{{LuaCallout
|prefix = gl.
|name = UnsafeState
|arg1 = {{type|number}} state {{bracket}}
|arg2 = {{type|bool}} disable_state {{rbracket}}
|arg3 = {{type|bool}} func
|arg4 = {{type|arg1}}
|arg5 = {{type|arg2}}
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Calls glEnable(state) or glDisable(state) (if disable_state==true) and then calls the lua_function and afterwards reverts the state.
}}

{{LuaCallout
|prefix = gl.
|name = GetShadowMapParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} xmid, {{type|number}} ymid, {{type|number}} p17, {{type|number}} p18
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.PROJECTION {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.MODELVIEW {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.TEXTURE {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "shadow"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "camera"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}
{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "caminv"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "camprj"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "billboard"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Flush
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Finish
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Shaders (GLSL) =
[[Lua_GLSL_Api]]

[[category: Lua]]

User:Master-athmos

2021-04-21T20:47:47Z

Master-athmos:

User:Master-athmos

2021-04-21T18:15:37Z

Master-athmos:

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>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()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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!
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> 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 ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= 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 ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= Text =

{{LuaCallout
|prefix = gl.
|name = Text
|arg1 = {{type|string}} "text"
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} size {{bracket}}
|arg5 = {{type|string}} "options" {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = GetTextWidth
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} width
|info = Width in pixels, with a font size of 1.0.
}}

{{LuaCallout
|prefix = gl.
|name = GetTextHeight
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height, {{type|number}} descender, {{type|number}} numlines
|info = Height in pixels, with a font size of 1.0. Further descriptions here: [[GetTextHeight]]
}}

{{LuaCallout
|prefix = gl.
|name = BeginText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
}}

{{LuaCallout
|prefix = gl.
|name = EndText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Unit/Feature Draw Functions =

{{LuaCallout
|prefix = gl.
|name = Unit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws a unit - on default it uses LOD, with lod<0 it is turned off, else it defines a specific level.
}}

{{LuaCallout
|prefix = gl.
|name = UnitRaw
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Doesn't apply worldspace->unit transformation! only works if rawdraw is true.
}}

{{LuaCallout
|prefix = gl.
|name = UnitShape
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} rawState
|arg4 = {{type|bool}} toScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.
}}

{{LuaCallout
|prefix = gl.
|name = UnitMultMatrix
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = world space -> unit space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMultMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = unit space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPiece
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws the unit piece.
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use gl.UnitPieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = Feature
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureRaw
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShape
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} custom
|arg4 = {{type|bool}} drawScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureMultMatrix
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} world space -> feature space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMultMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} feature space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePiece
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Draws the Feature piece.
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Use gl.FeaturePieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = DrawListAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} listID {{bracket}}
|arg3 = {{type|bool}} midPos
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} degrees
|arg6 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DrawFuncAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} midPos
|arg3 = {{type|function}} {{bracket}}, arg1, ... {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= States (Blending,AlphaTest...) =

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|string}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Mode can be set to:
}}
<pre>"add"
= GL.ONE, GL.ONE

"alpha_add"
= GL.SRC_ALPHA, GL.ONE

"alpha"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"reset"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"color"
= GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA

"modulate"
= GL.DST_COLOR, GL.ZERO

"disable"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA</pre>

{{LuaCallout
|prefix = gl.
|name = BlendEquation
|arg1 = {{type|number}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendFunc
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendEquationSeparate
|arg1 = {{type|number}} modeRGB
|arg2 = {{type|number}} modeAlpha
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = BlendFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcRGB]]
|arg2 = {{type|number}} [Lua_ConstGL#BlendingFactorDest|dstRGB]]
|arg3 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]]
|arg4 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstAlpha]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = AlphaTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 = {{type|number}} threshold
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Culling
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthClamp
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Not always available, needs GL.NV_depth_clamp!
}}

{{LuaCallout
|prefix = gl.
|name = DepthMask
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} masked
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} r, {{type|bool}} g, {{type|bool}} b, {{type|bool}} a
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LogicOp
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#LogicOp|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Fog
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Smoothing
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} point
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} line
|arg3 = {{type|bool}} enable {{pipe}} {{type|number}} polygon
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|number}} intX, {{type|number}} intY, {{type|number}} intW, {{type|number}} intH
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|string}} any
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use springs default line stipple.
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|number}} intFactor
|arg2 = {{type|number}} pattern
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonMode
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} [[Lua_ConstGL#PolygonMode|mode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonOffset
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} factor
|arg2 = {{type|number}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushAttrib
|arg1 = {{bracket}} {{type|number}} [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopAttrib
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Stencil =

{{LuaCallout
|prefix = gl.
|name = StencilTest
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMask
|arg1 = {{type|number}} mask
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilFunc
|arg1 = {{type|number}} func
|arg2 = {{type|number}} ref
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilOp
|arg1 = {{type|number}} fail
|arg2 = {{type|number}} zfail
|arg3 = {{type|number}} zpass
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMaskSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} mask
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} func
|arg3 = {{type|number}} ref
|arg4 = {{type|number}} mask
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilOpSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} fail
|arg3 = {{type|number}} zfail
|arg4 = {{type|number}} zpass
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= LineWidth & PointSize =

{{LuaCallout
|prefix = gl.
|name = LineWidth
|arg1 = {{type|number}} width
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PointSize
|arg1 = {{type|number}} size
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390
}}

{{LuaCallout
|prefix = gl.
|name = PointSprite
|arg1 = {{type|bool}} enable {{bracket}}
|arg2 = {{type|bool}} coord_replace
|arg3 = {{type|bool}} coord_origin_upper {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = PointParameter
|arg1 = {{type|number}} v1, {{type|number}} v2, {{type|number}} v3 {{bracket}}
|arg2 = {{type|number}} sizeMin
|arg3 = {{type|number}} sizeMax
|arg4 = {{type|number}} sizeFade {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= Textures =

{{LuaCallout
|prefix = gl.
|name = Texture
|arg1 = {{bracket}} {{type|number}} texNum, {{rbracket}} {{type|bool}} enable {{pipe}} {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} loaded
|info = 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.
}}
name may be:

#12
= unitDef 12 buildpic

%34:1
= unitDef 34 s3o tex2 (:0->tex1,:1->tex2)

%-102:0
= featureDef 102 s3o tex1

!56
= lua generated texture 56 (= return value of gl.CreateTexture)

$units
= 3do textureatlas tex1

$units1
= 3do textureatlas tex1

$units2
= 3do textureatlas tex2

$shadow
= shadowmap

$specular
= specular cube map (removed in the latest develop)

$reflection
= reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)

$shading
= ground shading texture

$grass
= grass shading texture

$heightmap
= heightmap (needs HeightMapTexture=1 set in spring config)

$minimap
= minimap texture

$map_reflection
= same as "$reflection" {{new|101.0}}

$sky_reflection
= defined for SSMF maps that have a skyReflectModTex {{new|101.0}}

$detail
= detail texture {{new|101.0}}

$normals
= auto generated normals texture {{new|101.0}}

$ssmf_normals
= SSMF normals texture {{new|101.0}}

$ssmf_specular
= SSMF specular texture {{new|101.0}}

$ssmf_splat_distr
= SSMF splat distribution texture {{new|101.0}}

$ssmf_splat_detail
= SSMF splat detail texture {{new|101.0}}

$ssmf_splat_normals
= SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted

$ssmf_emission
= SSMF emission texture {{new|101.0}}

$ssmf_parallax
= SSMF parallax texture {{new|101.0}}

$info
= currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale

$info_losmap
= los texture (L-view)

$info_mtlmap
= metal map texture (F4-view)

$info_hgtmap
= height map texture (F1-view)

$info_blkmap
= blocking map texture (F2-view)

$map_gbuffer_normtex
= contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$map_gbuffer_difftex
= contains the diffuse texture buffer of the map in view {{new|95}}

$map_gbuffer_spectex
= contains the specular textures of the map in view {{new|95}}

$map_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$map_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$map_gbuffer_zvaltex
= contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use:

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;

$model_gbuffer_normtex
= contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$model_gbuffer_difftex
= contains the diffuse texture buffer of the models in view {{new|95}}

$model_gbuffer_spectex
= contains the specular textures of the models in view {{new|95}}

$model_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$model_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$model_gbuffer_zvaltex
= contains the depth values (z-buffer) of the models in view. {{new|95}}

${opt}:/LuaUI/images/image.png
= 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
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

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)


{{LuaCallout
|prefix = gl.
|name = CreateTexture
|arg1 = {{type|number}} intXSize
|arg2 = {{type|number}} intYSize {{bracket}}
|arg3 = {{type|table}} texProps {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} texture
|info = texProps contains:
}}
<pre>{{type|table}} texProps = {
[target = number,](like GL.TEXTURE_1D,GL.TEXTURE_2D,...)(Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[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!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
}</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteTexture
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteTextureFBO
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = TextureInfo
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} texInfo
|info = texInfo contains:
}}
<pre> {{type|table}} texInfo = {
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().</pre>

{{LuaCallout
|prefix = gl.
|name = MultiTexCoord
|arg1 = {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} {{pipe}} {{type|table}} texCoords = { {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} state
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|bool}} state
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CopyToTexture
|arg1 = {{type|string}} texture
|arg2 = {{type|number}} intXOff
|arg3 = {{type|number}} intYOff
|arg4 = {{type|number}} intX
|arg5 = {{type|number}} intY
|arg6 = {{type|number}} intW
|arg7 = {{type|number}} intH {{bracket}}
|arg8 = {{type|number}} target
|arg9 = {{type|number}} level {{rbracket}}
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = RenderToTexture
|arg1 = {{type|string}} fbotexture
|arg2 = {{type|function}} lua_func
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = GenerateMipmap
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} created
|info = Needs glGenerateMipmapEXT!
}}
<pre>The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")</pre>

{{LuaCallout
|prefix = gl.
|name = UnitTextures
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = UnitShapeTextures
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureTextures
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShapeTextures
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

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


grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index


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

This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.


= 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]]

User:Master-athmos

2021-04-21T16:00:07Z

Master-athmos:

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>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()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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!
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> 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 ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= 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 ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= Text =

{{LuaCallout
|prefix = gl.
|name = Text
|arg1 = {{type|string}} "text"
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} size {{bracket}}
|arg5 = {{type|string}} "options" {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = GetTextWidth
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} width
|info = Width in pixels, with a font size of 1.0.
}}

{{LuaCallout
|prefix = gl.
|name = GetTextHeight
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height, {{type|number}} descender, {{type|number}} numlines
|info = Height in pixels, with a font size of 1.0. Further descriptions here: [[GetTextHeight]]
}}

{{LuaCallout
|prefix = gl.
|name = BeginText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
}}

{{LuaCallout
|prefix = gl.
|name = EndText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Unit/Feature Draw Functions =

{{LuaCallout
|prefix = gl.
|name = Unit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws a unit - on default it uses LOD, with lod<0 it is turned off, else it defines a specific level.
}}

{{LuaCallout
|prefix = gl.
|name = UnitRaw
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Doesn't apply worldspace->unit transformation! only works if rawdraw is true.
}}

{{LuaCallout
|prefix = gl.
|name = UnitShape
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} rawState
|arg4 = {{type|bool}} toScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.
}}

{{LuaCallout
|prefix = gl.
|name = UnitMultMatrix
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = world space -> unit space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMultMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = unit space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPiece
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws the unit piece.
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use gl.UnitPieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = Feature
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureRaw
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShape
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} custom
|arg4 = {{type|bool}} drawScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureMultMatrix
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} world space -> feature space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMultMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} feature space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePiece
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Draws the Feature piece.
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Use gl.FeaturePieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = DrawListAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} listID {{bracket}}
|arg3 = {{type|bool}} midPos
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} degrees
|arg6 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DrawFuncAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} midPos
|arg3 = {{type|function}} {{bracket}}, arg1, ... {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= States (Blending,AlphaTest...) =

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|string}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Mode can be set to:
}}
<pre>"add"
= GL.ONE, GL.ONE

"alpha_add"
= GL.SRC_ALPHA, GL.ONE

"alpha"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"reset"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"color"
= GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA

"modulate"
= GL.DST_COLOR, GL.ZERO

"disable"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA</pre>

{{LuaCallout
|prefix = gl.
|name = BlendEquation
|arg1 = {{type|number}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendFunc
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendEquationSeparate
|arg1 = {{type|number}} modeRGB
|arg2 = {{type|number}} modeAlpha
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = BlendFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcRGB]]
|arg2 = {{type|number}} [Lua_ConstGL#BlendingFactorDest|dstRGB]]
|arg3 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]]
|arg4 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstAlpha]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = AlphaTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 = {{type|number}} threshold
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Culling
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthClamp
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Not always available, needs GL.NV_depth_clamp!
}}

{{LuaCallout
|prefix = gl.
|name = DepthMask
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} masked
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} r, {{type|bool}} g, {{type|bool}} b, {{type|bool}} a
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LogicOp
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#LogicOp|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Fog
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Smoothing
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} point
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} line
|arg3 = {{type|bool}} enable {{pipe}} {{type|number}} polygon
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|number}} intX, {{type|number}} intY, {{type|number}} intW, {{type|number}} intH
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|string}} any
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use springs default line stipple.
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|number}} intFactor
|arg2 = {{type|number}} pattern
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonMode
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} [[Lua_ConstGL#PolygonMode|mode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonOffset
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} factor
|arg2 = {{type|number}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushAttrib
|arg1 = {{bracket}} {{type|number}} [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopAttrib
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Stencil =

{{LuaCallout
|prefix = gl.
|name = StencilTest
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMask
|arg1 = {{type|number}} mask
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilFunc
|arg1 = {{type|number}} func
|arg2 = {{type|number}} ref
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilOp
|arg1 = {{type|number}} fail
|arg2 = {{type|number}} zfail
|arg3 = {{type|number}} zpass
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMaskSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} mask
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} func
|arg3 = {{type|number}} ref
|arg4 = {{type|number}} mask
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilOpSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} fail
|arg3 = {{type|number}} zfail
|arg4 = {{type|number}} zpass
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= LineWidth & PointSize =

{{LuaCallout
|prefix = gl.
|name = LineWidth
|arg1 = {{type|number}} width
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PointSize
|arg1 = {{type|number}} size
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390
}}

{{LuaCallout
|prefix = gl.
|name = PointSprite
|arg1 = {{type|bool}} enable {{bracket}}
|arg2 = {{type|bool}} coord_replace
|arg3 = {{type|bool}} coord_origin_upper {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = PointParameter
|arg1 = {{type|number}} v1, {{type|number}} v2, {{type|number}} v3 {{bracket}}
|arg2 = {{type|number}} sizeMin
|arg3 = {{type|number}} sizeMax
|arg4 = {{type|number}} sizeFade {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= Textures =

{{LuaCallout
|prefix = gl.
|name = Texture
|arg1 = {{bracket}} {{type|number}} texNum, {{rbracket}} {{type|bool}} enable {{pipe}} {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} loaded
|info = 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.
}}
name may be:

#12
= unitDef 12 buildpic

%34:1
= unitDef 34 s3o tex2 (:0->tex1,:1->tex2)

%-102:0
= featureDef 102 s3o tex1

!56
= lua generated texture 56 (= return value of gl.CreateTexture)

$units
= 3do textureatlas tex1

$units1
= 3do textureatlas tex1

$units2
= 3do textureatlas tex2

$shadow
= shadowmap

$specular
= specular cube map (removed in the latest develop)

$reflection
= reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)

$shading
= ground shading texture

$grass
= grass shading texture

$heightmap
= heightmap (needs HeightMapTexture=1 set in spring config)

$minimap
= minimap texture

$map_reflection
= same as "$reflection" {{new|101.0}}

$sky_reflection
= defined for SSMF maps that have a skyReflectModTex {{new|101.0}}

$detail
= detail texture {{new|101.0}}

$normals
= auto generated normals texture {{new|101.0}}

$ssmf_normals
= SSMF normals texture {{new|101.0}}

$ssmf_specular
= SSMF specular texture {{new|101.0}}

$ssmf_splat_distr
= SSMF splat distribution texture {{new|101.0}}

$ssmf_splat_detail
= SSMF splat detail texture {{new|101.0}}

$ssmf_splat_normals
= SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted

$ssmf_emission
= SSMF emission texture {{new|101.0}}

$ssmf_parallax
= SSMF parallax texture {{new|101.0}}

$info
= currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale

$info_losmap
= los texture (L-view)

$info_mtlmap
= metal map texture (F4-view)

$info_hgtmap
= height map texture (F1-view)

$info_blkmap
= blocking map texture (F2-view)

$map_gbuffer_normtex
= contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$map_gbuffer_difftex
= contains the diffuse texture buffer of the map in view {{new|95}}

$map_gbuffer_spectex
= contains the specular textures of the map in view {{new|95}}

$map_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$map_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$map_gbuffer_zvaltex
= contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use:

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;

$model_gbuffer_normtex
= contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$model_gbuffer_difftex
= contains the diffuse texture buffer of the models in view {{new|95}}

$model_gbuffer_spectex
= contains the specular textures of the models in view {{new|95}}

$model_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$model_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$model_gbuffer_zvaltex
= contains the depth values (z-buffer) of the models in view. {{new|95}}

${opt}:/LuaUI/images/image.png
= 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
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

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,...) (Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[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!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
} ]
) -> 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

The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")

'''gl.UnitTextures'''
( number unitID, boolean enable ) -> boolean

'''gl.UnitShapeTextures'''
( number unitDefID, boolean enable ) -> boolean

'''gl.FeatureTextures'''
( number featureID, boolean enable ) -> boolean

'''gl.FeatureShapeTextures'''
( number featureDefID, boolean enable ) -> boolean

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


grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index


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

This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.


= 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]]

User:Master-athmos

2021-04-21T13:22:56Z

Master-athmos:

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>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()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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!
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> 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 ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= 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 ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= Text =

{{LuaCallout
|prefix = gl.
|name = Text
|arg1 = {{type|string}} "text"
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} size {{bracket}}
|arg5 = {{type|string}} "options" {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = GetTextWidth
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} width
|info = Width in pixels, with a font size of 1.0.
}}

{{LuaCallout
|prefix = gl.
|name = GetTextHeight
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height, {{type|number}} descender, {{type|number}} numlines
|info = Height in pixels, with a font size of 1.0. Further descriptions here: [[GetTextHeight]]
}}

{{LuaCallout
|prefix = gl.
|name = BeginText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
}}

{{LuaCallout
|prefix = gl.
|name = EndText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Unit/Feature Draw Functions =

{{LuaCallout
|prefix = gl.
|name = Unit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws a unit - on default it uses LOD, with lod<0 it is turned off, else it defines a specific level.
}}

{{LuaCallout
|prefix = gl.
|name = UnitRaw
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Doesn't apply worldspace->unit transformation! only works if rawdraw is true.
}}

{{LuaCallout
|prefix = gl.
|name = UnitShape
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} rawState
|arg4 = {{type|bool}} toScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.
}}

{{LuaCallout
|prefix = gl.
|name = UnitMultMatrix
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = world space -> unit space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMultMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = unit space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPiece
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws the unit piece.
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use gl.UnitPieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = Feature
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureRaw
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShape
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} custom
|arg4 = {{type|bool}} drawScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureMultMatrix
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} world space -> feature space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMultMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} feature space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePiece
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Draws the Feature piece.
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Use gl.FeaturePieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = DrawListAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} listID {{bracket}}
|arg3 = {{type|bool}} midPos
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} degrees
|arg6 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DrawFuncAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} midPos
|arg3 = {{type|function}} {{bracket}}, arg1, ... {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= States (Blending,AlphaTest...) =

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|string}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Mode can be set to:
}}
<pre>"add"
= GL.ONE, GL.ONE

"alpha_add"
= GL.SRC_ALPHA, GL.ONE

"alpha"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"reset"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"color"
= GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA

"modulate"
= GL.DST_COLOR, GL.ZERO

"disable"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA</pre>

{{LuaCallout
|prefix = gl.
|name = BlendEquation
|arg1 = {{type|number}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendFunc
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendEquationSeparate
|arg1 = {{type|number}} modeRGB
|arg2 = {{type|number}} modeAlpha
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = BlendFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcRGB]]
|arg2 = {{type|number}} [Lua_ConstGL#BlendingFactorDest|dstRGB]]
|arg3 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]]
|arg4 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstAlpha]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = AlphaTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 = {{type|number}} threshold
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Culling
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthClamp
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Not always available, needs GL.NV_depth_clamp!
}}

{{LuaCallout
|prefix = gl.
|name = DepthMask
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} masked
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} r, {{type|bool}} g, {{type|bool}} b, {{type|bool}} a
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LogicOp
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#LogicOp|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Fog
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Smoothing
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} point
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} line
|arg3 = {{type|bool}} enable {{pipe}} {{type|number}} polygon
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|number}} intX, {{type|number}} intY, {{type|number}} intW, {{type|number}} intH
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|string}} any
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use springs default line stipple.
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|number}} intFactor
|arg2 = {{type|number}} pattern
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonMode
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} [[Lua_ConstGL#PolygonMode|mode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonOffset
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} factor
|arg2 = {{type|number}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushAttrib
|arg1 = {{bracket}} {{type|number}} [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopAttrib
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= 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` may be:
|-
| 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 (removed in the latest develop)
|-
| style="color:#55ee99" | $reflection
| style="color:#55ee99" | = reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)
|-
| 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" | $minimap
| style="color:#55ee99" | = minimap texture
|-
| style="color:#55ee99" | $map_reflection
| style="color:#55ee99" | = same as "$reflection" {{new|101.0}}
|-
| style="color:#55ee99" | $sky_reflection
| style="color:#55ee99" | = defined for SSMF maps that have a skyReflectModTex {{new|101.0}}
|-
| style="color:#55ee99" | $detail
| style="color:#55ee99" | = detail texture {{new|101.0}}
|-
| style="color:#55ee99" | $normals
| style="color:#55ee99" | = auto generated normals texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_normals
| style="color:#55ee99" | = SSMF normals texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_specular
| style="color:#55ee99" | = SSMF specular texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_distr
| style="color:#55ee99" | = SSMF splat distribution texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_detail
| style="color:#55ee99" | = SSMF splat detail texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_normals
| style="color:#55ee99" | = SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted
|-
| style="color:#55ee99" | $ssmf_emission
| style="color:#55ee99" | = SSMF emission texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_parallax
| style="color:#55ee99" | = SSMF parallax texture {{new|101.0}}
|-
| style="color:#55ee99" | $info
| style="color:#55ee99" | = currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale
|-
| style="color:#55ee99" | $info_losmap
| style="color:#55ee99" | = los texture (L-view)
|-
| style="color:#55ee99" | $info_mtlmap
| style="color:#55ee99" | = metal map texture (F4-view)
|-
| style="color:#55ee99" | $info_hgtmap
| style="color:#55ee99" | = height map texture (F1-view)
|-
| style="color:#55ee99" | $info_blkmap
| style="color:#55ee99" | = blocking map texture (F2-view)
|-
| style="color:#55ee99" | $map_gbuffer_normtex
| style="color:#55ee99" | = contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_difftex
| style="color:#55ee99" | = contains the diffuse texture buffer of the map in view {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_spectex
| style="color:#55ee99" | = contains the specular textures of the map in view {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_emittex
| style="color:#55ee99" | = for emissive materials (bloom would be the canonical use) {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_misctex
| style="color:#55ee99" | = for arbitrary shader data {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_zvaltex
| style="color:#55ee99" | = contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use: 

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;
|-
| style="color:#55ee99" | $model_gbuffer_normtex
| style="color:#55ee99" | = contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_difftex
| style="color:#55ee99" | = contains the diffuse texture buffer of the models in view {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_spectex
| style="color:#55ee99" | = contains the specular textures of the models in view {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_emittex
| style="color:#55ee99" | = for emissive materials (bloom would be the canonical use) {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_misctex
| style="color:#55ee99" | = for arbitrary shader data {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_zvaltex
| style="color:#55ee99" | = contains the depth values (z-buffer) of the models in view. {{new|95}}
|-
| 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
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

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,...) (Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[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!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
} ]
) -> 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

The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")

'''gl.UnitTextures'''
( number unitID, boolean enable ) -> boolean

'''gl.UnitShapeTextures'''
( number unitDefID, boolean enable ) -> boolean

'''gl.FeatureTextures'''
( number featureID, boolean enable ) -> boolean

'''gl.FeatureShapeTextures'''
( number featureDefID, boolean enable ) -> boolean

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


grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index


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

This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.


= 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]]

User:Master-athmos

2021-04-21T11:09:20Z

Master-athmos:

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>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()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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!
}}
<pre> 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)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> 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 ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= 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 ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= 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, bool rawState, bool toScreen, bool opaque ) -> nil

{{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.

'''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.Feature'''
( number featureID ) -> nil

'''gl.FeatureRaw''' {{new|101.0}}
( number featureID, [ boolean rawdraw, int lod ] ) -> nil

'''gl.FeatureShape'''
( number featureDefID, number teamID, bool custom, bool drawScreen, bool opaque ) -> nil

'''gl.FeatureMultMatrix''' {{new|101.0}} (world space -> feature space)
( number featureID ) -> nil

'''gl.FeaturePieceMultMatrix''' {{new|101.0}} (feature space -> piece space)
( number featureID, int piece ) -> nil

'''gl.FeaturePiece''' {{new|101.0}} (draws the Feature piece)
( number featureID, int piece ) -> nil

'''gl.FeaturePieceMatrix''' {{new|101.0}} (use gl.FeaturePieceMultMatrix instead!)
( number featureID, 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''' {{removed|104.0}}
( (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` may be:
|-
| 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 (removed in the latest develop)
|-
| style="color:#55ee99" | $reflection
| style="color:#55ee99" | = reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)
|-
| 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" | $minimap
| style="color:#55ee99" | = minimap texture
|-
| style="color:#55ee99" | $map_reflection
| style="color:#55ee99" | = same as "$reflection" {{new|101.0}}
|-
| style="color:#55ee99" | $sky_reflection
| style="color:#55ee99" | = defined for SSMF maps that have a skyReflectModTex {{new|101.0}}
|-
| style="color:#55ee99" | $detail
| style="color:#55ee99" | = detail texture {{new|101.0}}
|-
| style="color:#55ee99" | $normals
| style="color:#55ee99" | = auto generated normals texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_normals
| style="color:#55ee99" | = SSMF normals texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_specular
| style="color:#55ee99" | = SSMF specular texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_distr
| style="color:#55ee99" | = SSMF splat distribution texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_detail
| style="color:#55ee99" | = SSMF splat detail texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_normals
| style="color:#55ee99" | = SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted
|-
| style="color:#55ee99" | $ssmf_emission
| style="color:#55ee99" | = SSMF emission texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_parallax
| style="color:#55ee99" | = SSMF parallax texture {{new|101.0}}
|-
| style="color:#55ee99" | $info
| style="color:#55ee99" | = currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale
|-
| style="color:#55ee99" | $info_losmap
| style="color:#55ee99" | = los texture (L-view)
|-
| style="color:#55ee99" | $info_mtlmap
| style="color:#55ee99" | = metal map texture (F4-view)
|-
| style="color:#55ee99" | $info_hgtmap
| style="color:#55ee99" | = height map texture (F1-view)
|-
| style="color:#55ee99" | $info_blkmap
| style="color:#55ee99" | = blocking map texture (F2-view)
|-
| style="color:#55ee99" | $map_gbuffer_normtex
| style="color:#55ee99" | = contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_difftex
| style="color:#55ee99" | = contains the diffuse texture buffer of the map in view {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_spectex
| style="color:#55ee99" | = contains the specular textures of the map in view {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_emittex
| style="color:#55ee99" | = for emissive materials (bloom would be the canonical use) {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_misctex
| style="color:#55ee99" | = for arbitrary shader data {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_zvaltex
| style="color:#55ee99" | = contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use: 

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;
|-
| style="color:#55ee99" | $model_gbuffer_normtex
| style="color:#55ee99" | = contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_difftex
| style="color:#55ee99" | = contains the diffuse texture buffer of the models in view {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_spectex
| style="color:#55ee99" | = contains the specular textures of the models in view {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_emittex
| style="color:#55ee99" | = for emissive materials (bloom would be the canonical use) {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_misctex
| style="color:#55ee99" | = for arbitrary shader data {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_zvaltex
| style="color:#55ee99" | = contains the depth values (z-buffer) of the models in view. {{new|95}}
|-
| 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
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

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,...) (Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[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!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
} ]
) -> 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

The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")

'''gl.UnitTextures'''
( number unitID, boolean enable ) -> boolean

'''gl.UnitShapeTextures'''
( number unitDefID, boolean enable ) -> boolean

'''gl.FeatureTextures'''
( number featureID, boolean enable ) -> boolean

'''gl.FeatureShapeTextures'''
( number featureDefID, boolean enable ) -> boolean

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


grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index


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

This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.


= 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]]

User:Master-athmos

2021-04-21T08:53:51Z

Master-athmos:

User:Master-athmos

2021-04-21T07:59:02Z

Master-athmos:

User:Master-athmos

2021-04-19T21:29:51Z

Master-athmos:

'''Note: After discussion <ref>{{forumlink|topic=28935|title=anything against removal of lualobby?}}</ref> LuaLobby was removed<ref>[https://github.com/spring/spring/commit/05f61e76f7522096faeef2eaa6aaa16bc2b55d71 github commit]</ref> from engine > 91.0''' 

Instead [[LuaSocket]] can be used.
There's an existing LuaSocket implementation available at: https://github.com/gajop/liblobby with docs at: http://gajop.github.io/liblobby/.

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

=Create=
'''Script.CreateLobby'''
( ) -> userdata lobby

=Userdata Functions=
'''lobby:Connect'''
( string url, int port ) -> nil
'''lobby:Disconnect'''
( ) -> nil
'''lobby:Login'''
( string username, string password ) -> nil
'''lobby:Rename'''
( string newname ) -> nil
'''lobby:ChangePass'''
( string oldpassword, string newpassword ) -> nil
'''lobby:Register'''
( string username, string password ) -> nil
'''lobby:ConfirmAggreement'''
( ) -> nil
'''lobby:JoinChannel'''
( string chan_name [,string password] ) -> nil
'''lobby:LeaveChannel'''
( string chan_name ) -> nil
'''lobby:Say'''
( string chan_name, string message ) -> nil
'''lobby:SayEx'''
( string chan_name, string message ) -> nil
'''lobby:SayPrivate'''
( string user_name, string message ) -> nil
'''lobby:StatusUpdate'''
( bool ingame, bool away ) -> nil
'''lobby:Channels'''
( ) -> nil
'''lobby:KickChannelMember'''
( string chan_name, string user_name, string reason) -> nil
'''lobby:ChangeTopic'''
( string chan_name, string topic) -> nil
'''lobby:Poll'''
( ) -> nil

=Userdata Events=
'''lobby.DoneConnecting''' = function(bool sucess, string error_message) 
'''lobby.ServerGreeting''' = function(string server_version, string spring_version, int udp_port, int mode) 
'''lobby.RegisterDenied''' = function(string reason) 
'''lobby.RegisterAccepted''' = function() 
'''lobby.LoginDenied''' = function(string reason) 
'''lobby.LoginEnd''' = function() 
'''lobby.Aggreement''' = function(string text) 
'''lobby.Motd''' = function(string text) 
'''lobby.ServerMessage''' = function(string text) 
'''lobby.ServerMessageBox''' = function(string text, string url) 
'''lobby.AddUser''' = function(string user_name, string country, number cpu) 
'''lobby.RemoveUser''' = function(string user_name) 
'''lobby.UserStatusUpdate''' = function(string user_name, bool away, bool bot, bool ingame, bool moderator, int rank) 
'''lobby.ChannelInfo''' = function(string chan_name, int num_users) 
'''lobby.ChannelInfoEnd''' = function() 
'''lobby.RequestMutelist''' = function(string chan_name) 
'''lobby.Mutelist''' = function(string chan_name, table {"userABC","userXYZ",...}) 
'''lobby.Joined''' = function(string chan_name) 
'''lobby.JoinFailed''' = function(string chan_name, string reason) 
'''lobby.ChannelMember''' = function(string chan_name, string user_name, bool joined) 
'''lobby.ChannelMemberLeft''' = function(string chan_name, string user_name, string reason) 
'''lobby.ChannelMemberKicked''' = function(string chan_name, string user_name, string reason) 
'''lobby.ChannelTopic''' = function(string chan_name, string author, int time, string topic) 
'''lobby.ChannelMessage''' = function(string chan_name, string text) 
'''lobby.Said''' = function(string chan_name, string user_name, string text) 
'''lobby.SaidEx''' = function(string chan_name, string user_name, string text) 
'''lobby.SaidPrivate''' = function(string user_name, string text) 
'''lobby.Disconnected''' = function() 
'''lobby.NetworkError''' = function(string message) 

[[category: Lua]]

<references />

Lua UnsyncedRead

2021-04-19T21:28:05Z

Master-athmos: Updated page with new anchorable templates

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

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{type|number}} mouseZ {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===

{{LuaCallout
|prefix = Spring.
|name = IsGUIHidden
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isHidden
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveShadows
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShadows
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveAdvShading
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWaterMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|string}} mode
|info =
}}
<pre> mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown</pre>

{{LuaCallout
|prefix = Spring.
|name = GetMapDrawMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "normal" {{pipe}} {{type|string}} "height" {{pipe}} {{type|string}} "metal" {{pipe}} {{type|string}} "pathTraversability" {{pipe}} {{type|string}} "los"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawSelectionInfo
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} drawSelectInfo
|info = Returns whether "Selected units" text is displayed.
}}

=== Unit & Feature GUI States ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitLuaDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} unitDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noMinimap
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLuaDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} featureDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

=== Minimap ===

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} sizeX, {{type|number}} sizeY, {{type|bool}} minimized, {{type|bool}} maximized
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapDualScreen
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} false {{pipe}} {{type|string}} "left" {{pipe}} {{type|string}} "right"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAboveMiniMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAbove
|info =
}}

=== (Build-)Menu ===

{{LuaCallout
|prefix = Spring.
|name = GetActiveCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDefaultCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDescs
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDesc
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetCmdDescIndex
|arg1 = {{type|number}} cmdID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActivePage
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pageNum, {{type|number}} maxPages
|info =
}}

=== Build Facing ===

{{LuaCallout
|prefix = Spring.
|name = GetBuildFacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetBuildSpacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spacing
|info =
}}

=== GatherMode & InvertQueueKey ===

{{LuaCallout
|prefix = Spring.
|name = GetGatherMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gatherMode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetInvertQueueKey
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} queueKey
|info =
}}

=== Mouse States ===

{{LuaCallout
|prefix = Spring.
|name = GetMouseState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|bool}} leftPressed, {{type|bool}} middlePressed, {{type|bool}} rightPressed, {{type|bool}} offscreen
|info = {{new|104.0}} Sixth return value offscreen. X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseCursor
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string }} name, {{type|number}} scale
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseStartPosition
|arg1 = {{type|number}} mouseButton
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pressedX, {{type|number}} pressedY, {{type|number}} camPosX, {{type|number}} camPosY, {{type|number}} camPosZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

=== (Hot-)Keys ===

{{LuaCallout
|prefix = Spring.
|name = GetKeyState
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} keyState
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetModKeyState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} alt, {{type|bool}} ctrl, {{type|bool}} meta, {{type|bool}} shift
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPressedKeys
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} code{{rbracket}} = {{type|bool}}, {{bracket}}{{type|string}} name{{rbracket}} = {{type|bool}}, ... }
|info = {{new|99.0}}: {{type|string}} name
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeySymbol
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "keysym1", {{type|string}} "keysym2"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyBindings
|arg1 = {{type|string}} keyset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} keyBindings
|info = keyBindings contains:
}}
<pre>keyBindings = {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActionHotKeys
|arg1 = {{type|string}} action
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} hotKey, ... }
|info =
}}

=== Console ===

{{LuaCallout
|prefix = Spring.
|name = GetLastMessagePositions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { {{type|number}} x, {{type|number}} y, {{type|number}} z }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConsoleBuffer
|arg1 = {{bracket}}{{type|number}} maxLines{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { text = {{type|string}}, priority = {{type|number}} }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCurrentTooltip
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} tooltip
|info =
}}

=== LOS Colors ===

{{LuaCallout
|prefix = Spring.
|name = GetLosViewColors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} always = {r,g,b}, {{type|table}} LOS = {r,g,b}, {{type|table}} radar = {r,g,b}, {{type|table}} jam = {r,g,b}, {{type|table}} radar2 = {r,g,b}
|info = {{new|100}}
}}

== Config ==

{{LuaCallout
|prefix = Spring.
|name = GetConfigParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} configParams
|info = Same information as <code>spring --list-config-vars</code> configParams contains:
}}
<pre>configParams = {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetConfigInt
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configInt
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigFloat
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configFloat
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigString
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} configString
|info =
}}

== FPS & GetDrawFrame ==

{{LuaCallout
|prefix = Spring.
|name = GetFPS
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} fps
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} low_16bit, {{type|number}} high_16bit
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVideoCapturingMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} videoCaptureAllowed
|info = {{new|104.0}}
}}

== Time ==

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = {{new|98.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} finishedLoading, {{type|bool}} loadedFromSave, {{type|bool}} locallyPaused, {{type|bool}} laggingWrtExpectedFromSimtime
|info = {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimeOffset
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} offset
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLastUpdateSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lastUpdateSeconds
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHasLag
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasLag
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = {{new|102.0}} Get a timer for the start of the frame, this should give better results for camera interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = DiffTimers
|arg1 = {{type|timer}} cur
|arg2 = {{type|timer}} ago {{bracket}}
|arg3 = {{type|bool}} inMilliseconds {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info = {{New|95.0}} Optional third argument (boolean) to return dt in milliseconds.
}}

== Rendering ==

{{LuaCallout
|prefix = Spring.
|name = GetMapSquareTexture
|arg1 = {{type|number}} texSqrX, {{type|number}} texSqrY
|arg2 = {{type|number}} texMipLvl
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

== Logging ==

{{LuaCallout
|prefix = Spring.
|name = GetLogSections
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }
|info =
}}

== Misc ==

{{LuaCallout
|prefix = Spring.
|name = GetClipboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} text
|info = {{new|98.0}}
}}

[[category: Lua]]

User:Master-athmos

2021-04-19T21:27:05Z

Master-athmos:

User:Master-athmos

2021-04-19T18:13:50Z

Master-athmos:

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

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{type|number}} mouseZ {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit & Feature GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean
'''Spring.GetFeatureLuaDraw'''
( number featureID ) -> nil | boolean
'''Spring.GetFeatureNoDraw'''
( number featureID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> nil | {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}
'''Spring.GetActiveCmdDesc'''
( number index ) -> nil | {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}
'''Spring.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''

( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed,
boolean offscreen

X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner.

{{new|104.0}} Sixth return value offscreen

For world coordinates see Spring.TraceScreenRay

'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number code] = boolean,
[string name] = boolean, {{new|99.0}}
...
}

'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

=== LOS Colors ===
'''Spring.GetLosViewColors'''

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

== Config ==
'''Spring.GetConfigParams''' same information as <code>spring --list-config-vars</code>
( ) -> table {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}

'''Spring.GetConfigInt'''
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigFloat''' {{new|104.0}}
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigString'''
( string name [, string default ] ) -> nil | string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit
'''Spring.GetVideoCapturingMode''' {{new|104.0}}
( ) -> boolean videoCaptureAllowed

== Time ==
'''Spring.GetGameSpeed''' {{new|98.0}}
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameState''' {{new|105.0}}
( ) -> boolean finishedLoading, boolean loadedFromSave, boolean locallyPaused, boolean laggingWrtExpectedFromSimtime
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.GetFrameTimer''' {{new|102.0}}
( ) -> timer
Get a timer for the start of the frame, this should give better results for camera interpolations.

'''Spring.DiffTimers'''
( timer cur, timer ago, [boolean inMilliseconds]) -> number seconds
{{New|95.0}} optional third argument (boolean) to return dt in milliseconds

== Rendering ==

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

== Logging ==
'''Spring.GetLogSections'''
( ) -> table { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

== Misc ==
'''Spring.GetClipboard''' {{new|98.0}}
( ) -> string text

[[category: Lua]]

User:Master-athmos

2021-04-19T15:24:42Z

Master-athmos:

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

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetReplayLength''' {{new|92.0}}
( ) -> nil | number (in seconds)
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== Game/Menu Name ==
'''Spring.GetGameName''' {{new|104.0}}
( ) -> string name

Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".

'''Spring.GetMenuName''' {{new|104.0}}
( ) -> string name

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] | [number sortType], [bool showPathingPlayers] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}
if pingTime is == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number vFov, number hFov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z

'''Spring.TraceScreenRay'''

( number mouseX, number mouseY [, boolean onlyCoords
[, boolean useMinimap [, boolean includeSky [, boolean ignoreWater [, number D] ] ] ] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

{{new|101.0}} Exended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

to get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")

'''Spring.GetPixelDir''' {{New|95.0}}
( number x, number y ) -> number dirx, number diry, number dirz

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean midPos = false ] ) -> nil | number x, number y, number z
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)
'''Spring.GetUnitSelectionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== Feature ==
'''Spring.GetFeatureSelectionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

== Projectiles ==
'''Spring.GetVisibleProjectiles''' {{New|95.0}}
([ number allyTeamID = -1
[ , boolean addSyncedProjectiles = true
[ , boolean addWeaponProjectiles = true
[ , boolean addPieceProjectiles = true ]]]]
) --> nil | {[1] = projectileID, ...}

== UI ==
'''Spring.GetUICommands''' {{new|101.0}}
( ) -> nil | {
[1] = {
command=string,
description=string,
synced=bool,
cheat=bool,
}, ...
}
Returns a list of available [[UI commands]].

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit & Feature GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean
'''Spring.GetFeatureLuaDraw'''
( number featureID ) -> nil | boolean
'''Spring.GetFeatureNoDraw'''
( number featureID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> nil | {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}
'''Spring.GetActiveCmdDesc'''
( number index ) -> nil | {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}
'''Spring.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''

( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed,
boolean offscreen

X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner.

{{new|104.0}} Sixth return value offscreen

For world coordinates see Spring.TraceScreenRay

'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number code] = boolean,
[string name] = boolean, {{new|99.0}}
...
}

'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

=== LOS Colors ===
'''Spring.GetLosViewColors'''

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

== Config ==
'''Spring.GetConfigParams''' same information as <code>spring --list-config-vars</code>
( ) -> table {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}

'''Spring.GetConfigInt'''
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigFloat''' {{new|104.0}}
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigString'''
( string name [, string default ] ) -> nil | string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit
'''Spring.GetVideoCapturingMode''' {{new|104.0}}
( ) -> boolean videoCaptureAllowed

== Time ==
'''Spring.GetGameSpeed''' {{new|98.0}}
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameState''' {{new|105.0}}
( ) -> boolean finishedLoading, boolean loadedFromSave, boolean locallyPaused, boolean laggingWrtExpectedFromSimtime
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.GetFrameTimer''' {{new|102.0}}
( ) -> timer
Get a timer for the start of the frame, this should give better results for camera interpolations.

'''Spring.DiffTimers'''
( timer cur, timer ago, [boolean inMilliseconds]) -> number seconds
{{New|95.0}} optional third argument (boolean) to return dt in milliseconds

== Rendering ==

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

== Logging ==
'''Spring.GetLogSections'''
( ) -> table { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

== Misc ==
'''Spring.GetClipboard''' {{new|98.0}}
( ) -> string text

[[category: Lua]]

Lua UnsyncedCtrl

2021-04-19T15:24:02Z

Master-athmos: /* Map */

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

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

= UI =

{{LuaCallout
|prefix = Spring.
|name = SetLastMessagePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Ingame Console =

{{LuaCallout
|prefix = Spring.
|name = Echo
|arg1 = {{type|arg1}} {{bracket}}
|arg2 = {{type|arg2}} {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.
}}

{{LuaCallout
|prefix = Spring.
|name = Log
|arg1 = {{type|string}} section
|arg2 = {{type|number}} logLevel {{pipe}} {{type|string}} logLevel
|arg3 = {{type|string}} LogMessage1 {{bracket}}
|arg4 = {{type|string}} LogMessage2{{bracket}}
|arg5 = ... {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>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</pre>

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = {{type|string}} command1 {{bracket}}
|arg2 = {{type|string}} command2 {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = { {{type|string}} command1, {{type|string}} command2, ... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== GUI ==

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|string}} action {{bracket}}
|arg2 = {{type|string}} actionExtra {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|number}} cmdIndex {{bracket}}
|arg2 = {{type|number}} button = 1 {{bracket}}
|arg3 = {{type|bool}} leftClick {{bracket}}
|arg4 = {{type|bool}} rightClick {{bracket}}
|arg5 = {{type|bool}} alt {{bracket}}
|arg6 = {{type|bool}} ctrl {{bracket}}
|arg7 = {{type|bool}} meta {{bracket}}
|arg8 = {{type|bool}} shift {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCmdColorsConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCtrlPanelConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = ForceLayoutUpdate
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Disables the "Selected Units x" box in the GUI.
}}

== Mouse ==

{{LuaCallout
|prefix = Spring.
|name = SetMouseCursor
|arg1 = {{type|string}} cursorName {{bracket}}
|arg2 = {{type|number}} scale {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = WarpMouse
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== LOS Colors ==

{{LuaCallout
|prefix = Spring.
|name = SetLosViewColors
|arg1 = {{type|table}} always = {r,g,b}
|arg2 = {{type|table}} LOS = {r,g,b}
|arg3 = {{type|table}} radar = {r,g,b}
|arg4 = {{type|table}} jam = {r,g,b}
|arg5 = {{type|table}} radar2 = {r,g,b}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. New arguments since 100.0 (radar2 is the inside of radar edge). Arguments for 99.0 and before: 
}}
<pre>( 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</pre>

== SendMessage ==

{{LuaCallout
|prefix = Spring.
|name = SendMessage
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToPlayer
|arg1 = {{type|number}} playerID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToTeam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToAllyTeam
|arg1 = {{type|number}} allyID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToSpectators
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("<PLAYER1> did something") might display as "ProRusher did something"
}}

== Markers ==

{{LuaCallout
|prefix = Spring.
|name = MarkerAddPoint
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|string}} text = "" {{bracket}}
|arg5 = {{type|bool}} localOnly {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerAddLine
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} z1
|arg4 = {{type|number}} x2
|arg5 = {{type|number}} y2
|arg6 = {{type|number}} z2
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerErasePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= Sounds =

{{LuaCallout
|prefix = Spring.
|name = LoadSoundDef
|arg1 = {{type|string}} soundfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
}}

{{LuaCallout
|prefix = Spring.
|name = PlaySoundFile
|arg1 = {{type|string}} soundfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|number}} posx {{bracket}}
|arg4 = {{type|number}} posy {{bracket}}
|arg5 = {{type|number}} posz {{bracket}}
|arg6 = {{type|number}} speedx{{bracket}}
|arg7 = {{type|number}} speedy{{bracket}}
|arg8 = {{type|number}} speedz{{bracket}}
|arg9 = {{type|number}} {{pipe}} {{type|string}} channel {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|nil}} {{pipe}} {{type|bool}} playSound
|info = Possible arguments for channel argument:
}}
<pre> "general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3</pre>

{{LuaCallout
|prefix = Spring.
|name = PlaySoundStream
|arg1 = {{type|string}} oggfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|bool}} enqueue {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Allows to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once.
}}

{{LuaCallout
|prefix = Spring.
|name = StopSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Terminates any SoundStream currently running.
}}

{{LuaCallout
|prefix = Spring.
|name = PauseSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSoundStreamVolume
|arg1 = {{type|number}} volume
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

{{LuaCallout
|prefix = Spring.
|name = SendLuaUIMsg
|arg1 = {{type|string}} message
|arg2 = {{type|string}} mode
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Possible modes are: "s"/"specs" & "a"/"allies"
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaGaiaMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaRulesMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= AI =

{{LuaCallout
|prefix = Spring.
|name = SendSkirmishAIMessage
|arg1 = {{type|number}} aiTeam
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} ai_processed, { {{bracket|1}} = {{type|string}} response1, ... }
|info = {{new|83.0}} Note there is nothing in this table due to "limitations" of the AI interface.
}}

= Units =

{{LuaCallout
|prefix = Spring.
|name = SetUnitLeaveTracks
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} leavetracks
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

== Unit Selection ==

{{LuaCallout
|prefix = Spring.
|name = SelectUnitMap
|arg1 = { {{bracket|unitID}} = anything, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbacket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SelectUnitArray
|arg1 = { {{bracket|1}} = unitID1, {{bracket|2}} = unitID2, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbacket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} drawSelectionInfo
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit Group ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} groupID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== Give Order ==

{{LuaCallout
|prefix = Spring.
|name = GiveOrder
|arg1 = {{type|number}} cmdID
|arg2 = {{type|table}} params = {number, etc...}
|arg3 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. Gives order to all selected units.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|1}} = {{type|number}} unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|11}} = {{type|number}} unitID, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} } {{bracket}}
|arg3 = {{type|bool}} pairwise {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. "pairwise" paramater ({{new|89.0}}) is used to send multiple units a single individual command.
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildFacing
|arg1 = {{type|number}} facing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildSpacing
|arg1 = {{type|number}} spacing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit NoDraw,NoSelect,NoMinimap ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noMinimap
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= Features =

{{LuaCallout
|prefix = Spring.
|name = SetFeatureFade
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} allow
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Control whether a feature will fade or not when zoomed out.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= Developers =

{{LuaCallout
|prefix = Spring.
|name = SetDrawSky
|arg1 = {{type|bool}} drawSky
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawWater
|arg1 = {{type|bool}} drawWater
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGround
|arg1 = {{type|bool}} drawGround
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetWaterParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 104.0 no longer needs cheating enabled. 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 contains:
}}
<pre> 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,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetMapRenderingParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Allows to change map rendering params at runtime. "Params" table contains:
}}
<pre> 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,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetLogSectionFilterLevel
|arg1 = {{type|string}} sectionName
|arg2 = {{type|string}} {{pipe}} {{type|number}} logLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}} See [[infolog.txt]] for possible log sections.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGroundDeferred
|arg1 = {{type|bool}} drawGroundDeferred {{bracket}}
|arg2 = {{type|bool}} drawGroundForward {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawModelsDeferred
|arg1 = {{type|bool}} drawUnitsDeferred
|arg2 = {{type|bool}} drawFeaturesDeferred {{bracket}}
|arg3 = {{type|bool}} drawUnitsForward {{bracket}}
|arg4 = {{type|bool}} drawFeaturesForward {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingMode
|arg1 = {{type|bool}} allowCaptureMode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingTimeOffset
|arg1 = {{type|bool}} timeOffset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= GUI =

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|1}} = unitID, ... } {{bracket}}
|arg2 = {{type|bool}} false
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|unitID}} = arg1, ... }
|arg2 = {{type|bool}} true
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamColor
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AssignMouseCursor
|arg1 = {{type|string}} cmdName
|arg2 = {{type|string}} iconFileName {{bracket}}
|arg3 = {{type|bool}} overwrite = true {{bracket}}
|arg4 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Changes/creates the cursor of a single CursorCmd. Note, that iconFileName is not the full filename instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack
}}

{{LuaCallout
|prefix = Spring.
|name = ReplaceMouseCursor
|arg1 = {{type|string}} oldFileName
|arg2 = {{type|string}} newFileName {{bracket}}
|arg3 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Mass replace all occurrence of the cursor in all CursorCmds.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} cmdID_cloneIcon {{pipe}} {{type|string}} iconname
|arg3 = {{type|table}} RGBA = { {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a } {{bracket}}
|arg4 = {{type|bool}} showArea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|nil}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

= Sharing =

{{LuaCallout
|prefix = Spring.
|name = SetShareLevel
|arg1 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg2 = {{type|number}} shareLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only! Note: shareLevel is 0<= x <= 1 .
}}

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

or

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= UnitDef RadarIcons & BuildPics =

{{LuaCallout
|prefix = Spring.
|name = AddUnitIcon
|arg1 = {{type|string}} iconName
|arg2 = {{type|string}} texFile {{bracket}}
|arg3 = {{type|number}} size {{bracket}}
|arg4 = {{type|number}} dist {{bracket}}
|arg5 = {{type|bool}} radAdjust {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} added
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FreeUnitIcon
|arg1 = {{type|string}} iconName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} freed
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefIcon
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} iconName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets radar icon.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefImage
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} luaTexture {{pipe}} {{type|string}} texFile
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets buildpic.
}}

= Camera =

{{LuaCallout
|prefix = Spring.
|name = SetCameraState
|arg1 = {{type|table}} camState
|arg2 = {{type|number}} camTime
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stateSet
|info = 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. [https://springrts.com/mantis/view.php?id=5028#c15491] Also see #5028]
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraTarget
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} transTime {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraOffset
|arg1 = {{type|number}} px = 0 {{bracket}}
|arg2 = {{type|number}} py = 0 {{bracket}}
|arg3 = {{type|number}} pz = 0 {{bracket}}
|arg4 = {{type|number}} tx = 0 {{bracket}}
|arg5 = {{type|number}} ty = 0 {{bracket}}
|arg6 = {{type|number}} tz = 0 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= (Virtual-)FileSystem =

{{LuaCallout
|prefix = Spring.
|name = ExtractModArchiveFile
|arg1 = {{type|string}} modfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} extracted
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = CreateDir
|arg1 = {{type|string}} path
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} dirCreated
|info = Needs ModUICtrl.
}}

The full VFS API is available at [[Lua_VFS|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.

{{LuaCallout
|prefix = Spring.
|name = SetConfigInt
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigFloat
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigString
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= World Primitives =
outdated! use opengl api instead!

{{LuaCallout
|prefix = Spring.
|name = AddWorldIcon
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldText
|arg1 = {{type|string}} text
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldUnit
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 = {{type|number}} team
|arg4 = {{type|number}} facing
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = SetSunManualControl
|arg1 = {{type|bool}} setManualControl
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunParameters
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 = {{type|number}} dist
|arg5 = {{type|number}} startTime
|arg6 = {{type|number}} orbitTime
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunDirection
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunLighting
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following sun lighting parameters:
}}
<pre> {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} })</pre>

{{LuaCallout
|prefix = Spring.
|name = SetAtmosphere
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following atmosphere parameters:
}}
<pre> fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})</pre>

= Misc =

{{LuaCallout
|prefix = Spring.
|name = Reload
|arg1 = {{type|string}} startscript
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|99.0}} start-script is the CONTENT of the [[script.txt]] spring should use to start.
}}

{{LuaCallout
|prefix = Spring.
|name = Restart
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|0.79}} If this call returns, something went wrong. ''commandline_args'' are commandline arguments passed to spring executable.
}}

{{LuaCallout
|prefix = Spring.
|name = Start
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|102.0}} 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''.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMIcon
|arg1 = {{type|string}} iconFileName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMCaption
|arg1 = {{type|string}} title {{bracket}}
|arg2 = {{type|string}} titleShort = title {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearWatchDogTimer
|arg1 = {{bracket}} {{type|string}} threadName = main {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetClipboard
|arg1 = {{type|string}} text
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}}
}}

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

{{LuaCallout
|prefix = Spring.
|name = PreloadUnitDefModel
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = PreloadFetureDefModel
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

{{LuaCallout
|prefix = Spring.
|name = AddMapLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = AddModelLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateMapLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateModelLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetModelLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

'''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 =

{{LuaCallout
|prefix = Spring.
|name = SetSkyBoxTexture
|arg1 = {{type|string}} texName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShadingTexture
|arg1 = {{type|string}} texType
|arg2 = {{type|string}} texName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|101.0}}
}}

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTexture
|arg1 = {{type|number}} texSqrX
|arg2 = {{type|number}} texSqrY
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShader
|arg1 = {{type|number}} standardShaderID
|arg2 = {{type|number}} deferredShaderID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

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

[[category: Lua]]

Lua UnsyncedCtrl

2021-04-19T15:23:15Z

Master-athmos: Updated page with new anchorable templates

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

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

= UI =

{{LuaCallout
|prefix = Spring.
|name = SetLastMessagePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Ingame Console =

{{LuaCallout
|prefix = Spring.
|name = Echo
|arg1 = {{type|arg1}} {{bracket}}
|arg2 = {{type|arg2}} {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.
}}

{{LuaCallout
|prefix = Spring.
|name = Log
|arg1 = {{type|string}} section
|arg2 = {{type|number}} logLevel {{pipe}} {{type|string}} logLevel
|arg3 = {{type|string}} LogMessage1 {{bracket}}
|arg4 = {{type|string}} LogMessage2{{bracket}}
|arg5 = ... {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>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</pre>

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = {{type|string}} command1 {{bracket}}
|arg2 = {{type|string}} command2 {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = { {{type|string}} command1, {{type|string}} command2, ... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== GUI ==

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|string}} action {{bracket}}
|arg2 = {{type|string}} actionExtra {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|number}} cmdIndex {{bracket}}
|arg2 = {{type|number}} button = 1 {{bracket}}
|arg3 = {{type|bool}} leftClick {{bracket}}
|arg4 = {{type|bool}} rightClick {{bracket}}
|arg5 = {{type|bool}} alt {{bracket}}
|arg6 = {{type|bool}} ctrl {{bracket}}
|arg7 = {{type|bool}} meta {{bracket}}
|arg8 = {{type|bool}} shift {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCmdColorsConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCtrlPanelConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = ForceLayoutUpdate
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Disables the "Selected Units x" box in the GUI.
}}

== Mouse ==

{{LuaCallout
|prefix = Spring.
|name = SetMouseCursor
|arg1 = {{type|string}} cursorName {{bracket}}
|arg2 = {{type|number}} scale {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = WarpMouse
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== LOS Colors ==

{{LuaCallout
|prefix = Spring.
|name = SetLosViewColors
|arg1 = {{type|table}} always = {r,g,b}
|arg2 = {{type|table}} LOS = {r,g,b}
|arg3 = {{type|table}} radar = {r,g,b}
|arg4 = {{type|table}} jam = {r,g,b}
|arg5 = {{type|table}} radar2 = {r,g,b}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. New arguments since 100.0 (radar2 is the inside of radar edge). Arguments for 99.0 and before: 
}}
<pre>( 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</pre>

== SendMessage ==

{{LuaCallout
|prefix = Spring.
|name = SendMessage
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToPlayer
|arg1 = {{type|number}} playerID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToTeam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToAllyTeam
|arg1 = {{type|number}} allyID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToSpectators
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("<PLAYER1> did something") might display as "ProRusher did something"
}}

== Markers ==

{{LuaCallout
|prefix = Spring.
|name = MarkerAddPoint
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|string}} text = "" {{bracket}}
|arg5 = {{type|bool}} localOnly {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerAddLine
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} z1
|arg4 = {{type|number}} x2
|arg5 = {{type|number}} y2
|arg6 = {{type|number}} z2
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerErasePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= Sounds =

{{LuaCallout
|prefix = Spring.
|name = LoadSoundDef
|arg1 = {{type|string}} soundfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
}}

{{LuaCallout
|prefix = Spring.
|name = PlaySoundFile
|arg1 = {{type|string}} soundfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|number}} posx {{bracket}}
|arg4 = {{type|number}} posy {{bracket}}
|arg5 = {{type|number}} posz {{bracket}}
|arg6 = {{type|number}} speedx{{bracket}}
|arg7 = {{type|number}} speedy{{bracket}}
|arg8 = {{type|number}} speedz{{bracket}}
|arg9 = {{type|number}} {{pipe}} {{type|string}} channel {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|nil}} {{pipe}} {{type|bool}} playSound
|info = Possible arguments for channel argument:
}}
<pre> "general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3</pre>

{{LuaCallout
|prefix = Spring.
|name = PlaySoundStream
|arg1 = {{type|string}} oggfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|bool}} enqueue {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Allows to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once.
}}

{{LuaCallout
|prefix = Spring.
|name = StopSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Terminates any SoundStream currently running.
}}

{{LuaCallout
|prefix = Spring.
|name = PauseSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSoundStreamVolume
|arg1 = {{type|number}} volume
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

{{LuaCallout
|prefix = Spring.
|name = SendLuaUIMsg
|arg1 = {{type|string}} message
|arg2 = {{type|string}} mode
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Possible modes are: "s"/"specs" & "a"/"allies"
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaGaiaMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaRulesMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= AI =

{{LuaCallout
|prefix = Spring.
|name = SendSkirmishAIMessage
|arg1 = {{type|number}} aiTeam
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} ai_processed, { {{bracket|1}} = {{type|string}} response1, ... }
|info = {{new|83.0}} Note there is nothing in this table due to "limitations" of the AI interface.
}}

= Units =

{{LuaCallout
|prefix = Spring.
|name = SetUnitLeaveTracks
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} leavetracks
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

== Unit Selection ==

{{LuaCallout
|prefix = Spring.
|name = SelectUnitMap
|arg1 = { {{bracket|unitID}} = anything, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbacket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SelectUnitArray
|arg1 = { {{bracket|1}} = unitID1, {{bracket|2}} = unitID2, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbacket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} drawSelectionInfo
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit Group ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} groupID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== Give Order ==

{{LuaCallout
|prefix = Spring.
|name = GiveOrder
|arg1 = {{type|number}} cmdID
|arg2 = {{type|table}} params = {number, etc...}
|arg3 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. Gives order to all selected units.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|1}} = {{type|number}} unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|11}} = {{type|number}} unitID, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} } {{bracket}}
|arg3 = {{type|bool}} pairwise {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. "pairwise" paramater ({{new|89.0}}) is used to send multiple units a single individual command.
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildFacing
|arg1 = {{type|number}} facing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildSpacing
|arg1 = {{type|number}} spacing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit NoDraw,NoSelect,NoMinimap ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noMinimap
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= Features =

{{LuaCallout
|prefix = Spring.
|name = SetFeatureFade
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} allow
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Control whether a feature will fade or not when zoomed out.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= Developers =

{{LuaCallout
|prefix = Spring.
|name = SetDrawSky
|arg1 = {{type|bool}} drawSky
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawWater
|arg1 = {{type|bool}} drawWater
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGround
|arg1 = {{type|bool}} drawGround
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetWaterParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 104.0 no longer needs cheating enabled. 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 contains:
}}
<pre> 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,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetMapRenderingParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Allows to change map rendering params at runtime. "Params" table contains:
}}
<pre> 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,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetLogSectionFilterLevel
|arg1 = {{type|string}} sectionName
|arg2 = {{type|string}} {{pipe}} {{type|number}} logLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}} See [[infolog.txt]] for possible log sections.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGroundDeferred
|arg1 = {{type|bool}} drawGroundDeferred {{bracket}}
|arg2 = {{type|bool}} drawGroundForward {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawModelsDeferred
|arg1 = {{type|bool}} drawUnitsDeferred
|arg2 = {{type|bool}} drawFeaturesDeferred {{bracket}}
|arg3 = {{type|bool}} drawUnitsForward {{bracket}}
|arg4 = {{type|bool}} drawFeaturesForward {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingMode
|arg1 = {{type|bool}} allowCaptureMode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingTimeOffset
|arg1 = {{type|bool}} timeOffset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= GUI =

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|1}} = unitID, ... } {{bracket}}
|arg2 = {{type|bool}} false
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|unitID}} = arg1, ... }
|arg2 = {{type|bool}} true
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamColor
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AssignMouseCursor
|arg1 = {{type|string}} cmdName
|arg2 = {{type|string}} iconFileName {{bracket}}
|arg3 = {{type|bool}} overwrite = true {{bracket}}
|arg4 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Changes/creates the cursor of a single CursorCmd. Note, that iconFileName is not the full filename instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack
}}

{{LuaCallout
|prefix = Spring.
|name = ReplaceMouseCursor
|arg1 = {{type|string}} oldFileName
|arg2 = {{type|string}} newFileName {{bracket}}
|arg3 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Mass replace all occurrence of the cursor in all CursorCmds.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} cmdID_cloneIcon {{pipe}} {{type|string}} iconname
|arg3 = {{type|table}} RGBA = { {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a } {{bracket}}
|arg4 = {{type|bool}} showArea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|nil}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

= Sharing =

{{LuaCallout
|prefix = Spring.
|name = SetShareLevel
|arg1 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg2 = {{type|number}} shareLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only! Note: shareLevel is 0<= x <= 1 .
}}

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

or

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= UnitDef RadarIcons & BuildPics =

{{LuaCallout
|prefix = Spring.
|name = AddUnitIcon
|arg1 = {{type|string}} iconName
|arg2 = {{type|string}} texFile {{bracket}}
|arg3 = {{type|number}} size {{bracket}}
|arg4 = {{type|number}} dist {{bracket}}
|arg5 = {{type|bool}} radAdjust {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} added
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FreeUnitIcon
|arg1 = {{type|string}} iconName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} freed
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefIcon
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} iconName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets radar icon.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefImage
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} luaTexture {{pipe}} {{type|string}} texFile
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets buildpic.
}}

= Camera =

{{LuaCallout
|prefix = Spring.
|name = SetCameraState
|arg1 = {{type|table}} camState
|arg2 = {{type|number}} camTime
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stateSet
|info = 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. [https://springrts.com/mantis/view.php?id=5028#c15491] Also see #5028]
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraTarget
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} transTime {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraOffset
|arg1 = {{type|number}} px = 0 {{bracket}}
|arg2 = {{type|number}} py = 0 {{bracket}}
|arg3 = {{type|number}} pz = 0 {{bracket}}
|arg4 = {{type|number}} tx = 0 {{bracket}}
|arg5 = {{type|number}} ty = 0 {{bracket}}
|arg6 = {{type|number}} tz = 0 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= (Virtual-)FileSystem =

{{LuaCallout
|prefix = Spring.
|name = ExtractModArchiveFile
|arg1 = {{type|string}} modfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} extracted
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = CreateDir
|arg1 = {{type|string}} path
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} dirCreated
|info = Needs ModUICtrl.
}}

The full VFS API is available at [[Lua_VFS|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.

{{LuaCallout
|prefix = Spring.
|name = SetConfigInt
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigFloat
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigString
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= World Primitives =
outdated! use opengl api instead!

{{LuaCallout
|prefix = Spring.
|name = AddWorldIcon
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldText
|arg1 = {{type|string}} text
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldUnit
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 = {{type|number}} team
|arg4 = {{type|number}} facing
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = SetSunManualControl
|arg1 = {{type|bool}} setManualControl
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunParameters
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 = {{type|number}} dist
|arg5 = {{type|number}} startTime
|arg6 = {{type|number}} orbitTime
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunDirection
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunLighting
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following sun lighting parameters:
}}
<pre> {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} })</pre>

{{LuaCallout
|prefix = Spring.
|name = SetAtmosphere
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following atmosphere parameters:
}}
<pre> fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})</pre>

= Misc =

{{LuaCallout
|prefix = Spring.
|name = Reload
|arg1 = {{type|string}} startscript
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|99.0}} start-script is the CONTENT of the [[script.txt]] spring should use to start.
}}

{{LuaCallout
|prefix = Spring.
|name = Restart
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|0.79}} If this call returns, something went wrong. ''commandline_args'' are commandline arguments passed to spring executable.
}}

{{LuaCallout
|prefix = Spring.
|name = Start
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|102.0}} 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''.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMIcon
|arg1 = {{type|string}} iconFileName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMCaption
|arg1 = {{type|string}} title {{bracket}}
|arg2 = {{type|string}} titleShort = title {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearWatchDogTimer
|arg1 = {{bracket}} {{type|string}} threadName = main {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetClipboard
|arg1 = {{type|string}} text
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}}
}}

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

{{LuaCallout
|prefix = Spring.
|name = PreloadUnitDefModel
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = PreloadFetureDefModel
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

{{LuaCallout
|prefix = Spring.
|name = AddMapLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = AddModelLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateMapLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateModelLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetModelLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

'''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 =

{{LuaCallout
|prefix = Spring.
|name = SetSkyBoxTexture
|arg1 = {{type|string}} texName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShadingTexture
|arg1 = {{type|string}} texType
|arg2 = {{type|string}} texName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|101.0}}
}}

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTexture
|arg1 = {{type|number}} texSqrX
|arg2 = {{type|number}} texSqrY
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShader
|arg1 = {{type|number}} standardShaderID
|arg2 = {{type|number}} deferredShaderID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{101.0}}
}}

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

[[category: Lua]]

User:Master-athmos

2021-04-19T15:21:41Z

Master-athmos:

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

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

= UI =

{{LuaCallout
|prefix = Spring.
|name = SetLastMessagePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Ingame Console =

{{LuaCallout
|prefix = Spring.
|name = Echo
|arg1 = {{type|arg1}} {{bracket}}
|arg2 = {{type|arg2}} {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.
}}

{{LuaCallout
|prefix = Spring.
|name = Log
|arg1 = {{type|string}} section
|arg2 = {{type|number}} logLevel {{pipe}} {{type|string}} logLevel
|arg3 = {{type|string}} LogMessage1 {{bracket}}
|arg4 = {{type|string}} LogMessage2{{bracket}}
|arg5 = ... {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>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</pre>

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = {{type|string}} command1 {{bracket}}
|arg2 = {{type|string}} command2 {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = { {{type|string}} command1, {{type|string}} command2, ... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== GUI ==

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|string}} action {{bracket}}
|arg2 = {{type|string}} actionExtra {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|number}} cmdIndex {{bracket}}
|arg2 = {{type|number}} button = 1 {{bracket}}
|arg3 = {{type|bool}} leftClick {{bracket}}
|arg4 = {{type|bool}} rightClick {{bracket}}
|arg5 = {{type|bool}} alt {{bracket}}
|arg6 = {{type|bool}} ctrl {{bracket}}
|arg7 = {{type|bool}} meta {{bracket}}
|arg8 = {{type|bool}} shift {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCmdColorsConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCtrlPanelConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = ForceLayoutUpdate
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Disables the "Selected Units x" box in the GUI.
}}

== Mouse ==

{{LuaCallout
|prefix = Spring.
|name = SetMouseCursor
|arg1 = {{type|string}} cursorName {{bracket}}
|arg2 = {{type|number}} scale {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = WarpMouse
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== LOS Colors ==

{{LuaCallout
|prefix = Spring.
|name = SetLosViewColors
|arg1 = {{type|table}} always = {r,g,b}
|arg2 = {{type|table}} LOS = {r,g,b}
|arg3 = {{type|table}} radar = {r,g,b}
|arg4 = {{type|table}} jam = {r,g,b}
|arg5 = {{type|table}} radar2 = {r,g,b}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. New arguments since 100.0 (radar2 is the inside of radar edge). Arguments for 99.0 and before: 
}}
<pre>( 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</pre>

== SendMessage ==

{{LuaCallout
|prefix = Spring.
|name = SendMessage
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToPlayer
|arg1 = {{type|number}} playerID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToTeam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToAllyTeam
|arg1 = {{type|number}} allyID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToSpectators
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("<PLAYER1> did something") might display as "ProRusher did something"
}}

== Markers ==

{{LuaCallout
|prefix = Spring.
|name = MarkerAddPoint
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|string}} text = "" {{bracket}}
|arg5 = {{type|bool}} localOnly {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerAddLine
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} z1
|arg4 = {{type|number}} x2
|arg5 = {{type|number}} y2
|arg6 = {{type|number}} z2
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerErasePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= Sounds =

{{LuaCallout
|prefix = Spring.
|name = LoadSoundDef
|arg1 = {{type|string}} soundfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
}}

{{LuaCallout
|prefix = Spring.
|name = PlaySoundFile
|arg1 = {{type|string}} soundfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|number}} posx {{bracket}}
|arg4 = {{type|number}} posy {{bracket}}
|arg5 = {{type|number}} posz {{bracket}}
|arg6 = {{type|number}} speedx{{bracket}}
|arg7 = {{type|number}} speedy{{bracket}}
|arg8 = {{type|number}} speedz{{bracket}}
|arg9 = {{type|number}} {{pipe}} {{type|string}} channel {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|nil}} {{pipe}} {{type|bool}} playSound
|info = Possible arguments for channel argument:
}}
<pre> "general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3</pre>

{{LuaCallout
|prefix = Spring.
|name = PlaySoundStream
|arg1 = {{type|string}} oggfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|bool}} enqueue {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Allows to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once.
}}

{{LuaCallout
|prefix = Spring.
|name = StopSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Terminates any SoundStream currently running.
}}

{{LuaCallout
|prefix = Spring.
|name = PauseSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSoundStreamVolume
|arg1 = {{type|number}} volume
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

{{LuaCallout
|prefix = Spring.
|name = SendLuaUIMsg
|arg1 = {{type|string}} message
|arg2 = {{type|string}} mode
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Possible modes are: "s"/"specs" & "a"/"allies"
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaGaiaMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaRulesMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= AI =

{{LuaCallout
|prefix = Spring.
|name = SendSkirmishAIMessage
|arg1 = {{type|number}} aiTeam
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} ai_processed, { {{bracket|1}} = {{type|string}} response1, ... }
|info = {{new|83.0}} Note there is nothing in this table due to "limitations" of the AI interface.
}}

= Units =

{{LuaCallout
|prefix = Spring.
|name = SetUnitLeaveTracks
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} leavetracks
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

== Unit Selection ==

{{LuaCallout
|prefix = Spring.
|name = SelectUnitMap
|arg1 = { {{bracket|unitID}} = anything, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbacket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SelectUnitArray
|arg1 = { {{bracket|1}} = unitID1, {{bracket|2}} = unitID2, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbacket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} drawSelectionInfo
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit Group ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} groupID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== Give Order ==

{{LuaCallout
|prefix = Spring.
|name = GiveOrder
|arg1 = {{type|number}} cmdID
|arg2 = {{type|table}} params = {number, etc...}
|arg3 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. Gives order to all selected units.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|1}} = {{type|number}} unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|11}} = {{type|number}} unitID, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} } {{bracket}}
|arg3 = {{type|bool}} pairwise {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. "pairwise" paramater ({{new|89.0}}) is used to send multiple units a single individual command.
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildFacing
|arg1 = {{type|number}} facing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildSpacing
|arg1 = {{type|number}} spacing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit NoDraw,NoSelect,NoMinimap ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noMinimap
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= Features =

{{LuaCallout
|prefix = Spring.
|name = SetFeatureFade
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} allow
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Control whether a feature will fade or not when zoomed out.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= Developers =

{{LuaCallout
|prefix = Spring.
|name = SetDrawSky
|arg1 = {{type|bool}} drawSky
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawWater
|arg1 = {{type|bool}} drawWater
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGround
|arg1 = {{type|bool}} drawGround
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetWaterParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 104.0 no longer needs cheating enabled. 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 contains:
}}
<pre> 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,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetMapRenderingParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Allows to change map rendering params at runtime. "Params" table contains:
}}
<pre> 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,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetLogSectionFilterLevel
|arg1 = {{type|string}} sectionName
|arg2 = {{type|string}} {{pipe}} {{type|number}} logLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}} See [[infolog.txt]] for possible log sections.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGroundDeferred
|arg1 = {{type|bool}} drawGroundDeferred {{bracket}}
|arg2 = {{type|bool}} drawGroundForward {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawModelsDeferred
|arg1 = {{type|bool}} drawUnitsDeferred
|arg2 = {{type|bool}} drawFeaturesDeferred {{bracket}}
|arg3 = {{type|bool}} drawUnitsForward {{bracket}}
|arg4 = {{type|bool}} drawFeaturesForward {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingMode
|arg1 = {{type|bool}} allowCaptureMode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingTimeOffset
|arg1 = {{type|bool}} timeOffset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= GUI =

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|1}} = unitID, ... } {{bracket}}
|arg2 = {{type|bool}} false
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|unitID}} = arg1, ... }
|arg2 = {{type|bool}} true
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamColor
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AssignMouseCursor
|arg1 = {{type|string}} cmdName
|arg2 = {{type|string}} iconFileName {{bracket}}
|arg3 = {{type|bool}} overwrite = true {{bracket}}
|arg4 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Changes/creates the cursor of a single CursorCmd. Note, that iconFileName is not the full filename instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack
}}

{{LuaCallout
|prefix = Spring.
|name = ReplaceMouseCursor
|arg1 = {{type|string}} oldFileName
|arg2 = {{type|string}} newFileName {{bracket}}
|arg3 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Mass replace all occurrence of the cursor in all CursorCmds.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} cmdID_cloneIcon {{pipe}} {{type|string}} iconname
|arg3 = {{type|table}} RGBA = { {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a } {{bracket}}
|arg4 = {{type|bool}} showArea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|nil}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

= Sharing =

{{LuaCallout
|prefix = Spring.
|name = SetShareLevel
|arg1 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg2 = {{type|number}} shareLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only! Note: shareLevel is 0<= x <= 1 .
}}

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

or

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= UnitDef RadarIcons & BuildPics =

{{LuaCallout
|prefix = Spring.
|name = AddUnitIcon
|arg1 = {{type|string}} iconName
|arg2 = {{type|string}} texFile {{bracket}}
|arg3 = {{type|number}} size {{bracket}}
|arg4 = {{type|number}} dist {{bracket}}
|arg5 = {{type|bool}} radAdjust {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} added
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FreeUnitIcon
|arg1 = {{type|string}} iconName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} freed
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefIcon
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} iconName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets radar icon.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefImage
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} luaTexture {{pipe}} {{type|string}} texFile
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets buildpic.
}}

= Camera =

{{LuaCallout
|prefix = Spring.
|name = SetCameraState
|arg1 = {{type|table}} camState
|arg2 = {{type|number}} camTime
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stateSet
|info = 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. [https://springrts.com/mantis/view.php?id=5028#c15491] Also see #5028]
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraTarget
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} transTime {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraOffset
|arg1 = {{type|number}} px = 0 {{bracket}}
|arg2 = {{type|number}} py = 0 {{bracket}}
|arg3 = {{type|number}} pz = 0 {{bracket}}
|arg4 = {{type|number}} tx = 0 {{bracket}}
|arg5 = {{type|number}} ty = 0 {{bracket}}
|arg6 = {{type|number}} tz = 0 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= (Virtual-)FileSystem =

{{LuaCallout
|prefix = Spring.
|name = ExtractModArchiveFile
|arg1 = {{type|string}} modfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} extracted
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = CreateDir
|arg1 = {{type|string}} path
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} dirCreated
|info = Needs ModUICtrl.
}}

The full VFS API is available at [[Lua_VFS|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.

{{LuaCallout
|prefix = Spring.
|name = SetConfigInt
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigFloat
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigString
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= World Primitives =
outdated! use opengl api instead!

{{LuaCallout
|prefix = Spring.
|name = AddWorldIcon
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldText
|arg1 = {{type|string}} text
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldUnit
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 = {{type|number}} team
|arg4 = {{type|number}} facing
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = SetSunManualControl
|arg1 = {{type|bool}} setManualControl
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunParameters
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 = {{type|number}} dist
|arg5 = {{type|number}} startTime
|arg6 = {{type|number}} orbitTime
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunDirection
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunLighting
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following sun lighting parameters:
}}
<pre> {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} })</pre>

{{LuaCallout
|prefix = Spring.
|name = SetAtmosphere
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following atmosphere parameters:
}}
<pre> fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})</pre>

= Misc =

{{LuaCallout
|prefix = Spring.
|name = Reload
|arg1 = {{type|string}} startscript
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|99.0}} start-script is the CONTENT of the [[script.txt]] spring should use to start.
}}

{{LuaCallout
|prefix = Spring.
|name = Restart
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|0.79}} If this call returns, something went wrong. ''commandline_args'' are commandline arguments passed to spring executable.
}}

{{LuaCallout
|prefix = Spring.
|name = Start
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|102.0}} 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''.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMIcon
|arg1 = {{type|string}} iconFileName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMCaption
|arg1 = {{type|string}} title {{bracket}}
|arg2 = {{type|string}} titleShort = title {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearWatchDogTimer
|arg1 = {{bracket}} {{type|string}} threadName = main {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetClipboard
|arg1 = {{type|string}} text
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}}
}}

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

{{LuaCallout
|prefix = Spring.
|name = PreloadUnitDefModel
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = PreloadFetureDefModel
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

{{LuaCallout
|prefix = Spring.
|name = AddMapLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = AddModelLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateMapLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateModelLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetModelLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

'''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 =

{{LuaCallout
|prefix = Spring.
|name = SetSkyBoxTexture
|arg1 = {{type|string}} texName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShadingTexture
|arg1 = {{type|string}} texType
|arg2 = {{type|string}} texName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|101.0}}
}}

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTexture
|arg1 = {{type|number}} texSqrX
|arg2 = {{type|number}} texSqrY
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShader
|arg1 = {{type|number}} standardShaderID
|arg2 = {{type|number}} deferredShaderID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{101.0}}
}}

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

[[category: Lua]]

User:Master-athmos

2021-04-18T18:28:10Z

Master-athmos:

User:Master-athmos

2021-04-07T21:57:32Z

Master-athmos:

Lua SyncedCtrl

2021-04-07T21:54:57Z

Master-athmos: /* Unit Control */

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

= Game End =

{{LuaCallout
|prefix = Spring.
|name = KillTeam
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.
}}

{{LuaCallout
|prefix = Spring.
|name = GameOver
|arg1 = {{type|number}} allyTeamID1
|arg2 = {{type|number}} allyTeamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed.
}}

= RulesParams =
String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.

{{LuaCallout
|prefix = Spring.
|name = SetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible keys for the losAccess table are:
`private` : only readable by the ally (default)
`allied` : readable by ally + ingame allied
`inlos` : readable if the unit is in LOS
`inradar` : readable if the unit is in AirLOS
`public` : readable by all
note: if one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with `inradar=true` even if the param has `inlos=false`)
note2: all GameRulesParam are public, TeamRulesParams can just be `private`,`allied` and/or `public`
note3: You can read RulesParams from '''any''' Lua enviroments! With those losAccess policies you can limit their access.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = New since 102.0. See above for further documentation of losAccess.
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}

{{LuaCallout
|prefix = Spring.
|name = SetGameRulesParam
|arg1 = {{type|string}} paramName
|arg2 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg3 = {{type|table}} losAccess {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}

= Resources =

{{LuaCallout
|prefix = Spring.
|name = AddTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Adds metal or energy resources to the specified team.
}}

{{LuaCallout
|prefix = Spring.
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Consumes metal and/or energy resources of the specified team.
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are: "m" = metal "e" = energy "ms" = metal storage "es" = energy storage 
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamShareLevel
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.
}}

{{LuaCallout
|prefix = Spring.
|name = ShareTeamResource
|arg1 = {{type|number}} teamID_src
|arg2 = {{type|number}} teamID_recv
|arg3 = {{type|string}} "metal" {{pipe}} "energy"
|arg4 = {{type|number}} amount
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Transfers resources between two teams.
}}

= Teams =

{{LuaCallout
|prefix = Spring.
|name = SetAlly
|arg1 = {{type|number}} firstAllyTeamID
|arg2 = {{type|number}} secondAllyTeamID
|arg3 = {{type|bool}} ally
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}} Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
}}

{{LuaCallout
|prefix = Spring.
|name = AssignPlayerToTeam
|arg1 = {{type|number}} playerID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}} Assigns a player to a team.
}}

{{LuaCallout
|prefix = Spring.
|name = SetGlobalLos
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|bool}} globallos
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Changes access to global line of sight for a team and its allies.
}}

= Unit Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateUnit
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number }} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|string}} "facing" {{pipe}} {{type|number }} facing
|arg6 = {{type|number}} teamID {{bracket}}
|arg7 = {{type|bool}} build = false {{bracket}}
|arg8 = {{type|bool}} flattenGround = true {{bracket}}
|arg9 = {{type|number}} builderID {{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|number}} unitID {{pipe}} {{type|nil}} (meaning unit was not created)
|info = Offmap positions are clamped! Use MoveCtrl to move to such positions. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 3 If build is true, the unit is created in "being built" state with buildProgress = 0 unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with a specific ID.
}}

{{LuaCallout
|prefix = Spring.
|name = DestroyUnit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} selfd = false {{bracket}}
|arg3 = {{type|bool}} reclaimed = false {{bracket}}
|arg4 = {{type|number}} attackerID {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = selfd := Makes the unit act like it self-destructed. reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
}}

{{LuaCallout
|prefix = Spring.
|name = TransferUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} newTeamID {{bracket}}
|arg3 = {{type|bool}} given = true {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If given=false, the unit is captured.
}}

== Unit Control ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCosts
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} buildTime = {{type|number}} amount {{rbracket}}
|arg3 = {{bracket}} metalCost = {{type|number}} amount {{rbracket}}
|arg4 = {{bracket}} energyCost = {{type|number}} amount {{rbracket}} }
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "tooltip"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} health {{pipe}} { {{bracket}} health = {{type|number}} health {{rbracket}}
|arg3 = {{bracket}} capture = {{type|number}} capture {{rbracket}}
|arg4 = {{bracket}} paralyze = {{type|number}} paralyze {{rbracket}}
|arg5 = {{bracket}} build = {{type|number}} build {{rbracket}} }
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxHealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitDamage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} damage {{bracket}}
|arg3 = {{type|number}} paralyze = 0 {{bracket}}
|arg4 = {{type|number}} attackerID = -1 {{bracket}}
|arg5 = {{type|number}} weaponID = -1 {{bracket}}
|arg6 = {{type|number}} impulse_x {{bracket}}
|arg7 = {{type|number}} impulse_y {{bracket}}
|arg8 = {{type|number}} impulse_z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = The number in the paralyze parameter equals to the paralyzetime in the WeaponDef.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitStockpile
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} stockpile {{bracket}}
|arg3 = {{type|number}} buildPercent {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} experience
|arg3 = {{type|number}} buildPercent
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} fuel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCrashing
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} crashing
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} teamID {{bracket}}
|arg3 = {{type|bool}} isRoot {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} neutral
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x {{pipe}} {{type|nil}}
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|bool}} dgun = false {{bracket}}
|arg6 = {{type|bool}} userTarget = false {{bracket}}
|arg7 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} enemyUnitID {{pipe}} {{type|nil}} {{bracket}}
|arg3 = {{type|bool}} dgun = false {{bracket}}
|arg4 = {{type|bool}} userTarget = false {{bracket}}
|arg5 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Defines a unit's target. Nil as 2nd argument drops the unit's current target. UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxRange
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMass
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} isblocking
|arg3 = {{type|bool}} isSolidObjectCollidable
|arg4 = {{type|bool}} isProjectileCollidable
|arg5 = {{type|bool}} isRaySegmentCollidable
|arg6 = {{type|bool}} crushable
|arg7 = {{type|bool}} blockEnemyPushing
|arg8 = {{type|bool}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}} Changed parameters.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} depth {{bracket}}
|arg3 = {{type|number}} range {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Parameter "depth" corresponds to metal extraction rate. Range value is similar to "extractsMetal" in unitDefs.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitBuildSpeed
|arg1 = {{type|number}} builderID
|arg2 = {{type|number}} buildSpeed {{bracket}}
|arg3 = {{type|number}} repairSpeed {{bracket}}
|arg4 = {{type|number}} reclaimSpeed{{bracket}}
|arg5 = {{type|number}} resurrectSpeed {{bracket}}
|arg6 = {{type|number}} captureSpeed {{bracket}}
|arg7 = {{type|number}} terraformSpeed {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNanoPieces
|arg1 = {{type|number}} builderID
|arg2 = {{type|table}} pieces
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|92.0}} This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!
}}

{{LuaCallout
|prefix = Spring.
|name = UnitAttach
|arg1 = {{type|number}} transporterID
|arg2 = {{type|number}} passengerID
|arg3 = {{type|number}} pieceNum
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitDetach
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitDetachFromAir
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLoadingTransport
|arg1 = {{type|number}} passengerID
|arg2 = {{type|number}} transportID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Disables collisions between the two units to allow colvol intersection during the approach.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceParent
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} AlteredPiece
|arg3 = {{type|number}} ParentPiece
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 = {{type|table }} matrix
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Sets the local (i.e. parent-relative) matrix of the given piece if any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed (matrix should be an array of 16 floats, but is not otherwise sanity-checked).
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} armored {{bracket}}
|arg3 = {{type|number}} armorMultiple {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = armorMultiple new in version 0.83.x
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{bracket}}
|arg3 = {{type|bool}} enabled {{bracket}}
|arg4 = {{type|number}} power {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode"
|arg3 = {{type|number }} mode
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "moveFactor"
|arg3 = {{type|number }} factor
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "minDamage"
|arg3 = {{type|number }} minDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "maxDamage"
|arg3 = {{type|number }} maxDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 = {{type|number }} x
|arg4 = {{type|number }} y
|arg5 = {{type|number }} z
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table }} states
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string }} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
Format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,] (*)
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["salvoLeft" = number value,]
["nextSalvo" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.


{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
Format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}


{{LuaCallout
|prefix = Spring.
|name = SetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};


{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ {{bracket}}
|arg6 = {{type|number}} volumeType {{bracket}}
|arg7 = {{type|number}} primaryAxis {{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} travel {{bracket}}
|arg3 = {{type|number}} travelPeriod {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMoveGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{bracket}}
|arg4 = {{type|number}} moveSpeed {{bracket}}
|arg5 = {{type|bool}} moveRaw {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used by default commands to get in build-, attackrange etc. {{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLandGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Used in conjunction with {{name|Spring.UnitAttach}} et al. to re-implement old airbase & fuel system in Lua.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearUnitGoal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|102.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Drag new in version 95.0
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|bool}} alwaysAboveSea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|90.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} velX
|arg3 = {{type|number}} velY
|arg4 = {{type|number}} velZ
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} rotX
|arg3 = {{type|number}} rotY
|arg4 = {{type|number}} rotZ
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitImpulse
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} decayRate {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitSeismicPing
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pingSize
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveBuildingDecal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMidAndAimPos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}} mpx, mpy, mpz: New middle position of unit apx, apy, apz: New position that enemies aim at on this unit relative: Are the new coordinates relative to world or unit coordinates?
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitRadiusAndHeight
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitWeaponFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UnitWeaponHoldFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit LOS ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCloak
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} cloaked {{pipe}} {{type|number}} scriptCloak {{bracket}}
|arg3 = {{type|bool}} decloakAbs {{pipe}} {{type|number}} decloakDistance {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If the 2nd argument is a number, the value works like this: 1:=normal cloak 2:=for free cloak (cost no E) 3:=for free + no decloaking (except the unit is stunned) 4:=ultimative cloak (no ecost, no decloaking, no stunned decloak) The decloak distance is only changed: - if the 3th argument is a number or a boolean. - if the boolean is false it takes the default decloak distance for that unitdef, - if the boolean is true it takes the absolute value of it.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSonarStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} sonarStealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} stealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitAlwaysVisible
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLosMask
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = The 3rd argument is either the bit-and combination of the following numbers: LOS_INLOS = 1 LOS_INRADAR = 2 LOS_PREVLOS = 4 LOS_CONTRADAR = 8 or a table of the following form: losTypes = { [los = boolean,] [radar = boolean,] [prevLos = boolean,] [contRadar = boolean] }
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLosState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for more info on the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} type
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newRadius
|info = Type can be: "los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"
}}

{{LuaCallout
|prefix = Spring.
|name = SetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|number }} allyteamErrorSize {{bracket}}
|arg3 = {{type|number}} baseErrorSize {{bracket}}
|arg4 = {{type|number}} baseErrorMult {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z,
|arg3 = {{type|number}} posErrorDelta.x, {{type|number}} number posErrorDelta.y, {{type|number}} posErrorDelta.z {{bracket}}
|arg4 = {{type|number}} nextPosErrorUpdate {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

== Unit Resourcing ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = { res = {{type|number}} amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are: "[u{{pipe}}c][u{{pipe}}m][m{{pipe}}e]" unconditional {{pipe}} conditional use {{pipe}} make metal {{pipe}} energy
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} "m" {{pipe}} "metal" {{pipe}} "e" {{pipe}} "energy" {{rbracket}} = amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} metal
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|97.0}} See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

= Feature Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateFeature
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number}} featureDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|number}} heading {{bracket}}
|arg4 = {{type|number}} AllyTeamID {{bracket}}
|arg5 = {{type|number}} featureID {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} featureID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = DestroyFeature
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TransferFeature
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Feature Control ==

{{LuaCallout
|prefix = Spring.
|name = SetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} health
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} metal
|arg3 = {{type|number}} energy {{bracket}}
|arg4 = {{type|number}} reclaimTime {{bracket}}
|arg5 = {{type|number}} reclaimLeft {{rbracket}}{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureReclaim
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} reclaimLeft
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} unitDefID {{pipe}} {{type|string}} unitDefName {{bracket}}
|arg3 = {{type|number}} facing {{pipe}} {{type|string}} "facing" {{bracket}}
|arg4 = {{type|number}} progress {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing {{value|-1}}. The level of progress can now be set via the additional 4th param. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 3
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeaturePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} snapToGround {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureVelocity
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMoveCtrl
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} enable {{bracket}}
|arg3 = {{type|number*}} args {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this callout to control feature movement. The number* arguments are parsed as follows and all optional: If enable is true: {{bracket}}, velVector(x,y,z) -- initial velocity for feature {{bracket}}, accVector(x,y,z) -- acceleration added every frame{{rbracket}}{{rbracket}} If enable is false: {{bracket}}, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl {{bracket}}, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl {{bracket}}, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl{{rbracket}}{{rbracket}}{{rbracket}} As of spring 103.0 it is necessary to unlock feature movement on x,z axis before changing feature physics. For example use "Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)" to unlock all movement prior to making SetFeatureVelocity calls.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureAlwaysVisible
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg6 = {{type|number}} Axis
|arg7 = {{type|number}} volumeType {{bracket}}
|arg8 = {{type|number}} primaryAxis {{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMidAndAimPos
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}} Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRadiusAndHeight
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 = {{type|boolean}} isBlocking
|arg3 = {{type|boolean}} isSolidObjectCollidable
|arg4 = {{type|boolean}} isProjectileCollidable
|arg5 = {{type|boolean}} isRaySegmentCollidable
|arg6 = {{type|boolean}} crushable
|arg7 = {{type|boolean}} blockEnemyPushing
|arg8 = {{type|boolean}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}} Changed parameters.
}}

= Lua to COB =

{{LuaCallout
|prefix = Spring.
|name = CallCOBScript
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} funcID {{pipe}} {{type|string}} funcName
|arg3 = {{type|number}} retArgs
|arg4 = COBArg1
|arg5 = COBArg2
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} returnValue, {{type|number}} retArg1, {{type|number}} retArg2, ...
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBScriptID
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} funcName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} funcID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCOBValue
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} splitData=false {{rbracket}}
|arg3 = {{type|number}} COBValue {{bracket}}
|arg4 = {{type|number}} param1 {{bracket}}
|arg5 = {{type|number}} param2 {{bracket}}
|arg6 = {{type|number}} param3 {{bracket}}
|arg7 = {{type|number}} param4 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|number}} result {{pipe}} {{type|number}} result1, {{type|number}} result2
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCOBValue
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} COBValue
|arg3 = {{type|number}} param1 {{bracket}}
|arg4 = {{type|number}} param2 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

= Give Order =

Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) 
See [[Lua CMDs]] for relevant constants.

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = unitMap = { {{bracket}}unitID{{rbracket}} = example, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = unitMap = { {{bracket}}{{type|number}} unitID{{rbracket}} = example, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = {{type|number}} unitID, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

=Ground=
== Grass ==

{{LuaCallout
|prefix = Spring.
|name = AddGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Heightmap ==
Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is [[Lua_ConstGame|Game.squareSize]].

{{LuaCallout
|prefix = Spring.
|name = LevelHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AdjustHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = (heightmap[x][z] += height;)
}}

{{LuaCallout
|prefix = Spring.
|name = RevertHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetHeightMapFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}
Example code:<pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)</pre>

{{LuaCallout
|prefix = Spring.
|name = AddHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetHeightMapFunc()
}}

{{LuaCallout
|prefix = Spring.
|name = SetHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetHeightMapFunc(). The terraform argument is a scaling factor: 
If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.
}}

{{LuaCallout
|prefix = Spring.
|name = LevelSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AdjustSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RevertSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSmoothMeshFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetSmoothMeshFunc().
}}

{{LuaCallout
|prefix = Spring.
|name = SetSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetSmoothMeshFunc().
}}

== TerrainTypes ==

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTerrainType
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} newType
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} oldType
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTerrainTypeData
|arg1 = {{type|number}} typeIndex {{bracket}}
|arg2 = {{type|number}} speedTanks = nil {{bracket}}
|arg3 = {{type|number}} speedKBOts = nil {{bracket}}
|arg4 = {{type|number}} speedHovers = nil {{bracket}}
|arg5 = {{type|number}} speedShips = nil {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSquareBuildingMask
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|103.0}}
}}

See also {{xtaglink|Gamedev:UnitDefs|buildingMask}} unitdef tag.

== MetalAmount ==

{{LuaCallout
|prefix = Spring.
|name = SetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} metalAmount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} x & z coords are in worldspace/16. metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
}}

= Command Descriptions =
Doesn't work in unsynced code! 

{{LuaCallout
|prefix = Spring.
|name = EditUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdDescID
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ queueing = boolean ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}</pre>
{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).

{{LuaCallout
|prefix = Spring.
|name = InsertUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Other =

{{LuaCallout
|prefix = Spring.
|name = SetNoPause
|arg1 = {{type|bool}} noPause
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitToFeature
|arg1 = {{type|bool}} tofeature
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = An ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag) [http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
}}

{{LuaCallout
|prefix = Spring.
|name = SetExperienceGrade
|arg1 = {{type|number}} expGrade {{bracket}}
|arg2 = {{type|number}} ExpPowerScale {{bracket}}
|arg3 = {{type|number}} ExpHealthScale {{bracket}}
|arg4 = {{type|number}} ExpReloadScale {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = expGrade defines how often UnitExperience() will be called. Prior to 104.0 it is based on the following equation: (int) {{bracket}}exp/(exp+1){{rbracket}} / expGrade Post 104.0 it is the raw change.
}}

{{LuaCallout
|prefix = Spring.
|name = SpawnExplosion
|arg1 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg2 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg3 = {{type|table}} explosionParams
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}
<pre>Possible keys of explosionParams are:
weaponDef = number,
owner = number,
hitUnit = number,
hitFeature = number,
craterAreaOfEffect = number,
damageAreaOfEffect = number,
edgeEffectiveness = number,
explosionSpeed = number,
gfxMod = number,
impactOnly = boolean,
ignoreOwner = boolean,
damageGround = boolean

Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
The weapondefID is only used for visuals and for passing into callins like UnitDamaged.</pre>

{{LuaCallout
|prefix = Spring.
|name = SpawnCEG
|arg1 = {{type|string}} "cegname" | {{type|number}} cegID
|arg2 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg3 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg4 = {{type|number}} radius = 0
|arg5 = {{type|number}} damage = 0
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success, {{type|number}} cegID
|info = cegID new in 95.0.
}}

{{LuaCallout
|prefix = Spring.
|name = SpawnSFX
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} sfxID
|arg3 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg4 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg5 = {{type|number}} radius = 0
|arg6 = {{type|number}} damage = 0 {{bracket}}
|arg7 = {{type|bool}} absolute {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}}
}}

Equal to the [[Animation-LuaCallouts#Effects|UnitScript versions of EmitSFX]], but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

= Projectiles =

{{LuaCallout
|prefix = Spring.
|name = SpawnProjectile
|arg1 = {{type|number}} weaponDefID
|arg2 = {{type|table}} projectileParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} projectileID
|info =
}}
<pre>Possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string</pre>

{{LuaCallout
|prefix = Spring.
|name = DeleteProjectile
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Silently removes projectiles (no explosion).
}}

Pre 95.0:
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|string}} targetTypeStr {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}

Post 95.0:
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|number}} targetType {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}
<pre>targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = SetProjectileIgnoreTrackingError
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} ignore
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileIsIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileMoveControl
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Disables engine movecontrol, so lua can fully control the physics.
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectilePosition
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} posX = 0 {{bracket}}
|arg3 = {{type|number}} posY = 0 {{bracket}}
|arg4 = {{type|number}} posZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileVelocity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} velX = 0 {{bracket}}
|arg3 = {{type|number}} velY = 0 {{bracket}}
|arg4 = {{type|number}} velZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileCollision
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileGravity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} grav = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinAngle
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinAngle = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} speed = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinVec
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinX = 0 {{bracket}}
|arg3 = {{type|number}} spinY = 0 {{bracket}}
|arg4 = {{type|number}} spinZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileCEG
|arg1 = {{type|number}} projectileID
|arg2 = {{type|string}} ceg_name
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetPieceProjectileParams
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} explosionFlags {{bracket}}
|arg3 = {{type|number}} spinAngle {{bracket}}
|arg4 = {{type|number}} spinSpeed {{bracket}}
|arg5 = {{type|number}} spinVector.x {{bracket}}
|arg6 = {{type|number}} spinVector.y {{bracket}}
|arg7 = {{type|number}} spinVector.z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileAlwaysVisible
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
<pre>Format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}</pre>

[[category: Lua]]

Lua SyncedCtrl

2021-04-06T08:08:01Z

Master-athmos: /* Projectiles */

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

= Game End =

{{LuaCallout
|prefix = Spring.
|name = KillTeam
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.
}}

{{LuaCallout
|prefix = Spring.
|name = GameOver
|arg1 = {{type|number}} allyTeamID1
|arg2 = {{type|number}} allyTeamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed.
}}

= RulesParams =
String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.

{{LuaCallout
|prefix = Spring.
|name = SetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible keys for the losAccess table are:
`private` : only readable by the ally (default)
`allied` : readable by ally + ingame allied
`inlos` : readable if the unit is in LOS
`inradar` : readable if the unit is in AirLOS
`public` : readable by all
note: if one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with `inradar=true` even if the param has `inlos=false`)
note2: all GameRulesParam are public, TeamRulesParams can just be `private`,`allied` and/or `public`
note3: You can read RulesParams from '''any''' Lua enviroments! With those losAccess policies you can limit their access.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = New since 102.0. See above for further documentation of losAccess.
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}

{{LuaCallout
|prefix = Spring.
|name = SetGameRulesParam
|arg1 = {{type|string}} paramName
|arg2 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg3 = {{type|table}} losAccess {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}

= Resources =

{{LuaCallout
|prefix = Spring.
|name = AddTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Adds metal or energy resources to the specified team.
}}

{{LuaCallout
|prefix = Spring.
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Consumes metal and/or energy resources of the specified team.
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are: "m" = metal "e" = energy "ms" = metal storage "es" = energy storage 
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamShareLevel
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.
}}

{{LuaCallout
|prefix = Spring.
|name = ShareTeamResource
|arg1 = {{type|number}} teamID_src
|arg2 = {{type|number}} teamID_recv
|arg3 = {{type|string}} "metal" {{pipe}} "energy"
|arg4 = {{type|number}} amount
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Transfers resources between two teams.
}}

= Teams =

{{LuaCallout
|prefix = Spring.
|name = SetAlly
|arg1 = {{type|number}} firstAllyTeamID
|arg2 = {{type|number}} secondAllyTeamID
|arg3 = {{type|bool}} ally
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}} Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
}}

{{LuaCallout
|prefix = Spring.
|name = AssignPlayerToTeam
|arg1 = {{type|number}} playerID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}} Assigns a player to a team.
}}

{{LuaCallout
|prefix = Spring.
|name = SetGlobalLos
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|bool}} globallos
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Changes access to global line of sight for a team and its allies.
}}

= Unit Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateUnit
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number }} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|string}} "facing" {{pipe}} {{type|number }} facing
|arg6 = {{type|number}} teamID {{bracket}}
|arg7 = {{type|bool}} build = false {{bracket}}
|arg8 = {{type|bool}} flattenGround = true {{bracket}}
|arg9 = {{type|number}} builderID {{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|number}} unitID {{pipe}} {{type|nil}} (meaning unit was not created)
|info = Offmap positions are clamped! Use MoveCtrl to move to such positions. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 3 If build is true, the unit is created in "being built" state with buildProgress = 0 unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with a specific ID.
}}

{{LuaCallout
|prefix = Spring.
|name = DestroyUnit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} selfd = false {{bracket}}
|arg3 = {{type|bool}} reclaimed = false {{bracket}}
|arg4 = {{type|number}} attackerID {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = selfd := Makes the unit act like it self-destructed. reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
}}

{{LuaCallout
|prefix = Spring.
|name = TransferUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} newTeamID {{bracket}}
|arg3 = {{type|bool}} given = true {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If given=false, the unit is captured.
}}

== Unit Control ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCosts
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} buildTime = {{type|number}} amount {{rbracket}}
|arg3 = {{bracket}} metalCost = {{type|number}} amount {{rbracket}}
|arg4 = {{bracket}} energyCost = {{type|number}} amount {{rbracket}} }
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "tooltip"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} health {{pipe}} { {{bracket}} health = {{type|number}} health {{rbracket}}
|arg3 = {{bracket}} capture = {{type|number}} capture {{rbracket}}
|arg4 = {{bracket}} paralyze = {{type|number}} paralyze {{rbracket}}
|arg5 = {{bracket}} build = {{type|number}} build {{rbracket}} }
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxHealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitDamage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} damage {{bracket}}
|arg3 = {{type|number}} paralyze = 0 {{bracket}}
|arg4 = {{type|number}} attackerID = -1 {{bracket}}
|arg5 = {{type|number}} weaponID = -1 {{bracket}}
|arg6 = {{type|number}} impulse_x {{bracket}}
|arg7 = {{type|number}} impulse_y {{bracket}}
|arg8 = {{type|number}} impulse_z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = The number in the paralyze parameter equals to the paralyzetime in the WeaponDef.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitStockpile
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} stockpile {{bracket}}
|arg3 = {{type|number}} buildPercent {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} experience
|arg3 = {{type|number}} buildPercent
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} fuel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCrashing
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} crashing
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} teamID {{bracket}}
|arg3 = {{type|bool}} isRoot {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} neutral
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x {{pipe}} {{type|nil}}
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|bool}} dgun = false {{bracket}}
|arg6 = {{type|bool}} userTarget = false {{bracket}}
|arg7 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} enemyUnitID {{pipe}} {{type|nil}} {{bracket}}
|arg3 = {{type|bool}} dgun = false {{bracket}}
|arg4 = {{type|bool}} userTarget = false {{bracket}}
|arg5 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Defines a unit's target. Nil as 2nd argument drops the unit's current target. UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxRange
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMass
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} isblocking
|arg3 = {{type|bool}} isSolidObjectCollidable
|arg4 = {{type|bool}} isProjectileCollidable
|arg5 = {{type|bool}} isRaySegmentCollidable
|arg6 = {{type|bool}} crushable
|arg7 = {{type|bool}} blockEnemyPushing
|arg8 = {{type|bool}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}} Changed parameters.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} depth {{bracket}}
|arg3 = {{type|number}} range {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Parameter "depth" corresponds to metal extraction rate. Range value is similar to "extractsMetal" in unitDefs.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitBuildSpeed
|arg1 = {{type|number}} builderID
|arg2 = {{type|number}} buildSpeed {{bracket}}
|arg3 = {{type|number}} repairSpeed {{bracket}}
|arg4 = {{type|number}} reclaimSpeed{{bracket}}
|arg5 = {{type|number}} resurrectSpeed {{bracket}}
|arg6 = {{type|number}} captureSpeed {{bracket}}
|arg7 = {{type|number}} terraformSpeed {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNanoPieces
|arg1 = {{type|number}} builderID
|arg2 = {{type|table}} pieces {{bracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|92.0}} This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!
}}

{{LuaCallout
|prefix = Spring.
|name = UnitAttach
|arg1 = {{type|number}} transporterID
|arg2 = {{type|number}} passengerID
|arg3 = {{type|number}} pieceNum
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitDetach
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitDetachFromAir
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLoadingTransport
|arg1 = {{type|number}} passengerID
|arg2 = {{type|number}} transportID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Disables collisions between the two units to allow colvol intersection during the approach.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceParent
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} AlteredPiece
|arg3 = {{type|number}} ParentPiece
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 = {{type|table }} matrix
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Sets the local (i.e. parent-relative) matrix of the given piece if any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed (matrix should be an array of 16 floats, but is not otherwise sanity-checked).
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} armored {{bracket}}
|arg3 = {{type|number}} armorMultiple {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = armorMultiple new in version 0.83.x
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{bracket}}
|arg3 = {{type|bool}} enabled {{bracket}}
|arg4 = {{type|number}} power {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode"
|arg3 = {{type|number }} mode
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "moveFactor"
|arg3 = {{type|number }} factor
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "minDamage"
|arg3 = {{type|number }} minDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "maxDamage"
|arg3 = {{type|number }} maxDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 = {{type|number }} x
|arg4 = {{type|number }} y
|arg5 = {{type|number }} z
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table }} states
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string }} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
Format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,] (*)
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["salvoLeft" = number value,]
["nextSalvo" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.


{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
Format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}


{{LuaCallout
|prefix = Spring.
|name = SetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};


{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ {{bracket}}
|arg6 = {{type|number}} volumeType {{bracket}}
|arg7 = {{type|number}} primaryAxis {{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} travel {{bracket}}
|arg3 = {{type|number}} travelPeriod {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMoveGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{bracket}}
|arg4 = {{type|number}} moveSpeed {{bracket}}
|arg5 = {{type|bool}} moveRaw {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used by default commands to get in build-, attackrange etc. {{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLandGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Used in conjunction with {{name|Spring.UnitAttach}} et al. to re-implement old airbase & fuel system in Lua.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearUnitGoal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|102.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Drag new in version 95.0
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|bool}} alwaysAboveSea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|90.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} velX
|arg3 = {{type|number}} velY
|arg4 = {{type|number}} velZ
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} rotX
|arg3 = {{type|number}} rotY
|arg4 = {{type|number}} rotZ
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitImpulse
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} decayRate {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitSeismicPing
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pingSize
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveBuildingDecal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMidAndAimPos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}} mpx, mpy, mpz: New middle position of unit apx, apy, apz: New position that enemies aim at on this unit relative: Are the new coordinates relative to world or unit coordinates?
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitRadiusAndHeight
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitWeaponFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UnitWeaponHoldFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit LOS ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCloak
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} cloaked {{pipe}} {{type|number}} scriptCloak {{bracket}}
|arg3 = {{type|bool}} decloakAbs {{pipe}} {{type|number}} decloakDistance {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If the 2nd argument is a number, the value works like this: 1:=normal cloak 2:=for free cloak (cost no E) 3:=for free + no decloaking (except the unit is stunned) 4:=ultimative cloak (no ecost, no decloaking, no stunned decloak) The decloak distance is only changed: - if the 3th argument is a number or a boolean. - if the boolean is false it takes the default decloak distance for that unitdef, - if the boolean is true it takes the absolute value of it.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSonarStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} sonarStealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} stealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitAlwaysVisible
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLosMask
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = The 3rd argument is either the bit-and combination of the following numbers: LOS_INLOS = 1 LOS_INRADAR = 2 LOS_PREVLOS = 4 LOS_CONTRADAR = 8 or a table of the following form: losTypes = { [los = boolean,] [radar = boolean,] [prevLos = boolean,] [contRadar = boolean] }
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLosState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for more info on the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} type
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newRadius
|info = Type can be: "los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"
}}

{{LuaCallout
|prefix = Spring.
|name = SetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|number }} allyteamErrorSize {{bracket}}
|arg3 = {{type|number}} baseErrorSize {{bracket}}
|arg4 = {{type|number}} baseErrorMult {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z,
|arg3 = {{type|number}} posErrorDelta.x, {{type|number}} number posErrorDelta.y, {{type|number}} posErrorDelta.z {{bracket}}
|arg4 = {{type|number}} nextPosErrorUpdate {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

== Unit Resourcing ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = { res = {{type|number}} amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are: "[u{{pipe}}c][u{{pipe}}m][m{{pipe}}e]" unconditional {{pipe}} conditional use {{pipe}} make metal {{pipe}} energy
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} "m" {{pipe}} "metal" {{pipe}} "e" {{pipe}} "energy" {{rbracket}} = amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} metal
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|97.0}} See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

= Feature Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateFeature
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number}} featureDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|number}} heading {{bracket}}
|arg4 = {{type|number}} AllyTeamID {{bracket}}
|arg5 = {{type|number}} featureID {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} featureID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = DestroyFeature
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TransferFeature
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Feature Control ==

{{LuaCallout
|prefix = Spring.
|name = SetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} health
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} metal
|arg3 = {{type|number}} energy {{bracket}}
|arg4 = {{type|number}} reclaimTime {{bracket}}
|arg5 = {{type|number}} reclaimLeft {{rbracket}}{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureReclaim
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} reclaimLeft
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} unitDefID {{pipe}} {{type|string}} unitDefName {{bracket}}
|arg3 = {{type|number}} facing {{pipe}} {{type|string}} "facing" {{bracket}}
|arg4 = {{type|number}} progress {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing {{value|-1}}. The level of progress can now be set via the additional 4th param. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 3
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeaturePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} snapToGround {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureVelocity
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMoveCtrl
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} enable {{bracket}}
|arg3 = {{type|number*}} args {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this callout to control feature movement. The number* arguments are parsed as follows and all optional: If enable is true: {{bracket}}, velVector(x,y,z) -- initial velocity for feature {{bracket}}, accVector(x,y,z) -- acceleration added every frame{{rbracket}}{{rbracket}} If enable is false: {{bracket}}, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl {{bracket}}, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl {{bracket}}, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl{{rbracket}}{{rbracket}}{{rbracket}} As of spring 103.0 it is necessary to unlock feature movement on x,z axis before changing feature physics. For example use "Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)" to unlock all movement prior to making SetFeatureVelocity calls.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureAlwaysVisible
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg6 = {{type|number}} Axis
|arg7 = {{type|number}} volumeType {{bracket}}
|arg8 = {{type|number}} primaryAxis {{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMidAndAimPos
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}} Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRadiusAndHeight
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 = {{type|boolean}} isBlocking
|arg3 = {{type|boolean}} isSolidObjectCollidable
|arg4 = {{type|boolean}} isProjectileCollidable
|arg5 = {{type|boolean}} isRaySegmentCollidable
|arg6 = {{type|boolean}} crushable
|arg7 = {{type|boolean}} blockEnemyPushing
|arg8 = {{type|boolean}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}} Changed parameters.
}}

= Lua to COB =

{{LuaCallout
|prefix = Spring.
|name = CallCOBScript
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} funcID {{pipe}} {{type|string}} funcName
|arg3 = {{type|number}} retArgs
|arg4 = COBArg1
|arg5 = COBArg2
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} returnValue, {{type|number}} retArg1, {{type|number}} retArg2, ...
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBScriptID
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} funcName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} funcID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCOBValue
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} splitData=false {{rbracket}}
|arg3 = {{type|number}} COBValue {{bracket}}
|arg4 = {{type|number}} param1 {{bracket}}
|arg5 = {{type|number}} param2 {{bracket}}
|arg6 = {{type|number}} param3 {{bracket}}
|arg7 = {{type|number}} param4 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|number}} result {{pipe}} {{type|number}} result1, {{type|number}} result2
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCOBValue
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} COBValue
|arg3 = {{type|number}} param1 {{bracket}}
|arg4 = {{type|number}} param2 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

= Give Order =

Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) 
See [[Lua CMDs]] for relevant constants.

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = unitMap = { {{bracket}}unitID{{rbracket}} = example, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = unitMap = { {{bracket}}{{type|number}} unitID{{rbracket}} = example, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = {{type|number}} unitID, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

=Ground=
== Grass ==

{{LuaCallout
|prefix = Spring.
|name = AddGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Heightmap ==
Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is [[Lua_ConstGame|Game.squareSize]].

{{LuaCallout
|prefix = Spring.
|name = LevelHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AdjustHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = (heightmap[x][z] += height;)
}}

{{LuaCallout
|prefix = Spring.
|name = RevertHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetHeightMapFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}
Example code:<pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)</pre>

{{LuaCallout
|prefix = Spring.
|name = AddHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetHeightMapFunc()
}}

{{LuaCallout
|prefix = Spring.
|name = SetHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetHeightMapFunc(). The terraform argument is a scaling factor: 
If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.
}}

{{LuaCallout
|prefix = Spring.
|name = LevelSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AdjustSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RevertSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSmoothMeshFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetSmoothMeshFunc().
}}

{{LuaCallout
|prefix = Spring.
|name = SetSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetSmoothMeshFunc().
}}

== TerrainTypes ==

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTerrainType
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} newType
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} oldType
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTerrainTypeData
|arg1 = {{type|number}} typeIndex {{bracket}}
|arg2 = {{type|number}} speedTanks = nil {{bracket}}
|arg3 = {{type|number}} speedKBOts = nil {{bracket}}
|arg4 = {{type|number}} speedHovers = nil {{bracket}}
|arg5 = {{type|number}} speedShips = nil {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSquareBuildingMask
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|103.0}}
}}

See also {{xtaglink|Gamedev:UnitDefs|buildingMask}} unitdef tag.

== MetalAmount ==

{{LuaCallout
|prefix = Spring.
|name = SetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} metalAmount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} x & z coords are in worldspace/16. metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
}}

= Command Descriptions =
Doesn't work in unsynced code! 

{{LuaCallout
|prefix = Spring.
|name = EditUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdDescID
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ queueing = boolean ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}</pre>
{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).

{{LuaCallout
|prefix = Spring.
|name = InsertUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Other =

{{LuaCallout
|prefix = Spring.
|name = SetNoPause
|arg1 = {{type|bool}} noPause
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitToFeature
|arg1 = {{type|bool}} tofeature
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = An ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag) [http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
}}

{{LuaCallout
|prefix = Spring.
|name = SetExperienceGrade
|arg1 = {{type|number}} expGrade {{bracket}}
|arg2 = {{type|number}} ExpPowerScale {{bracket}}
|arg3 = {{type|number}} ExpHealthScale {{bracket}}
|arg4 = {{type|number}} ExpReloadScale {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = expGrade defines how often UnitExperience() will be called. Prior to 104.0 it is based on the following equation: (int) {{bracket}}exp/(exp+1){{rbracket}} / expGrade Post 104.0 it is the raw change.
}}

{{LuaCallout
|prefix = Spring.
|name = SpawnExplosion
|arg1 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg2 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg3 = {{type|table}} explosionParams
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}
<pre>Possible keys of explosionParams are:
weaponDef = number,
owner = number,
hitUnit = number,
hitFeature = number,
craterAreaOfEffect = number,
damageAreaOfEffect = number,
edgeEffectiveness = number,
explosionSpeed = number,
gfxMod = number,
impactOnly = boolean,
ignoreOwner = boolean,
damageGround = boolean

Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
The weapondefID is only used for visuals and for passing into callins like UnitDamaged.</pre>

{{LuaCallout
|prefix = Spring.
|name = SpawnCEG
|arg1 = {{type|string}} "cegname" | {{type|number}} cegID
|arg2 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg3 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg4 = {{type|number}} radius = 0
|arg5 = {{type|number}} damage = 0
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success, {{type|number}} cegID
|info = cegID new in 95.0.
}}

{{LuaCallout
|prefix = Spring.
|name = SpawnSFX
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} sfxID
|arg3 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg4 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg5 = {{type|number}} radius = 0
|arg6 = {{type|number}} damage = 0 {{bracket}}
|arg7 = {{type|bool}} absolute {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}}
}}

Equal to the [[Animation-LuaCallouts#Effects|UnitScript versions of EmitSFX]], but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

= Projectiles =

{{LuaCallout
|prefix = Spring.
|name = SpawnProjectile
|arg1 = {{type|number}} weaponDefID
|arg2 = {{type|table}} projectileParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} projectileID
|info =
}}
<pre>Possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string</pre>

{{LuaCallout
|prefix = Spring.
|name = DeleteProjectile
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Silently removes projectiles (no explosion).
}}

Pre 95.0:
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|string}} targetTypeStr {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}

Post 95.0:
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|number}} targetType {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}
<pre>targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = SetProjectileIgnoreTrackingError
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} ignore
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileIsIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileMoveControl
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Disables engine movecontrol, so lua can fully control the physics.
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectilePosition
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} posX = 0 {{bracket}}
|arg3 = {{type|number}} posY = 0 {{bracket}}
|arg4 = {{type|number}} posZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileVelocity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} velX = 0 {{bracket}}
|arg3 = {{type|number}} velY = 0 {{bracket}}
|arg4 = {{type|number}} velZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileCollision
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileGravity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} grav = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinAngle
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinAngle = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} speed = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinVec
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinX = 0 {{bracket}}
|arg3 = {{type|number}} spinY = 0 {{bracket}}
|arg4 = {{type|number}} spinZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileCEG
|arg1 = {{type|number}} projectileID
|arg2 = {{type|string}} ceg_name
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetPieceProjectileParams
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} explosionFlags {{bracket}}
|arg3 = {{type|number}} spinAngle {{bracket}}
|arg4 = {{type|number}} spinSpeed {{bracket}}
|arg5 = {{type|number}} spinVector.x {{bracket}}
|arg6 = {{type|number}} spinVector.y {{bracket}}
|arg7 = {{type|number}} spinVector.z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileAlwaysVisible
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
<pre>Format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}</pre>

[[category: Lua]]

User:Master-athmos

2021-04-04T20:01:26Z

Master-athmos:

Lua SyncedRead

2021-04-04T01:59:05Z

Master-athmos: Updated page with new anchorable templates

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1
|info = With x & z in worldspace coordinates.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)

facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

User:Master-athmos

2021-04-04T01:57:00Z

Master-athmos: /* Feature Pieces */

User:Master-athmos

2021-04-04T01:55:21Z

Master-athmos: /* Unit Pieces */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1
|info = With x & z in worldspace coordinates.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)

facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

User:Master-athmos

2021-04-04T01:50:45Z

Master-athmos: /* Mod-/Map-Options */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1
|info = With x & z in worldspace coordinates.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)

facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

User:Master-athmos

2021-04-04T01:46:14Z

Master-athmos:

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1
|info = With x & z in worldspace coordinates.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)

facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

User:Master-athmos

2021-04-04T00:44:45Z

Master-athmos:

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1
|info = With x & z in worldspace coordinates.
}}

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|95.0}} parameters now are:
number unitDefID,
number pos.x, number pos.y, number pos.z
[, number dir.x
[, number dir.y
[, number dir.z
[, boolean testTerrain
[, boolean testObjects
[, boolean centerOnly ]]]]]]
) --> boolean

'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos''' optional param ''facing'' supported in 0.83 and later
( number unitDefID, number x, number y, number z[, number facing] )
-> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState''' jammed new in 95.0
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
jammed indicates if a position is actively being radar- or sonar-jammed by '''any''' allyteam

'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

( number xmin, number zmin, number xmax, number zmax
[, boolean excludeWeaponProjectiles
[, boolean excludePieceProjectiles] ] )
-> nil | projectileTable = { [1] = number projectileID, etc... }

'''Spring.GetProjectileOwnerID''' {{new|99.0}}
(number projectileID) -> nil | number unitID

'''Spring.GetProjectileTeamID''' {{new|99.0}}
(number projectileID) -> nil | number teamID

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID )
Pre 95.0: -> nil | number targetID, string targetTypeStr
Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE

'''Spring.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
{{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons

'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.GetPieceProjectileParams''' {{new|95.0}}
( number projectileID ) -> nil | number explosionFlags, number spinAngle,
number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
Where explosionFlags use binary flags with the following integer equivalents:
more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 

'''Spring.GetProjectileTimeToLive''' {{new|99.0}}
( number projectileID ) -> nil | number ttl

'''Spring.GetProjectileDirection''' {{new|95.0}}
( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

'''Spring.GetProjectileSpinAngle''' Deprecated in 95.0
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' Deprecated in 95.0
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' Deprecated in 95.0
( number projectileID ) -> nil | number x, number y, number z

'''Spring.GetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.

[[category: Lua]]

User:Master-athmos

2021-03-27T21:18:08Z

Master-athmos:

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===
See #Unit_Pieces for full details.

'''Spring.GetFeatureLastAttackedPiece'''

'''Spring.GetFeaturePieceMap'''

'''Spring.GetFeaturePieceList'''

'''Spring.GetFeaturePieceInfo'''

'''Spring.GetFeaturePiecePosition'''

'''Spring.GetFeaturePieceDirection'''

'''Spring.GetFeaturePiecePosDir'''

'''Spring.GetFeaturePieceMatrix'''

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
''This returns the ground original (before terraforming) height at a given x,z position''

'''Spring.GetGroundNormal'''
( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope
{{new|100.0}}: smoothedNormal and slope

'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

'''Spring.GetMetalMapSize'''
( ) -> number sizeX, number sizeY

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetTerrainTypeData''' {{new|92.0}}
( number i )
-> nil | string "name", number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
boolean receiveTracks

'''Spring.GetGrass'''
( number x, number z ) -> number 0 | 1
where x & z are in worldspace coordinates

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|95.0}} parameters now are:
number unitDefID,
number pos.x, number pos.y, number pos.z
[, number dir.x
[, number dir.y
[, number dir.z
[, boolean testTerrain
[, boolean testObjects
[, boolean centerOnly ]]]]]]
) --> boolean

'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos''' optional param ''facing'' supported in 0.83 and later
( number unitDefID, number x, number y, number z[, number facing] )
-> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState''' jammed new in 95.0
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
jammed indicates if a position is actively being radar- or sonar-jammed by '''any''' allyteam

'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

( number xmin, number zmin, number xmax, number zmax
[, boolean excludeWeaponProjectiles
[, boolean excludePieceProjectiles] ] )
-> nil | projectileTable = { [1] = number projectileID, etc... }

'''Spring.GetProjectileOwnerID''' {{new|99.0}}
(number projectileID) -> nil | number unitID

'''Spring.GetProjectileTeamID''' {{new|99.0}}
(number projectileID) -> nil | number teamID

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID )
Pre 95.0: -> nil | number targetID, string targetTypeStr
Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE

'''Spring.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
{{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons

'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.GetPieceProjectileParams''' {{new|95.0}}
( number projectileID ) -> nil | number explosionFlags, number spinAngle,
number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
Where explosionFlags use binary flags with the following integer equivalents:
more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 

'''Spring.GetProjectileTimeToLive''' {{new|99.0}}
( number projectileID ) -> nil | number ttl

'''Spring.GetProjectileDirection''' {{new|95.0}}
( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

'''Spring.GetProjectileSpinAngle''' Deprecated in 95.0
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' Deprecated in 95.0
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' Deprecated in 95.0
( number projectileID ) -> nil | number x, number y, number z

'''Spring.GetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.

[[category: Lua]]

User:Master-athmos

2021-03-27T20:43:16Z

Master-athmos:

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info = reclaimTime {{new|105.0}}
}}

'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeaturePieceCollisionVolumeData''' {{new|101.0}}
( number featuerID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeatureBlocking'''
(number featureID) --> boolean collidable, boolean crushable, boolean blocking
{{new|95.0}} Now return values are:
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

=== Feature Pieces ===
See #Unit_Pieces for full details.

'''Spring.GetFeatureLastAttackedPiece'''

'''Spring.GetFeaturePieceMap'''

'''Spring.GetFeaturePieceList'''

'''Spring.GetFeaturePieceInfo'''

'''Spring.GetFeaturePiecePosition'''

'''Spring.GetFeaturePieceDirection'''

'''Spring.GetFeaturePiecePosDir'''

'''Spring.GetFeaturePieceMatrix'''

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
''This returns the ground original (before terraforming) height at a given x,z position''

'''Spring.GetGroundNormal'''
( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope
{{new|100.0}}: smoothedNormal and slope

'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

'''Spring.GetMetalMapSize'''
( ) -> number sizeX, number sizeY

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetTerrainTypeData''' {{new|92.0}}
( number i )
-> nil | string "name", number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
boolean receiveTracks

'''Spring.GetGrass'''
( number x, number z ) -> number 0 | 1
where x & z are in worldspace coordinates

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|95.0}} parameters now are:
number unitDefID,
number pos.x, number pos.y, number pos.z
[, number dir.x
[, number dir.y
[, number dir.z
[, boolean testTerrain
[, boolean testObjects
[, boolean centerOnly ]]]]]]
) --> boolean

'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos''' optional param ''facing'' supported in 0.83 and later
( number unitDefID, number x, number y, number z[, number facing] )
-> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState''' jammed new in 95.0
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
jammed indicates if a position is actively being radar- or sonar-jammed by '''any''' allyteam

'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

( number xmin, number zmin, number xmax, number zmax
[, boolean excludeWeaponProjectiles
[, boolean excludePieceProjectiles] ] )
-> nil | projectileTable = { [1] = number projectileID, etc... }

'''Spring.GetProjectileOwnerID''' {{new|99.0}}
(number projectileID) -> nil | number unitID

'''Spring.GetProjectileTeamID''' {{new|99.0}}
(number projectileID) -> nil | number teamID

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID )
Pre 95.0: -> nil | number targetID, string targetTypeStr
Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE

'''Spring.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
{{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons

'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.GetPieceProjectileParams''' {{new|95.0}}
( number projectileID ) -> nil | number explosionFlags, number spinAngle,
number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
Where explosionFlags use binary flags with the following integer equivalents:
more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 

'''Spring.GetProjectileTimeToLive''' {{new|99.0}}
( number projectileID ) -> nil | number ttl

'''Spring.GetProjectileDirection''' {{new|95.0}}
( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

'''Spring.GetProjectileSpinAngle''' Deprecated in 95.0
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' Deprecated in 95.0
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' Deprecated in 95.0
( number projectileID ) -> nil | number x, number y, number z

'''Spring.GetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.

[[category: Lua]]

User:Master-athmos

2021-03-18T00:01:58Z

Master-athmos:

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeatureMass''' {{new|101.0}}
( number featureID ) -> nil | number
'''Spring.GetFeatureSeparation''' {{new|101.0}}
( number featureID1, number featureID2 [, boolean 2D] ) -> nil | number distance
'''Spring.GetFeaturePosition'''
( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
since 89.0, returns the base (default), middle or aim position of the feature.

'''Spring.GetFeatureVelocity''' {{new|95.0}}
( number featureID [, boolean norm] )
-> nil | number velx, number vely, number velz, number velLength

'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz

'''Spring.GetFeatureRotation''' {{New|101.0}}
(number featureID) --> nil | number pitch, number yaw, number roll

'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources''' reclaimTime {{new|105.0}}
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft, number reclaimTime
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeaturePieceCollisionVolumeData''' {{new|101.0}}
( number featuerID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeatureBlocking'''
(number featureID) --> boolean collidable, boolean crushable, boolean blocking
{{new|95.0}} Now return values are:
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

=== Feature Pieces ===
See #Unit_Pieces for full details.

'''Spring.GetFeatureLastAttackedPiece'''

'''Spring.GetFeaturePieceMap'''

'''Spring.GetFeaturePieceList'''

'''Spring.GetFeaturePieceInfo'''

'''Spring.GetFeaturePiecePosition'''

'''Spring.GetFeaturePieceDirection'''

'''Spring.GetFeaturePiecePosDir'''

'''Spring.GetFeaturePieceMatrix'''

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
''This returns the ground original (before terraforming) height at a given x,z position''

'''Spring.GetGroundNormal'''
( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope
{{new|100.0}}: smoothedNormal and slope

'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

'''Spring.GetMetalMapSize'''
( ) -> number sizeX, number sizeY

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetTerrainTypeData''' {{new|92.0}}
( number i )
-> nil | string "name", number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
boolean receiveTracks

'''Spring.GetGrass'''
( number x, number z ) -> number 0 | 1
where x & z are in worldspace coordinates

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|95.0}} parameters now are:
number unitDefID,
number pos.x, number pos.y, number pos.z
[, number dir.x
[, number dir.y
[, number dir.z
[, boolean testTerrain
[, boolean testObjects
[, boolean centerOnly ]]]]]]
) --> boolean

'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos''' optional param ''facing'' supported in 0.83 and later
( number unitDefID, number x, number y, number z[, number facing] )
-> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState''' jammed new in 95.0
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
jammed indicates if a position is actively being radar- or sonar-jammed by '''any''' allyteam

'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

( number xmin, number zmin, number xmax, number zmax
[, boolean excludeWeaponProjectiles
[, boolean excludePieceProjectiles] ] )
-> nil | projectileTable = { [1] = number projectileID, etc... }

'''Spring.GetProjectileOwnerID''' {{new|99.0}}
(number projectileID) -> nil | number unitID

'''Spring.GetProjectileTeamID''' {{new|99.0}}
(number projectileID) -> nil | number teamID

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID )
Pre 95.0: -> nil | number targetID, string targetTypeStr
Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE

'''Spring.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
{{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons

'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.GetPieceProjectileParams''' {{new|95.0}}
( number projectileID ) -> nil | number explosionFlags, number spinAngle,
number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
Where explosionFlags use binary flags with the following integer equivalents:
more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 

'''Spring.GetProjectileTimeToLive''' {{new|99.0}}
( number projectileID ) -> nil | number ttl

'''Spring.GetProjectileDirection''' {{new|95.0}}
( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

'''Spring.GetProjectileSpinAngle''' Deprecated in 95.0
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' Deprecated in 95.0
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' Deprecated in 95.0
( number projectileID ) -> nil | number x, number y, number z

'''Spring.GetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.

[[category: Lua]]