User:Master-athmos

Development < Lua Scripting < User:Master-athmos

Game

Special TeamID Variables

The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID().

number Spring.ALL_UNITS

number Spring.MY_UNITS

number Spring.ALLY_UNITS

number Spring.ENEMY_UNITS

Spring.GetGaiaTeamID ( )
return: number teamID

GameStates

Spring.IsGodModeEnabled ( )
return: bool enabled

Spring.IsCheatingEnabled ( )
return: bool enabled

Spring.IsDevLuaEnabled ( )
return: bool enabled

Spring.IsEditDefsEnabled ( )
return: bool enabled

Spring.AreHelperAIsEnabled ( )
return: bool enabled

Spring.FixedAllies ( )
return: nil | bool enabled

Spring.IsGameOver ( )
return: bool enabled

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.

Spring.GetGameRulesParam ( number ruleIndex | string ruleName )
return: nil | number value | string value

Spring.GetGameRulesParams ( )
return: nil | { [ruleName1] = number value1 | string value1, ... }

Spring.GetTeamRulesParam ( number teamID, number index | string ruleName )
return: nil | number value | string value

Spring.GetTeamRulesParams ( number teamID )
return: nil | { [ruleName1] = number value1 | string value1, ... }

Spring.GetUnitRulesParam ( number unitID, number index | string ruleName )
return: nil | number value | string value

Spring.GetUnitRulesParams ( number unitID )
return: nil | { [ruleName1] = number value1 | string value1, ... }

Spring.GetFeatureRulesParam ( number featureID, number index | string ruleName )
return: nil | number value | string value

Spring.GetFeatureRulesParams ( number featureID )
return: nil | { [ruleName1] = number value1 | string value1, ... }

Mod-/Map-Options

Spring.GetModOptions ( )
return: nil | { "keyName1" = string "value", "keyName2" = string "value", ... }

Spring.GetMapOptions ( )
return: nil | { "keyName1" = string "value", "keyName2" = string "value", ... }

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

Speed/Time

Spring.GetGameSpeed ( )
return: number userSpeedFactor, number speedFactor, bool paused

As of 98.0 moved to Lua_UnsyncedRead due to desyncs in replays/demos

Spring.GetGameFrame ( )
return: number frameNum%dayFrames, number frameNum/dayFrames

Spring.GetGameSeconds ( )
return: number seconds

Vectors

Spring.GetWind ( )
return: number dirX, number dirY, number dirZ, number strength, number normDirX, number normDirY, number normDirZ

Spring.GetHeadingFromVector ( number x, number z )
return: number heading

Spring.GetVectorFromHeading ( number heading )
return: number x, number z

Sides/Factions

Spring.GetSideData ( string sideName )
return: nil | string startUnit, string caseSensitiveSideName

or

Spring.GetSideData ( number sideID )
return: nil | string sideName, string startUnit, string caseSensitiveSideName

or

Spring.GetSideData ( )
return: { [1] = { sideName = string, caseName = string, startUnit = string} }, [2] = { ..., ..., ... }, ... }

Teams

StartBoxes/StartPositions

Spring.GetAllyTeamStartBox ( number allyID )
return: nil | number xMin, number zMin, number xMax, number zMax

Spring.GetTeamStartPosition ( number teamID )
return: nil | number x, number y, number z

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 here

Spring.GetPlayerList ( [ number teamID = -1 | bool onlyActive = false [, number teamID | bool onlyActive ] ] )
return: nil | { [1] = number playerID, etc... }

From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.

Spring.GetTeamList ( [ number allyTeamID = -1 ] )
return: nil | { [1] = number teamID, etc... }

Spring.GetAllyTeamList ( )
return: { [1] = number teamID, etc... }

Spring.GetPlayerInfo ( number playerID )
return: nil | string "name", bool active, bool spectator, number teamID, number allyTeamID, number pingTime, number cpuUsage, string "country", number rank, table customPlayerKeys

PRE-83.0: in synced code "name" is "SYNCED_NONAME"!

Spring.GetPlayerControlledUnit ( number playerID )
return: nil | number unitID

Spring.GetAIInfo ( number teamID )
return: number skirmishAIID, string "name", number hostingPlayerID, string "shortName", string "version", table options

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)

Spring.GetAllyTeamInfo ( number allyteamID )
return: nil | table customTeamKeys

Spring.GetTeamInfo ( number teamID )
return: nil | number teamID, number leader, bool isDead, bool isAiTeam, string "side", number allyTeam, number incomeMultiplier, table customTeamKeys

Spring.GetTeamResources ( number teamID, string "metal" | "energy" )
return: nil | number currentLevel, number storage, number pull, number income, number expense, number share, number sent, number received

Spring.GetTeamUnitStats ( number teamID )
return: nil | number killed, number died, number capturedBy, number capturedFrom, number received, number sent

Spring.GetTeamUnitStats ( number teamID, string "metal" | "energy" )
return: nil | number used, number produced, number excessed, number received, number sent

Spring.GetTeamUnitStats ( number teamID )
return: nil | number cur_max_index

cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}

or

Spring.GetTeamUnitStats ( number teamID, number startIndex [, number endIndex = startIndex ] )
return: nil | table stats (see below for table content description)

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

Spring.GetTeamLuaAI ( number teamID )
return: string "luaAI"

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

Spring.AreTeamsAllied ( number teamID1, number teamID2, ... )
return: nil | bool isAllied

Spring.ArePlayersAllied ( number playerID1, number playerID2, ... )
return: nil | bool isAllied

Units

GetUnits

Spring.GetAllUnits ( )
return: nil | table unitTable = { [1] = number unitID, ... }

Spring.GetTeamUnits ( number teamID )
return: nil | table unitTable = { [1] = number unitID, ... }

Spring.GetTeamUnitsSorted ( number teamID )
return: nil | table unitDefTable = { [number unitDefID] = { [1] = number unitID, ... }, ... }

Spring.GetTeamUnitsCounts ( number teamID )
return: nil | table countTable = { [number unitDefID] = count, ... }

Spring.GetTeamUnitsByDefs ( number teamID, number unitDefID | tableUnitDefs = { number unitDefID1, ... } )
return: nil | table unitTable = { [1] = number unitID, ... }

Spring.GetTeamUnitDefCount ( number teamID, number unitDefID )
return: nil | number count

Spring.GetTeamUnitCount ( number teamID )
return: nil | number count

Spring.GetUnitsInRectangle ( number xmin, number zmin, number xmax, number zmax [, number teamID ] )
return: nil | table unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInBox ( number xmin, number ymin, number zmin, number xmax, number ymax, number zmax [, number teamID ] )
return: nil | table unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInSphere ( number x, number y, number z, number radius [, number teamID ] )
return: nil | table unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInCylinder ( number x, number z, number radius [, number teamID ] )
return: nil | table unitTable = { [1] = number unitID, etc... }

Spring.GetUnitsInPlanes ( table planes = { [1] = number normalVecX, number normalVecY, number normalVecZ, number d }, etc... } )
return: nil | table 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 ] )
return: nil | number unitID

Spring.GetUnitNearestEnemy ( number unitID [, number range [, bool useLOS ]] )
return: nil | number unitID

Post 95.0 this no longer returns neutral units.

Unit Informations

Spring.ValidUnitID ( number unitID )
return: bool valid

Spring.GetUnitIsDead ( number unitID )
return: nil | bool isDead

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() ).

Spring.GetUnitTooltip ( number unitID )
return: nil | string tooltip

Spring.GetUnitDefID ( number unitID )
return: nil | number unitDefID

Spring.GetUnitTeam ( number unitID )
return: nil | number teamID

Spring.GetUnitAllyTeam ( number unitID )
return: nil | number allyID

Spring.GetUnitLineage ( number unitID )
return: nil | number lineage | number lineage, bool lineageIsRoot

Removed from version 83.0

Spring.GetUnitNeutral ( number unitID )
return: nil | bool neutral

Spring.GetUnitHealth ( number unitID )
return: nil | number health, number maxHealth, number paralyzeDamage, number captureProgress, number buildProgress

Build progress is returned as floating point number between 0.0 and 1.0.

Spring.GetUnitArmored ( number unitID )
return: nil | bool armored, number armorMultiple

armorMultiple new in version 0.83.x.

Spring.GetUnitIsStunned ( number unitID )
return: nil | bool stunned_or_inbuild, bool stunned, bool inbuild

Spring.GetUnitMaxRange ( number unitID )
return: nil | number maxEngagementRange

Spring.GetUnitResources ( number unitID )
return: nil | number metalMake, number metalUse, number energyMake, number energyUse

Spring.GetUnitHarvestStorage ( number unitID )
return: nil | number metal

See also harvestStorage UnitDef tag.

Spring.GetUnitMetalExtraction ( number unitID )
return: nil | number metalExtraction

0.82+ and later

Spring.GetUnitExperience ( number unitID )
return: nil | number experience

0.82+ and later

Spring.GetUnitStates ( number unitID )
return: nil | table unitStates

The unitStates table arguments are:

unitStates = {
    "firestate" = number,
    "movestate" = number,
    "repeat" = boolean,
    "cloak" = boolean,
    "active" = boolean,
    "trajectory" = boolean,
    ["autoland" = boolean,]
    ["autorepairlevel" = number,]
    ["loopbackattack" = boolean]
  } 

Spring.GetUnitIsActive ( number unitID )
return: nil | bool active

Spring.GetUnitIsCloaked ( number unitID )
return: nil | bool isCloaked

Spring.GetUnitSelfDTime ( number unitID )
return: nil | number time

Spring.GetUnitStockpile ( number unitID )
return: nil | number numStockpiled, number numStockpileQued, number buildPercent

Spring.GetUnitHeight ( number unitID )
return: nil | number height

Spring.GetUnitRadius ( number unitID )
return: nil | number radius

Spring.GetUnitMass ( number unitID )
return: nil | number mass

New in version 101.0

Spring.GetUnitBlocking ( number unitID )
return: nil | bool isBlocking, bool isSolidObjectCollidable, bool isProjectileCollidable, bool isRaySegmentCollidable, bool crushable, bool blockEnemyPushing, bool blockHeightChanges

New in version 95.0
Additional output arguments.

Spring.GetUnitPosition ( number unitID [, bool midPos [, bool aimPos ]] )
return: nil | number basePointX, number basePointY, number basePointZ [, number midPointX, number midPointY, number midPointZ [, number aimPointX, number aimPointY, number aimPointZ ]]

Since 89.0, returns the base (default), middle or aim position of the unit.

Spring.GetUnitBasePosition ( number unitID )
return: nil | number posX, number posY, number posZ

Removed from version 89.0 Use GetUnitPosition instead. Returned the bottom of the unit.

Spring.GetUnitDirection ( number unitID )
return: nil | number dirX, number dirY, number dirZ

Returns the direction vector.

Spring.GetUnitHeading ( number unitID )
return: nil | number heading

Returns heading directions used in COB scripts.

Spring.GetUnitRotation ( number unitID )
return: nil | number pitch, number yaw, number roll

New in version 95.0

Spring.GetUnitVelocity ( number unitID )
return: nil | number velX, number velY, number velZ, number velLength

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.

Spring.GetUnitBuildFacing ( number unitID )
return: nil | number facing

Spring.GetUnitIsBuilding ( number unitID )
return: nil | number unitID

Returns what unit a constructor/factory is currently building.

Spring.GetUnitCurrentBuildPower ( number unitID )
return: nil | number buildPower

New in version 92.0

Spring.GetUnitNanoPieces ( number unitID )
return: nil | { [1] = number piece1, etc ... }

Spring.GetUnitTransporter ( number unitID )
return: nil | number unitID

Spring.GetUnitIsTransporting ( number unitID )
return: nil | { [1] = number unitID, etc ... }

Spring.GetUnitShieldState ( number unitID [, number weaponID = -1 ] )
return: nil | number isEnabled, number curPower

Spring.GetUnitTravel ( number unitID )
return: nil | number travel, number travelPeriod

Marked as deprecated.

Spring.GetUnitFuel ( number unitID )
return: nil | number fuel

Marked as deprecated.

Spring.GetUnitFlanking ( number unitID, string "dir" )
return: nil | number x, number y, number z

or

Spring.GetUnitFlanking ( number unitID, string "mode" | string "dir" | string "moveFactor" | string "minDamage" | string "maxDamage" )
return: nil | number flankingBonusMode | number flankingBonusDir.x, number flankingBonusDir.y, number flankingBonusDir.z | number flankingBonusMobilityAdd | number minDamage | number maxDamage

or

Spring.GetUnitFlanking ( number unitID )
return: nil | number mode, number modilityAdd, number minDamage, number maxDamage, number dirX, number dirY, number dirZ

Spring.GetUnitSensorRadius ( number unitID, string type )
return: nil | number radius

Possible types are:
los, airLos, radar, sonar, seismic, radarJammer, sonarJammer

Spring.GetUnitLosState ( number unitID [, number allyTeamID [, bool raw ]] )
return: nil | number raw | [ string "los" = true [, string "radar" = true [, string "typed" = true ]]]

Raw is only available in gadgets.

Spring.GetUnitSeparation ( number unitID1, number unitID2 [, bool 2D [, bool surfaceDist ]] )
return: nil | number distance

SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.

Spring.GetUnitFeatureSeparation ( number unitID, number featureID [, bool 2D ] )
return: nil | number distance

New in version 101.0

Spring.GetUnitDefDimensions ( number unitDefID )
return: nil | table defDimensions

DefDimensions table arguments are:

defDimensions =    {
      "height" = number,
      "radius" = number,
      "midx"   = number,
      "minx"   = number,
      "maxx"   = number,
      "midy"   = number,
      "miny"   = number,
      "maxy"   = number,
      "midz"   = number,
      "minz"   = number,
      "maxz"   = number
    }

Spring.GetUnitLastAttacker ( number unitID )
return: nil | number unitID

Spring.GetUnitLastAttackedPiece ( number unitID )
return: nil | string pieceName, number gameframe

Spring.GetUnitMoveTypeData ( number unitID )
return: nil | table movetypeData

Spring.GetUnitCollisionVolumeData ( number unitID )
return: nil | number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetZ, number volumeType, number testType, number primaryAxis, bool disabled

Unit Weapon Informations

Spring.GetUnitWeaponState ( number unitID, number weaponNum )
return: nil | bool angleGood, bool loaded, number reloadFrame, number salvoLeft, number numStockpiled

or

Spring.GetUnitWeaponState ( number unitID, number weaponNum, string tag )
return: nil | number tagVariable

String argument "tag" can return a specific variable. Possilbe tags are:

  "reloadState" == "reloadFrame"
  "reloadTime"
  "accuracy"
  "sprayAngle"
  "range"
  "projectileSpeed"
  "burst"
  "burstRate"
  "projectiles"

  The following 4 tags were added in 104.0:
  "salvoError"
  "salvoLeft"
  "nextSalvo"
  "targetMoveError"

Spring.GetUnitWeaponDamages ( number unitID, number weaponNum | string "selfDestruct" | string "explode", string tag )
return: nil | number tagVariable

String argument "tag" can return a specific variable. Possilbe tags are:

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

Spring.GetUnitWeaponVectors ( number unitID, number weaponNum )
return: nil | number posX, number posY, number posZ, number dirX, number dirY, number dirZ

Spring.GetUnitWeaponTryTarget ( number unitID, number weaponNum, number targetID | number posX, number posY, number posZ )
return: nil | bool success

New in version 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.

Spring.GetUnitWeaponTestTarget ( number unitID, number weaponNum, number targetID | number posX, number posY, number posZ )
return: nil | bool success

New in version 94.0
Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.

Spring.GetUnitWeaponTestRange ( number unitID, number weaponNum, number targetID | number posX, number posY, number posZ )
return: nil | bool success

New in version 94.0
Checks if target is in range including height modifiers and cylinder targeting if set.

Spring.GetUnitWeaponHaveFreeLineOfFire ( number unitID, number weaponNum, number targetID | number posX, number posY, number posZ )
return: nil | bool success

New in version 94.0
Runs a raytrace from unit aimpoint respecting collision flags.

or

Spring.GetUnitWeaponHaveFreeLineOfFire ( number unitID, number weaponNum, number targetID | [ number srcPosX [, number srcPosY [, number srcPosZ [, number tgtPosX [, number tgtPosY [, number tgtPosZ ]]]]]] )
return: nil | bool success

New in version 104.0
The param list was changed so that the source firing position can also be passed.

Spring.GetUnitWeaponCanFire ( number unitID, number weaponNum )
return: nil | bool canFire

New in version 95.0

Spring.GetUnitWeaponTarget ( number unitID, number weaponNum )
return: nil | number 0 | number 1, bool isUserTarget, number unitID | number 2, bool isUserTarget, { number posX, number posY, number posZ } | number 3, bool isUserTarget, number projectileID

New in version 95.0
Returned number of args is always 3 if targetType != None.

Spring.GetRadarErrorParams ( number allyTeamID )
return: nil | number allyteamErrorSize, number baseErrorSize, number baseErrorMult

New in version 95.0

Spring.GetUnitPosErrorParams ( number unitID )
return: nil | number posErrorVector.x, number posErrorVector.y, number posErrorVector.z, number posErrorDelta.x, number posErrorDelta.y, number posErrorDelta.z, number nextPosErrorUpdatebaseErrorMult

New in version 95.0

Unit LOS

Spring.IsUnitInLos New in version 101.0

 ( number unitID, number allyID ) -> boolean

Spring.IsUnitInAirLos New in version 101.0

 ( number unitID, number allyID ) -> boolean

Spring.IsUnitInRadar New in version 101.0

 ( number unitID, number allyID ) -> boolean

Spring.IsUnitInJammer New in version 101.0

 ( number unitID, number allyID ) -> boolean

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. Also remember to multiply the x-axis value with -1 if you want move a piece to another piece.

Spring.GetUnitPieceDirection Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir

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

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

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 }, 
   "parent" = string "parentpiecename",   
 }

New in version 95.0 "parent" field New in version 101.0 parent for root pieces is now "[null]" instead of ""

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

 ( number unitID, number pieceID )
 -> number scaleX, number scaleY, number scaleZ,
 number offsetX, number offsetY, number offsetZ,
 number volumeType, number testType, number primaryAxis, boolean disabled

As of 101.0 this is 1-based piece index argument (was 0-based).

CommandQueues

Spring.GetUnitCommands
Spring.GetCommandQueue (Alias)

 ( number unitID, number count = 0 ) -> nil | number commandQueueSize New in version 96
 ( number unitID [, number count = -1] ) 
 -> nil | table commandQueueTable = {
    [1] = {
      "id"      = number,
      "params"  = { [1] = number, ...},
      "options" = {
        "coded"    = number,
        "alt"      = boolean,
        "ctrl"     = boolean,
        "shift"    = boolean,
        "right"    = boolean,
        "internal" = boolean,
        "meta"    = boolean
      }
    }, ...
  }

This function can trigger an error if called too often without passing a second parameter. Refer to LuaSyncedRead.cpp#L3983-L3996

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 = 0 ) -> nil | number commandQueueSize New in version 96
 ( number unitID [, number count = -1 ] ) 
 -> nil | table commandQueueTable = {
    [1] = {
      "id"      = number,
      "params"  = { [1] = number, ...},
      "options" = {
        "coded"    = number,
        "alt"      = boolean,
        "ctrl"     = boolean,
        "shift"    = boolean,
        "right"    = boolean,
        "internal" = boolean,
        "meta"    = 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 )
   -> featureTable = { [1] = number featureID, etc... }

Spring.GetFeaturesInSphere

 ( number x, number y, number z, number radius )
   -> featureTable = { [1] = number featureID, etc... }

Spring.GetFeaturesInCylinder

 ( number x, number z, number radius )
   -> featureTable = { [1] = number featureID, etc... }

Spring.GetAllFeatures

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

Feature Informations

Spring.ValidFeatureID

 ( number featureID ) -> boolean

Spring.GetFeatureDefID

 ( number featureID ) -> nil | number featureDefID

Spring.GetFeatureTeam

 ( number featureID ) -> nil | number teamID

Spring.GetFeatureAllyTeam

 ( number featureID ) -> nil | number allyID

Spring.GetFeatureHealth

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

Spring.GetFeatureHeight

 ( number featureID ) -> nil | number

Spring.GetFeatureRadius

 ( number featureID ) -> nil | number

Spring.GetFeatureMass New in version 101.0

 ( number featureID ) -> nil | number

Spring.GetFeatureSeparation New in version 101.0

 ( number featureID1, number featureID2 [, boolean 2D] ) -> nil | number distance

Spring.GetFeaturePosition

 ( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
 nil |
 number bpx, number bpy, number bpz [,
 number mpx, number mpy, number mpz [,
 number apx, number apy, number apz ]]

since 89.0, returns the base (default), middle or aim position of the feature.

Spring.GetFeatureVelocity New in version 95.0

 ( number featureID [, boolean norm] )
 -> nil | number velx, number vely, number velz, number velLength

Spring.GetFeatureDirection

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

Spring.GetFeatureRotation New in version 101.0

  (number featureID) --> nil | number pitch, number yaw, number roll 

Spring.GetFeatureHeading

 ( number featureID ) -> nil | number heading

Spring.GetFeatureResources reclaimTime New in version 105.0

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

Spring.GetFeatureNoSelect

 ( number featureID ) -> nil | boolean noSelect

Spring.GetFeatureResurrect

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

Spring.GetFeatureCollisionVolumeData

 ( number featureID )
 -> number scaleX, number scaleY, number scaleZ,
 number offsetX, number offsetY, number offsetZ,
 number volumeType, number testType, number primaryAxis, boolean disabled

Spring.GetFeaturePieceCollisionVolumeData New in version 101.0

 ( number featuerID, number pieceID )
 -> number scaleX, number scaleY, number scaleZ,
 number offsetX, number offsetY, number offsetZ,
 number volumeType, number testType, number primaryAxis, boolean disabled

Spring.GetFeatureBlocking

 (number featureID) --> boolean collidable, boolean crushable, boolean blocking

New in version 95.0 Now return values are:

 boolean isBlocking,
 boolean isSolidObjectCollidable,
 boolean isProjectileCollidable,
 boolean isRaySegmentCollidable,
 boolean crushable,
 boolean blockEnemyPushing,
 boolean blockHeightChanges

Feature Pieces

See #Unit_Pieces for full details.

Spring.GetFeatureLastAttackedPiece

Spring.GetFeaturePieceMap

Spring.GetFeaturePieceList

Spring.GetFeaturePieceInfo

Spring.GetFeaturePiecePosition

Spring.GetFeaturePieceDirection

Spring.GetFeaturePiecePosDir

Spring.GetFeaturePieceMatrix

COB

Spring.GetCOBUnitVar

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

Spring.GetCOBTeamVar

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

Spring.GetCOBAllyTeamVar

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

Spring.GetCOBGlobalVar

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

Ground

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

Spring.GetGroundHeight

 ( number x, number z ) -> number y

Spring.GetGroundOrigHeight

 ( number x, number z ) -> number y

This returns the ground original (before terraforming) height at a given x,z position

Spring.GetGroundNormal

 ( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope 

New in version 100.0: smoothedNormal and slope

Spring.GetGroundInfo

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

Spring.GetGroundBlocked

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

Spring.GetGroundExtremes

 ( ) -> nil | number minHeight, number maxHeight

Spring.GetSmoothMeshHeight

 ( number x, number z ) -> number y

Spring.GetMetalMapSize

 ( ) -> number sizeX, number sizeY

Spring.GetMetalAmount

 ( number x, number z ) -> number metalAmount 

where x & z are in metal map coordinates (worldspace/16)

Spring.GetMetalExtraction

 ( number x, number z ) -> number extractionAmount 

where x & z are in metal map coordinates (worldspace/16)

Spring.GetTerrainTypeData New in version 92.0

 ( number i )
   -> nil |  string "name", number hardness,
             number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
             boolean receiveTracks

Spring.GetGrass

 ( number x, number z ) -> number 0 | 1 

where x & z are in worldspace coordinates

Test Orders

Spring.TestMoveOrder

 ( number unitDefID, number x, number y, number z) -> boolean validMove

New in version 95.0 parameters now are:

   number unitDefID,
   number pos.x, number pos.y, number pos.z
   [, number dir.x
   [, number dir.y
   [, number dir.z
   [, boolean testTerrain
   [, boolean testObjects
   [, boolean centerOnly ]]]]]]
   ) --> boolean 

Spring.TestBuildOrder

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

 blocking can be:
   0 - blocked
   1 - mobile unit in the way
   2 - free  (or if featureID is != nil then with a blocking feature that can be reclaimed)
 facing can be:
   0, "s", "south"
   1, "e", "east"
   2, "n", "north"
   3, "w", "west"

Spring.Pos2BuildPos optional param facing supported in 0.83 and later

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

PathFinding

Spring.GetUnitEstimatedPath

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

LOS

Spring.IsPosInLos

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

Spring.IsPosInRadar

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

Spring.IsPosInAirLos

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

Spring.GetPositionLosState jammed new in 95.0

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

jammed indicates if a position is actively being radar- or sonar-jammed by any allyteam

Spring.GetClosestValidPosition //NOT FINISHED YET

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

Projectiles

Spring.GetProjectilesInRectangle

( number xmin, number zmin, number xmax, number zmax
  [, boolean excludeWeaponProjectiles
  [, boolean excludePieceProjectiles] ] )
  -> nil | projectileTable = { [1] = number projectileID, etc... }

Spring.GetProjectileOwnerID New in version 99.0

  (number projectileID) -> nil | number unitID

Spring.GetProjectileTeamID New in version 99.0

  (number projectileID) -> nil | number teamID

Spring.GetProjectileDefID

  (number projectileID) -> nil | number weaponDefID
 using this to get a weaponDefID is HIGHLY preferred 
 to indexing WeaponDefNames via GetProjectileName

Spring.GetProjectileName

 ( number projectileID ) -> nil | string name

Spring.GetProjectileType

 ( number projectileID ) -> nil | boolean weapon, boolean piece

Spring.GetProjectileTarget

 ( number projectileID )
 Pre 95.0:  -> nil | number targetID, string targetTypeStr
 Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

 targetTypeStr can be one of: 
   'u' - unit
   'f' - feature
   'p' - projectile
 while targetTypeInt is one of:
   string.byte('g') := GROUND
   string.byte('u') := UNIT
   string.byte('f') := FEATURE
   string.byte('p') := PROJECTILE
 

Spring.GetProjectileIntercepted New in version 99.0

 ( number projectileID ) -> nil | boolean isBeingIntercepted

Spring.GetProjectilePosition

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

Spring.GetProjectileVelocity

 ( number projectileID ) -> nil | number vx, number vy, number vz
 New in version 95.0: returns (targetPos - startPos) for Beamlasers and similar weapons

Spring.GetProjectileGravity

 ( number projectileID ) -> nil | number gravity

Spring.GetPieceProjectileParams New in version 95.0

 ( number projectileID ) -> nil |  number explosionFlags, number spinAngle, 
 number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
 Where explosionFlags use binary flags with the following integer equivalents: 
  more info here
  SHATTER = 1,  EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
  NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128   

Spring.GetProjectileTimeToLive New in version 99.0

 ( number projectileID ) -> nil | number ttl

Spring.GetProjectileDirection New in version 95.0

 ( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

Spring.GetProjectileSpinAngle Deprecated in 95.0

 ( number projectileID ) -> nil | number angle

Spring.GetProjectileSpinSpeed Deprecated in 95.0

 ( number projectileID ) -> nil | number spinSpeed

Spring.GetProjectileSpinVec Deprecated in 95.0

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

Spring.GetProjectileDamages New in version 101.0

 ( number unitID, number weaponNum, string tag ) -> nil | number
 `tag` can be:
 "paralyzeDamageTime"
 "impulseFactor"
 "impulseBoost"
 "craterMult"
 "craterBoost"
 "dynDamageExp"
 "dynDamageMin"
 "dynDamageRange"
 "dynDamageInverted"
 "craterAreaOfEffect"
 "damageAreaOfEffect"
 "edgeEffectiveness"
 "explosionSpeed"
 - or -
 an armor type index to get the damage against it.