Spring - User contributions [en]

Lua:Tutorial GettingStarted

2023-06-21T03:30:45Z

Masterbel: <syntaxhighlight> doesn't appear to be working, so for the time being I've subbed it out with <pre><code>

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

Here are some examples of small widgets, with useful code to get you started!

To play with each example, place the code into a "my_new_widget_name.lua" file in your Spring/LuaUI/widgets dir (create it if not already present) and run Spring with any game. Your widget should then appear ingame!

To see many more examples, check out the LuaUI/widgets directory of the games in [[Gamedev:PublicRepos|PublicRepos]].

Note that every widget (and gadget) must include a GetInfo() callin, but all other callins are optional.

==Example 1==
The "hello world" example, with a ticking clock.

<code><pre>
function widget:GetInfo()
return {
name = "Name as shown in widget list",
desc = "Description as normally shown in tooltip",
author = "It could be you!",
date = "now",
license = "PD", -- should be compatible with Spring
layer = 0,
enabled = true
}
end

local helloWorld = "I STARTED LOOK AT ME JIM!"
local toggle

function widget:Initialize()
Spring.Echo(helloWorld)
end

function widget:Update()
if (toggle == true) then
Spring.Echo("TOCK")
toggle = false
else
Spring.Echo("TICK")
toggle = true
end
end
</pre></code>

==Example 2==
How to make stuff happen when units do stuff.
<code><pre>
function widget:GetInfo()
return {
name = "Unit Announcer",
desc = "Units are proud to be alive",
author = "Some guy",
date = "I don't know why we include dates",
license = "GPLv2 or later",
layer = 0,
enabled = true
}
end

local machoUnits = {}

function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
Spring.Echo("HELLO")

local humanName = UnitDefs[unitDefID].humanName
local numWeapons = #UnitDefs[unitDefID].weapons
local plural = numWeapons~=1 and "s" or ""

Spring.Echo("I am unit " .. unitID .. ". I am a " .. humanName .. ".")
Spring.Echo("I have " .. numWeapons .. " weapon" .. plural .. ".")
if numWeapons>0 then
machoUnits[unitID] = true
end
end

function widget:UnitDestroyed(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam)
machoUnits[unitID] = nil
end

function widget:UnitDamaged(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)
if machoUnits[unitID] then return end

local n = math.random(3,10)
local ow = "O"
for i=1,n do
ow = ow .. "W"
end
Spring.Echo(ow)
end
</pre></code>

==Example 3==
Something actually useful.
<code><pre>
function widget:GetInfo()
return {
name = "Stop means Stop",
desc = "Cancels Self D orders when unit is given a stop command",
author = "enotseulB",
date = "GPL v2 or later",
license = "Feb 2015",
layer = 0,
enabled = true
}
end

local CMD_STOP = CMD.STOP

function widget:UnitCommand(unitID, unitDefID, teamID, cmdID, cmdParams, cmdOptions)
if cmdID ~= CMD_STOP then return end
if not unitID then return end
if teamID ~= Spring.GetMyTeamID() then return end

if (Spring.GetUnitSelfDTime(unitID) > 0) then
Spring.GiveOrderToUnit(unitID, CMD.SELFD, {}, {})
end
end
</pre></code>
[[category: Lua]]

Lua SyncedRead

2022-06-23T00:03:24Z

Masterbel: typo: Possilbe changed to Possible

[[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 = Note that when called from a widget, this also returns units that are only radar blips. For units that are radar blips, you may want to check if they are in los, as GetUnitDefID() will still return true if they have previously been seen. See the UnsyncedRead GetVisibleUnits() call.
}}

{{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() ). Also very important to note, that you can receive units that are 'already dead', when you do a Spring.GetAllUnits() call. These 'dead' units have already had their unitdestroyed callins called, and that will not get called again, and even more interestingly, these units are also valid, as in the above ValidUnitID callin will return true. The GetUnitIsDead howerver, will return true for these units, that are already dead but still valid units.
}}

{{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 = Gets which team a unit belongs to. Note that this still returns the old team when called from the UnitTaken / UnitGiven callins.
}}

{{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. And RAW returns an bitmask integer, where the bits are: 1: LOS_INLOS, the unit is currently in the los of the allyteam, 2: LOS_INRADAR the unit is currently in radar from the allyteam, 4: LOS_PREVLOS the unit has previously been in los from the allyteam, 8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam
}}

{{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. Possible 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. Possible 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 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

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

Lua SyncedRead

2022-06-23T00:02:27Z

Masterbel: typo: Possilbe changed to Possible

[[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 = Note that when called from a widget, this also returns units that are only radar blips. For units that are radar blips, you may want to check if they are in los, as GetUnitDefID() will still return true if they have previously been seen. See the UnsyncedRead GetVisibleUnits() call.
}}

{{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() ). Also very important to note, that you can receive units that are 'already dead', when you do a Spring.GetAllUnits() call. These 'dead' units have already had their unitdestroyed callins called, and that will not get called again, and even more interestingly, these units are also valid, as in the above ValidUnitID callin will return true. The GetUnitIsDead howerver, will return true for these units, that are already dead but still valid units.
}}

{{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 = Gets which team a unit belongs to. Note that this still returns the old team when called from the UnitTaken / UnitGiven callins.
}}

{{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. And RAW returns an bitmask integer, where the bits are: 1: LOS_INLOS, the unit is currently in the los of the allyteam, 2: LOS_INRADAR the unit is currently in radar from the allyteam, 4: LOS_PREVLOS the unit has previously been in los from the allyteam, 8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam
}}

{{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. Possible 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 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

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

Lua UnsyncedRead

2022-01-05T03:07:30Z

Masterbel:

[[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 = GetLocalAllyTeamID
|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, {{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 Returns the SDL1 codes for the pressed keys, first as an integer, a string containing the hex representation. Use Spring.[[Lua_UnsyncedRead#GetKeySymbol|GetKeySymbol]] to convert to an SDL2 symbol.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info = Returns the SDL1 code for the SDL2 symbol
}}

{{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 = Converts an SDL1 keycode into an SDL2 keycode, represented as a hexadecimal string. For most cases, these values will be the same.
}}

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

FAQ:trouble

2021-02-07T20:58:42Z

Masterbel: Add fix for repeating tile bug

[[Category:FAQ]]

=Troubleshooting=

==Network==

===My buddy can not connect to a game I've opened. What can we do?===
The engine uses UDP port 8452 by default, which can be changed in the lobby. If you are behind a router, and are having problems hosting, try forwarding the correct port and also make sure the firewall is not blocking it. If you do not know what a port or a firewall is, use a relay host instead: when hosting a game, tick the check-box labeled "Use relayhost".

===I can not connect to the online lobby server?===
See in the [http://springrts.com/phpbb/index.php forum] if others have the same problem.

The server might be temporary down for maintenance.
Most lobbies should allow you to connect to a "backup server" or just try again after some time.

==Graphics==

===Map texture repeating across the map in squares===
[[File:Screenshot Spring Squares of Doom.jpg|200px]]

Try adding <code>UsePBO = 0</code> to your springsettings.cfg.

===Low fps that get better in metalview (F4)===
Try typing into ingame chat:

''/advmapshading 0

/advmodelshading 0''

And/Or add to springsettings.cfg:

''AdvMapShading = 0

AdvUnitShading = 0''

(usually the AdvMapShading part is enough)

===I am having really bad framerates (fps) on my dual core! What am I doing wrong?===
Some of this helped other users:

* This error is sometimes reported by people having multicore-CPUs. To solve this, you could try to restrict it to run on one core. Enable "SetCoreAffinity=1" in your [[springrc]].
* Installing the latest processor drivers and Windows hotfixes for your system may also help.
* Also try to disabling the "Exhaust" effect on planes could help: Press f11 while ingame, disable LUPS and Lups manager (by clicking on them to make them turn red)

===How to Alt-Tab out of full-screen on Linux?===
Play windowed with ''/grabinput'', or [http://springrts.com/phpbb/viewtopic.php?p=449972#p449972 use devilspie].

===I use Linux with Open-Source Gfx drivers, and the map is all white!===
[[File:Whitemap.png|200px]]

Due to patents S3TC texture support is disabled by default. To enable it you need the tool driconf (note, you no longer require libdxtn):

<code><pre>
$ sudo apt-get install libgl1-mesa-dev driconf
$ driconf
</pre></code>

On the "Image Quality" tab activate "Enable S3TC texture compression even if software support is not available".

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=20&t=20809 Spring on Intel or ATI 'open-source' drivers]

===It crashes, hangs, ...===
Possible fixes are:
* updating your graphics driver
* lowering the graphic-settings at SpringSettings
* disabling graphics effects at SpringSettings

=== Spring crashes on my notebook but it has a really nice graphic card! (or some effects are messed up) ===
for example air plane trails might look like:

[[File: Bugged_plane_trails_graphics.jpg]]

Some notebooks have two graphic cards: One for 3D and a small integrated one to save power while on facebook.
Setting it to use the correct 3D card has helped some players.
Use the internet to find out how to do that.
Screenhot of such controll panel, though it might look different on different computers:

[[File: Graphic_cards_selection.png]]

===Nvidia===

====I am having really bad framerates (FPS)!====
Turn off 'threaded optimizations' for Spring in the nVidia control panel, enable "Compress textures" in SpringSettings.

[[File:MToptimizations.png|200px]]

====After playing Spring, in background running firefox window is white or gray. ====

Disable Anti-Aliasing / decrease graphic-quality (<=high) in SpringSettings.

====Shadows on Units doesn't work====
[[File:Shadows_fail.jpg|200px]]

Check if Shadows and AdvUnitShading is enabled, update your graphics driver.

====It crashes/hangs====

* try disabling shadows (SpringSettings)
* try disabling advanced map shading (AdvMapShading=0)

===Intel===

====Why does spring hang for a few seconds?====
This bug occurs on maps like FolsomDamDeluxeV2, Tangerline. FPS suddenly drops to 1 and game runs very slowly. This seems to be an Intel driver bug. For Windows Vista/7 try updating driver up to 8.15.10.2246 or newer. For Windows XP there is no solution yet.

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23541 Intel HD Graphics Driver issue?]
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23081 Performance issues on Intel X4500]

====Fonts are unreadable====
[[File:IntelBorkedFonts.png|200px]]

This is a driver bug, try to update/downgrade your driver.

====It crashes, hangs etc...====
Possible fixes are:
* disabling texture-compression at SpringSettings
* disabling reflective units at SpringSettings
* disable ReflectiveWater
* [http://downloadcenter.intel.com/ updating your driver]
* use linux! (yes, this hint sucks, but the open-source-drivers seems to work better...)

===ATI/AMD===
First of all, if you encourage a graphics related problem on ATI/AMD graphic device update your drivers to the latest version [http://support.amd.com/us/gpudownload/Pages/index.aspx ATI/AMD dowload].

==== I've got the most recent drivers and the game crashes in atioglxx.dll====
As of Spring 0.80.5, use only basic or dynamic water. Bump water with disabled shore waves should also work. Reflective or refractive water will make the game crash after 15-20 minutes due to a memory leak.

Spring 0.81.2 and/or Catalyst 10.2 drivers or newer should fix this problem.

if the game crashes immediatly after the loading screen is finished ("Finalizing") in the Zero-K or Gundam mods and the video card is based on the RV670 GPU (some models of: 3690, 3850, 3870, 4570, 4730, 3730, 3610, 4580, 4750, 3750, 2600 XT/PRO, 3830) Catalyst 8.12 drivers may fix it (windows xp 32-bit, possibly other NT5-based 32-bit platforms), however even with that driver there may still be a crash (not immediatly after the loading screen, as soon as the simulations starts) in Annihilation-based mods that use RED UI, the same lua-based atioglxx.dll crash also happens with the 1944 mod.

also note that later versions of Catalyst drivers for these cards reduce performance in OpenGL applications (windows xp 32-bit, possibly other NT5-based 32-bit platforms) (found at least in: spring, quake3 and Nexuiz), for spring the most significant drop (by ~15%) appears in 9.10 and higher Catalyst versions (more than 15%), if you have one of the lower-performing models of these and don't use shadows you may want to try the Catalyst 8.3 and 8.4 drivers (they do not support shadows but should work ~5% faster compared to 8.12) but those drivers may be less stable

====I've got a notebook and official ATI/AMD drivers refuse to install, what to do?====
First of all, make sure you're installing the 'AMD Mobility Radeon' driver pack branch.
Use [http://www.driverheaven.net/modtool.php ATI Mobility Modder] or unofficial drivers - DNA or Omega. Use [http://google.com Google] or get them from [http://downloads.guru3d.com/Videocards----ATI-Catalyst-(Modified)_c24.html guru3d].

====UI disapears after 5-10 mins of play on old ATI videocards====
In cmdcolors.txt, simply comment out or remove the following lines:
stipplePattern 0xffcc
stippleFactor 1
stippleSpeed 1.0
The problem detected on:
* ATI Radeon X3200 with latest drivers ([http://springrts.com/phpbb/viewtopic.php?f=11&t=20817 ref])
* ATI Radeon 9500 with Omega drivers 3.8.442 ([http://springrts.com/phpbb/viewtopic.php?f=11&t=23526 ref])

====I see the complete screen full of red/green/yellow or giant dots on minimap====

[[File:Redui-minimap-bug.pngâ€Ž|200px]]

This is a bug somewhere in LUA drawing with ATI/AMD. Disable widgets that draw via F11 menu to find the one. There is no real fix. A Widget causing this is "Red UI Minimap", "Highlight Units" or "Chili Minimap". Setting "Max nano simultaneous particles" (SpringSettings) seems to help, too.

====I see big green rectagle on minimap====
[[File:AMD-Minimap-green_rectangle-bug.png|200px]]

Try to set [[Springsettings.cfg#MiniMapDrawProjectiles|MiniMapDrawProjectiles]] in Spring settings to 0.

====The textures looks scary====
[[File:Ati-drawing-issues.jpg|200px]]

This is a known ATI/AMD-bug. Try using different driver, preferably other than 10.5, 10.6, 10.7 -> newer driver pack with fixed OpenGL driver should be fine.

====Units are almost invisible, except for same black pieces====
For example on Radeon X1300/X1550 Series.

[[File:InvisibleUnitBug_Radeon_X1300X1550AdvUnitShading.jpg]]

Set [[Springsettings.cfg#AdvUnitShading]] = 0

====It crashes always at start, hangs etc...====
Check [[infolog.txt]], as it mostly contains hints whats the cause for the crash.
Possible fixes are:
* try the [[springsettings.cfg#Safemode|safemode]] / set [[springsettings.cfg]] safemode values.
* updating or even downgrading [http://support.amd.com/ ATI driver]

==Sound==

===The Sound is crackling/pausing in Windows, what can i do?===
Try:
* Update the sounds driver
* Enable SystemSoundsService in Vista/Seven

===I am having sound problems under Linux! What can i do?===
In more then 90% of the cases, this is caused by PulseAudio. If this is the problem, there are three known solutions to solve it. Use one of them.

====disable sound effects====
Make sure you have the OpenAL-Soft configuration utility. You might want to run:

<code><pre>
# install
sudo apt-get install alsoft-conf
# run
alsoft-conf
</pre></code>

If you're not on a debian-based distribution, you can download the source from the project's homepage: http://www.anduin.net/~angasule/?x=entry:entry091211-133213. You can also check if there's a newer version.
<code><pre>
#download
wget http://www.anduin.net/~angasule/fp-content/attachs/alsoft-conf_1.4.3.tar.gz
#extract
tar xvf alsoft-conf_1.4.3.tar.gz
cd alsoft-conf-1.4.3
#compile
cmake .
make
#run
./alsoft-conf
</pre></code>

In the "Effects" tab remove everything from "Allowed effects".

====disable non-ALSA (preferred)====
run alsoft-conf (for installation see above)

In the "backend" tab, keep only "ALSA" on the left column, then save. Done!

''Side Note:'' ALSA is redirected to the PulseAudio layer when installed.

==Misc==

===Middle mouse button does not work ingame===

If you use Logitech Setpoint be aware that it sets your middle mouse button by default to 'Autoscroll'. It should be set to 'Middle button' instead. Change the setting in Setpoint.

===Spring crashes after Error opening cache\ ... in infolog.txt===

[f=0000000] Reading Estimate PathCosts [8]
[f=0000000] Error opening cache\paths\...

this is a known bug in 0.82.7.1. Your cpu also has many cores?
Then try to set HardwareThreadCount=2" in [[springrc]]. Spring tries to create the PathCache with to many threads in parallel and crashes because out of memory.

===I have a problem that is not described here! What can i do?===
There is a number of things you can do, among these are:
* Search in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum], and ask if you can not find a suiting topic.
* Check the games forum or homepage.
* Look at the [[Gentoo_install#Linux_specific_Troubleshooting|Linux only FAQ]].
* Ask for help in the lobby in a suiting channel, eg: #springlobby, #de, #fr, #ai, #main
* Ask the FAQ-Bot in the lobby in channel #springlobby. To get a list of topics, write ''!faqlist'' and then use ''!faq <topic-name>'' to get the help text. For example, try ''!faq rename''.

===The ingame chat spams a lot of cryptic error messages===
This is most likely a problem with the game's Lua scripting.
Report it in the games forum or its bug tracker.
[[Bugs|Here]] are some hints how to so.

File:Screenshot Spring Squares of Doom.jpg

2021-02-07T20:54:47Z

Masterbel:

FAQ:trouble

2021-02-07T20:52:44Z

Masterbel: Undo revision 31458 by Masterbel (talk)

[[Category:FAQ]]

=Troubleshooting=

==Network==

===My buddy can not connect to a game I've opened. What can we do?===
The engine uses UDP port 8452 by default, which can be changed in the lobby. If you are behind a router, and are having problems hosting, try forwarding the correct port and also make sure the firewall is not blocking it. If you do not know what a port or a firewall is, use a relay host instead: when hosting a game, tick the check-box labeled "Use relayhost".

===I can not connect to the online lobby server?===
See in the [http://springrts.com/phpbb/index.php forum] if others have the same problem.

The server might be temporary down for maintenance.
Most lobbies should allow you to connect to a "backup server" or just try again after some time.

==Graphics==
===Low fps that get better in metalview (F4)===
Try typing into ingame chat:

''/advmapshading 0

/advmodelshading 0''

And/Or add to springsettings.cfg:

''AdvMapShading = 0

AdvUnitShading = 0''

(usually the AdvMapShading part is enough)

===I am having really bad framerates (fps) on my dual core! What am I doing wrong?===
Some of this helped other users:

* This error is sometimes reported by people having multicore-CPUs. To solve this, you could try to restrict it to run on one core. Enable "SetCoreAffinity=1" in your [[springrc]].
* Installing the latest processor drivers and Windows hotfixes for your system may also help.
* Also try to disabling the "Exhaust" effect on planes could help: Press f11 while ingame, disable LUPS and Lups manager (by clicking on them to make them turn red)

===How to Alt-Tab out of full-screen on Linux?===
Play windowed with ''/grabinput'', or [http://springrts.com/phpbb/viewtopic.php?p=449972#p449972 use devilspie].

===I use Linux with Open-Source Gfx drivers, and the map is all white!===
[[File:Whitemap.png|200px]]

Due to patents S3TC texture support is disabled by default. To enable it you need the tool driconf (note, you no longer require libdxtn):

<code><pre>
$ sudo apt-get install libgl1-mesa-dev driconf
$ driconf
</pre></code>

On the "Image Quality" tab activate "Enable S3TC texture compression even if software support is not available".

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=20&t=20809 Spring on Intel or ATI 'open-source' drivers]

===It crashes, hangs, ...===
Possible fixes are:
* updating your graphics driver
* lowering the graphic-settings at SpringSettings
* disabling graphics effects at SpringSettings

=== Spring crashes on my notebook but it has a really nice graphic card! (or some effects are messed up) ===
for example air plane trails might look like:

[[File: Bugged_plane_trails_graphics.jpg]]

Some notebooks have two graphic cards: One for 3D and a small integrated one to save power while on facebook.
Setting it to use the correct 3D card has helped some players.
Use the internet to find out how to do that.
Screenhot of such controll panel, though it might look different on different computers:

[[File: Graphic_cards_selection.png]]

===Nvidia===

====I am having really bad framerates (FPS)!====
Turn off 'threaded optimizations' for Spring in the nVidia control panel, enable "Compress textures" in SpringSettings.

[[File:MToptimizations.png|200px]]

====After playing Spring, in background running firefox window is white or gray. ====

Disable Anti-Aliasing / decrease graphic-quality (<=high) in SpringSettings.

====Shadows on Units doesn't work====
[[File:Shadows_fail.jpg|200px]]

Check if Shadows and AdvUnitShading is enabled, update your graphics driver.

====It crashes/hangs====

* try disabling shadows (SpringSettings)
* try disabling advanced map shading (AdvMapShading=0)

===Intel===

====Why does spring hang for a few seconds?====
This bug occurs on maps like FolsomDamDeluxeV2, Tangerline. FPS suddenly drops to 1 and game runs very slowly. This seems to be an Intel driver bug. For Windows Vista/7 try updating driver up to 8.15.10.2246 or newer. For Windows XP there is no solution yet.

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23541 Intel HD Graphics Driver issue?]
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23081 Performance issues on Intel X4500]

====Fonts are unreadable====
[[File:IntelBorkedFonts.png|200px]]

This is a driver bug, try to update/downgrade your driver.

====It crashes, hangs etc...====
Possible fixes are:
* disabling texture-compression at SpringSettings
* disabling reflective units at SpringSettings
* disable ReflectiveWater
* [http://downloadcenter.intel.com/ updating your driver]
* use linux! (yes, this hint sucks, but the open-source-drivers seems to work better...)

===ATI/AMD===
First of all, if you encourage a graphics related problem on ATI/AMD graphic device update your drivers to the latest version [http://support.amd.com/us/gpudownload/Pages/index.aspx ATI/AMD dowload].

==== I've got the most recent drivers and the game crashes in atioglxx.dll====
As of Spring 0.80.5, use only basic or dynamic water. Bump water with disabled shore waves should also work. Reflective or refractive water will make the game crash after 15-20 minutes due to a memory leak.

Spring 0.81.2 and/or Catalyst 10.2 drivers or newer should fix this problem.

if the game crashes immediatly after the loading screen is finished ("Finalizing") in the Zero-K or Gundam mods and the video card is based on the RV670 GPU (some models of: 3690, 3850, 3870, 4570, 4730, 3730, 3610, 4580, 4750, 3750, 2600 XT/PRO, 3830) Catalyst 8.12 drivers may fix it (windows xp 32-bit, possibly other NT5-based 32-bit platforms), however even with that driver there may still be a crash (not immediatly after the loading screen, as soon as the simulations starts) in Annihilation-based mods that use RED UI, the same lua-based atioglxx.dll crash also happens with the 1944 mod.

also note that later versions of Catalyst drivers for these cards reduce performance in OpenGL applications (windows xp 32-bit, possibly other NT5-based 32-bit platforms) (found at least in: spring, quake3 and Nexuiz), for spring the most significant drop (by ~15%) appears in 9.10 and higher Catalyst versions (more than 15%), if you have one of the lower-performing models of these and don't use shadows you may want to try the Catalyst 8.3 and 8.4 drivers (they do not support shadows but should work ~5% faster compared to 8.12) but those drivers may be less stable

====I've got a notebook and official ATI/AMD drivers refuse to install, what to do?====
First of all, make sure you're installing the 'AMD Mobility Radeon' driver pack branch.
Use [http://www.driverheaven.net/modtool.php ATI Mobility Modder] or unofficial drivers - DNA or Omega. Use [http://google.com Google] or get them from [http://downloads.guru3d.com/Videocards----ATI-Catalyst-(Modified)_c24.html guru3d].

====UI disapears after 5-10 mins of play on old ATI videocards====
In cmdcolors.txt, simply comment out or remove the following lines:
stipplePattern 0xffcc
stippleFactor 1
stippleSpeed 1.0
The problem detected on:
* ATI Radeon X3200 with latest drivers ([http://springrts.com/phpbb/viewtopic.php?f=11&t=20817 ref])
* ATI Radeon 9500 with Omega drivers 3.8.442 ([http://springrts.com/phpbb/viewtopic.php?f=11&t=23526 ref])

====I see the complete screen full of red/green/yellow or giant dots on minimap====

[[File:Redui-minimap-bug.pngâ€Ž|200px]]

This is a bug somewhere in LUA drawing with ATI/AMD. Disable widgets that draw via F11 menu to find the one. There is no real fix. A Widget causing this is "Red UI Minimap", "Highlight Units" or "Chili Minimap". Setting "Max nano simultaneous particles" (SpringSettings) seems to help, too.

====I see big green rectagle on minimap====
[[File:AMD-Minimap-green_rectangle-bug.png|200px]]

Try to set [[Springsettings.cfg#MiniMapDrawProjectiles|MiniMapDrawProjectiles]] in Spring settings to 0.

====The textures looks scary====
[[File:Ati-drawing-issues.jpg|200px]]

This is a known ATI/AMD-bug. Try using different driver, preferably other than 10.5, 10.6, 10.7 -> newer driver pack with fixed OpenGL driver should be fine.

====Units are almost invisible, except for same black pieces====
For example on Radeon X1300/X1550 Series.

[[File:InvisibleUnitBug_Radeon_X1300X1550AdvUnitShading.jpg]]

Set [[Springsettings.cfg#AdvUnitShading]] = 0

====It crashes always at start, hangs etc...====
Check [[infolog.txt]], as it mostly contains hints whats the cause for the crash.
Possible fixes are:
* try the [[springsettings.cfg#Safemode|safemode]] / set [[springsettings.cfg]] safemode values.
* updating or even downgrading [http://support.amd.com/ ATI driver]

==Sound==

===The Sound is crackling/pausing in Windows, what can i do?===
Try:
* Update the sounds driver
* Enable SystemSoundsService in Vista/Seven

===I am having sound problems under Linux! What can i do?===
In more then 90% of the cases, this is caused by PulseAudio. If this is the problem, there are three known solutions to solve it. Use one of them.

====disable sound effects====
Make sure you have the OpenAL-Soft configuration utility. You might want to run:

<code><pre>
# install
sudo apt-get install alsoft-conf
# run
alsoft-conf
</pre></code>

If you're not on a debian-based distribution, you can download the source from the project's homepage: http://www.anduin.net/~angasule/?x=entry:entry091211-133213. You can also check if there's a newer version.
<code><pre>
#download
wget http://www.anduin.net/~angasule/fp-content/attachs/alsoft-conf_1.4.3.tar.gz
#extract
tar xvf alsoft-conf_1.4.3.tar.gz
cd alsoft-conf-1.4.3
#compile
cmake .
make
#run
./alsoft-conf
</pre></code>

In the "Effects" tab remove everything from "Allowed effects".

====disable non-ALSA (preferred)====
run alsoft-conf (for installation see above)

In the "backend" tab, keep only "ALSA" on the left column, then save. Done!

''Side Note:'' ALSA is redirected to the PulseAudio layer when installed.

==Misc==

===Middle mouse button does not work ingame===

If you use Logitech Setpoint be aware that it sets your middle mouse button by default to 'Autoscroll'. It should be set to 'Middle button' instead. Change the setting in Setpoint.

===Spring crashes after Error opening cache\ ... in infolog.txt===

[f=0000000] Reading Estimate PathCosts [8]
[f=0000000] Error opening cache\paths\...

this is a known bug in 0.82.7.1. Your cpu also has many cores?
Then try to set HardwareThreadCount=2" in [[springrc]]. Spring tries to create the PathCache with to many threads in parallel and crashes because out of memory.

===I have a problem that is not described here! What can i do?===
There is a number of things you can do, among these are:
* Search in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum], and ask if you can not find a suiting topic.
* Check the games forum or homepage.
* Look at the [[Gentoo_install#Linux_specific_Troubleshooting|Linux only FAQ]].
* Ask for help in the lobby in a suiting channel, eg: #springlobby, #de, #fr, #ai, #main
* Ask the FAQ-Bot in the lobby in channel #springlobby. To get a list of topics, write ''!faqlist'' and then use ''!faq <topic-name>'' to get the help text. For example, try ''!faq rename''.

===The ingame chat spams a lot of cryptic error messages===
This is most likely a problem with the game's Lua scripting.
Report it in the games forum or its bug tracker.
[[Bugs|Here]] are some hints how to so.

FAQ:trouble

2021-02-07T20:51:13Z

Masterbel: /* Graphics */

[[Category:FAQ]]

=Troubleshooting=

==Network==

===My buddy can not connect to a game I've opened. What can we do?===
The engine uses UDP port 8452 by default, which can be changed in the lobby. If you are behind a router, and are having problems hosting, try forwarding the correct port and also make sure the firewall is not blocking it. If you do not know what a port or a firewall is, use a relay host instead: when hosting a game, tick the check-box labeled "Use relayhost".

===I can not connect to the online lobby server?===
See in the [http://springrts.com/phpbb/index.php forum] if others have the same problem.

The server might be temporary down for maintenance.
Most lobbies should allow you to connect to a "backup server" or just try again after some time.

==Graphics==
===Low fps that get better in metalview (F4)===
Try typing into ingame chat:

''/advmapshading 0

/advmodelshading 0''

And/Or add to springsettings.cfg:

''AdvMapShading = 0

AdvUnitShading = 0''

(usually the AdvMapShading part is enough)

===The map is broken into weird squares!===
[[File:Https://springrts.com/phpbb/download/file.php?mode=view&id=11229|200px|thumb]]

Try adding `UsePBO = 0` to springsettings.cfg.

===I am having really bad framerates (fps) on my dual core! What am I doing wrong?===
Some of this helped other users:

* This error is sometimes reported by people having multicore-CPUs. To solve this, you could try to restrict it to run on one core. Enable "SetCoreAffinity=1" in your [[springrc]].
* Installing the latest processor drivers and Windows hotfixes for your system may also help.
* Also try to disabling the "Exhaust" effect on planes could help: Press f11 while ingame, disable LUPS and Lups manager (by clicking on them to make them turn red)

===How to Alt-Tab out of full-screen on Linux?===
Play windowed with ''/grabinput'', or [http://springrts.com/phpbb/viewtopic.php?p=449972#p449972 use devilspie].

===I use Linux with Open-Source Gfx drivers, and the map is all white!===
[[File:Whitemap.png|200px]]

Due to patents S3TC texture support is disabled by default. To enable it you need the tool driconf (note, you no longer require libdxtn):

<code><pre>
$ sudo apt-get install libgl1-mesa-dev driconf
$ driconf
</pre></code>

On the "Image Quality" tab activate "Enable S3TC texture compression even if software support is not available".

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=20&t=20809 Spring on Intel or ATI 'open-source' drivers]

===It crashes, hangs, ...===
Possible fixes are:
* updating your graphics driver
* lowering the graphic-settings at SpringSettings
* disabling graphics effects at SpringSettings

=== Spring crashes on my notebook but it has a really nice graphic card! (or some effects are messed up) ===
for example air plane trails might look like:

[[File: Bugged_plane_trails_graphics.jpg]]

Some notebooks have two graphic cards: One for 3D and a small integrated one to save power while on facebook.
Setting it to use the correct 3D card has helped some players.
Use the internet to find out how to do that.
Screenhot of such controll panel, though it might look different on different computers:

[[File: Graphic_cards_selection.png]]

===Nvidia===

====I am having really bad framerates (FPS)!====
Turn off 'threaded optimizations' for Spring in the nVidia control panel, enable "Compress textures" in SpringSettings.

[[File:MToptimizations.png|200px]]

====After playing Spring, in background running firefox window is white or gray. ====

Disable Anti-Aliasing / decrease graphic-quality (<=high) in SpringSettings.

====Shadows on Units doesn't work====
[[File:Shadows_fail.jpg|200px]]

Check if Shadows and AdvUnitShading is enabled, update your graphics driver.

====It crashes/hangs====

* try disabling shadows (SpringSettings)
* try disabling advanced map shading (AdvMapShading=0)

===Intel===

====Why does spring hang for a few seconds?====
This bug occurs on maps like FolsomDamDeluxeV2, Tangerline. FPS suddenly drops to 1 and game runs very slowly. This seems to be an Intel driver bug. For Windows Vista/7 try updating driver up to 8.15.10.2246 or newer. For Windows XP there is no solution yet.

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23541 Intel HD Graphics Driver issue?]
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23081 Performance issues on Intel X4500]

====Fonts are unreadable====
[[File:IntelBorkedFonts.png|200px]]

This is a driver bug, try to update/downgrade your driver.

====It crashes, hangs etc...====
Possible fixes are:
* disabling texture-compression at SpringSettings
* disabling reflective units at SpringSettings
* disable ReflectiveWater
* [http://downloadcenter.intel.com/ updating your driver]
* use linux! (yes, this hint sucks, but the open-source-drivers seems to work better...)

===ATI/AMD===
First of all, if you encourage a graphics related problem on ATI/AMD graphic device update your drivers to the latest version [http://support.amd.com/us/gpudownload/Pages/index.aspx ATI/AMD dowload].

==== I've got the most recent drivers and the game crashes in atioglxx.dll====
As of Spring 0.80.5, use only basic or dynamic water. Bump water with disabled shore waves should also work. Reflective or refractive water will make the game crash after 15-20 minutes due to a memory leak.

Spring 0.81.2 and/or Catalyst 10.2 drivers or newer should fix this problem.

if the game crashes immediatly after the loading screen is finished ("Finalizing") in the Zero-K or Gundam mods and the video card is based on the RV670 GPU (some models of: 3690, 3850, 3870, 4570, 4730, 3730, 3610, 4580, 4750, 3750, 2600 XT/PRO, 3830) Catalyst 8.12 drivers may fix it (windows xp 32-bit, possibly other NT5-based 32-bit platforms), however even with that driver there may still be a crash (not immediatly after the loading screen, as soon as the simulations starts) in Annihilation-based mods that use RED UI, the same lua-based atioglxx.dll crash also happens with the 1944 mod.

also note that later versions of Catalyst drivers for these cards reduce performance in OpenGL applications (windows xp 32-bit, possibly other NT5-based 32-bit platforms) (found at least in: spring, quake3 and Nexuiz), for spring the most significant drop (by ~15%) appears in 9.10 and higher Catalyst versions (more than 15%), if you have one of the lower-performing models of these and don't use shadows you may want to try the Catalyst 8.3 and 8.4 drivers (they do not support shadows but should work ~5% faster compared to 8.12) but those drivers may be less stable

====I've got a notebook and official ATI/AMD drivers refuse to install, what to do?====
First of all, make sure you're installing the 'AMD Mobility Radeon' driver pack branch.
Use [http://www.driverheaven.net/modtool.php ATI Mobility Modder] or unofficial drivers - DNA or Omega. Use [http://google.com Google] or get them from [http://downloads.guru3d.com/Videocards----ATI-Catalyst-(Modified)_c24.html guru3d].

====UI disapears after 5-10 mins of play on old ATI videocards====
In cmdcolors.txt, simply comment out or remove the following lines:
stipplePattern 0xffcc
stippleFactor 1
stippleSpeed 1.0
The problem detected on:
* ATI Radeon X3200 with latest drivers ([http://springrts.com/phpbb/viewtopic.php?f=11&t=20817 ref])
* ATI Radeon 9500 with Omega drivers 3.8.442 ([http://springrts.com/phpbb/viewtopic.php?f=11&t=23526 ref])

====I see the complete screen full of red/green/yellow or giant dots on minimap====

[[File:Redui-minimap-bug.pngâ€Ž|200px]]

This is a bug somewhere in LUA drawing with ATI/AMD. Disable widgets that draw via F11 menu to find the one. There is no real fix. A Widget causing this is "Red UI Minimap", "Highlight Units" or "Chili Minimap". Setting "Max nano simultaneous particles" (SpringSettings) seems to help, too.

====I see big green rectagle on minimap====
[[File:AMD-Minimap-green_rectangle-bug.png|200px]]

Try to set [[Springsettings.cfg#MiniMapDrawProjectiles|MiniMapDrawProjectiles]] in Spring settings to 0.

====The textures looks scary====
[[File:Ati-drawing-issues.jpg|200px]]

This is a known ATI/AMD-bug. Try using different driver, preferably other than 10.5, 10.6, 10.7 -> newer driver pack with fixed OpenGL driver should be fine.

====Units are almost invisible, except for same black pieces====
For example on Radeon X1300/X1550 Series.

[[File:InvisibleUnitBug_Radeon_X1300X1550AdvUnitShading.jpg]]

Set [[Springsettings.cfg#AdvUnitShading]] = 0

====It crashes always at start, hangs etc...====
Check [[infolog.txt]], as it mostly contains hints whats the cause for the crash.
Possible fixes are:
* try the [[springsettings.cfg#Safemode|safemode]] / set [[springsettings.cfg]] safemode values.
* updating or even downgrading [http://support.amd.com/ ATI driver]

==Sound==

===The Sound is crackling/pausing in Windows, what can i do?===
Try:
* Update the sounds driver
* Enable SystemSoundsService in Vista/Seven

===I am having sound problems under Linux! What can i do?===
In more then 90% of the cases, this is caused by PulseAudio. If this is the problem, there are three known solutions to solve it. Use one of them.

====disable sound effects====
Make sure you have the OpenAL-Soft configuration utility. You might want to run:

<code><pre>
# install
sudo apt-get install alsoft-conf
# run
alsoft-conf
</pre></code>

If you're not on a debian-based distribution, you can download the source from the project's homepage: http://www.anduin.net/~angasule/?x=entry:entry091211-133213. You can also check if there's a newer version.
<code><pre>
#download
wget http://www.anduin.net/~angasule/fp-content/attachs/alsoft-conf_1.4.3.tar.gz
#extract
tar xvf alsoft-conf_1.4.3.tar.gz
cd alsoft-conf-1.4.3
#compile
cmake .
make
#run
./alsoft-conf
</pre></code>

In the "Effects" tab remove everything from "Allowed effects".

====disable non-ALSA (preferred)====
run alsoft-conf (for installation see above)

In the "backend" tab, keep only "ALSA" on the left column, then save. Done!

''Side Note:'' ALSA is redirected to the PulseAudio layer when installed.

==Misc==

===Middle mouse button does not work ingame===

If you use Logitech Setpoint be aware that it sets your middle mouse button by default to 'Autoscroll'. It should be set to 'Middle button' instead. Change the setting in Setpoint.

===Spring crashes after Error opening cache\ ... in infolog.txt===

[f=0000000] Reading Estimate PathCosts [8]
[f=0000000] Error opening cache\paths\...

this is a known bug in 0.82.7.1. Your cpu also has many cores?
Then try to set HardwareThreadCount=2" in [[springrc]]. Spring tries to create the PathCache with to many threads in parallel and crashes because out of memory.

===I have a problem that is not described here! What can i do?===
There is a number of things you can do, among these are:
* Search in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum], and ask if you can not find a suiting topic.
* Check the games forum or homepage.
* Look at the [[Gentoo_install#Linux_specific_Troubleshooting|Linux only FAQ]].
* Ask for help in the lobby in a suiting channel, eg: #springlobby, #de, #fr, #ai, #main
* Ask the FAQ-Bot in the lobby in channel #springlobby. To get a list of topics, write ''!faqlist'' and then use ''!faq <topic-name>'' to get the help text. For example, try ''!faq rename''.

===The ingame chat spams a lot of cryptic error messages===
This is most likely a problem with the game's Lua scripting.
Report it in the games forum or its bug tracker.
[[Bugs|Here]] are some hints how to so.

Read Me First

2021-02-07T11:28:44Z

Masterbel: Updated BA link; springfightclub.com now redirects to balancedannhilation.com, so we'll use that address instead.

__NOTOC__= Playing =
'''Spring is an engine!''' It can play many different games and maps. To play, you need at least one [[Games|Game]] and [[Maps|Map]]!

==Getting Started==

To get started with Spring, download [https://springlobby.info/ SpringLobby], which you can use to play, chat and download games and maps.

==Downloading Games/Maps==

'''To download [[Games|Games]] (or [[Maps|Maps]]), use your lobby to join an online battle hosting the game/map that you want. It should offer to download for you.'''

If the download fails, or if no games/maps show up, you should check that your lobby has found your Spring install. With SpringLobby, click edit -> preferences -> Spring, and make sure that it has the correct paths.

You can also download games and maps manually, see the [[FAQ|FAQ]]. There is also the option to install different [[GamesDownloads#Universal_Downloaders|Lobbies]].

==Single-Player==

To start a single-player game, use your lobby. Go to the Single-Player tab. Select a game, map and [[AIs|AI]] and click "Start".

Some AIs don't work with all games. If the one you pick builds nothing, try another!

==Playing Online==
To play online, you need the latest version of the [[Download|Spring Engine]]. To join matches, look for the "battles" or "multiplayer" tab in your lobby client.

== Wondering where some former popular games are? ==
Some larger games run their own lobby servers!
* Zero-k (which grew out of CA) can be found at https://zero-k.info/
* Beyond All Reason (which grew out of BAR) can be found at https://www.beyondallreason.info/
* Balanced Annihilation and some other legacy *A games can be found at at https://balancedannihilation.com/

==Lan Party==
See the dedicated page [[Spring_on_a_LAN|Playing on a lan]].

=Useful Hotkeys, Etc.=

For the default keyboard layout please look at the [[Keyboard]] page.

=The Spring Forum=
[[Forum_Etiquette|Guidelines For Forum Etiquette]]

=Development=
To get started with development check the [[Engine_Development|Development]] page.

=Your question not answered here? Got problems?=
Read the [[FAQ|Frequently Asked Questions]] or ask in the [http://springrts.com/phpbb/viewforum.php?f=11 Forum].
You can also report [[Bugs]] to the developers so they can be fixed.

==Game Specific Questions==
If you have a question or problem with a certain gameplay mechanic in a game, you can talk about it at the [http://springrts.com/phpbb/viewforum.php?f=47 game's subforum]

If Spring crashes/hangs, please look at the [[FAQ:trouble|FAQ]].

[[Category:Help]]

Building Spring on MacOSX

2020-03-04T12:47:29Z

Masterbel: /* Macports */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

This is a guide to the requirements for building the Spring RTS engine on MacOS. If you want only to play a spring game, follow the [[Spring_on_MacOSX]] Tutorial.

=Building Spring on MacOS=

'''This guide is for x86/Intel based MacOS installs'''

Even though it will not run, Spring should successfully compile on Mac for both 104.0 and the latest develop version.

NOTE: Only official spring versions 99.0-103.1 will compile and run on MacOS. 104+ will compile, but uses an incompatible OpenGL version. When 105.0 is released, a MacOS - compatible OpenGL version will be used, however at this point in time '''there are other blocking issues'''.

Questions about this process should be asked [https://springrts.com/phpbb/viewforum.php?f=65 here].

=Requirements=

==Command Line Tools==

Install the [http://developer.apple.com/TOOLS/Xcode/ Xcode developers package] (this requires a free membership to apple's ADC website).

==Package Manager==

Either [http://brew.sh Homebrew] or [http://www.macports.org/install.php MacPorts] may be used to fetch dependencies. The MacOS Buildbot (run by Turboss) uses Homebrew. The writer uses Macports.

== Compiler==

Compiler: GCC must be used, and dependencies must be compiled with GCC

=== MacPorts ===

For MacPorts:
<pre>
port install
sudo port select --set gcc mp-gcc8
hash -r # Reload the terminal
</pre>

To check for installed gcc:
<code>
port select --list gcc
</code>

===HomeBrew===

<pre>
brew install gcc@8
</pre>

==Dependencies==

===MacPorts===

Necessary dependencies for the develop branch are below (as called by Macports):

<pre>
port install sudo port install cmake libsdl2 p7zip libdevil libvorbis minizip openal-soft glew freetype binutils libXcursor +gcc8
</pre>

(This list has not been tested for errors; please message MasterBel if they do not work for you.)

Compiling Spring 104.0 (current master) or older will also require Boost. [https://sourceforge.net/projects/boost/ Retreive source] and compile with gcc. '''TODO: Instructions?'''

===HomeBrew===

Note that this list is incomplete:

<pre>
brew install cmake minizip freetype glew openal-soft p7zip clang-format libvorbis jsoncpp PkgConfig devil sdl2
</pre>

==Obtaining Source==

<code>
git clone --recursive git://github.com/spring/spring.git -b <branch>
</code>

The “master” branch is the latest stable release. “develop” branch is the latest development release. (Note: The recursive argument is important for submodules.) 
Update with: <code>git pull --rebase</code>

=Compiling Source=

<pre>
cmake . -DCMAKE_CXX_COMPILER=/path/to/bin/g++-mp-8 -DCMAKE_C_COMPILER=/path/to/bin/gcc-mp-8
make spring
</pre>

Other common Cmake flags are:
<pre>
-DGLEW_INCLUDE_DIR=/path/to/include
-DGLEW_LIBRARIES=/path/to/lib/libGLEW.a
-DOPENAL_INCLUDE_DIR=/path/to/include/AL
-DCMAKE_INSTALL_PREFIX:PATH=/path/to/output/directory
-DCMAKE_PREFIX_PATH=/path/
</pre>

If boost is used:
<code>
-DBoost_Root=/path/to/boost
</code>

Number of simultaneous jobs may be specified by: <code>make spring -j<n></code> Where n is number of jobs. It is common for n to be number of cores + 1

Other targets may be made also/instead, e.g.

<pre>
make prdownloader -j<n>
make install-spring -j<n>
</pre>

=Additional Notes=

==Using Macports==
As hint: set "buildmakejobs" to cpu-core count + 1 in /opt/local/etc/macports/macports.conf. For example:
<code>
buildmakejobs 5
</code>

==Using Homebrew==

Hombrew can install boost, but it must be recompiled with gcc <version>:
<code>
brew install boost --build-from-source --cc=gcc<version>
</code>

These flags were recommended by a previous editor:
<pre>
cmake . -DAPPLE=1 -DCMAKE_CXX_COMPILER=/usr/local/Cellar/gcc48/4.8.3/bin/g++-4.8 \
-DCMAKE_C_COMPILER=/usr/local/Cellar/gcc48/4.8.3/bin/gcc-4.8 \
-DIL_INCLUDE_DIR=/usr/local/include \
-DGLEW_INCLUDE_DIR=/usr/local/include \
-DOPENAL_DIR=/usr/local/include/AL \
-DNO_SOUND=1
</pre>

=Examples=

==Macports==

<pre>
# Example setup script (for MacOS Catalina)

# Macports must be installed prior to running this script. Macports requires XCode to be installed.
# Boost sources must be located in

# Requires the following directory format:
# $DIR (customisable; set on line 16)
# /setup.sh
# /build.sh
# /Sources
# /boost_1_68_0
# /Builds
# /Bunldes

DIR=~/Spring # The root directory; to be set manually

SCRIPTDIR=~/Documents/Spring/ # The directory the build script is located in

SOURCES=$DIR/Sources
SPRING=$SOURCES/spring
BOOST=$SOURCES/boost_1_66_0/boost

cd $DIR

# Install the necessary compiler. Version gcc5 is oldest compatible with High Sierra; gcc48 is the oldest I know works
sudo port install gcc9

# Set compiler as default
sudo port select --set gcc mp-gcc9
hash -r

sudo port install cmake libsdl2 p7zip libdevil libvorbis minizip openal-soft glew freetype binutils dylibbundler xorg-libXcursor +gcc9
#dylibbundler is for the bundling stage, not actual dependency

cd $SOURCES

# Clone from git (creates the directory $SPRING for us)
git clone --recursive git://github.com/spring/spring.git
cd $SPRING
git fetch --all --tags --prune
git checkout tags/103.0 -b master

# Install Boost

cd $BOOST

./bootstrap.sh --with-toolset=gcc --with-libraries=all # Not sure which libaries.
./b2 # install

# Try compiling spring

cd $SCRIPTDIR

sh build.sh

</pre>

<pre>

# Example buildscript (for MacOS Catalina)

# This script assumes that setup.sh (the above example) has been run.

# Build Configuration

BRANCH=<branch name> # The source branch to checkout and build.
REPOSITORY=spring # The name of the folder containing the git repository.
WIPE=0 # Wipes previous build on WIPE = 1 (flag -w)

for arg in "$@"
do
if [ "$arg" == "-w" ]; then
echo "Initiating clean build."
WIPE=1
else
echo "Unknown flag ${arg}"
fi
done

echo "Building sources at/to ${REPOSITORY}"

# Directory Setup

DIR=~/Spring # Where everything is/will be
SOURCES=$DIR/Sources
SPRING=$SOURCES/$REPOSITORY
BUILD=$DIR/Builds/$REPOSITORY
BOOST=$SOURCES/boost_1_55_0 # Where boost can be found. Must be prepared as per the setup script (above).

MACPORTS=/opt/local # The install directory of MACPORTS

if [ -d $BUILD ]; then
if [ $WIPE != 0 ]; then
echo "Wiping previous build…"
rm -r $BUILD # Wipe preivous build

echo "Making new build directory…"
mkdir $BUILD # The others should have already been made
fi
else
echo "Making new build directory…"
mkdir $BUILD # The others should have already been made
fi

if [ -e $DIR/log.txt ]; then
echo "Removing outdated log…"
rm $DIR/log.txt
fi

# Source setup

if [ -d $SPRING ]; then
cd $SPRING
else
echo "Cloning remote…"
cd $SOURCES
git clone --recursive git://github.com/spring/spring.git $REPOSITORY

cd $SPRING
fi

# Update repository

CURRENTBRANCH=$(git rev-parse --abbrev-ref HEAD)

if [ "$CURRENTBRANCH" != "$BRANCH" ]; then
git fetch --all
echo "Switching branch from ${CURRENTBRANCH} to ${BRANCH}"
git checkout $BRANCH
fi

echo "Updating to latest…"
git pull # Update to latest
echo "Updating submodules"
git submodule update

# Metadata

REV=$(git describe --tags)
VERSION=`echo "${REV}" | tr '<>:\"/\\|?*' -`

# Compile

echo "Compiling Spring ${VERSION}"

cd $BUILD

cmake . $SPRING -DCMAKE_PREFIX_PATH=$MACPORTS -DCMAKE_CXX_COMPILER=$MACPORTS/bin/g++-mp-9 -DCMAKE_C_COMPILER=$MACPORTS/bin/gcc-mp-9 -DGLEW_INCLUDE_DIR=$MACPORTS/include -DGLEW_LIBRARIES=$MACPORTS/lib/libGLEW.a -DOPENAL_INCLUDE_DIR=$MACPORTS/include/AL -DBOOST_ROOT=$BOOST -DBoost_USE_STATIC_LIBS=YES -DCMAKE_CXX_FLAGS="${FLAGS}" -DCMAKE_C_FLAGS="${FLAGS}"

make spring -j5 # >>$DIR/log.txt 2>&1

make pr-downloader # -j5 >>$DIR/log.txt 2>&1

make install-spring DESTDIR=$BUILD/temp #>>$DIR/log.txt 2>&1

# Bundling spring

BUNDLES=$DIR/Bundles
BUNDLE=$BUNDLES/Spring_${VERSION}.app

mkdir $BUNDLES
mkdir $BUNDLE
mkdir $BUNDLE/Contents
mkdir $BUNDLE/Contents/MacOS
mkdir $BUNDLE/Contents/Resources
mkdir $BUNDLE/Contents/lib

cp $BUILD/spring $BUNDLE/Contents/MacOS/spring #>>$DIR/log.txt 2>&1
cp $SPRING/installer/Mac/spring.icns $BUNDLE/Contents/Resources/spring.icns #>>$DIR/log.txt 2>&1
cp -R $BUILD/temp/usr/local/share $BUNDLE/Contents/share #>>$DIR/log.txt 2>&1

cat $SPRING/installer/Mac/Info.plist | sed s/###VERSION###/${VERSION}/ > $BUNDLE/Contents/Info.plist

cp $BUILD/tools/pr-downloader/src/pr-downloader $BUNDLE/Contents/MacOS #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUILD/temp/usr/local/lib/libunitsync.dylib -d $BUNDLE/Contents/MacOS -p @loader_path/../MacOS #>>$DIR/log.txt 2>&1

dylibbundler -of -cd -b -x $BUNDLE/Contents/MacOS/spring -d $BUNDLE/Contents/lib -p @executable_path/../lib #>>$DIR/log.txt 2>&1

install_name_tool -change $MACPORTS/lib/libX11.6.dylib @executable_path/../lib/libX11.6.dylib $BUNDLE/Contents/lib/libXcursor.1.dylib #>>$DIR/log.txt 2>&1

dylibbundler -of -cd -b -x $BUNDLE/Contents/MacOS/pr-downloader -d $BUNDLE/Contents/lib -p @executable_path/../lib #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Interfaces/C/0.1/libAIInterface.dylib -d $BUNDLE/Contents/share/games/spring/AI/Interfaces/C/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Interfaces/Java/0.1/libAIInterface.dylib -d $BUNDLE/Contents/share/games/spring/AI/Interfaces/Java/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/AAI/0.9/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/AAI/0.9 -p @loader_path/../0.9 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/CppTestAI/0.1/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/CppTestAI/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/E323AI/3.25.0/libSkirmishAI.dylib -d $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/E323AI/3.25.0 -p @loader_path/../3.25.0 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/KAIK/0.13/libSkirmishAI.dylib -d $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/KAIK/0.13 -p @loader_path/../0.13 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/NullAI/0.1/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/NullAI/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/RAI/0.601/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/RAI/0.601 -p @loader_path/../0.601 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/Shard/dev/libSkirmishAI.dylib -d $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/Shard/dev -p @loader_path/../dev #>>$DIR/log.txt 2>&1

if [ ! -e $BUNDLE/Contents/MacOS/spring ];then
echo "Error: App did not build correctly. Check log for details"
ERRORBUILD=1
fi

if [ "$ERRORBUILD" = "1" ]; then
echo "Build Failed."
fi

echo "Done!"
exit 0

</pre>

[[Category:Compiling]]

Building Spring on MacOSX

2020-03-04T12:46:29Z

Masterbel: Added example setup & build scripts for Macports

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

This is a guide to the requirements for building the Spring RTS engine on MacOS. If you want only to play a spring game, follow the [[Spring_on_MacOSX]] Tutorial.

=Building Spring on MacOS=

'''This guide is for x86/Intel based MacOS installs'''

Even though it will not run, Spring should successfully compile on Mac for both 104.0 and the latest develop version.

NOTE: Only official spring versions 99.0-103.1 will compile and run on MacOS. 104+ will compile, but uses an incompatible OpenGL version. When 105.0 is released, a MacOS - compatible OpenGL version will be used, however at this point in time '''there are other blocking issues'''.

Questions about this process should be asked [https://springrts.com/phpbb/viewforum.php?f=65 here].

=Requirements=

==Command Line Tools==

Install the [http://developer.apple.com/TOOLS/Xcode/ Xcode developers package] (this requires a free membership to apple's ADC website).

==Package Manager==

Either [http://brew.sh Homebrew] or [http://www.macports.org/install.php MacPorts] may be used to fetch dependencies. The MacOS Buildbot (run by Turboss) uses Homebrew. The writer uses Macports.

== Compiler==

Compiler: GCC must be used, and dependencies must be compiled with GCC

=== MacPorts ===

For MacPorts:
<pre>
port install
sudo port select --set gcc mp-gcc8
hash -r # Reload the terminal
</pre>

To check for installed gcc:
<code>
port select --list gcc
</code>

===HomeBrew===

<pre>
brew install gcc@8
</pre>

==Dependencies==

===MacPorts===

Necessary dependencies for the develop branch are below (as called by Macports):

<pre>
port install sudo port install cmake libsdl2 p7zip libdevil libvorbis minizip openal-soft glew freetype binutils libXcursor +gcc8
</pre>

(This list has not been tested for errors; please message MasterBel if they do not work for you.)

Compiling Spring 104.0 (current master) or older will also require Boost. [https://sourceforge.net/projects/boost/ Retreive source] and compile with gcc. '''TODO: Instructions?'''

===HomeBrew===

Note that this list is incomplete:

<pre>
brew install cmake minizip freetype glew openal-soft p7zip clang-format libvorbis jsoncpp PkgConfig devil sdl2
</pre>

==Obtaining Source==

<code>
git clone --recursive git://github.com/spring/spring.git -b <branch>
</code>

The “master” branch is the latest stable release. “develop” branch is the latest development release. (Note: The recursive argument is important for submodules.) 
Update with: <code>git pull --rebase</code>

=Compiling Source=

<pre>
cmake . -DCMAKE_CXX_COMPILER=/path/to/bin/g++-mp-8 -DCMAKE_C_COMPILER=/path/to/bin/gcc-mp-8
make spring
</pre>

Other common Cmake flags are:
<pre>
-DGLEW_INCLUDE_DIR=/path/to/include
-DGLEW_LIBRARIES=/path/to/lib/libGLEW.a
-DOPENAL_INCLUDE_DIR=/path/to/include/AL
-DCMAKE_INSTALL_PREFIX:PATH=/path/to/output/directory
-DCMAKE_PREFIX_PATH=/path/
</pre>

If boost is used:
<code>
-DBoost_Root=/path/to/boost
</code>

Number of simultaneous jobs may be specified by: <code>make spring -j<n></code> Where n is number of jobs. It is common for n to be number of cores + 1

Other targets may be made also/instead, e.g.

<pre>
make prdownloader -j<n>
make install-spring -j<n>
</pre>

=Additional Notes=

==Using Macports==
As hint: set "buildmakejobs" to cpu-core count + 1 in /opt/local/etc/macports/macports.conf. For example:
<code>
buildmakejobs 5
</code>

==Using Homebrew==

Hombrew can install boost, but it must be recompiled with gcc <version>:
<code>
brew install boost --build-from-source --cc=gcc<version>
</code>

These flags were recommended by a previous editor:
<pre>
cmake . -DAPPLE=1 -DCMAKE_CXX_COMPILER=/usr/local/Cellar/gcc48/4.8.3/bin/g++-4.8 \
-DCMAKE_C_COMPILER=/usr/local/Cellar/gcc48/4.8.3/bin/gcc-4.8 \
-DIL_INCLUDE_DIR=/usr/local/include \
-DGLEW_INCLUDE_DIR=/usr/local/include \
-DOPENAL_DIR=/usr/local/include/AL \
-DNO_SOUND=1
</pre>

=Examples=

==Macports==

<code>
# Example setup script (for MacOS Catalina)

# Macports must be installed prior to running this script. Macports requires XCode to be installed.
# Boost sources must be located in

# Requires the following directory format:
# $DIR (customisable; set on line 16)
# /setup.sh
# /build.sh
# /Sources
# /boost_1_68_0
# /Builds
# /Bunldes

DIR=~/Spring # The root directory; to be set manually

SCRIPTDIR=~/Documents/Spring/ # The directory the build script is located in

SOURCES=$DIR/Sources
SPRING=$SOURCES/spring
BOOST=$SOURCES/boost_1_66_0/boost

cd $DIR

# Install the necessary compiler. Version gcc5 is oldest compatible with High Sierra; gcc48 is the oldest I know works
sudo port install gcc9

# Set compiler as default
sudo port select --set gcc mp-gcc9
hash -r

sudo port install cmake libsdl2 p7zip libdevil libvorbis minizip openal-soft glew freetype binutils dylibbundler xorg-libXcursor +gcc9
#dylibbundler is for the bundling stage, not actual dependency

cd $SOURCES

# Clone from git (creates the directory $SPRING for us)
git clone --recursive git://github.com/spring/spring.git
cd $SPRING
git fetch --all --tags --prune
git checkout tags/103.0 -b master

# Install Boost

cd $BOOST

./bootstrap.sh --with-toolset=gcc --with-libraries=all # Not sure which libaries.
./b2 # install

# Try compiling spring

cd $SCRIPTDIR

sh build.sh

</code>

<code>

# Example buildscript (for MacOS Catalina)

# This script assumes that setup.sh (the above example) has been run.

# Build Configuration

BRANCH=<branch name> # The source branch to checkout and build.
REPOSITORY=spring # The name of the folder containing the git repository.
WIPE=0 # Wipes previous build on WIPE = 1 (flag -w)

for arg in "$@"
do
if [ "$arg" == "-w" ]; then
echo "Initiating clean build."
WIPE=1
else
echo "Unknown flag ${arg}"
fi
done

echo "Building sources at/to ${REPOSITORY}"

# Directory Setup

DIR=~/Spring # Where everything is/will be
SOURCES=$DIR/Sources
SPRING=$SOURCES/$REPOSITORY
BUILD=$DIR/Builds/$REPOSITORY
BOOST=$SOURCES/boost_1_55_0 # Where boost can be found. Must be prepared as per the setup script (above).

MACPORTS=/opt/local # The install directory of MACPORTS

if [ -d $BUILD ]; then
if [ $WIPE != 0 ]; then
echo "Wiping previous build…"
rm -r $BUILD # Wipe preivous build

echo "Making new build directory…"
mkdir $BUILD # The others should have already been made
fi
else
echo "Making new build directory…"
mkdir $BUILD # The others should have already been made
fi

if [ -e $DIR/log.txt ]; then
echo "Removing outdated log…"
rm $DIR/log.txt
fi

# Source setup

if [ -d $SPRING ]; then
cd $SPRING
else
echo "Cloning remote…"
cd $SOURCES
git clone --recursive git://github.com/spring/spring.git $REPOSITORY

cd $SPRING
fi

# Update repository

CURRENTBRANCH=$(git rev-parse --abbrev-ref HEAD)

if [ "$CURRENTBRANCH" != "$BRANCH" ]; then
git fetch --all
echo "Switching branch from ${CURRENTBRANCH} to ${BRANCH}"
git checkout $BRANCH
fi

echo "Updating to latest…"
git pull # Update to latest
echo "Updating submodules"
git submodule update

# Metadata

REV=$(git describe --tags)
VERSION=`echo "${REV}" | tr '<>:\"/\\|?*' -`

# Compile

echo "Compiling Spring ${VERSION}"

cd $BUILD

cmake . $SPRING -DCMAKE_PREFIX_PATH=$MACPORTS -DCMAKE_CXX_COMPILER=$MACPORTS/bin/g++-mp-9 -DCMAKE_C_COMPILER=$MACPORTS/bin/gcc-mp-9 -DGLEW_INCLUDE_DIR=$MACPORTS/include -DGLEW_LIBRARIES=$MACPORTS/lib/libGLEW.a -DOPENAL_INCLUDE_DIR=$MACPORTS/include/AL -DBOOST_ROOT=$BOOST -DBoost_USE_STATIC_LIBS=YES -DCMAKE_CXX_FLAGS="${FLAGS}" -DCMAKE_C_FLAGS="${FLAGS}"

make spring -j5 # >>$DIR/log.txt 2>&1

make pr-downloader # -j5 >>$DIR/log.txt 2>&1

make install-spring DESTDIR=$BUILD/temp #>>$DIR/log.txt 2>&1

# Bundling spring

BUNDLES=$DIR/Bundles
BUNDLE=$BUNDLES/Spring_${VERSION}.app

mkdir $BUNDLES
mkdir $BUNDLE
mkdir $BUNDLE/Contents
mkdir $BUNDLE/Contents/MacOS
mkdir $BUNDLE/Contents/Resources
mkdir $BUNDLE/Contents/lib

cp $BUILD/spring $BUNDLE/Contents/MacOS/spring #>>$DIR/log.txt 2>&1
cp $SPRING/installer/Mac/spring.icns $BUNDLE/Contents/Resources/spring.icns #>>$DIR/log.txt 2>&1
cp -R $BUILD/temp/usr/local/share $BUNDLE/Contents/share #>>$DIR/log.txt 2>&1

cat $SPRING/installer/Mac/Info.plist | sed s/###VERSION###/${VERSION}/ > $BUNDLE/Contents/Info.plist

cp $BUILD/tools/pr-downloader/src/pr-downloader $BUNDLE/Contents/MacOS #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUILD/temp/usr/local/lib/libunitsync.dylib -d $BUNDLE/Contents/MacOS -p @loader_path/../MacOS #>>$DIR/log.txt 2>&1

dylibbundler -of -cd -b -x $BUNDLE/Contents/MacOS/spring -d $BUNDLE/Contents/lib -p @executable_path/../lib #>>$DIR/log.txt 2>&1

install_name_tool -change $MACPORTS/lib/libX11.6.dylib @executable_path/../lib/libX11.6.dylib $BUNDLE/Contents/lib/libXcursor.1.dylib #>>$DIR/log.txt 2>&1

dylibbundler -of -cd -b -x $BUNDLE/Contents/MacOS/pr-downloader -d $BUNDLE/Contents/lib -p @executable_path/../lib #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Interfaces/C/0.1/libAIInterface.dylib -d $BUNDLE/Contents/share/games/spring/AI/Interfaces/C/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Interfaces/Java/0.1/libAIInterface.dylib -d $BUNDLE/Contents/share/games/spring/AI/Interfaces/Java/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/AAI/0.9/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/AAI/0.9 -p @loader_path/../0.9 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/CppTestAI/0.1/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/CppTestAI/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/E323AI/3.25.0/libSkirmishAI.dylib -d $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/E323AI/3.25.0 -p @loader_path/../3.25.0 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/KAIK/0.13/libSkirmishAI.dylib -d $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/KAIK/0.13 -p @loader_path/../0.13 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/NullAI/0.1/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/NullAI/0.1 -p @loader_path/../0.1 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/RAI/0.601/libSkirmishAI.dylib -d $BUNDLE/Contents/share/games/spring/AI/Skirmish/RAI/0.601 -p @loader_path/../0.601 #>>$DIR/log.txt 2>&1

dylibbundler -cd -b -x $BUNDLE/Contents/share/games/spring/AI/Skirmish/Shard/dev/libSkirmishAI.dylib -d $BUILD/Spring.app/Contents/share/games/spring/AI/Skirmish/Shard/dev -p @loader_path/../dev #>>$DIR/log.txt 2>&1

if [ ! -e $BUNDLE/Contents/MacOS/spring ];then
echo "Error: App did not build correctly. Check log for details"
ERRORBUILD=1
fi

if [ "$ERRORBUILD" = "1" ]; then
echo "Build Failed."
fi

echo "Done!"
exit 0

</code>

[[Category:Compiling]]

Building Spring on MacOSX

2018-12-30T15:15:20Z

Masterbel: /* Obtaining Source */ Formatting tweak

Building Spring on MacOSX

2018-12-30T15:14:37Z

Masterbel: /* Compiling Source */ formatting tweak

Building Spring on MacOSX

2018-12-30T15:13:52Z

Masterbel: Fix formating

Building Spring on MacOSX

2018-12-28T08:54:44Z

Masterbel: /* Compiling Source: fix */

Building Spring on MacOSX

2018-12-28T07:52:22Z

Masterbel: Grammar error

Building Spring on MacOSX

2018-12-28T07:50:33Z

Masterbel: Rewrite the guide to (hopefully) be cleaner, and (definitely) be more up-to-date

Building Spring on MacOSX

2018-12-28T07:41:26Z

Masterbel: Rewrite the guide to (hopefully) be cleaner, and (definitely) be more up-to-date