[wiki] Using headers for calls?

Forboding Angel · Post by **Forboding Angel** » 04 Sep 2016, 06:43

Do you find this helpful, or does it muddy the waters so much that it ends up being detrimental?

Flozi, if you like it this way, here is the wikitext for it:

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''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

=== RulesParams ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br>
<span class=warning>string values are new since 95.0</span>


==== Spring.GetRulesInfoMap ====
 <span class=warning>REMOVED in 0.82!</span>
  ( ) -> { [key1] = string value1, [key2] = string value2, ... }
  ( string "key" ) -> string


==== Spring.GetGameRulesParam ====
  ( number ruleIndex | string ruleName ) -> nil | number value | string value

==== Spring.GetGameRulesParams ====
  ( ) -> nil | { [ruleIndex1] = {[ruleName1] = number | string value1}, ... }


==== Spring.GetTeamRulesParam ====
  ( number teamID, number index | string ruleName ) -> nil | number value | string value

==== Spring.GetTeamRulesParams ====
  ( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number | string value1}, ... }



==== Spring.GetUnitRulesParam ====
  ( number unitID, number index | string ruleName ) -> nil | number value | string value

==== Spring.GetUnitRulesParams ====
  ( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number | string value1}, ... }

=== Mod-/Map-Options ===

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

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


! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition:<br><br>
<font color="#55ee99">"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end"</font><br>
not only:<br>
<span class="warning">"if (Spring.GetModOptions.exampleOption) then...end"</span>

=== Speed/Time ===

==== Spring.GetGameSpeed ====
 <span class="warning">As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos</span>
  ( ) -> 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",  <span class="note">(PRE-83.0: in synced code this is "SYNCED_NONAME"!)</span>
          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 ) -> 
          number  skirmishAIID,
          string  name,
          number  hostingPlayerID,
          string  shortName, <span class="note">(synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN")</span>
          string  version,   <span class="note">(synced => "SYNCED_NOVERSION";   non-local => "UNKNOWN")</span>
          table   options    <span class="note">(synced & non-local => empty-table)</span>
<span class="warning">Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.</span>



==== Spring.GetAllyTeamInfo ====
  ( number allyteamID ) -> nil | table   customTeamKeys


==== Spring.GetTeamInfo ====
  ( number teamID ) ->
    nil | number  teamID,
          number  leader, <span class=note>(:= a player id)</span>
          boolean isDead,
          boolean isAiTeam,
          string  "side",
          number  allyTeam,
          table   customTeamKeys,
          number  incomeMultiplier

==== 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.GetTeamResourceStats ====
<span class="note">0.82 and later</span>
  ( number teamID,  string "metal" | "energy" ) ->
    nil | number used,
          number produced,
          number excessed,
          number received,
          number sent

==== Spring.GetTeamStatsHistory ====
  ( number teamID [, number startIndex [, number endIndex = startIndex ]]) ->
    nil |
    number cur_max_index |
    {
      [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
      }, ...
   }
<span class="note">if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}</span>



==== Spring.GetTeamLuaAI ====
  ( number teamID ) -> 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, so maybe depends, but in my LuaAI.lua name is on first position...

=== 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... }
<font color="#55ee99">
  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
</font>


==== Spring.GetUnitNearestAlly ====
  ( number unitID [, number range ] ) -> nil | number unitID

==== Spring.GetUnitNearestEnemy ====
  ( number unitID [, number range [, bool useLOS]] ) -> nil | number unitID

<span class="note">Post 95.0 this no longer returns neutral units</span>

=== Unit Informations ===

==== Spring.ValidUnitID ====
  ( number unitID ) -> boolean

==== Spring.GetUnitIsDead ====
  ( number unitID ) -> nil | boolean
<span class="note">Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise<br/>
keep this in mind when using (not Spring.GetUnitIsDead())</span>


==== 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 ====
<span class="warning"> Removed from version 0.83.x</span> <br>
  ( 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
build Progress is returned as floating Point between 0.0 and 1.0


==== Spring.GetUnitArmored ====
<span class="warning">armorMultiple new in version 0.83.x</span>
  ( number unitID ) -> nil | boolean armored, number armorMultiple

==== Spring.GetUnitIsStunned ====
  ( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild

==== Spring.GetUnitMaxRange ====
  ( number unitID ) -> nil | number maxEngagementRange

==== Spring.GetUnitResources ====
  ( number unitID ) -> nil | number metalMake, number metalUse,
                             number energyMake, number energyUse

==== Spring.GetUnitHarvestStorage ====
  ( number unitID ) -> nil | number metal
<span class = "note">See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.</span>


==== Spring.GetUnitMetalExtraction ====
<span class="note">0.82+ and later</span>
  ( number unitID ) -> nil | number

==== 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.GetUnitMass ====
{{new|101.0}}
  ( number unitID ) -> nil | number

==== Spring.GetUnitBlocking ====
{{new|85.0}}
  ( number unitID ) -> nil | boolean blocking, boolean crushable
{{new|95.0}} Now return values are: 
  boolean isBlocking,
  boolean isSolidObjectCollidable,
  boolean isProjectileCollidable,
  boolean isRaySegmentCollidable,
  boolean crushable,
  boolean blockEnemyPushing,
  boolean blockHeightChanges


==== Spring.GetUnitPosition ====
  ( number unitID, [, boolean midPos [, boolean aimPos ] ] ) ->
    nil |
    number bpx, number bpy, number bpz
    [, number mpx, number mpy, number mpz ]
    [, number apx, number apy, number apz ]
<span class="note">since 89.0, returns the base (default), middle or aim position of the unit.</span>


==== Spring.GetUnitBasePosition ====
<span class="warning">Deprecated in 89.0, use GetUnitPosition</span>
  ( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>


==== Spring.GetUnitDirection ====
  ( number unitID ) -> nil | number dx, number dy, number dz
<span class="note">returns the direction vector</span>


==== Spring.GetUnitHeading ====  
  ( number unitID ) -> nil | number heading
<span class="note">returns heading directions used in COB scripts</span>


==== Spring.GetUnitRotation ====
{{New|95.0}}
   (number unitID) --> nil | number pitch, number yaw, number roll 
<span class="note">Marked as (WIP) in changelog</span>



==== Spring.GetUnitVelocity ====
<span class="warning">velw new in 95.0</span>
  ( number unitID ) -> nil | number velx, number vely, number velz, number velLength

==== Spring.GetUnitBuildFacing ====
  ( number unitID ) -> nil | number

==== Spring.GetUnitIsBuilding ====
<font color="#55ee99">returns what unit a constructor/factory is currently building</font>
  ( number unitID ) -> nil | number unitID

==== Spring.GetUnitCurrentBuildPower ====
{{new|92.0}}
  ( number unitID ) -> nil | number buildPower

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

==== Spring.GetUnitTransporter ====
  ( number unitID ) -> nil | number unitID

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

==== Spring.GetUnitShieldState ====
  ( number unitID [, number weaponID = -1] ) -> 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
<font color="#55ee99">possible types are:<br>los, airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>


==== Spring.GetUnitLosState ====
<font color="red">raw is only available in gadgets</font>
  ( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil | number raw |
  { ["los" = true] [, "radar" = true] [, "typed" = true] }

==== Spring.GetUnitSeparation ====
<span class="warning">surfaceDist new in 95.0</span>
  ( number unitID1, number unitID2 [, boolean 2D] [, boolean surfaceDist] ) -> nil | number distance
<font color="#55ee99">returns the distance of 2 units, surfaceDist calculates the distance between the unitsphere surfaces instead of their midpos</font>


==== Spring.GetUnitFeatureSeparation ====
{{new|101.0}}
  ( number unitID, number featureID [, 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.GetUnitLastAttacker ====
  ( number unitID ) -> nil | number unitID

==== Spring.GetUnitLastAttackedPiece ====
  ( number unitID ) -> nil | string pieceName, number gameframe

==== Spring.GetUnitMoveTypeData ====
<span class="note">new in version 0.80+</span>
  ( number unitID ) -> nil | { movetype data }

==== Spring.GetUnitCollisionVolumeData ====
  ( number unitID )
  -> number scaleX, number scaleY, number scaleZ,
  number offsetX, number offsetY, number offsetZ,
  number volumeType, number testType, number primaryAxis, boolean disabled

==== Unit Weapon Informations ====

==== 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
  <span class=note>`tag` can be:
  "reloadState" == "reloadFrame"
  "reloadTime"
  "accuracy"
  "sprayAngle"
  "range"
  "projectileSpeed"
  "burst"
  "burstRate"
  "projectiles"</span>


==== Spring.GetUnitWeaponDamages ====
{{new|101.0}}
  ( number unitID, number weaponNum | "selfDestruct" | "explode", string tag ) -> nil | number
  <span class=note>`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.</span>


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


==== Spring.GetUnitWeaponTryTarget ====
{{new|94.0}}
  ( number unitID, number weaponNum, 
    number targetID | number posX, number posY, number posZ ) -> nil | boolean success


==== Spring.GetUnitWeaponTestTarget ====
{{new|94.0}}
  ( number unitID, number weaponNum, 
    number targetID | number posX, number posY, number posZ ) -> nil | boolean success


==== Spring.GetUnitWeaponTestRange ====
{{new|94.0}}
  ( number unitID, number weaponNum, 
    number targetID | number posX, number posY, number posZ ) -> nil | boolean success


==== Spring.GetUnitWeaponHaveFreeLineOfFire ====
{{new|94.0}}
  ( number unitID, number weaponNum, 
    number targetID | number posX, number posY, number posZ ) -> nil | boolean success


==== Spring.GetUnitWeaponCanFire ====
{{new|95.0}}
  ( number unitID, number weaponNum ) -> nil | boolean canFire


==== Spring.GetUnitWeaponTarget ====
{{new|95.0}}
  ( number unitID, number weaponNum ) -> 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


==== Spring.GetRadarErrorParams ====
{{new|95.0}}
  (number allyTeamID) --> nil | 
  number allyteamErrorSize, number baseErrorSize, number baseErrorMult


==== Spring.GetUnitPosErrorParams ====
{{new|95.0}}
  (number unitID) --> nil |
       number posErrorVector.x, number posErrorVector.y, number posErrorVector.z,
       number posErrorDelta.x, number posErrorDelta.y, number posErrorDelta.z,
       number nextPosErrorUpdate

==== Unit LOS ====

==== Spring.IsUnitInLos ====
{{new|101.0}}
  ( number unitID, number allyID ) -> boolean

==== Spring.IsUnitInAirLos ====
{{new|101.0}}
  ( number unitID, number allyID ) -> boolean

==== Spring.IsUnitInRadar ====
{{new|101.0}}
  ( number unitID, number allyID ) -> boolean

==== Spring.IsUnitInJammer ====
{{new|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
<font color="#55ee99">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.</font>


==== Spring.GetUnitPieceDirection ====
<font color="red">Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir</font>
  ( 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
<font color="#55ee99">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.</font>


==== 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|95.0}} "parent" field
{{new|101.0}} parent for root pieces is now "[null]" instead of ""


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

<font color="#55ee99">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 <i>piece</i> definition in your cob/bos.</font>


==== 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 ====
<br/>

==== Spring.GetCommandQueue ====
<span class="note">(Alias)</span>
  ( number unitID, number count = 0 ) -> nil | number commandQueueSize {{new|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
       }
     }, ...
   }

<font color="#55ee99">This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]</font>


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

==== Spring.GetRealBuildQueue ====
<font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
  ( number unitID ) ->
  nil | buildOrders = {
          [1] = { [number unitDefID] = number count },  etc...
        }

==== Spring.GetFactoryCommands ====
  ( number unitID, number count = 0 ) -> nil | number commandQueueSize {{new|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|101.0}}
  ( number featureID ) -> nil | number

==== Spring.GetFeatureSeparation ====
{{new|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 ]]
<span class="note">since 89.0, returns the base (default), middle or aim position of the feature.</span>


==== Spring.GetFeatureVelocity ====
{{new|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|101.0}}
   (number featureID) --> nil | number pitch, number yaw, number roll 


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

==== 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|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|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 ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>


==== Spring.GetGroundHeight ====
  ( number x, number z ) -> number y

==== Spring.GetGroundOrigHeight ====
  ( number x, number z ) -> number y

==== Spring.GetGroundNormal ====
  ( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope 
{{new|100.0}}<span class="warning">: smoothedNormal and slope</span>


==== 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 
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>


==== Spring.GetMetalExtraction ====
  ( number x, number z ) -> number extractionAmount 
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>


==== Spring.GetTerrainTypeData ====
{{new|92.0}}
  ( number i )
    -> nil |  string "name", number hardness,
              number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
              boolean receiveTracks

=== Test Orders ===

==== Spring.TestMoveOrder ====
  ( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|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]

  <font color="#55ee99">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"</font>

==== Spring.Pos2BuildPos ====
<font color="#FF0000">optional param ''facing'' supported in 0.83 and later</font>
  ( 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,
   }
  <font color="#55ee99">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.</font>

=== 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 ====
<span class="warning">jammed new in 95.0</span>
  ( number x, number y, number z [, number allyID] )
    -> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
<span class="note">jammed indicates if a position is actively being radar- or sonar-jammed by  ==== any ====  allyteam</span>



==== Spring.GetClosestValidPosition ====
<span class="warning">//NOT FINISHED YET</span>
  ( 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|99.0}}
   (number projectileID) -> nil | number unitID


==== Spring.GetProjectileTeamID ====
{{new|99.0}}
   (number projectileID) -> nil | number teamID


==== Spring.GetProjectileDefID ====
   (number projectileID) -> nil | number weaponDefID
  <span class=note>using this to get a weaponDefID is HIGHLY preferred <br/> to indexing WeaponDefNames via GetProjectileName<span>


==== Spring.GetProjectileName ====
  ( number projectileID ) -> nil | string name

==== Spring.GetProjectileType ====
  ( number projectileID ) -> nil | boolean weapon, boolean piece


==== Spring.GetProjectileTarget ====
  ( number projectileID )
  <span class="warning">Pre 95.0:</span>  -> nil | number targetID, string <span class=note>targetTypeStr</span>
  <span class="warning">Post 95.0:</span> -> nil | [number <span class=note>targetTypeInt</span>, number targetID | table targetPos = {x, y, z}]

  <span class=note>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
  </span>

==== Spring.GetProjectileIntercepted ====
{{new|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|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons


==== Spring.GetProjectileGravity ====
  ( number projectileID ) -> nil | number gravity


==== Spring.GetPieceProjectileParams ====
{{new|95.0}}
  ( number projectileID ) -> nil |  number explosionFlags, number spinAngle, 
  number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
  <span class=note>Where explosionFlags use binary flags with the following integer equivalents: 
   more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
   SHATTER = 1,  EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
   NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128   </span>


==== Spring.GetProjectileTimeToLive ====
{{new|99.0}}
  ( number projectileID ) -> nil | number ttl


==== Spring.GetProjectileDirection ====
{{new|95.0}}
  ( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z


==== Spring.GetProjectileSpinAngle ====
<span class="warning">Deprecated in 95.0</span>
  ( number projectileID ) -> nil | number angle

==== Spring.GetProjectileSpinSpeed ====
<span class="warning">Deprecated in 95.0</span>
  ( number projectileID ) -> nil | number spinSpeed

==== Spring.GetProjectileSpinVec ====
<span class="warning">Deprecated in 95.0</span>
  ( number projectileID ) -> nil | number x, number y, number z



==== Spring.GetProjectileDamages ====
{{new|101.0}}
  ( number unitID, number weaponNum, string tag ) -> nil | number
  <span class=note>`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.</span>

[[category: Lua]]

At first I did it thinking that it would make the page easier to read, but I couldn't decide so I figured you had probably considered it at one point, therefore it made sense to get your input.

The idea was to save searching (ctrl+f), but I almost feel like with a list that big I would be searching anyway, therefore the point defeats itself.

Post by **gajop** » 04 Sep 2016, 08:24

It could be nice if each element had more detailed explanation and some examples.

Silentwings · Post by **Silentwings** » 04 Sep 2016, 10:50

I prefer it as it is, on my machine that makes the list of title headers take up three screenfuls, which imo defeats the point.

A line of explanation on the body text where the callin name is not self-explanatory would be good though. Detailed explanations seem a bit much for an already long page, but +1 for example gadgets elsewhere.

FLOZi · Post by **FLOZi** » 04 Sep 2016, 11:59

All these requests are basically subsumed into 'make callout pages templatised like callins and defs'.

It's a nice idea in theory Forb but as you realised and others pointed out, it's too much TOC and not enough page, ctrl+f is sufficient, the nav links in the TOC should be sectional as they are now imo.

Looks like I forgot to add the anchor to the revised Lua Callin template, but it's still in tag so that you can do e.g. https://springrts.com/wiki/Modrules.lua ... lowEnemies to link someone directly to an entry, though I do need to modify it to be a right-clickable link for easy copy pasta.

Replicating the current BNF style form in a template is not easy though, and there are so many diverse calls in the API that it is easy to overlook some case that needs to be addressed.

edit: so yeah my ideal is that you can do https://springrts.com/wiki/Lua:Callins#GameProgress, with it modifiied to be a right-clickable link at the point where it is displayed, and each callout should have a brief explanation akin to the ones on Callins, examples only where necessary on the main page, links otherwise.

Forboding Angel · Post by **Forboding Angel** » 04 Sep 2016, 15:40

Yeah, for me it all started cause I wanted to link someone to getPlayerInfo.

Spring RTS Engine

[wiki] Using headers for calls?

[wiki] Using headers for calls?

Re: [wiki] Using headers for calls?

Re: [wiki] Using headers for calls?

Re: [wiki] Using headers for calls?

Re: [wiki] Using headers for calls?