Game

Special TeamID Variables

(those special TeamIDs are not supported by all functions)
Spring.ALL_UNITS
Spring.MY_UNITS
Spring.ALLY_UNITS
Spring.ENEMY_UNITS

Spring.GetGaiaTeamID

 ( ) -> number teamID

GameStates

Spring.IsGodModeEnabled

 ( ) -> boolean

Spring.IsCheatingEnabled

 ( ) -> boolean

Spring.IsDevLuaEnabled

 ( ) -> boolean

Spring.IsEditDefsEnabled

 ( ) -> boolean

Spring.AreHelperAIsEnabled

 ( ) -> boolean

Spring.IsGameOver

 ( ) -> boolean

Rules

Spring.GetRulesInfoMap

 ( ) -> { [key1] = string value1, [key2] = string value2, ... }
 ( string "key" ) -> string

Spring.GetGameRulesParam

 ( number index | string ruleName ) -> number value

Spring.GetGameRulesParams

 ( ) -> { [rule1] = number value1, [rule2] = number value2, ... }

Spring.GetTeamRulesParam

 ( number teamID, number index | string ruleName ) -> nil | number value

Spring.GetTeamRulesParams

 ( number teamID ) -> nil | { [rule1] = number value1, [rule2] = number value2, ... }

Spring.GetUnitRulesParam

 ( number unitID, number index | string ruleName ) -> nil | number value

Spring.GetUnitRulesParams

 ( number unitID ) -> nil | { [rule1] = number value1, [rule2] = number value2, ... }

Mod-/Map-Options

Spring.GetModOptions

 ( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }

Spring.GetMapOptions

 ( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }

Speed/Time

Spring.GetGameSpeed

 ( ) -> number userSpeedFactor, number speedFactor, boolean paused

Spring.GetGameFrame

 ( ) -> number frameNum%dayFrames, number frameNum/dayFrames

Spring.GetGameSeconds

 ( ) -> number seconds

Vectors

Spring.GetWind

 ( ) -> number dirX, number dirY, number dirZ, 
        number strength,  number normDirX, number normDirY, number normDirZ

Spring.GetHeadingFromVector

 ( number x, number z ) -> number heading

Spring.GetVectorFromHeading

 ( number heading ) -> number x, number z

Teams

StartBoxes/StartPositions

Spring.GetAllyTeamStartBox

 ( number allyID ) -> nil | number xmin, number zmin, number xmax, number zmax

Spring.GetTeamStartPosition

 ( number teamID ) -> nil | number x, number y, number z

Player,Team,Ally Lists/Info

Spring.GetPlayerList

 ( [number teamID, boolean onlyActive] ) -> nil | { [1] = number playerID, etc... }

Spring.GetTeamList

 ( [number allyTeamID] ) -> nil | { [1] = number teamID, etc... }

Spring.GetAllyTeamList

 ( ) -> { [1] = number allyTeamID, etc... }

Spring.GetPlayerInfo

 ( number playerID ) -> 
   nil | string  "name",  (in synced code this is "SYNCED_NONAME"!)
         boolean active,
         boolean spectator,
         number  teamID,
         number  allyTeamID,
         number  pingTime,
         number  cpuUsage,
         string  country,
         number  rank

Spring.GetPlayerControlledUnit

 ( number playerID ) -> nil | number unitID

Spring.GetTeamInfo

 ( number teamID ) ->
   nil | number  teamNum,
         number  leader,
         boolean isDead,
         boolean isAiTeam,
         string  "side",
         number  allyTeam

Spring.GetTeamResources

 ( number teamID, string "metal" | "energy" ) ->
   nil | number currentLevel,
         number storage,
         number pull,
         number income,
         number expense,
         number share,
         number sent,
         number received

Spring.GetTeamUnitStats

 ( number teamID ) ->
   nil | number killed,
         number died,
         number capturedBy,
         number capturedFrom,
         number received,
         number sent

Spring.GetTeamStatsHistory

 ( number teamID, number startTime, number endTime ) ->
   {
     [1] = {
       "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
     }, ...
  }

Spring.GetTeamLuaAI

 ( number teamID ) -> string "luaAI"

Teams/PlayersAllied

Spring.AreTeamsAllied

 ( number teamID1, number teamID2 ) -> nil | boolean

Spring.ArePlayersAllied

 ( number playerID1, number playerID2 ) -> nil | boolean

Units

GetUnits

Spring.GetAllUnits

 ( ) -> nil | unitTable = { [1] = number unitID, ... }

Spring.GetTeamUnits

 ( number teamID ) -> nil | unitTable = { [1] = number unitID, etc... }

Spring.GetTeamUnitsSorted

 ( number teamID ) -> nil |
   unitDefTable = {
     [number unitDefID] = { [1] = [number unitID], etc... },
     etc...
   }

Spring.GetTeamUnitsCounts

 ( number teamID ) -> nil | countTable = { [number unitDefID] = count, etc... }

Spring.GetTeamUnitsByDefs

 ( number teamID, number unitDefID | { number unitDefID1, ... } )
   -> nil | unitTable = { [1] = number unitID, etc... }

Spring.GetTeamUnitDefCount

 ( number teamID, number unitDefID ) -> nil | number count

Spring.GetTeamUnitCount

 ( number teamID ) -> nil | number count

Spring.GetUnitsInRectangle

 ( number xmin, number zmin, number xmax, number zmax [,number teamID] ) 
   -> nil | unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInBox

 ( number xmin, number ymin, number zmin,
   number xmax, number ymax, number zmax [,number teamID] )
   -> nil | unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInSphere

 ( number x, number y, number z, number radius [,number teamID] )
   -> nil | unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInCylinder

 ( number x, number z, number radius [,number teamID] )
   -> nil | unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInPlanes

 ( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
   -> nil | unitTable = { [1] = number unitID, etc... }

 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

Spring.GetUnitNearestAlly

 ( number unitID [, number range ] ) -> nil | number unitID

Spring.GetUnitNearestEnemy

 ( number unitID [, number range ] ) -> nil | number unitID

Unit Informations

Spring.GetUnitTooltip

 ( number unitID ) -> nil | string tooltip

Spring.GetUnitDefID

 ( number unitID ) -> nil | number unitDefID

Spring.GetUnitTeam

 ( number unitID ) -> nil | number teamID

Spring.GetUnitAllyTeam

 ( number unitID ) -> nil | number allyID

Spring.GetUnitLineage

 ( number unitID ) -> nil | number lineage, boolean lineageRoot

Spring.GetUnitNeutral

 ( number unitID ) -> nil | boolean neutral

Spring.GetUnitHealth

 ( number unitID ) -> nil | number health, number maxHealth, number paralyzeDamage,
                            number captureProgress, number buildProgress

Spring.GetUnitIsDead

 ( number unitID ) -> nil | boolean dead

Spring.GetUnitIsStunned

 ( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild

Spring.GetUnitResources

 ( number unitID ) -> nil | number metalMake, number metalUse,
                            number energyMake, number energyUse

Spring.GetUnitExperience

 ( number unitID ) -> nil | number experience

Spring.GetUnitStates

 ( number unitID ) -> nil | {
   "firestate" = number,
   "movestate" = number,
   "repeat" = boolean,
   "cloak" = boolean,
   "active" = boolean,
   "trajectory" = boolean,
   ["autoland" = boolean,]
   ["autorepairlevel" = number,]
   ["loopbackattack" = boolean]
 } 

Spring.GetUnitIsActive

 ( number unitID ) -> nil | boolean

Spring.GetUnitIsCloaked

 ( number unitID ) -> nil | boolean

Spring.GetUnitSelfDTime

 ( number unitID ) -> nil | number

Spring.GetUnitStockpile

 ( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
                            number buildPercent

Spring.GetUnitHeight

 ( number unitID ) -> nil | number

Spring.GetUnitRadius

 ( number unitID ) -> nil | number

Spring.GetUnitPosition

 ( number unitID ) -> nil | number x, number y, number z

Spring.GetUnitBasePosition

 ( number unitID ) -> nil | number x, number y, number z

Spring.GetUnitDirection

 ( number unitID ) -> nil | number dx, number dy, number dz

Spring.GetUnitHeading

 ( number unitID ) -> nil | number heading

Spring.GetUnitVelocity

 ( number unitID ) -> nil | number velx, number vely, number velz

Spring.GetUnitBuildFacing

 ( number unitID ) -> nil | number

Spring.GetUnitIsBuilding

 ( number unitID ) -> nil | number unitID

Spring.GetUnitTransporter

 ( number unitID ) -> nil | number unitID

Spring.GetUnitIsTransporting

 ( number unitID ) -> nil | { [1] = number unitID, etc... }

Spring.GetUnitShieldState

 ( number unitID ) -> nil | number isEnabled, number curPower

Spring.GetUnitWeaponState

 ( number unitID [, number weaponNum] ) -> nil | 
 boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled

Spring.GetUnitTravel

 ( number unitID ) -> nil | number travel, number travelPeriod

Spring.GetUnitLosState

 ( number unitID [, number allyTeamID ] ) -> nil |
   { ["los" = true] [, "radar" = true] [, "typed" = true] }

Spring.GetUnitSeparation (returns the distance of 2 units)

 ( number unitID1, number unitID2 [, boolean 2D ] ) -> nil | number distance

Spring.GetUnitDefDimensions

 ( number unitDefID ) -> nil |
   {
     "height" = number,
     "radius" = number,
     "midx"   = number,
     "minx"   = number,
     "maxx"   = number,
     "midy"   = number,
     "miny"   = number,
     "maxy"   = number,
     "midz"   = number,
     "minz"   = number,
     "maxz"   = number
   }

CommandQueues

Spring.GetUnitCommands

 ( number unitID [, number count] ) -> nil | commandQueueTable = {
    [1] = {
      "id"      = number,
      "params"  = { [1] = number, ...},
      "options" = {
        "coded"    = number,
        "alt"      = boolean,
        "ctrl"     = boolean,
        "shift"    = boolean,
        "right"    = boolean,
        "internal" = boolean
      }
    }, ...
  }

Spring.GetCommandQueue (same as Spring.GetUnitCommands)

 ( number unitID [, number count] ) -> nil | commandQueueTable = {
    [1] = {
      "id"      = number,
      "params"  = { [1] = number, ...},
      "options" = {
        "coded"    = number,
        "alt"      = boolean,
        "ctrl"     = boolean,
        "shift"    = boolean,
        "right"    = boolean,
        "internal" = boolean
      }
    }, ...
  }

Spring.GetFullBuildQueue

 ( number unitID ) ->
 nil | buildOrders = {
         [1] = { [number unitDefID] = number count },  etc...
       }

Spring.GetRealBuildQueue (cleans the buildqueue of things the unit can't build itself)

 ( number unitID ) ->
 nil | buildOrders = {
         [1] = { [number unitDefID] = number count },  etc...
       }

Spring.GetFactoryCommands

 ( number unitID [, number count] ) -> nil | commandQueueTable = {
    [1] = {
      "id"      = number,
      "params"  = { [1] = number, ...},
      "options" = {
        "coded"    = number,
        "alt"      = boolean,
        "ctrl"     = boolean,
        "shift"    = boolean,
        "right"    = boolean,
        "internal" = boolean
      }
    }, ...
  }

Spring.GetFactoryCounts (used to get the buildqueue of a factory, seems screwed o_O)

 ( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
    [2] = { [number unitDefID | number -cmdID] = number count }, ...
  }

Command Descriptions/Buttons

Spring.GetUnitCmdDescs

 ( number unitID [, number startIndex [, number endIndex ] ] ) -> nil | {
     [1] = {
       "id"          = number,
       "type"        = number,
       "name"        = string,
       "action"      = string,
       "tooltip"     = string,
       "texture"     = string,
       "cursor"      = string,
       "hidden"      = boolean,
       "disabled"    = boolean,
       "showUnique"  = boolean,
       "onlyTexture" = boolean,

       "params"      = { [1] = string, ... }
    }, ...
  }

Spring.FindUnitCmdDesc

 ( number unitID, number cmdID ) -> nil | number index

Unit Pieces

Spring.GetUnitPiecePosition

 ( number unitID, number piece ) -> number posx, number posy, number posz

Spring.GetUnitPieceDirection

 ( number unitID, number piece ) -> number dirx, number diry, number dirz

Spring.GetUnitPieceMatrix

 ( number unitID, number piece ) -> { [1] = number, ... , [16] = number }

Spring.GetUnitPieceList

 ( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }

Spring.GetUnitPieceMap

 ( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }

Spring.GetUnitPieceInfo

 ( number unitID, number piece ) -> {
   "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 },    
 }

Spring.GetUnitScriptPiece

 ( number unitID [, number scriptPiece ] )
  -> nil | { scriptPieceNum = number modelPieceNum } | number modelPieceNum

 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 via Cob2Lua a pieceID 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.

Spring.GetUnitScriptNames

 ( number unitID )
  -> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }

Features

GetFeatures

Spring.GetFeaturesInRectangle

 ( number xmin, number zmin, number xmax, number zmax [,number teamID] )
   -> nil | featureTable = { [1] = number featureID, etc... }

Spring.GetAllFeatures

 ( ) -> nil | { [1] = number featureID, ... }

Spring.GetFeatureList // NOTE: this is not really required, now all FeatureDefs are pre-loaded

Feature Informations

Spring.GetFeatureDefID

 ( number featureID ) -> nil | number featureDefID

Spring.GetFeatureTeam

 ( number featureID ) -> nil | number teamID

Spring.GetFeatureAllyTeam

 ( number featureID ) -> nil | number allyID

Spring.GetFeatureHealth

 ( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress

Spring.GetFeatureHeight

 ( number featureID ) -> nil | number

Spring.GetFeatureRadius

 ( number featureID ) -> nil | number

Spring.GetFeaturePosition

 ( number featureID ) -> nil | number x, number y, number z

Spring.GetFeatureDirection

 ( number featureID ) -> nil | number dirx, number diry, number dirz

Spring.GetFeatureHeading

 ( number featureID ) -> nil | number heading

Spring.GetFeatureResources

 ( number featureID ) -> nil | number RemainingMetal, number maxMetal,
                               number RemainingEnergy, number maxEnergy, number reclaimLeft

Spring.GetFeatureNoSelect

 ( number featureID ) -> nil | boolean noSelect

Spring.GetFeatureResurrect

 ( number featureID ) -> nil | string UnitDefName, number buildFacing

COB

Spring.GetCOBUnitVar

 ( number unitID, integer varID [, boolean unpack = false ] )
  -> nil | number value | number unpackedX, number unpackedY

Spring.GetCOBTeamVar

 ( number teamID, integer varID [, boolean unpack = false ] )
  -> nil | number value | number unpackedX, number unpackedY

Spring.GetCOBAllyTeamVar

 ( number allyID, integer varID [, boolean unpack = false ] )
  -> nil | number value | number unpackedX, number unpackedY

Spring.GetCOBGlobalVar

 ( integer varID [, boolean unpack = false ] )
  -> nil | number value | number unpackedX, number unpackedY

Ground

Ground Informations

Spring.GetGroundHeight

 ( number x, number y ) -> number z

Spring.GetGroundOrigHeight

 ( number x, number y ) -> number z

Spring.GetGroundNormal

 ( number x, number y ) -> number x, number y, number z

Spring.GetGroundInfo

 ( number x, number y ) -> string "Type", number metal, number hardness,
                           number tankSpeed, number kbotSpeed, number hoverSpeed,
                           number shipSpeed, boolean receiveTracks

Spring.GetGroundBlocked

 ( number x, number y |
   number x1, number y1, number x2, number y2 )
   -> nil |  string "feature", number featureID  |  string "unit", number unitID

Spring.GetGroundExtremes

 ( ) -> nil | number minHeight, number maxHeight

Test Building

Spring.TestBuildOrder

 ( number unitDefID, number x, number y, number z, number facing)
   -> number blocking [,number featureID]

 blocking can be:
   0 - blocked
   1 - mobile unit in the way
   2 - free  (or if featureID is != 0 then with a blocking feature that can be reclaimed)

Spring.Pos2BuildPos

 ( number unitDefID, number x, number y, number z ) -> nil | number x, number y, number z

PathFinding

Spring.GetUnitEstimatedPath

 ( number unitID ) -> nil | {
    [1] = { x,y,z }, ...
  },{
    [1] = startIdxOfDetailedPath,
    [2] = startIdxOfDetailedEstimatedPath1,
    [3] = startIdxOfDetailedEstimatedPath2,
  }
 GetUnitEstimatedPath() returns 2 tables:
   1 table the waypoints and 1 table with indices (in the waypoint table)
   when a new (more lazy) pathfinding algorithm  begins.
   So the waypoint table contains 3 different levels of details.

LOS

Spring.GetPositionLosState

 ( number x, number y, number z [, number allyID] )
   -> boolean visible, boolean inLos, boolean inAirLos, boolean inRadar

Spring.GetClosestValidPosition //NOT FINISHED YET

 ( number unitDefID, number x, number z, number r ) -> nil

Projectiles

Spring.GetProjectilePosition

 ( projectileID ) --> px, py, pz

Spring.GetProjectileVelocity

 ( projectileID ) --> vx, vy, vz