Development < Lua Scripting < Lua SyncedRead

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.FixedAllies

 ( ) -> nil | boolean

Spring.IsGameOver

 ( ) -> boolean

Rules

Those 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.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

Sides/Factions

Spring.GetSideData

 ( string sideName ) -> nil | string startUnit, string caseSensitiveSideName
 ( number sideID ) -> nil | string sideName, string startUnit, string caseSensitiveSideName
 ( ) -> { [1] = { sideName=string,caseName=string,startUnit=string}, [2] = .., .. }

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 = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
 -> nil | { [1] = number playerID, etc... }

Spring.GetTeamList

 ( [number allyTeamID = -1] ) -> 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
         table   customPlayerKeys

Spring.GetPlayerControlledUnit

 ( number playerID ) -> nil | number unitID

Spring.GetAIInfo

 ( number teamID ) -> 
   nil | number  teamID
         number  skirmishAIID,
         string  name,
         number  hostingPlayerID,
         string  shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN")
         string  version,   (synced => "SYNCED_NOVERSION";   non-local => "UNKNOWN")
         table   options    (synced & non-local => empty-table)

Spring.GetAllyTeamInfo

 ( number allyteamID ) -> nil | table   customTeamKeys

Spring.GetTeamInfo

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

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] = {
       "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
     }, ...
  }

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 [, bool useLOS]] ) -> nil | number unitID

Unit Informations

Spring.ValidUnitID

 ( number unitID ) -> boolean

Spring.GetUnitIsDead

 ( number unitID ) -> nil | boolean

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 | number lineage, boolean lineageIsRoot

Spring.GetUnitNeutral

 ( number unitID ) -> nil | boolean neutral

Spring.GetUnitHealth

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

Spring.GetUnitArmored

 ( number unitID ) -> nil | boolean

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

returns the center position of the unit (midpos).

Spring.GetUnitBasePosition

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

returns the bottom of the unit.

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.GetUnitTravel

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

Spring.GetUnitFuel

 ( number unitID ) -> nil | number

Spring.GetUnitFlanking

 ( number unitID, string "dir" ) -> nil | number x, number y, number z
 ( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
 ( number unitID ) -> nil | number mode, number modilityAdd,
   number minDamage, number maxDamage, number dirX, number dirY, number dirZ

Spring.GetUnitSensorRadius

 ( number unitID, string type ) -> nil | number radius
 possible types are:
airLos, radar, sonar, seismic, radarJammer & sonarJammer

Spring.GetUnitLosState raw is only available in gadgets

 ( number unitID [, number allyTeamID [, boolean raw] ] ) -> 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
   }

Spring.GetUnitWeaponVectors

 ( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
   number dirX, number dirY, number dirZ

Spring.GetUnitWeaponState

 ( number unitID, number weaponNum ) -> nil |
   boolean angleGood, boolean loaded, number reloadFrame,
   number salvoLeft, number numStockpiled
 ( number unitID, number weaponNum, string tag ) -> nil | number
 tag can be:
 "reloadState" | "reloadTime" | "accuracy" | "sprayAngle" | 
 "range" | "projectileSpeed" | "burst" | "burstRate" | "projectiles"

Spring.GetUnitLastAttacker

 ( number unitID ) -> nil | number unitID

GetUnitMoveTypeData - new in version 0.80+

 ( number unitID ) -> nil | { movetype data }

Unit Pieces

Spring.GetUnitVectors

 ( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}

Spring.GetUnitPiecePosition

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

Returns piece position in unit space

Spring.GetUnitPieceDirection

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

Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)

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 }

Spring.GetUnitPiecePosDir

 ( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
   number dirX, number dirZ, number dirY

Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized.

This function defines position 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.

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

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.ValidFeatureID

 ( number featureID ) -> boolean

Spring.GetFeatureDefID

 ( number featureID ) -> nil | number featureDefID

Spring.GetFeatureTeam

 ( number featureID ) -> nil | number teamID

Spring.GetFeatureAllyTeam

 ( number featureID ) -> nil | number allyID

Spring.GetFeatureHealth

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

Spring.GetFeatureHeight

 ( number featureID ) -> nil | number

Spring.GetFeatureRadius

 ( number featureID ) -> nil | number

Spring.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

Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

Spring.GetGroundHeight

 ( number x, number z ) -> number y

Spring.GetGroundOrigHeight

 ( number x, number z ) -> number y

Spring.GetGroundNormal

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

Spring.GetGroundInfo

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

Spring.GetGroundBlocked

 ( number x, number z |
   number x1, number z1, number x2, number z2 )
   -> nil |  string "feature", number featureID  |  string "unit", number unitID

Spring.GetGroundExtremes

 ( ) -> nil | number minHeight, number maxHeight

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)
 facing can be:
   0, "s", "south"
   1, "e", "east"
   2, "n", "north"
   3, "w", "west"

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.IsPosInLos

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

Spring.IsPosInRadar

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

Spring.IsPosInAirLos

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

Spring.GetPositionLosState

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

Spring.GetClosestValidPosition //NOT FINISHED YET

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

Projectiles

Spring.GetProjectilePosition

 ( number projectileID ) --> px, py, pz

Spring.GetProjectileVelocity

 ( number projectileID ) --> vx, vy, vz