Module SyncedRead

Synced Read

---

See also:

• rts/Lua/LuaSyncedRead.cpp

Teams

Spring.GetGaiaTeamID

Spring.GetAllyTeamStartBox

Spring.GetTeamStartPosition

xyz

Cartesian triple (XYZ)

Spring.GetMapStartPositions

Spring.GetAllyTeamList

Spring.GetTeamList

Spring.GetPlayerList

Spring.GetTeamInfo

Spring.GetTeamAllyTeamID

Spring.GetTeamResources

Spring.GetTeamUnitStats

Spring.GetTeamResourceStats

Spring.GetTeamDamageStats

Gets team damage dealt/received totals

teamStats

Spring.GetTeamStatsHistory

Spring.GetTeamLuaAI

Spring.GetTeamMaxUnits

Returns a team's unit cap.

Spring.GetPlayerInfo

Spring.GetPlayerControlledUnit

Returns unit controlled by player on FPS mode

Spring.GetAIInfo

Spring.GetAllyTeamInfo

Spring.AreTeamsAllied

Spring.ArePlayersAllied

Misc

Spring.GetUnitEstimatedPath

Spring.GetUnitLastAttacker

Spring.GetUnitLastAttackedPiece

Spring.GetUnitCollisionVolumeData

Spring.GetUnitSeparation

Spring.GetUnitFeatureSeparation

Spring.GetUnitDefDimensions

Spring.GetCEGID

Spring.GetUnitBlocking

Spring.GetUnitMoveTypeData

Spring.GetUnitCurrentCommand

cmdOpts

Parameters for command options

cmd

Command

Spring.GetUnitCommands

Get the number or list of commands for a unit

Spring.GetFactoryCommands

Get the number or list of commands for a factory

unitID

Get the number of commands in a units queue.

Spring.GetFactoryBuggerOff

Spring.GetFactoryCounts

Gets the build queue of a factory

Spring.GetCommandQueue

Get the number or list of commands for a unit

Spring.GetFullBuildQueue

Returns the build queue

Spring.GetRealBuildQueue

Returns the build queue cleaned of things the unit can't build itself

Spring.GetUnitCmdDescs

Spring.FindUnitCmdDesc

Spring.ValidFeatureID

Spring.GetAllFeatures

Spring.GetFeatureDefID

Spring.GetFeatureTeam

Spring.GetFeatureAllyTeam

Spring.GetFeatureHealth

Spring.GetFeatureHeight

Spring.GetFeatureRadius

Spring.GetFeatureMass

Spring.GetFeaturePosition

Spring.GetFeatureSeparation

Spring.GetFeatureRotation

Spring.GetFeatureDirection

Spring.GetFeatureVelocity

Spring.GetFeatureHeading

Spring.GetFeatureResources

Spring.GetFeatureBlocking

Spring.GetFeatureNoSelect

Spring.GetFeatureResurrect

Spring.GetFeatureLastAttackedPiece

Spring.GetFeatureCollisionVolumeData

Spring.GetFeaturePieceCollisionVolumeData

Spring.GetRadarErrorParams

Game States

Spring.IsCheatingEnabled

Spring.IsGodModeEnabled

Spring.IsDevLuaEnabled

Spring.IsEditDefsEnabled

Spring.IsNoCostEnabled

Spring.GetGlobalLos

Spring.AreHelperAIsEnabled

Spring.FixedAllies

Spring.IsGameOver

Speed/Time

Spring.GetGameFrame

Spring.GetGameSeconds

Environment

Spring.GetTidal

Spring.GetWind

Rules/Params

Spring.GetGameRulesParams

Spring.GetTeamRulesParams

Spring.GetPlayerRulesParams

Spring.GetUnitRulesParams

Spring.GetFeatureRulesParams

Spring.GetGameRulesParam

Spring.GetTeamRulesParam

Spring.GetPlayerRulesParam

Spring.GetUnitRulesParam

Spring.GetFeatureRulesParam

Mod and Map options

Spring.GetMapOption

Spring.GetMapOptions

Spring.GetModOption

Spring.GetModOptions

Vectors

Spring.GetHeadingFromVector

Spring.GetVectorFromHeading

Spring.GetFacingFromHeading

Spring.GetHeadingFromFacing

Sides and Factions

sideSpec

Side spec

Spring.GetSideData

Spring.GetSideData

Spring.GetSideData

Unit queries

Spring.GetAllUnits

Get a list of all unitIDs

Spring.GetTeamUnits

Spring.GetTeamUnitsSorted

Spring.GetTeamUnitsCounts

Spring.GetTeamUnitsByDefs

Spring.GetTeamUnitDefCount

Spring.GetTeamUnitCount

Spatial unit queries

Spring.GetUnitsInRectangle

Spring.GetUnitsInBox

Spring.GetUnitsInCylinder

Spring.GetUnitsInSphere

planeSpec

Spring.GetUnitsInPlanes

Spring.GetUnitArrayCentroid

Returns the centroid of an array of units

Spring.GetUnitMapCentroid

Returns the centroid of a map of units

Spring.GetUnitNearestAlly

Spring.GetUnitNearestEnemy

Spatial feature queries

Spring.GetFeaturesInRectangle

Spring.GetFeaturesInSphere

Spring.GetFeaturesInCylinder

Spring.GetProjectilesInRectangle

Unit state

Spring.ValidUnitID

unitState

Spring.GetUnitStates

Spring.GetUnitArmored

Spring.GetUnitIsActive

Spring.GetUnitIsCloaked

Spring.GetUnitSeismicSignature

Spring.GetUnitSelfDTime

Spring.GetUnitStockpile

Spring.GetUnitSensorRadius

Spring.GetUnitPosErrorParams

Spring.GetUnitTooltip

Spring.GetUnitDefID

Spring.GetUnitTeam

Spring.GetUnitAllyTeam

Spring.GetUnitNeutral

Checks if a unit is neutral (NOT Gaia!)

Spring.GetUnitHealth

Spring.GetUnitIsDead

Spring.GetUnitIsStunned

Checks whether a unit is disabled and can't act

The first return value is a simple OR of the following ones, any of those conditions is sufficient to disable the unit.

Spring.GetUnitIsBeingBuilt

Spring.GetUnitResources

Spring.GetUnitCosts

Spring.GetUnitCostTable

Spring.GetUnitMetalExtraction

Spring.GetUnitExperience

Spring.GetUnitHeight

Spring.GetUnitRadius

Spring.GetUnitBuildeeRadius

Spring.GetUnitMass

Spring.GetUnitPosition

Spring.GetUnitBasePosition

Spring.GetUnitVectors

Spring.GetUnitRotation

Spring.GetUnitDirection

Spring.GetUnitHeading

Spring.GetUnitVelocity

Spring.GetUnitBuildFacing

Spring.GetUnitIsBuilding

Checks whether a unit is currently building another (NOT for checking if it's a structure)

Spring.GetUnitWorkerTask

Checks a builder's current task

Spring.GetUnitEffectiveBuildRange

Spring.GetUnitCurrentBuildPower

Spring.GetUnitHarvestStorage

Get a unit's carried resources

Spring.GetUnitBuildParams

Spring.GetUnitInBuildStance

Is builder in build stance

Spring.GetUnitNanoPieces

Get construction FX attachment points

Spring.GetUnitTransporter

Get the transport carrying the unit

Spring.GetUnitIsTransporting

Get units being transported

Spring.GetUnitShieldState

Spring.GetUnitFlanking

Spring.GetUnitMaxRange

Get a unit's engagement range

Unit weapon state

Spring.GetUnitWeaponState

Check the state of a unit's weapon

Spring.GetUnitWeaponDamages

Spring.GetUnitWeaponVectors

Spring.GetUnitWeaponTryTarget

Spring.GetUnitWeaponTestTarget

Spring.GetUnitWeaponTestRange

Spring.GetUnitWeaponHaveFreeLineOfFire

Spring.GetUnitWeaponCanFire

Spring.GetUnitWeaponTarget

Checks a weapon's target

Projectile state

Spring.GetProjectilePosition

Spring.GetProjectileDirection

Spring.GetProjectileVelocity

Spring.GetProjectileGravity

Spring.GetPieceProjectileParams

Spring.GetProjectileTarget

Spring.GetProjectileIsIntercepted

Spring.GetProjectileTimeToLive

Spring.GetProjectileOwnerID

Spring.GetProjectileTeamID

Spring.GetProjectileAllyTeamID

Spring.GetProjectileType

Spring.GetProjectileDefID

Spring.GetProjectileDamages

Ground

Spring.IsPosInMap

Spring.GetGroundHeight

Get ground height

Spring.GetWaterPlaneLevel

Get water plane height

Water may at some point become shaped (rivers etc) but for now it is always a flat plane.

Spring.GetWaterLevel

Get water level in a specific position

Water is currently a flat plane, so this returns the same value regardless of XZ.

Spring.GetGroundOrigHeight

Get ground height as it was at game start

Spring.GetGroundNormal

Spring.GetGroundInfo

Spring.GetGroundBlocked

Spring.GetGroundExtremes

Spring.GetTerrainTypeData

Spring.GetGrass

Spring.GetSmoothMeshHeight

Tests

Spring.TestMoveOrder

Spring.TestBuildOrder

Spring.Pos2BuildPos

Snaps a position to the building grid

Spring.ClosestBuildPos

Visibility

Spring.GetPositionLosState

Spring.IsPosInLos

Spring.IsPosInRadar

Spring.IsPosInAirLos

Spring.GetUnitLosState

Spring.IsUnitInLos

Spring.IsUnitInAirLos

Spring.IsUnitInRadar

Spring.IsUnitInJammer

Piece/Script

pieceSpec

Piece spec

Spring.GetModelRootPiece

Spring.GetModelPieceMap

Spring.GetModelPieceList

Spring.GetUnitRootPiece

Spring.GetUnitPieceMap

Spring.GetUnitPieceList

Spring.GetUnitPieceInfo

Spring.GetUnitPiecePosDir

Spring.GetUnitPiecePosition

Spring.GetUnitPieceDirection

Spring.GetUnitPieceMatrix

Spring.GetFeatureRootPiece

Spring.GetFeaturePieceMap

Spring.GetFeaturePieceList

Spring.GetFeaturePieceInfo

Spring.GetFeaturePiecePosDir

Spring.GetFeaturePiecePosition

Spring.GetFeaturePieceDirection

Spring.GetFeaturePieceMatrix

Spring.GetUnitScriptPiece

Spring.GetUnitScriptNames

Teams

---

Spring.GetGaiaTeamID()

Returns:

1. number teamID

Spring.GetAllyTeamStartBox(allyID)

Parameters:

1. allyID number

Returns:

1. number xMin
2. number zMin
3. number xMax
4. number zMax

Spring.GetTeamStartPosition(teamID)

Parameters:

1. teamID number

Returns:

1. number x
2. number y
3. number x

xyz

Cartesian triple (XYZ)

Fields:

1. x number
2. y number
3. z number

Spring.GetMapStartPositions()

Returns:

1. {xyz,...} array of positions indexed by teamID

Spring.GetAllyTeamList()

Returns:

1. {number,...} list of allyTeamIDs

Spring.GetTeamList([allyTeamID=-1])

Parameters:

1. allyTeamID number to filter teams belonging to when >= 0 (default -1)

Returns:

1. nil or {number,...} list of teamIDs

Spring.GetPlayerList([teamID=-1[, active=false]])

Parameters:

1. teamID number to filter by when >= 0 (default -1)
2. active bool whether to filter only active teams (default false)

Returns:

1. nil or {number,...} list of playerIDs

Spring.GetTeamInfo(teamID[, getTeamKeys=true])

Parameters:

1. teamID number
2. getTeamKeys bool whether to return the customTeamKeys table (default true)

Returns:

1. nil or number teamID
2. number leader
3. number isDead
4. number hasAI
5. string side
6. number allyTeam
7. number incomeMultiplier
8. {[string]=string,...} customTeamKeys when getTeamKeys is true, otherwise nil

Spring.GetTeamAllyTeamID(teamID)

Parameters:

1. teamID number

Returns:

1. nil or allyTeamID

Spring.GetTeamResources(teamID, resource)

Parameters:

1. teamID number
2. resource string one of "m(etal)?|e(nergy)?"

Returns:

1. nil or number currentLevel
2. number storage
3. number pull
4. number income
5. number expense
6. number share
7. number sent
8. number received

Spring.GetTeamUnitStats(teamID)

Parameters:

1. teamID number

Returns:

1. nil or number killed
2. number died
3. number capturedBy
4. number capturedFrom
5. number received
6. number sent

Spring.GetTeamResourceStats(teamID, resource)

Parameters:

1. teamID number
2. resource string one of "m(etal)?|e(nergy)?"

Returns:

1. nil or number used
2. number produced
3. number excessed
4. number received
5. number sent

Spring.GetTeamDamageStats(teamID)

Gets team damage dealt/received totals

Returns a team's damage stats. Note that all damage is counted, including self-inflicted and unconfirmed out-of-sight.

Parameters:

1. teamID number

Returns:

1. number damageDealt
2. number damageReceived

teamStats

Fields:

1. time number
2. frame number
3. metalUsed number
4. metalProduced number
5. metalExcess number
6. metalReceived number
7. metalSent number
8. energyUsed number
9. energyProduced number
10. energyExcess number
11. energyReceived number
12. energySent number
13. damageDealt number
14. damageReceived number
15. unitsProduced number
16. unitsDied number
17. unitsReceived number
18. unitsSent number
19. unitsCaptured number
20. unitsOutCaptured number

Spring.GetTeamStatsHistory(teamID[, startIndex[, endIndex=startIndex]])

Parameters:

1. teamID number
2. startIndex number when not specified return the number of history entries (optional)
3. endIndex number (default startIndex)

Returns:

1. nil, number or {teamStats,...}

Spring.GetTeamLuaAI(teamID)

Parameters:

1. teamID number

Returns:

1. string

Spring.GetTeamMaxUnits(teamID)

Returns a team's unit cap.

Also returns the current unit count for readable teams as the 2nd value.

Parameters:

1. teamID number

Returns:

1. number maxUnits
2. nil or number currentUnits

Spring.GetPlayerInfo(playerID[, getPlayerOpts=true])

Parameters:

1. playerID number
2. getPlayerOpts bool whether to return custom player options (default true)

Returns:

1. nil or string name
2. bool active
3. bool spectator
4. number teamID
5. number allyTeamID
6. number pingTime
7. number cpuUsage
8. string country
9. number rank
10. bool hasSkirmishAIsInTeam
11. {[string]=string} playerOpts when playerOpts is true
12. bool desynced

Spring.GetPlayerControlledUnit(playerID)

Returns unit controlled by player on FPS mode

Parameters:

1. playerID number

Returns:

1. nil or number

Spring.GetAIInfo(teamID)

Parameters:

1. teamID number

Returns:

1. number skirmishAIID
2. string name
3. number hostingPlayerID
4. string shortName when synced "SYNCED_NOSHORTNAME", otherwise the AI shortname or "UNKNOWN"
5. string version when synced "SYNCED_NOVERSION", otherwise the AI version or "UNKNOWN"
6. {[string]=string,...} options

Spring.GetAllyTeamInfo(allyTeamID)

Parameters:

1. allyTeamID number

Returns:

1. nil or {[string]=string,...}

Spring.AreTeamsAllied(teamID1, teamID2)

Parameters:

1. teamID1 number
2. teamID2 number

Returns:

1. nil or bool

Spring.ArePlayersAllied(playerID1, playerID2)

Parameters:

1. playerID1 number
2. playerID2 number

Returns:

1. nil or bool

Misc

---

Spring.GetUnitEstimatedPath(unitID)

Parameters:

1. unitID number

Spring.GetUnitLastAttacker(unitID)

Parameters:

1. unitID number

Spring.GetUnitLastAttackedPiece(unitID)

Parameters:

1. unitID number

Spring.GetUnitCollisionVolumeData(unitID)

Parameters:

1. unitID number

Spring.GetUnitSeparation(unitID1, unitID2[, direction=false[, subtractRadii=false]])

Parameters:

1. unitID1 number
2. unitID2 number
3. direction bool to subtract from, default unitID1 - unitID2 (default false)
4. subtractRadii bool whether units radii should be subtracted from the total (default false)

Returns:

1. nil or number

Spring.GetUnitFeatureSeparation(unitID)

Parameters:

1. unitID number

Spring.GetUnitDefDimensions(unitDefID)

Parameters:

1. unitDefID number

Spring.GetCEGID()

Spring.GetUnitBlocking(unitID)

Parameters:

1. unitID number

Returns:

1. nil or bool isBlocking
2. bool isSolidObjectCollidable
3. bool isProjectileCollidable
4. bool isRaySegmentCollidable
5. bool crushable
6. bool blockEnemyPushing
7. bool blockHeightChanges

Spring.GetUnitMoveTypeData(unitID)

Parameters:

1. unitID number

Spring.GetUnitCurrentCommand(unitID, cmdIndex)

Parameters:

1. unitID number Unit id.
2. cmdIndex number Command index to get. If negative will count from the end of the queue, for example -1 will be the last command.

cmdOpts

Parameters for command options

Fields:

1. coded number
2. alt bool
3. ctrl bool
4. shift bool
5. right bool
6. meta bool
7. internal bool

cmd

Command

Fields:

1. id number
2. params {number,...}
3. options cmdOpts
4. tag number

Spring.GetUnitCommands(unitID, count)

Get the number or list of commands for a unit

Same as Spring.GetCommandQueue

Parameters:

1. unitID number
2. count number when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise

Returns:

1. number or {cmd,...} commands

Spring.GetFactoryCommands(unitID, count)

Get the number or list of commands for a factory

Parameters:

1. unitID number
2. count number when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise

Returns:

1. number or {cmd,...} commands

unitID

Get the number of commands in a units queue.

1. unitID number

Spring.GetFactoryBuggerOff(unitID)

Parameters:

1. unitID number

Spring.GetFactoryCounts(unitID[, count=-1[, addCmds=false]])

Gets the build queue of a factory

Parameters:

1. unitID number
2. count number then number of commands to retrieve, when -1 all (default -1)
3. addCmds bool if commands other than buildunit are retrieved (default false)

Returns:

1. nil or {{[number]=number,...}} counts indexed by unitDefID or -cmdID

Spring.GetCommandQueue(unitID, count)

Get the number or list of commands for a unit

Same as Spring.GetUnitCommands

Parameters:

1. unitID number
2. count number when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise

Returns:

1. number or {cmd,...} commands

Spring.GetFullBuildQueue(unitID)

Returns the build queue

Parameters:

1. unitID number

Returns:

1. nil or {[number]=number,...} buildqueue indexed by unitDefID with count values

Spring.GetRealBuildQueue(unitID)

Returns the build queue cleaned of things the unit can't build itself

Parameters:

1. unitID number

Returns:

1. nil or {[number]=number,...} buildqueue indexed by unitDefID with count values

Spring.GetUnitCmdDescs(unitID)

Parameters:

1. unitID number

Spring.FindUnitCmdDesc(unitID)

Parameters:

1. unitID number

Spring.ValidFeatureID(featureID)

Parameters:

1. featureID number

Returns:

1. bool

Spring.GetAllFeatures()

Spring.GetFeatureDefID(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number

Spring.GetFeatureTeam(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number

Spring.GetFeatureAllyTeam(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number

Spring.GetFeatureHealth(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number health
2. number defHealth
3. number resurrectProgress

Spring.GetFeatureHeight(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number

Spring.GetFeatureRadius(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number

Spring.GetFeatureMass(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number

Spring.GetFeaturePosition(featureID)

Parameters:

1. featureID number

Spring.GetFeatureSeparation(featureID1, featureID2[, direction=false])

Parameters:

1. featureID1 number
2. featureID2 number
3. direction bool to subtract from, default featureID1 - featureID2 (default false)

Returns:

1. nil or number

Spring.GetFeatureRotation(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number pitch, rotation in X axis
2. number yaw, rotation in Y axis
3. number roll, rotation in Z axis

Spring.GetFeatureDirection(featureID)

Parameters:

1. featureID number

Returns:

1. nil or dirX
2. dirY
3. dirZ

Spring.GetFeatureVelocity(featureID)

Parameters:

1. featureID number

Spring.GetFeatureHeading(featureID)

Parameters:

1. featureID number

Spring.GetFeatureResources(featureID)

Parameters:

1. featureID number

Returns:

1. nil or number metal
2. number defMetal
3. number energy
4. number defEnergy
5. number reclaimLeft
6. number reclaimTime

Spring.GetFeatureBlocking(featureID)

Parameters:

1. featureID number

Returns:

1. nil or bool isBlocking
2. bool isSolidObjectCollidable
3. bool isProjectileCollidable
4. bool isRaySegmentCollidable
5. bool crushable
6. bool blockEnemyPushing
7. bool blockHeightChanges

Spring.GetFeatureNoSelect(featureID)

Parameters:

1. featureID number

Returns:

1. nil or bool

Spring.GetFeatureResurrect(featureID)

Parameters:

1. featureID number

Spring.GetFeatureLastAttackedPiece(featureID)

Parameters:

1. featureID number

Spring.GetFeatureCollisionVolumeData(featureID)

Parameters:

1. featureID number

Spring.GetFeaturePieceCollisionVolumeData(featureID)

Parameters:

1. featureID number

Spring.GetRadarErrorParams(allyTeamID)

Parameters:

1. allyTeamID number

Returns:

1. nil or number radarErrorSize actual radar error size (when allyTeamID is allied to current team) or base radar error size
2. number baseRadarErrorSize
3. number baseRadarErrorMult

Game States

---

Spring.IsCheatingEnabled()

Returns:

1. bool enabled

Spring.IsGodModeEnabled()

Returns:

1. bool enabled

Spring.IsDevLuaEnabled()

Returns:

1. bool enabled

Spring.IsEditDefsEnabled()

Returns:

1. bool enabled

Spring.IsNoCostEnabled()

Returns:

1. bool enabled

Spring.GetGlobalLos([teamID])

Parameters:

1. teamID number (optional)

Returns:

1. bool enabled

Spring.AreHelperAIsEnabled()

Returns:

1. bool enabled

Spring.FixedAllies()

Returns:

1. bool or nil enabled

Spring.IsGameOver()

Returns:

1. bool isGameOver

Speed/Time

---

Spring.GetGameFrame()

Returns:

1. number t1 frameNum % dayFrames
2. number t2 frameNum / dayFrames

Spring.GetGameSeconds()

Returns:

1. number seconds

Environment

---

Spring.GetTidal()

Returns:

1. number tidalStrength

Spring.GetWind()

Returns:

1. number windStrength

Rules/Params

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!)

---

Spring.GetGameRulesParams()

Returns:

1. {[string] = number,...} rulesParams map with rules names as key and values as values

Spring.GetTeamRulesParams(teamID)

Parameters:

1. teamID number

Returns:

1. {[string] = number,...} rulesParams map with rules names as key and values as values

Spring.GetPlayerRulesParams(playerID)

Parameters:

1. playerID number

Returns:

1. {[string] = number,...} rulesParams map with rules names as key and values as values

Spring.GetUnitRulesParams(unitID)

Parameters:

1. unitID number

Returns:

1. {[string] = number,...} rulesParams map with rules names as key and values as values

Spring.GetFeatureRulesParams(featureID)

Parameters:

1. featureID number

Returns:

1. {[string] = number,...} rulesParams map with rules names as key and values as values

Spring.GetGameRulesParam(ruleRef)

Parameters:

1. ruleRef number or string the rule index or name

Returns:

1. nil, number or string value

Spring.GetTeamRulesParam(teamID, ruleRef)

Parameters:

1. teamID number
2. ruleRef number or string the rule index or name

Returns:

1. nil, number or string value

Spring.GetPlayerRulesParam(playerID, ruleRef)

Parameters:

1. playerID number
2. ruleRef number or string the rule index or name

Returns:

1. nil, number or string value

Spring.GetUnitRulesParam(unitID, ruleRef)

Parameters:

1. unitID number
2. ruleRef number or string the rule index or name

Returns:

1. nil, number or string value

Spring.GetFeatureRulesParam(featureID, ruleRef)

Parameters:

1. featureID number
2. ruleRef number or string the rule index or name

Returns:

1. nil, number or string value

Mod and Map options

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:

 if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end

The following check therefore is insufficient!

 if (Spring.GetModOptions.exampleOption) then...end

---

Spring.GetMapOption(mapOption)

Parameters:

1. mapOption string

Returns:

1. string value of mapOption

Spring.GetMapOptions()

Returns:

1. {[string] = string,...} options map with options names as keys and values as values

Spring.GetModOption(modOption)

Parameters:

1. modOption string

Returns:

1. string value of modOption in option map

Spring.GetModOptions()

Returns:

1. {[string] = string,...} options map with options names as keys and values as values

Vectors

---

Spring.GetHeadingFromVector(x, z)

Parameters:

1. x number
2. z number

Returns:

1. number heading

Spring.GetVectorFromHeading(heading)

Parameters:

1. heading number

Returns:

1. number x
2. number z

Spring.GetFacingFromHeading(heading)

Parameters:

1. heading number

Returns:

1. number facing

Spring.GetHeadingFromFacing(facing)

Parameters:

1. facing number

Returns:

1. number heading

Sides and Factions

---

sideSpec

Side spec

Used when returning arrays of side specifications, is itself an array with positional values as below:

Fields:

1. sideName string
2. caseName string
3. startUnit string

Spring.GetSideData(sideName)

Parameters:

1. sideName string

Returns:

1. nil or string startUnit
2. string caseSensitiveSideName

Spring.GetSideData(sideID)

Parameters:

1. sideID number

Returns:

1. nil or string sideName
2. string startUnit
3. string caseSensitiveSideName

Spring.GetSideData()

Returns:

1. {[sideSpec],...} sideArray

Unit queries

---

Spring.GetAllUnits()

Get a list of all unitIDs

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.

Returns:

1. {number,...} unitIDs

See also:

• UnsyncedRead.GetVisibleUnits

Spring.GetTeamUnits(teamID)

Parameters:

1. teamID number

Returns:

1. nil or {number,...} unitIDs

Spring.GetTeamUnitsSorted(teamID)

Parameters:

1. teamID number

Returns:

1. nil or {[number]={number,...}} where keys are unitDefIDs and values are unitIDs

Spring.GetTeamUnitsCounts(teamID)

Parameters:

1. teamID number

Returns:

1. nil or {[number]=number} where keys are unitDefIDs and values are counts

Spring.GetTeamUnitsByDefs(teamID, unitDefIDs)

Parameters:

1. teamID number
2. unitDefIDs number or {number,...}

Returns:

1. nil or {number,...} unitIDs

Spring.GetTeamUnitDefCount(teamID, unitDefID)

Parameters:

1. teamID number
2. unitDefID number

Returns:

1. nil or number count

Spring.GetTeamUnitCount(teamID)

Parameters:

1. teamID number

Returns:

1. nil or number count

Spatial unit queries

For the allegiance parameters: AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4

---

Spring.GetUnitsInRectangle(xmin, zmin, xmax, zmax[, allegiance])

Parameters:

1. xmin number
2. zmin number
3. xmax number
4. zmax number
5. allegiance number (optional)

Returns:

1. {number,...} unitIDs

Spring.GetUnitsInBox(xmin, ymin, zmin, xmax, ymax, zmax[, allegiance])

Parameters:

1. xmin number
2. ymin number
3. zmin number
4. xmax number
5. ymax number
6. zmax number
7. allegiance number (optional)

Returns:

1. {number,...} unitIDs

Spring.GetUnitsInCylinder(x, z, radius)

Parameters:

1. x number
2. z number
3. radius number

Returns:

1. {number,...} unitIDs

Spring.GetUnitsInSphere(x, y, z, radius)

Parameters:

1. x number
2. y number
3. z number
4. radius number

Returns:

1. {number,...} unitIDs

planeSpec

Fields:

1. normalVecX number
2. normalVecY number
3. normalVecZ number
4. d number

Spring.GetUnitsInPlanes(planes[, allegiance])

Plane normals point towards accepted space, so the acceptance criteria for each plane is: radius = unit radius px, py, pz = unit position [(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0

Parameters:

1. planes {planeSpec,...}
2. allegiance number (optional)

Returns:

1. nil or {number,...} unitIDs

Spring.GetUnitArrayCentroid(units)

Returns the centroid of an array of units

Returns nil for an empty array

Parameters:

1. units table { unitID, unitID, ... }

Returns:

1. number centerX
2. number centerY
3. number centerZ

Spring.GetUnitMapCentroid(units)

Returns the centroid of a map of units

Returns nil for an empty map

Parameters:

1. units table { [unitID] = true, [unitID] = true, ... }

Returns:

1. number centerX
2. number centerY
3. number centerZ

Spring.GetUnitNearestAlly(unitID[, range=1.0e9f])

Parameters:

1. unitID number
2. range number (default 1.0e9f)

Returns:

1. nil or number unitID

Spring.GetUnitNearestEnemy(unitID[, range=1.0e9f[, useLOS=true]])

Parameters:

1. unitID number
2. range number (default 1.0e9f)
3. useLOS bool (default true)

Returns:

1. nil or number unitID

Spatial feature queries

---

Spring.GetFeaturesInRectangle(xmin, zmin, xmax, zmax)

Parameters:

1. xmin number
2. zmin number
3. xmax number
4. zmax number

Returns:

1. {number,...} featureIDs

Spring.GetFeaturesInSphere(x, y, z, radius)

Parameters:

1. x number
2. y number
3. z number
4. radius number

Returns:

1. {number,...} featureIDs

Spring.GetFeaturesInCylinder(x, z, radius[, allegiance])

Parameters:

1. x number
2. z number
3. radius number
4. allegiance number (optional)

Returns:

1. {number,...} featureIDs

Spring.GetProjectilesInRectangle(xmin, zmin, xmax, zmax[, excludeWeaponProjectiles=false[, excludePieceProjectiles=false]])

Parameters:

1. xmin number
2. zmin number
3. xmax number
4. zmax number
5. excludeWeaponProjectiles bool (default false)
6. excludePieceProjectiles bool (default false)

Returns:

1. {number,...} projectileIDs

Unit state

---

Spring.ValidUnitID(unitID)

Parameters:

1. unitID number

Returns:

1. bool

unitState

Fields:

1. firestate number
2. movestate number
3. repeat bool
4. cloak bool
5. active bool
6. trajectory bool
7. autoland bool optional
8. autorepairlevel number optional
9. loopbackattack bool optional

Spring.GetUnitStates(unitID)

Parameters:

1. unitID number

Returns:

1. {unitState,...}

Spring.GetUnitArmored(unitID)

Parameters:

1. unitID number

Returns:

1. nil or bool armored
2. number armorMultiple

Spring.GetUnitIsActive(unitID)

Parameters:

1. unitID number

Returns:

1. nil or bool

Spring.GetUnitIsCloaked(unitID)

Parameters:

1. unitID number

Returns:

1. nil or bool

Spring.GetUnitSeismicSignature(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitSelfDTime(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitStockpile(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number numStockpiled
2. number numStockpileQued
3. number buildPercent

Spring.GetUnitSensorRadius(unitID, type)

Parameters:

1. unitID number
2. type string one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer

Returns:

1. nil or number radius

Spring.GetUnitPosErrorParams(unitID[, allyTeamID])

Parameters:

1. unitID number
2. allyTeamID number (optional)

Returns:

1. nil or number posErrorVectorX
2. number posErrorVectorY
3. number posErrorVectorZ
4. number posErrorDeltaX
5. number posErrorDeltaY
6. number posErrorDeltaZ
7. number nextPosErrorUpdatebaseErrorMult
8. bool posErrorBit

Spring.GetUnitTooltip(unitID)

Parameters:

1. unitID number

Returns:

1. nil or string

Spring.GetUnitDefID(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitTeam(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitAllyTeam(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitNeutral(unitID)

Checks if a unit is neutral (NOT Gaia!)

Note that a "neutral" unit can belong to any ally-team (ally, enemy, Gaia). To check if a unit is Gaia, check its owner team.

Parameters:

1. unitID number

Returns:

1. nil or bool

Spring.GetUnitHealth(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number health
2. number maxHealth
3. number paralyzeDamage
4. number captureProgress
5. number buildProgress between 0.0-1.0

Spring.GetUnitIsDead(unitID)

Parameters:

1. unitID number

Returns:

1. nil or bool

Spring.GetUnitIsStunned(unitID)

Checks whether a unit is disabled and can't act The first return value is a simple OR of the following ones, any of those conditions is sufficient to disable the unit.

Note that EMP and being transported are mechanically the same and thus lumped together. Use other callouts to differentiate them if you need to.

Parameters:

1. unitID number

Returns:

1. nil or bool stunnedOrBuilt unit is disabled
2. bool stunned unit is either stunned via EMP or being transported by a non-fireplatform
3. bool beingBuilt unit is under construction

Spring.GetUnitIsBeingBuilt(unitID)

Parameters:

1. unitID number

Returns:

1. bool beingBuilt
2. number buildProgress

Spring.GetUnitResources(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number metalMake
2. number metalUse
3. number energyMake
4. number energyUse

Spring.GetUnitCosts(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number buildTime
2. number metalCost
3. number energyCost

Spring.GetUnitCostTable(unitID)

Parameters:

1. unitID number

Returns:

1. nil or { metal = number, energy = number }
2. number buildTime

Spring.GetUnitMetalExtraction(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitExperience(unitID)

Parameters:

1. unitID number

Returns:

1. number XP [0.0; +∞)
2. number limXP [0.0; 1.0) as experience approaches infinity

Spring.GetUnitHeight(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitRadius(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitBuildeeRadius(unitID)

Gets the unit's radius for when targeted by build, repair, reclaim-type commands.

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitMass(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number

Spring.GetUnitPosition(unitID[, midPos=false[, aimPos=false]])

Parameters:

1. unitID number
2. midPos bool return midpoint as well (default false)
3. aimPos bool return aimpoint as well (default false)

Returns:

1. nil or number basePointX
2. number basePointY
3. number basePointZ
4. nil or number midPointX
5. number midPointY
6. number midPointZ
7. nil or number aimPointX
8. number aimPointY
9. number aimPointZ

Spring.GetUnitBasePosition(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number posX
2. number posY
3. number posZ

Spring.GetUnitVectors(unitID)

Parameters:

1. unitID number

Returns:

1. nil or xyz front
2. xyz up
3. xyz right

Spring.GetUnitRotation(unitID)

Parameters:

1. unitID number

Returns:

1. nil or number pitch, rotation in X axis
2. number yaw, rotation in Y axis
3. number roll, rotation in Z axis

Spring.GetUnitDirection(unitID)

Parameters:

1. unitID number

Returns:

1. nil or dirX
2. dirY
3. dirZ

Spring.GetUnitHeading(unitID[, convertToRadians=false])

Parameters:

1. unitID number
2. convertToRadians bool (default false)

Returns:

1. heading

Spring.GetUnitVelocity(unitID)

Parameters:

1. unitID number

Spring.GetUnitBuildFacing(unitID)

Parameters:

1. unitID number

Spring.GetUnitIsBuilding(unitID)

Checks whether a unit is currently building another (NOT for checking if it's a structure)

Works for both mobile builders and factories.

Parameters:

1. unitID number

Returns:

1. number buildeeUnitID or nil

Spring.GetUnitWorkerTask(unitID)

Checks a builder's current task

Checks what a builder is currently doing. This is not the same as `Spring.GetUnitCurrentCommand`, because you can have a command at the front of the queue and not be doing it (for example because the target is still too far away), and on the other hand you can also be doing a task despite not having it in front of the queue (for example you're Guarding another builder who does). Also, it resolves the Repair command into either actual repair, or construction assist (in which case it returns the appropriate "build" command). Only build-related commands are returned (no Move or any custom commands). The possible commands returned are repair, reclaim, resurrect, capture, restore, and build commands (negative buildee unitDefID).

Parameters:

1. unitID number

Returns:

1. number cmdID of the relevant command
2. number targetID if applicable (all except RESTORE)

Spring.GetUnitEffectiveBuildRange(unitID, buildeeDefID)

Useful for setting move goals manually.

Parameters:

1. unitID number
2. buildeeDefID number or nil

Returns:

1. number effectiveBuildRange counted to the center of prospective buildee; buildRange if buildee nil

Spring.GetUnitCurrentBuildPower(unitID)

Parameters:

1. unitID number

Spring.GetUnitHarvestStorage(unitID)

Get a unit's carried resources

Checks resources being carried internally by the unit.

Parameters:

1. unitID number

Returns:

1. number storedMetal
2. number maxStoredMetal
3. number storedEnergy
4. number maxStoredEnergy

Spring.GetUnitBuildParams(unitID)

Parameters:

1. unitID number

Spring.GetUnitInBuildStance(unitID)

Is builder in build stance

Checks if a builder is in build stance, i.e. can create nanoframes. Returns nil for non-builders.

Parameters:

1. unitID number

Returns:

1. bool inBuildStance

Spring.GetUnitNanoPieces(unitID)

Get construction FX attachment points

Returns an array of pieces which represent construction points. Default engine construction FX (nano spray) will originate there. Only works on builders and factories, returns nil (NOT empty table) for other units.

Parameters:

1. unitID number

Returns:

1. pieceArray {pieceID, pieceID, ...}

Spring.GetUnitTransporter(unitID)

Get the transport carrying the unit

Returns the unit ID of the transport, if any. Returns nil if the unit is not being transported.

Parameters:

1. unitID number

Returns:

1. number or nil transportUnitID

Spring.GetUnitIsTransporting(unitID)

Get units being transported

Returns an array of unitIDs being transported by this unit. Returns nil (NOT an empty array) for units that are not transports.

Parameters:

1. unitID number

Returns:

1. transporteeArray {unitID, unitID, ...}

Spring.GetUnitShieldState(unitID[, weaponNum])

Parameters:

1. unitID number
2. weaponNum number Optional if the unit has just one shield (optional)

Returns:

1. number isEnabled Warning, number not bool. 0 or 1
2. number currentPower

Spring.GetUnitFlanking(unitID)

Parameters:

1. unitID number

Spring.GetUnitMaxRange(unitID)

Get a unit's engagement range

Returns the range at which a unit will stop to engage. By default this is the highest among the unit's weapon ranges (hence name), but can be changed dynamically. Also note that unarmed units ignore this.

Parameters:

1. unitID number

Returns:

1. number maxRange

Unit weapon state

---

Spring.GetUnitWeaponState(unitID, weaponNum, stateName)

Check the state of a unit's weapon

Available states to poll: "reloadFrame" (frame on which the weapon will be ready to fire), "reloadSpeed" (reload time in seconds), "range" (in elmos), "autoTargetRangeBoost" (predictive aiming range buffer, in elmos), "projectileSpeed" (in elmos/frame), "reloadTimeXP" (reload time after XP bonus, in seconds), "reaimTime" (frames between AimWeapon calls), "burst" (shots in a burst), "burstRate" (delay between shots in a burst, in seconds), "projectiles" (projectiles per shot), "salvoLeft" (shots remaining in ongoing burst), "nextSalvo" (simframe of the next shot in an ongoing burst), "accuracy" (INaccuracy after XP bonus), "sprayAngle" (spray angle after XP bonus), "targetMoveError" (extra inaccuracy against moving targets, after XP bonus) "avoidFlags" (bitmask for targeting avoidance), "collisionFlags" (bitmask for collisions). The state "salvoError" is an exception and returns a table: {x, y, z}, which represents the inaccuracy error of the ongoing burst.

Parameters:

1. unitID number
2. weaponNum number
3. stateName string

Returns:

1. number stateValue

Spring.GetUnitWeaponDamages(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponVectors(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponTryTarget(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponTestTarget(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponTestRange(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponHaveFreeLineOfFire(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponCanFire(unitID)

Parameters:

1. unitID number

Spring.GetUnitWeaponTarget(unitID, weaponNum)

Checks a weapon's target

Note that this doesn't need to reflect the unit's Attack orders or such, and that weapons can aim individually unless slaved.

Parameters:

1. unitID number
2. weaponNum number

Returns:

1. number targetType (0: none, 1: unit, 2: position, 3: projectile)
2. boolean isUserTarget
3. target (depending on type, 0: nil, 1: unitID, 2: table {x, y, z}, 3: projectileID)

Projectile state

---

Spring.GetProjectilePosition(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number posX
2. number posY
3. number posZ

Spring.GetProjectileDirection(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number dirX
2. number dirY
3. number dirZ

Spring.GetProjectileVelocity(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number velX
2. number velY
3. number velZ
4. number velW

Spring.GetProjectileGravity(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number

Spring.GetPieceProjectileParams(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number explosionFlags encoded bitwise with SHATTER = 1, EXPLODE = 2, EXPLODEONHIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NOCEGTRAIL = 64, NO_HEATCLOUD = 128
2. number spinAngle
3. number spinSpeed
4. number spinVectorX
5. number spinVectorY
6. number spinVectorZ

Spring.GetProjectileTarget(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number targetTypeInt where string.byte('g') := GROUND string.byte('u') := UNIT string.byte('f') := FEATURE string.byte('p') := PROJECTILE
2. number or xyz target targetID or targetPos when targetTypeInt == string.byte('g')

Spring.GetProjectileIsIntercepted(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or bool

Spring.GetProjectileTimeToLive(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number

Spring.GetProjectileOwnerID(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number

Spring.GetProjectileTeamID(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number

Spring.GetProjectileAllyTeamID(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or number

Spring.GetProjectileType(projectileID)

Parameters:

1. projectileID number

Returns:

1. nil or bool weapon
2. bool piece

Spring.GetProjectileDefID(projectileID)

Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

Parameters:

1. projectileID number

Returns:

1. nil or number

Spring.GetProjectileDamages(projectileID, tag)

Parameters:

1. projectileID number
2. tag string

   one of:

    "paralyzeDamageTime"
    "impulseFactor"
    "impulseBoost"
    "craterMult"
    "craterBoost"
    "dynDamageExp"
    "dynDamageMin"
    "dynDamageRange"
    "dynDamageInverted"
    "craterAreaOfEffect"
    "damageAreaOfEffect"
    "edgeEffectiveness"
    "explosionSpeed"
    - or -
    an armor type index to get the damage against it.
   

Returns:

1. nil or number

Ground

---

Spring.IsPosInMap(x, z)

Parameters:

1. x number
2. z number

Returns:

1. boolean inPlayArea whether the position is in the active play area
2. boolean inMap whether the position is in the full map area (currently this is the same as above)

Spring.GetGroundHeight(x, z)

Get ground height

On sea, this returns the negative depth of the seafloor

Parameters:

1. x number
2. z number

Returns:

1. number

Spring.GetWaterPlaneLevel()

Get water plane height Water may at some point become shaped (rivers etc) but for now it is always a flat plane.

Use this function instead of GetWaterLevel to denote you are relying on that assumption.

Returns:

1. number waterPlaneLevel

See also:

• Spring.GetWaterLevel

Spring.GetWaterLevel(x, z)

Get water level in a specific position Water is currently a flat plane, so this returns the same value regardless of XZ.

However water may become more dynamic at some point so by using this you are future-proof.

Parameters:

1. x number
2. z number

Returns:

1. number waterLevel

Spring.GetGroundOrigHeight(x, z)

Get ground height as it was at game start

Returns the original height before the ground got deformed

Parameters:

1. x number
2. z number

Returns:

1. number

Spring.GetGroundNormal(x, z[, smoothed=false])

Parameters:

1. x number
2. z number
3. smoothed bool raw or smoothed center normal (default false)

Returns:

1. number normalX
2. number normalY
3. number normalZ
4. number slope

Spring.GetGroundInfo(x, z)

Parameters:

1. x number
2. z number

Returns:

1. number ix
2. number iz
3. number terrainTypeIndex
4. string name
5. number metalExtraction
6. number hardness
7. number tankSpeed
8. number kbotSpeed
9. number hoverSpeed
10. number shipSpeed
11. bool receiveTracks

Spring.GetGroundBlocked()

Spring.GetGroundExtremes()

Returns:

1. number initMinHeight
2. number initMaxHeight
3. number currMinHeight
4. number currMaxHeight

Spring.GetTerrainTypeData(terrainTypeInfo)

Parameters:

1. terrainTypeInfo number

Returns:

1. number index
2. string name
3. number hardness
4. number tankSpeed
5. number kbotSpeed
6. number hoverSpeed
7. number shipSpeed
8. bool receiveTracks

Spring.GetGrass(x, z)

Parameters:

1. x number
2. z number

Returns:

1. number

Spring.GetSmoothMeshHeight(x, z)

Parameters:

1. x number
2. z number

Returns:

1. number height

Tests

---

Spring.TestMoveOrder(unitDefID, testTerrain, testObjects, centerOnly)

Parameters:

1. unitDefID number
2. testTerrain bool (default true)
3. testObjects bool (default true)
4. centerOnly bool (default false)

Returns:

1. bool

Spring.TestBuildOrder(unitDefID, x, y, z, facing)

Parameters:

1. unitDefID number
2. x number
3. y number
4. z number
5. facing number or string one of: 0-s,1-e,2-n,3-w

Returns:

1. number blocking one of: 0 = blocked, 1 = mobile unit on the way, 2 = reclaimable, 3 = open
2. nil or featureID when there's a reclaimable feature on the way

Spring.Pos2BuildPos(unitDefID, posX, posY, posZ[, buildFacing=0])

Snaps a position to the building grid

Parameters:

1. unitDefID number
2. posX number
3. posY number
4. posZ number
5. buildFacing number one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3 (default 0)

Returns:

1. number buildPosX
2. number buildPosY
3. number buildPosZ

Spring.ClosestBuildPos(teamID, unitDefID, posX, posY, posZ, searchRadius, minDistance, buildFacing)

Parameters:

1. teamID number
2. unitDefID number
3. posX number
4. posY number
5. posZ number
6. searchRadius number
7. minDistance number
8. buildFacing number one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3

Returns:

1. number buildPosX
2. number buildPosY
3. number buildPosZ

Visibility

---

Spring.GetPositionLosState(posX, posY, posZ[, allyTeamID])

Parameters:

1. posX number
2. posY number
3. posZ number
4. allyTeamID number (optional)

Returns:

1. bool inLosOrRadar
2. inLos
3. inRadar
4. inJammer

Spring.IsPosInLos(posX, posY, posZ[, allyTeamID])

Parameters:

1. posX number
2. posY number
3. posZ number
4. allyTeamID number (optional)

Returns:

1. bool

Spring.IsPosInRadar(posX, posY, posZ[, allyTeamID])

Parameters:

1. posX number
2. posY number
3. posZ number
4. allyTeamID number (optional)

Returns:

1. bool

Spring.IsPosInAirLos(posX, posY, posZ[, allyTeamID])

Parameters:

1. posX number
2. posY number
3. posZ number
4. allyTeamID number (optional)

Returns:

1. bool

Spring.GetUnitLosState(unitID[, allyTeamID[, raw=false]])

Parameters:

1. unitID number
2. allyTeamID number (optional)
3. raw bool (default false)

Returns:

1. nil, number or {los=bool,radar=bool,typed=bool} los

   Raw is only available in gadgets and when raw parameter is true.

   RAW returns an bitmask integer, where the bits are: 1: LOSINLOS, the unit is currently in the los of the allyteam, 2: LOSINRADAR the unit is currently in radar from the allyteam, 4: LOSPREVLOS the unit has previously been in los from the allyteam, 8: LOSCONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam

Spring.IsUnitInLos(unitID, allyTeamID)

Parameters:

1. unitID number
2. allyTeamID number

Returns:

1. bool inLos

Spring.IsUnitInAirLos(unitID, allyTeamID)

Parameters:

1. unitID number
2. allyTeamID number

Returns:

1. bool inAirLos

Spring.IsUnitInRadar(unitID, allyTeamID)

Parameters:

1. unitID number
2. allyTeamID number

Returns:

1. bool inRadar

Spring.IsUnitInJammer(unitID, allyTeamID)

Parameters:

1. unitID number
2. allyTeamID number

Returns:

1. bool inJammer

Piece/Script

---

pieceSpec

Piece spec

Fields:

1. name string
2. parent string
3. children {[string],...} names
4. empty bool
5. min {number,number,number} (x,y,z)
6. max {number,number,number} (x,y,z)
7. offset {number,number,number} (x,y,z)

Spring.GetModelRootPiece(modelName)

Parameters:

1. modelName string

Returns:

1. number index of the root piece

Spring.GetModelPieceMap(modelName)

Parameters:

1. modelName string

Returns:

1. nil or {[string]=number,...} pieceInfos where keys are piece names and values are indices

Spring.GetModelPieceList(modelName)

Parameters:

1. modelName string

Returns:

1. nil or {[string],...} pieceNames

Spring.GetUnitRootPiece(unitID)

Parameters:

1. unitID number

Returns:

1. number index of the root piece

Spring.GetUnitPieceMap(unitID)

Parameters:

1. unitID number

Returns:

1. nil or {[string]=number,...} pieceInfos where keys are piece names and values are indices

Spring.GetUnitPieceList(unitID)

Parameters:

1. unitID number

Returns:

1. {[string],...} pieceNames

Spring.GetUnitPieceInfo(unitID, pieceIndex)

Parameters:

1. unitID number
2. pieceIndex number

Returns:

1. nil or pieceSpec pieceInfo

Spring.GetUnitPiecePosDir(unitID, pieceIndex)

Parameters:

1. unitID number
2. pieceIndex number

Returns:

1. number or nil posX
2. number posY
3. number posZ
4. number dirX
5. number dirY
6. number dirZ

Spring.GetUnitPiecePosition(unitID, pieceIndex)

Parameters:

1. unitID number
2. pieceIndex number

Returns:

1. number or nil posX
2. number posY
3. number posZ

Spring.GetUnitPieceDirection(unitID, pieceIndex)

Parameters:

1. unitID number
2. pieceIndex number

Returns:

1. number or nil dirX
2. number dirY
3. number dirZ

Spring.GetUnitPieceMatrix(unitID)

Parameters:

1. unitID number

Returns:

1. number or nil m11
2. number m12
3. number m13
4. number m14
5. number m21
6. number m22
7. number m23
8. number m24
9. number m31
10. number m32
11. number m33
12. number m34
13. number m41
14. number m42
15. number m43
16. number m44

Spring.GetFeatureRootPiece(featureID)

Parameters:

1. featureID number

Returns:

1. number index of the root piece

Spring.GetFeaturePieceMap(featureID)

Parameters:

1. featureID number

Returns:

1. {[string]=number,...} pieceInfos where keys are piece names and values are indices

Spring.GetFeaturePieceList(featureID)

Parameters:

1. featureID number

Returns:

1. {[string],...} pieceNames

Spring.GetFeaturePieceInfo(featureID, pieceIndex)

Parameters:

1. featureID number
2. pieceIndex number

Returns:

1. nil or pieceSpec pieceInfo

Spring.GetFeaturePiecePosDir(featureID, pieceIndex)

Parameters:

1. featureID number
2. pieceIndex number

Returns:

1. number or nil posX
2. number posY
3. number posZ
4. number dirX
5. number dirY
6. number dirZ

Spring.GetFeaturePiecePosition(featureID, pieceIndex)

Parameters:

1. featureID number
2. pieceIndex number

Returns:

1. number or nil posX
2. number posY
3. number posZ

Spring.GetFeaturePieceDirection(featureID, pieceIndex)

Parameters:

1. featureID number
2. pieceIndex number

Returns:

1. number or nil dirX
2. number dirY
3. number dirZ

Spring.GetFeaturePieceMatrix(featureID)

Parameters:

1. featureID number

Returns:

1. number or nil m11
2. number m12
3. number m13
4. number m14
5. number m21
6. number m22
7. number m23
8. number m24
9. number m31
10. number m32
11. number m33
12. number m34
13. number m41
14. number m42
15. number m43
16. number m44

Spring.GetUnitScriptPiece(unitID[, scriptPiece])

Parameters:

1. unitID number
2. scriptPiece number (optional)

Returns:

1. {number,...} or number pieceIndices when scriptPiece is not specified, pieceIndex otherwise

Spring.GetUnitScriptNames(unitID)

Parameters:

1. unitID number

Returns:

1. {[string]=number,...} where keys are piece names and values are piece indices